The core pieces of the Oracle ATG Web Commerce RPC API architecture are:
atg.integrations.Command
interface – generic representation of a commandatg.integrations.CommandHandler
interface – executes a command, and performs pre- or post-processingatg.integrations.CommandResult
class – encapsulates the results of a command
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:
If the
Command
points to aCommandHandler
(that is, if theCommand.commandHandler
property is not null), pass theCommand
and its input to thatCommandHandler
by calling theCommandHandler.executeCommand()
method.If the
Command
does not point to aCommandHandler
, call theCommand.invokeRPC()
method.
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:
If the
CommandHandler
points to anotherCommandHandler
(that is, if theCommandHandler.nextCommandHandler
property is not null):Perform any preprocessing.
Pass along the
Command
and its input to the nextCommandHandler
by callingCommandHandler.getNextCommandHandler().executeCommand()
.Perform any post-processing.
If the
CommandHandler
does not point to anotherCommandHandler
:Perform any preprocessing.
Execute the
Command.invokeRPC()
method.Perform any post-processing.
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:
Examine the command to determine if it is in the cache.
If the command is in the cache, return the cached result.
If the command is not in the cache, execute the command, return the result, and cache the command and result.
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:
The
result
property is ajava.lang.Object
that is the actual object returned by the remote call.The
context
property is ajava.util.Map
that can be used to store additional parameters and their values.
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.