Java Class Template
Use this class as a template for a class that accesses record data and uses it to perform some operation. (The class is intentionally overly-complete. It's a lot easier to remove something you don't need than it is to look up the syntax for things you do need--or to know that syntax even exists.)
- <syntaxhighlight lang="java" enclose="div">
package com.platform.yourCompany.yourApplication;
// Basic imports import com.platform.api.*; import java.util.*;
// Reference static functions without having to specify the Functions class. // So Functions.throwError() can be written as throwError(). // (Code is shorter that way, but it's less obvious where things are defined.) import static com.platform.api.Functions.*;
// These are needed for advanced operations. //import com.platform.beans.*; //import static com.platform.api.CONSTANTS.*;
public class YourClass {
// Convenience methods to display a message to the user or add it the debug log. // Note: // When showMessage() is called multiple times, the strings are concatenated. // One long string is then displayed when the code returns to the platform. // We add an HTML linebreak (
) to separate them. Log messages, on the // other hand, use a Java "\n" (newline) character. public void show(String msg) throws Exception { Functions.showMessage(msg+"
"); } public void log(String msg) throws Exception { Logger.info(msg, "YourClass"); } public void debug(String msg) throws Exception { show(msg); log(msg); }
/**
* CALLED FROM THE PLATFORM (hence the Parameters argument)
*/
public void doSomething(Parameters p) throws Exception
{
try {
//Record incoming parameters in the log
//log( "Method params:\n"+ p.toString().replace(",","\n") );
String objectID = p.get("object_id");
String recordID = p.get("id");
// Define the parameters for some operation
Parameters params = Functions.getParametersInstance();
params.add("key", "value");
//...
// Do it.
// Result.getCode() >= 0 on success, -1 on failure
Result r = Functions.doSomething(params);
if (r.getCode() < 0) {
// Display message to user, add an entry to debug log, and
// roll back the current transaction (no changes are committed).
String msg = "Error <doing something>:\n"+ r.getMessage();
Functions.throwError(msg);
}
debug("Success");
} catch (Exception e) {
String msg = e.getMessage() + "\n methodName(): "+e.getClass().getName();
log(msg);
Functions.throwError(msg);
}
}
/**
* CALLED INTERNALLY(a utility function of some sort)
*/
public String getSomeValue(String x) throws Exception
{
try {
...
} catch (Exception e) {
String msg = e.getMessage() + "\n methodName(): "+e.getClass().getName();
Functions.throwError(msg);
}
}
/**
* UNIT TEST. (Note the @TestMethod pragma)
*/
@TestMethod
public void test1_DescribeTheTestHere() throws Exception
{
String expect = "some result";
String actual = methodThatReturnsSomeResult();
RunTest.assertEquals(expect, actual);
}
} // end class </syntaxhighlight>
Best Practice:
- Wrap code in a try..catch block, to guard against unexpected exceptions. (If not caught, they are simply ignored, and the method fails silently.)
- When you detect an error, put a detailed message into the Debug Log. Then call Functions.throwError to generate an exception, display a message for the user, and roll back the current transaction.
Accessing Incoming Parameters
- A Java method is always invoked in the context of some record. The method signature is therefore required to have take a Parameters argument, which contains the record fields, along with additional parameters.
- Learn more:
Using Object Names and IDs
- Most APIs take either object name or object ID. (Only a few require object ID.)
- For most operations you'll know which object you're operating on, so you'll specify the object name in a string.
- But the object ID is also available in the incoming Parameters, when you need it.
- Learn more: