HowTo:Classes, APIs, and Naming Conventions

From AgileApps Support Wiki

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:


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

  • 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();
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 =;
  • 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.)

HowTo:Create a JSP Page and Java Controller