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

Java classes and the methods they contain provide powerful functionality as Page controllers, but they can be used in other ways, as well:

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

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