HowTo:Classes, APIs, and Naming Conventions
From LongJump Support Wiki
HowTo:Classes, APIs, and Naming Conventions
For: Developers See more: |
This guide provides background information that is useful for Java developers, going forward.
Contents |
Uses for Java Classes
Java classes and the methods they contain provide powerful functionality as Page controllers, but they can be used in other ways, as well:
Data Policies
You can use Data Policies to send email or update a record, among other things. You can also use a Data Policy to execute Java code.
- Pre-processing
- A pre-processing policy executes before the trigger event has taken place, allowing you to:
- Validate data - Do sophisticated validation of incoming, throwing an exception to prevent invalid data from getting into the system.
- Mask Data - Intercept outgoing data before it is delivered, replacing the first several digits of a social security numbers with X's, for example. (Note: When masking data, it is important to execute the data policy on both List-display and record-display events.)
- Post-Processing
- A post-processing policy executes after the event has taken place. For example, after a record has been added to the system, you might use it's contents to update other records in the system.
Handlers
- Custom Email Handlers
- With a custom Email Handler, you intercept email messages sent to a special platform address, and process them however you need to.
- Learn more: HowTo:Handle Incoming Emails Programmatically
- Custom Package Data Handlers
- When a Package is created, it contains the skeleton for the database Objects that are included in the package. No data is included. In cases where data is needed, you can create a Package Data Handler with two methods defined by the interface. One tells the platform which data to include when a package is created. The other tells the platform what to do with the data when the package is installed.
- Learn more: HowTo:Create a Data Handler to Add Data to a Package
Invoking Java APIs
- Ninety-nine percent of the time, the Java APIs you invoke will be from com.platform.api.Functions class.
- Most APIs take an incoming com.platform.api.Parameters
- A Controller class creates a new Parameters instance, and can easily add all incoming HashMap arguments to it:
- execute(HashMap valueMap) {
- ...
- Parameters params = Functions.getParametersInstance();
- params.add(valueMap);
- execute(HashMap valueMap) {
- Most APIs return a com.platform.api.Result object:
- That object contains a list of Parameters objects (generally, records returned by a search)
- Loop on the ParametersIterator to process all of the results, or just grab the first one:
- <tt>ParametersIterator it = result.getIterator();
- Parameters result_params = it.next();
- Since a Page takes a HashMap as an argument, a controller class is generally in the business of converting Result object values into the form the Page expects.
Learn more:
Naming Conventions
Naming conventions help to prevent confusions. Names are "handles" you use to mentally manipulate concepts. Here are some suggested conventions to help keep your thinking straight:
- valueMap - HashMap instance passed to a Page
- page_control - passed to a Page in a valueMap
- params - Parameters instance passed to an API
- page_action - passed from a Page in the params
- result - Result values passed back from an API (results is another possibility, since the value that comes back is actually a list.)
- result_params - a Parameters object from the list (result is another possibility.)