Classes

> Customization > Developer Resources > Classes

About Classes

Standard Java classes can be used to create business logic that is not provided by the platform's basic building blocks.

A class can be used as a backend controller for a JSP Page. It can be invoked from a Rule, or used to define a custom handler--for example, a Package Data Handler. Or it can provide underlying functionality for such purposes.

You can make Java API calls in the Java code in a class, and you can create instances of classes in Java code.

There are some restrictions on the things you can do in a Java class, as described in Governors on Java Code.

In most cases, a Page communicates with a controller class, and the controller instantiates any other classes that are needed to carry out Page operations. (It is possible to instantiate a class directly in a page, but that is considered a bad practice.)

Considerations

• The Java 6 syntax and feature set are supported in custom classes.
• When pasting code into the online editor, make sure it comes from a plain text editor.

Learn more:

• Classes in the Developer Suite
• Working with Pages and Classes

Working with Classes

From the Classes page, a number of features are provided to view, create and manage classes.

View Classes

1. Click > Customization > Developer Resources > Classes

   Classes are displayed in a View.

2. Use standard Searching and Filtering operations to determine which records are displayed.
3. Use the action buttons:
   • [New Class] - Add a Class
   • [Run All Tests] - Run all Unit Tests defined in the classes

Add a Class

Prerequisite Before you create a class, you need to decide what package to put it in. Here are a few notes to help you make that decision:

• Packages let you organize classes into different directories according to their functionality, their usability, or any other category that makes sense. (The only rule is that classes in one package have a qualitatively different kind of functionality compared with those in another package.)
• Packages help to avoid class name collision. (The same class name can be used in different packages.)
• Classes in the same package can access each others package-protected fields and methods, as well as their public members, without doing an import. So classes that cooperate with each other extensively generally belong in the same package.
• Classes that are part of a different package can be accessed with an import declaration.

To add a class:

1. Click > Customization > Developer Resources > Classes
2. Click [New Class]
3. Fill in the class properties.
4. Click [Next]
   A class template appears.
5. Provide the code for the class.
6. Click [Save]

Class properties

Package

The package name

• The platform supplies this part: com.platform.{namespace},
  where {namespace} is defined in the Developer Configuration settings of the current tenancy.
• You supply this part: {packagename}

The result is the fully-qualified package path for the class: com.platform.{namespace}.{packagename}

Class Name

The name of the class. Must consist of alphanumeric characters (a-z,A-Z,0-9) or underscores (_). Must start with an alphabetic character (a-z,A-Z) or underscore (_).

Java code

Enter Java code in the text area.

Edit a Class

To edit a class:

1. Click > Customization > Developer Resources > Classes
2. Click the name of the class to edit
3. Click [Edit]
4. Edit the Java code in the text area
5. When done, click [Save]

Delete a Class

To delete a class:

1. Click > Customization > Developer Resources > Classes
2. Click the name of the class to delete
3. Click [Delete]

Creating Unit Tests

Any method in a Java class can be a test method, as long as it is tagged with the @TestMethod annotation. Within the test method, use assert statements like this one to compare expected results to actual results: RunTest.assertEquals(expected, actual).

Here's a template for a test method:

/**
 * javadoc comment
 */
@TestMethod
public void testSomeBehavior() throws Exception
{
    String expect = "It's working!";         
    String actual = someBehavior();          // Invoke the method you're testing

    RunTest.assertEquals(expect, actual);
}

See also: Code Sample:Test of Search using Java API

Tip: Give your test methods meaningful names that tell what the test was trying to do. That way, when you're reading a report that identifies a failure, the name will tell you a lot. For example: testTwoPlusTwoEqualsFour.

Considerations

• A single test method can contain multiple assertions.
• Each successful assertion adds to the success count and the count of total tests.
• A test method may contain no assertions at all. In that case, it runs to completion, but the test is not counted as a success.
• A test may fail either because an exception occurs, or because an assertion fails.
• In either case, the message is recorded. (For an exception, a stack trace is also recorded.)
• Whether an assertion succeeds or fails, the method continues running. It is only interrupted by an exception.
• If multiple assertions fail, all of the failure messages are reported.
• If one or more assertions fail, and then an exception occurs, all of the messages are reported, along with the exception.
• The test method (testSomeBehavior, above) must be public. If it isn't, an IllegalAccessException occurs when the @TestMethod annotation causes the Unit Test Framework to attempt execution.
• The RunTest.assertEquals() method takes Strings as arguments (and only Strings).

Important: When running tests, the UI is never affected. So your tests always run to completion without pausing for user interactions, regardless of the code contained in the executed methods. These cases in particular are executed without having any visible effect in the UI: Functions.showMessage - Ordinarily brings up a dialog. setTargetPage in a controller - Ordinarily specifies the next page the user will see. Any request sent from a controller - Ordinarily specifies the controller code or JSP page that will be visited next.

Learn more: Unit Test Framework

Invoke a method in a Java Class

Invoking a Java method lets you use the Java APIs to interact with the platform, and do anything else that you can accomplish using Java code.

Method Signature

You can select any method defined in a Java class, as long as it has the required signature:

public void someMethod(com.platform.api.Parameters inParams)

throws Exception {

...

Considerations

• The incoming parameters are the name/value pairs contained in the Parameters object.
  The most commonly accessed parameters are:

String objectID = inParams.get("object_id");
String recordID = inParams.get("id");

• The throws Exception is not a necessary part of the signature, but is generally required for any method that is doing real work. (If an invoked API generates an exception, the exception percolates back up to the top-level handler, which displays the message.)

• The method can be either a static class method or an instance method. An instance of the object is created before making the call.

• The method must be public, return void, and take a single Parameters argument.

Learn more: Incoming Method Parameters

Example: Validate Incoming Data

In addition to the data validation that is part of every Custom Object, you can use Java methods to do even more sophisticated validation.

In this example, the method ensures that the credit number is in the proper format -- exactly 16 digits, with no characters or spaces. The validation method is designed for the Orders object in the Sample Order Processing System, which has field named credit_card_number. Such a method could be invoked in a Rule Action that is triggered when a new record is created.

This is an important technique for more sophisticated validations. In this case, for example, a credit card number is too big to use a numeric field. The solution is to use a text field, use a data policy to parse the data, and throw an exception in the event of an error.

This code throws an exception if the format isn't valid. The exception will abort the transaction before it is committed.

String ccn_field = "credit_card_number";

public void validate_order(Parameters requestParams)
throws Exception
{
   String errMsg = "Invalid credit card number format. Needs 16 digits.";
   String ccn = (String) requestParams.get(ccn_field);
   if ((null != ccn) && (ccn.length() != 16)) {
       throw new Exception(errMsg);
   }
   for (int i=0; i<=15; i++) {
      char c = ccn.charAt(i);
      if (c < '0' || c > '9') {
         throw new Exception(errMsg);
      }
   }
   // Format validated
   return;
}

Editing Classes in Eclipse

Use the Eclipse Plug-In to add, edit or delete classes.