Implementing the Action Interface
The <action-class> tag above contains the class name of the atg.process.action.Action implementation that is invoked when your custom action occurs in a scenario. The Action interface refers to several other classes and interfaces. At a minimum, familiarize yourself with the following interfaces/classes before implementing your action:
atg.process.expression.Expression
atg.process.action.Action
atg.process.action.ActionImpl
atg.process.ProcessExecutionContext
The Expression interface represents an expression as described above (for example, “Person’s age,” or the value “249”). An Expression can be evaluated using a ProcessExecutionContext. Thus, the expression “Person’s age” returns the age in the current profile when evaluated against the current scenario execution context. You can also query the ProcessExecutionContext explicitly for the current user profile, request, and so on (see an example of this below).
The Action interface has an initialize method that is called when the action is first created. This method takes a Map of parameters. The keys in the Map are the String parameter names; the values are the Expression objects representing parameter values. The initialize method should store these parameter expressions for later evaluation. For example, suppose you create a scenario that contains a LogAction, with parameters configured as follows: logString is simply the string “this is a test,” and logInteger is the expression “Person’s age.” When the scenario is created, the action’s initialize method is called with a Map which contains two key/value pairs: "logString"/Expression, representing the string “this is a test,” and "logInteger"/Expression, representing “Person’s age.”
When the action is executed on a particular user or collection of users, one of its execute methods gets called. The first version of the execute method takes a ProcessExecutionContext. The action may use this context object to evaluate its parameter Expressions, or it may obtain information directly from the context (for example, the context contains the current DynamoHttpServletRequest, which can be used to evaluate any Nucleus expression, among other things).
The second version of the execute method takes an array of ProcessExecutionContext objects. It is called when several scenario instances are traveling through the scenario at the same time; typically, it just calls the first version of the method for each of the given context objects.
The class atg.process.action.ActionImpl is an abstract Action implementation that is provided to make implementing simple actions easier. It provides methods for storing, retrieving, and evaluating parameter Expressions so you do not have to re-implement the same logic for each action. It also implements both versions of the execute method in terms of an abstract method, executeAction, which takes a single ProcessExecutionContext. Thus, to implement your action, you need to implement only the methods initialize and executeAction.
The LogAction example below inherits from ActionImpl and demonstrates its use. In its initialize method, it uses the method storeRequiredParameter to store the Expressions for parameters logString and logInteger. Then, in the executeAction method, it uses the method getParameterValue to evaluate the parameter expressions and print them out. In addition, the test action prints out all of the values available from the context.
package test.scenario;
import java.util.Map;
import atg.servlet.DynamoHttpServletRequest;
import atg.process.ProcessExecutionContext;
import atg.process.ProcessException;
import atg.process.action.ActionImpl;
/**
* Custom scenario action that logs its parameters.
*
* @version $Revision$
**/
public class LogAction extends ActionImpl {
//-------------------------------------
// Constants
//-------------------------------------
/** parameter: logString **/
public static final String PARAM_LOG_STRING = "logString";
/** parameter: logInteger **/
public static final String PARAM_LOG_INTEGER = "logInteger";
//-------------------------------------
// ActionImpl overrides
//-------------------------------------
//-------------------------------------
/**
* Initializes the action with the given parameters. The keys in
* the parameter Map are the String parameter names; the values are
* the Expression objects representing parameter values.
*
* @exception ProcessException if the action could not be properly
* initialized - for example, if not all of the required parameters
* are present in the Map
**/
public void initialize(Map pParameters)
throws ProcessException
{
storeRequiredParameter(pParameters, PARAM_LOG_STRING, String.class);
storeRequiredParameter(pParameters, PARAM_LOG_INTEGER, Integer.class);
}
//-------------------------------------
/**
* Executes this action in the given single process execution
* context. Called by both of the execute methods.
*
* @exception ProcessException if the action can not be executed
**/
protected void executeAction(ProcessExecutionContext pContext)
throws ProcessException
{
// Get our request so that we can log stuff.
DynamoHttpServletRequest request = pContext.getRequest();
// use the context to evaluate the action's parameters
String str = (String) getParameterValue(PARAM_LOG_STRING, pContext);
Integer num = (Integer) getParameterValue(PARAM_LOG_INTEGER, pContext);
request.logInfo("string value = " + str);
request.logInfo("integer value = " + num);
// the following objects are available from the context
request.logInfo("scenario instance = " + pContext.getProcessInstance());
request.logInfo("subject = " + pContext.getSubject());
request.logInfo("message = " + pContext.getMessage());
request.logInfo("request = " + request);
request.logInfo("response = " + pContext.getResponse());
}
//-------------------------------------
}
