The core pieces of the Oracle Commerce Platform RPC API architecture are:

To implement the RPC API, you create classes that implement the Command or CommandHandler interface, and return CommandResult objects. This section discusses the expected behavior of these classes. Note that some of this behavior is not enforced by the interfaces, but is nonetheless required by the API.

For additional information about Command, CommandHandler, and CommandResult, see the ATG Platform API Reference.

Command Interface

The atg.integrations.Command interface is a generic representation of a command. You create specific commands by implementing this interface.

The Command interface has two methods for executing commands, execute() and invokeRPC(). Both of these methods take a java.lang.Object as input (to be as generic as possible), and return a CommandResult. The execute() method is the one actually called by an application. Invoking this method sets off a chain of actions that ultimately results in the invokeRPC() method being executed. The invokeRPC() method does the actual work of making a call to the remote system. Note, however, that applications should not call this method directly, as the processing of commands is based on the assumption that execute() is called first.

The Command.execute() method must implement the following logic:

CommandHandler Interface

The atg.integrations.CommandHandler interface is a generic representation of a handler class for preprocessing and post-processing commands. Command handlers are not a required part of the RPC API, since a Command.execute() method can call the corresponding Command.invokeRPC() method directly. However, command handlers add a great deal of power and flexibility to the RPC system.

To pass a Command and its input to a CommandHandler, the Command.execute() method calls the CommandHandler.executeCommand() method. The CommandHandler.executeCommand() method must implement the following logic:

This logic allows command handlers (and the services they implement) to be chained together. The final CommandHandler in the chain must be able to call the Command.invokeRPC() method, to ensure that the command can be executed. However, it is not required that the command is always executed. For example, one typical use for a command handler is caching of commands and their results. Such a command handler might work like this:

CommandResult Class

When a Command or CommandHandler object executes a Command, it must return a CommandResult. A CommandResult is just a container that has two other objects as properties:

Application code should access the results in the result object by using the DynamicBeans API. For example, suppose the RPC call adds two integers and stores the result as an integer named sum. The application code could obtain the value of sum like this:

Integer sum = (Integer)
 DynamicBeans.getPropertyValue(getCommandResult.getResults(),"sum");

The DynamicBeans API is recommended because it eliminates the need to convert the object returned from the transport RPC into a generic data format, which requires additional memory and processing time. For example, if a query returns a DOM object, the DynamicBeans API can be used to access the data directly from it, avoiding the need to copy the properties from the DOM object to another object type (such as a Map).

RPC implementations are not required to use the context Map. It is included in the CommandResult object to provide a way to store additional information that is not part of the result object.