HowTo:Classes, APIs, and Naming Conventions

For:   Developers Level: Intermediate Time:  10 minutes See more:     ◾ HowTo Guides

This guide provides background information that is useful for Java developers, going forward.

Uses for Java Classes

In addition to their use as Page "controllers", Java classes and the methods they contain can be used in many other ways:

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

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

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 convert Result object values into the form the Page expects.

Learn more:

• Parameters Class
• Result Class

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

Next

HowTo:Create a JSP Page and Java Controller