Command error handling

Command error handling

WebSphere Commerce uses a well-defined command error handling framework that is simple to use in customized code. By design, the framework handles errors in a manner that supports multicultural stores. The following sections describe the types of exceptions that a command can throw, how the exceptions are handled, how message text is stored and used, how the exceptions are logged, and how to use the provided framework in our own commands.

Types of exceptions

A command can throw one of the following exceptions:

ECApplicationException

This exception is thrown if the error is related to user input and will always fail. For example, when a user enters an invalid parameter, an ECApplicationException is thrown. When this exception is thrown, the solution controller does not retry the command, even if it is specified as a retriable command.

ECSystemException

This exception is thrown if a runtime exception or a WebSphere Commerce configuration error is detected. Examples of this type of exception include create exceptions, remote exceptions, and other EJB exceptions. When this type of exception is thrown, the solution controller retries the command if the command is retriable and the exception was caused by either a database deadlock or database rollback.

Both of the preceding listed exceptions are classes that extend from the ECException class, which is found in the com.ibm.commerce.exception package.
In order to throw one of these exceptions, the following information must be specified:
Error view name

The view that will be used to display the error. For Web requests, the Web controller looks up this name in the Struts configuration files.

ECMessage object

ECMessage defines the static information related to the reason for the exception. This value corresponds to the message text contained within a properties file.

ECParameter

ECParameter returns the errors associated with the application. The exception can indicate multiple errors since each part of an application exception represent an error.

Error parameters

These name-value pairs are used to substitute information into the error message. For example, a message may contain a parameter to hold the name of the method which threw the exception. This parameter is set when the exception is thrown, then when the error message is logged, the log file contains the actual method name.

Error data

These are optional attributes that can be made available to the JSP page through the error data bean.

Exception handling is tightly integrated with the logging system. When a system exception is thrown, it is automatically logged.

Error message properties files

In order to simplify the maintenance of error messages and to support multilingual stores, the text for error messages is stored in the properties files named xxxxSystemMessages_locale.properties or yyyyUserMessages_locale.properties, which are organized in packages named com.ibm.commerce.zzzz.ras.properties. Here, xxxx, yyyy, and zzzz are arbitrary strings.
Two types of messages are defined in the error message properties files: user messages and system messages. User messages are displayed to customers in their browsers. System messages are captured automatically in the message log, user messages are not.
The command context returns an identifier to indicate the language used by the client. When a message is required, the solution controller determines which properties file to use based upon the language identifier.
When an error is thrown, one of the required parameters is a message object. For ECSystemExceptions, the message object must contain two keys, one for the system message and one for the user message. The system message is logged, while the user message is displayed to the customer. For ECApplicationExceptions, the message object contains the key for the user message (system messages are not used).
System messages can be customized and we can create new ones. When customized code throws an ECSystemException, it must specify a message key for one of the predefined system messages or a customized system message. Customized user messages can also be created. New system messages and user messages must be stored in a separate properties file.

Exception handling flow

The solution controller invokes a controller command.
The command throws an exception that is caught by the solution controller. This can be either an ECApplicationException, or an ECSystemException. The exception object contains the following information:

Error view name
ECMessage object
Error parameters
Optional: Error data

For a Web application, the struts framework determines the error global forward found in the struts configuration file and invokes the specified error view. When invoking the command, the solution controller composes a set of properties from the ECException object and sets the error view using the setInputProperties method.
The ErrorDataBean passes the error parameters to the message helper object.
The StoreErrorDataBean maps the error codes to messages.

Exception handling in customized code

When creating new commands, it is important to include appropriate exception handling. We can take advantage of the error handling and messaging framework provided in WebSphere Commerce, by specifying the required information when catching an exception.
Writing our own exception handling logic, involves the following steps:

Catching the exceptions in your command that require special processing.
Constructing either an ECApplicationException or ECSystemException, based upon the type of exception caught.
If the ECApplicationException uses a new message, defining the message in a new properties file.

Catching and constructing exceptions

To illustrate the first two steps, the following code snippet shows an example of catching a system exception within a command:
try {
// your business logic
}
catch(FinderException e) {
     throw new ECSystemException (ECMessage._ERR_FINDER_EXCEPTION, 
          className, methodName, new Object [] {e.toString()}, e); 
}
The preceding _ERR_FINDER_EXCEPTION ECMessage object is defined as follows:
public static final ECMessage _ERR_FINDER_EXCEPTION = 
new ECMessage (ECMessageSeverity.ERROR, ECMessageType.SYSTEM, 
     ECMessageKey._ERR_FINDER_EXCEPTION);
The _ERR_FINDER_EXCEPTION message text is defined within the ecServerMessages_xx_XX.properties file (where _xx_XX is a locale indicator such as _en_US), as follows:
_ERR_FINDER_EXCEPTION  = 
     The following Finder Exception occurred during processing: "{0}".
When catching a system exception, there is a predefined set of messages that can be used. These are described in the following table:

Message Object Description
_ERR_FINDER_EXCEPTION Thrown when an error is returned from an EJB finder method call.
_ERR_REMOTE_EXCEPTION Thrown when an error is returned from an EJB remote method call.
_ERR_CREATE_EXCEPTION Thrown when an error occurs creating an EJB instance.
_ERR_NAMING_EXCEPTION Thrown when an error is returned from the name server.
_ERR_GENERIC Thrown when an unexpected system error occurs. For example, a null pointer exception.

When catching an application exception, we can either use an existing message specified in the appropriate error message properties file, or create a new message stored in a new properties file. As specified previously, we must not modify any of the predefined error message properties files.
The following code snippet shows an example of catching an application exception within a command:
try {
// your business logic

}
// catch some new type of application exception
catch(//your new exception)
 {
     throw new ECApplicationException (MyMessages._ERR_CUSTOMER_INVALID, 
          className, methodName, errorTaskName, someNVPs); 
}
The preceding _ERR_CUSTOMER_INVALID ECMessage object is defined as follows:
public static final ECMessage _ERR_CUSTOMER_INVALID = 
     new ECMessage (ECMessageSeverity.ERROR, ECMessageType.USER, 
     MyMessagesKey._ERR_CUSTOMER_INVALID, "ecCustomerMessages");
When constructing new user messages, you should assign them with a type of USER, as follows:
ECMessageType.USER
The text for the _ERR_CUSTOMER_INVALID message is contained in the ecCustomerMessages.properties file. This file must reside in a directory that is in the class path. The text is defined as follows:
_ERR_CUSTOMER_INVALID = Invalid ID "{0}"
Related concepts
JSP page error handling
Execution flow tracing
Logging and tracing

Related tasks
Creating messages

Related reference
JSP programming best practice: Use the StoreErrorDataBean data bean for error handling

Message Object	Description
_ERR_FINDER_EXCEPTION	Thrown when an error is returned from an EJB finder method call.
_ERR_REMOTE_EXCEPTION	Thrown when an error is returned from an EJB remote method call.
_ERR_CREATE_EXCEPTION	Thrown when an error occurs creating an EJB instance.
_ERR_NAMING_EXCEPTION	Thrown when an error is returned from the name server.
_ERR_GENERIC	Thrown when an unexpected system error occurs. For example, a null pointer exception.