Java Class Template

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

<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.
  public void show(String msg) throws Exception { Functions.showMessage(msg); }
  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 </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.

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 of Parameters

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

<syntaxhighlight lang="java" enclose="div">

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