Java Class Template
From AgileApps Support Wiki
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.)
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 (<br>) 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+"<br>"); } 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
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.