Client library exceptions

Client library exceptions consist of one or more instances of the ClientError object.

Handling client library exceptions

When the client library throws an exception, the exception contains one or more instances of the ClientError object. The component exception is always an extension of AbstractBusinessObjectDocumentException and contains a list of these client error objects, each error representing an invalid input statement.

The following sample code illustrates how to retrieve the localized message, error message key, and error code from the client errors from a client library exception (the variable e in the first line):

List listErrors = e.getClientErrors();
  if (listErrors != null) {
   for (int i=0; i < listErrors.size(); i++) {
    ClientError clientError = (ClientError) listErrors.get(i);
    System.out.println("Message: " +
clientError.getLocalizedMessage(Locale.ENGLISH));
    System.out.println("Error key: " + clientError.getErrorKey());
    System.out.println("Error code: " +
clientError.getErrorCode());
   }
  }

Throwing client library exceptions

The client library builds Service Data Objects (SDO) objects based on input parameters. Because SDO objects are Java objects, some validation is required on the client side to ensure proper typing. This exception handling cannot be avoided on the client, especially for the map-based methods to handle Web requests. When the client is preparing the request message, it has to return its exception to represent the parameter error. On the client side you need to check for missing parameters that are needed to create the SDO, before calling out to a service.

To create a client error, you need to pass:

• the error type

• message key

• the parameters used to format the appropriate message

• the resource bundle name.

The error type indicates the type of error and the message key will be something that uniquely identifies the problem. The other parameters are the parameters to pass to the message and the last is the resource bundle name. As shown in the coding example below, this is how to instantiate an object. Note the second parameter messageKey. It clearly identifies the problem is the order Id has an invalid value. So if the customer wants to change this message, they do not need to do a lot of additional checking.

The client library provides a default message for each error that might happen. Each service module uses the properties file associated with its logger to contain the client-friendly messages. This property file is in the MyServiceModule-Client project under the com.ibm.commerce. component.facade.logging.properties package.

ClientError clientError = new
ClientError(ClientError.TYPE_INVALID_PARAMETER_VALUE,
"INVALID_PARAMETER_VALUE_ORDER_ID", new Object[] { "orderId", "abc"
}, LOGGER.getResourceBundleName());
exception = new OrderException(null);
exception.addClientError(clientError);
//add more client errors if necessary
throw exception;

Two types of exceptions can be thrown:

Application exceptions

An application exception is a component typed exception used to signal business events, such as invalid parameters. The component explicitly declares the application exceptions it can throw. This application exception extends an abstract application exception class to match a structure that matches the exception information to be included with the BOD responses. On instantiation, the corresponding message is logged as INFO message.

System exceptions

A system exception is an unchecked exception that the client does not need to catch explicitly. These system exceptions indicate an underlying failure (code defect, connection problems, unrecoverable fault) that the framework, not the component, would handle. If components want to throw system exceptions, they should extend the new abstract system exception class for common logging and other quality of service. On instantiation, the corresponding message is logged as SEVERE message, but a generic system error response is reported back to the user.

Related concepts
Service Data Objects (SDO)
Client library for WebSphere Commerce services
WebSphere Commerce services error information

Related tasks
Creating the client library
Deploying the client library