Java Class Template

Use this class as a template for a class that accesses record data and uses it to perform some operation.

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.
   public void show(String msg) throws Exception { Functions.showMessage(msg+"<br>"); }
   public void log(String msg) throws Exception { Logger.info(msg, "Your Class"); }
   public void debug(String msg) throws Exception { show(msg); log(msg); }

   public void doSomething(Parameters p) throws Exception
   {
      try {
         debug("Started");
         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 = "Something failed";
            log(msg);
            Functions.throwError(msg + "\n" + r.getMessage() );      
         }  
         debug("Success");
      } catch (Exception e) {
         // Catch surprises, display a popup, and put them in the log.
         String msg = "Unexpected exception";
         log(msg + ":\n" + e.getMessage() );
         Functions.throwError(msg + " - see debug log");      
      }
   }
} // 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.

Additional Notes:

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

• List incoming parameters

• Add this line to the code above to put a complete list of incoming parameters into the debug log:

// Generate a newline-separated list of parameters
debug( p.toString().replace(",", ",\n") );