Use of 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
.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. Your Java code must be Java 7 compliant.
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.
- Type Java in the Method field of the step.
- 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 Pega Community 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:
Value | Description |
---|---|
filesystem
|
The regular, physical file system (Default) |
resadaptor
|
A Java EE resource adapter |
embedded
|
(Reserved) |
datasource
|
A database accessed through a JDBC Datasource |
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.