View source for HowTo:Classes, APIs, and Naming Conventions

<noinclude>
{{Orientation | Developers | Intermediate | 10}}
</noinclude>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: 
<blockquote>

====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]]
</blockquote>

===Invoking Java APIs===
:* Ninety-nine percent of the time, the Java APIs you invoke will be from [{{DOCHOST}}/javadocs/com/platform/api/Functions.html com.platform.api.Functions] class.

:* Most APIs take an incoming [{{DOCHOST}}/javadocs/com/platform/api/Parameters.html com.platform.api.Parameters] 

:* A Controller class creates a new Parameters instance, and can easily add all incoming HashMap arguments to it: 
:::<tt>execute(HashMap valueMap) {</tt>
::::<tt>...</tt>
::::<tt>Parameters params = Functions.getParametersInstance();</tt>
::::<tt>params.add(valueMap);

:* Most APIs return a [{{DOCHOST}}/javadocs/com/platform/api/Result.html com.platform.api.Result] object:
::That object contains a ''list'' of Parameters objects (generally, records returned by a search)
::Loop on the [{{DOCHOST}}/javadocs/com/platform/api/ParametersIterator.html ParametersIterator] to process all of the results, or just grab the first one:
:::<tt>ParametersIterator it = result.getIterator();</tt>
:::<tt>Parameters result_params = it.next();</tt>

:* 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 (<tt>results</tt> is another possibility, since the value that comes back is actually a list.)
:* '''result_params -''' a Parameters object from the list (<tt>result</tt> is another possibility.)
<!--
===Wrap Up===
...What you've done....
...List of things you've explored/learned about/played with:
:* ...

:''Learn more:''
::* ...
-->
<br>
;Next:
: [[HowTo:Create a JSP Page and Java Controller]]