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.)

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.