Controller command programming model

The abstract class and interface are both found in the com.ibm.commerce.command package.

The following diagram illustrates the relationship between the implementation class and interface of a new controller command with the existing abstract implementation class and interface.

A new controller command should extend the abstract controller command class ( com.ibm.commerce.command.ControllerCommandImpl). When writing a new controller command, you should override the following methods from the abstract class:

isGeneric()

In the standard WebSphere Commerce implementation there are multiple types of users. These include generic, guest, and registered users. Within the grouping of registered users there are customers and administrators.

The generic user has a common user ID used across the entire system. This common user ID supports general browsing on the site in a manner that minimizes system resource usage. It is more efficient to use this common user ID for general browsing, since the Web controller does not need to retrieve a user object for commands that can be invoked by the generic user.

The isGeneric method returns a Boolean value which specifies whether the command can be invoked by the generic user. The isGeneric method of a controller command's superclass sets the value to false (meaning that the invoker must be either a registered customer or a guest customer). If your new controller command can be invoked by generic users, override this method to return true.

You should override this method to return true if your new command does not fetch or create resources associated with a user. An example of a command that can be invoked by a generic user is the ProductDisplay command. It is sensible to allow any user to be able to view products. An example of a command for which a user must be either a guest or registered user (and hence, isGeneric returns false) is the OrderItemAdd command.

When isGeneric returns a value of true, the Web controller does not create a new user object for the current session. As such, commands that can be invoked by the generic user run faster, since the Web controller does not need to retrieve a user object.

isRetriable()

The isRetriable method returns a Boolean value which specifies whether the command can be retried on a transaction rollback exception. The isRetriable method of the new controller command's superclass returns a value of false. You should override this method and return a value of true, if your command can be retried on a transaction rollback exception.

An example of a command that should not be retried in the case of a transaction exception is the OrderProcess command. This command invokes the third party payment authorization process. It cannot be retried, since that authorization cannot be reversed. An example of a command that can be retried is the ProductDisplay command.

setRequestProperties(com.ibm.commerce.datatype.TypedProperty reqParms)

The setRequestProperties method is invoked by the Web controller to pass all input properties to the controller command. The controller command must parse the input properties and set each individual property explicitly within this method. This explicit setting of properties by the controller command itself promotes the concept of type safe properties.

validateParameters()

The validateParameters method is used to do initial parameter checking and any necessary resolution of parameters. For example, it could be used to resolve orderId=*. This method is called before both the getResources and performExecute methods.

getResources()

This method is used to implement resource-level access control. It returns a vector of resource-action pairs upon which the command intends to act. If nothing is returned, no resource-level access control is performed.

performExecute()

The performExecute method contains the business logic for our command. It should invoke the performExecute method of the command's superclass before any new business logic is executed. At the end, it must return a view name.

Related concepts
WebSphere Commerce functional overview
Long-running controller commands

Related tasks
Customizing existing controller commands