Using Java in an activity step

Most activities can be defined by using only methods and instructions. Some activities require inline Java.

Reviewing generated Java

Activities run as server-side Java, so you can include custom Java statements within your activities. However, experience with designing, coding, and testing Java is required.

When you save an activity, the system validates Java code from information in the form and in other rule instances. This generated Java is read-only. To review the generated Java code, select Actions > View Java.

The window provides a preview of the Java that implements this rule instance. The Java code presented is similar to but not identical to the Java that executes at run time, which includes inline Java code from other rule instances and reflects rules in the requestor's RuleSet list.

The first time a requestor session selects this activity for execution, the rules assembly occurs again, generating and compiling Java that is specific to the RuleSet list and other context of that requestor. The next execution of the same execution by that requestor, or other requestors with identical access, does not require assembly or compilation.

The Java instruction

To run your custom Java within the generated Java for an activity, add inline Java into an activity step. (These are known as Java steps.)

Inline Java steps can introduce complex processing into your application. Use this facility only when necessary. Following the SmartBuild guardrails, avoid Java steps when other approaches can achieve the same computational result. Activities containing a Java step are flagged with a warning message when you save the Activity form, and when you run the Guardrails tool.

1. Type Java in the Method field of the step.
2. Click the Expand icon to expand the Method field. A text box appears in which you can enter normal Java code and the Pega Platform -specific Java.

Your Java code can use two sources of the Pega Platform -specific Java:

• Functions defined through the Rule-Utility-Function rule type (See About Function rules )
• Java methods defined in the Pega Platform PublicAPI

In addition, your Java can call methods and functions in external libraries, if all these conditions are true:

• The JAR file for the library is in the proper directory of the application server.
• The name is included in the class path.
• The Java classes are loaded.

See the PDN article About the Process Commander class paths. Consider Connect JAVA rules or Connect EJB rules as alternatives to Java steps.

Because the Java you write in an activity step is inline Java, you cannot import your Java libraries or add Java import statements. However, you can refer to Java classes using a fully qualified class name.

For example, the Pega Platform cannot accept the following code:

Vector x = new Vector();

However, you can specify:

java.util.Vector x = new java.util.Vector();

Use the String.equals() Java method, not the == or != operators, to compare the value of a property to a literal string or to the value of another property.

Use the Loop button to identify the iteration of the Steps array. See Activity form - Completing the Steps tab - Entering loops.

Calling PublicAPI Java methods

For a complete list of available PublicAPI Java methods, consult the Public Javadoc API documentation. By convention, the tools variable identifies the PublicAPI class.

For example, the Java methods getProperty() and setProperty() get and set property values on a page. Similarly, the Java methods getParameterValue() and setParameterValue() get and set parameter values:

• getProperty(string prop_ref)
• setProperty(string dict_ref, string value)
• getParameterValue(string param_name)
• setParameterValue(string param_name, string value)

In many cases, your Java code needs to reference variables defined in the Java generated for a step. For example, the generated Java often uses the variable myStepPage to refer to the current step page. (The step page must be on the clipboard before the Java step starts.)

Your Java activity step can access Pega Platform facilities, using the classes and interfaces in the com.pega.pegarules.pub.* packages.

For example, the following PublicAPI Java methods are part of the ClipboardProperty interface to the com.pega.pegarules.pub.clipboard package:

• public ClipboardProperty getProperty(java.lang.String propertyreference)
• public boolean ClipboardProperty setValue(ClipboardProperty avalue)

Calling function rules

In addition to the normal Java libraries, your Java step can call functions in the Rule-Utility-Function class. This class contains functions ( Rule-Utility-Function rule type), organized into libraries ( Rule-Utility-Library rule type).

Each function rule belongs to a RuleSet. To call a function rule from a Java step, refer to each library by its RuleSet and library name. For example, a standard library named String is defined in the Pega-RULES RuleSet. To reference this library in your Java, use this syntax:

pega_rules_string.

After the dot, enter the name of the String library function using exact case, and any required parameters:

pega_rules_string.equalsIgnoreCase ("ABC123DEF", pyWorkPage.Account);

Reserved variable names

Certain variables have assigned purposes and are reserved. See Activity rules — Reserved names for parameters and local variables.

Java EE enterprise support

In many cases, a Java EE application cannot directly access the file system on the application server. To allow customers to prepare for this capability, the PublicAPI contains Java classes that mimic many features of java.io facilities. Together, these are known as the Virtual File Interface.

The com.pega.pegarules.pub.util Package contains these classes:

• PRFile class — Mimics a subset of methods in java.io.File
• PRInputStream — Emulates java.io.InputStream
• PROutputStream class — Emulates java.io.OutputStream
• PRReader class — Emulates java.io.Reader
• PRWriter class — Emulates java.io.Writer

Consult the PublicAPI Javadoc documentation for details on these Java classes.

In Web tier deployments of Pega Platform, these facilities operate the same as the corresponding java.io facilities.

In e-tier deployments, operation of file access depends on the following Dynamic System Setting:

Dynamic System Setting: prconfig/storage/class/default

The prconfig/storage/class/default setting provides the configuration for the storage mechanisms, as well as the mapping between the resource types and those mechanisms.

The following values are valid for this Dynamic System Setting:

Checking for security issues

As a best practice for activities that contain hand-crafted Java, run the Rule Security Analyzer to check for code that may expose your application to security vulnerabilities.

Checking status

Technically, the text Java in the Method column does not reference a Pega Platform method. But like methods, the Java instruction updates the pxMethodStatus property. See How to test method results using a transition.

Methods and instructions by function