Wire format handler errors

A wire format handler can transform data between a Service Component Architecture (SCA) application and the application binding. This topic discusses the different types of exceptions and errors that can result at run time in an SCA application that uses wire format handlers. The product supports wire format handling for a Java Message Service (JMS) binding.

The information in this topic pertains to both OSOA and OASIS applications.

• Business exceptions

• Runtime exceptions

• Service and reference exceptions

• Exception handling from a wire format handler

Business exceptions

Business exceptions are business errors or exceptions that occur during processing.

A business exception is a checked exception. It inherits from the Exception class. Client code must handle a checked exception in a catch clause or with a throws clause.

When a business exception occurs, a checked exception object results from the service business exception in the SCA application. The object calls the wire format handler configured on the service.

Runtime exceptions

Runtime exceptions are exceptions that occur in the SCA application from processing of a request. Runtime exceptions do not correspond to business exceptions. Unlike business exceptions, runtime exceptions are not defined on the interface.

We can propagate runtime exceptions to the client application so that the client application handles the exceptions. For example, if a client sends a request to create a customer to an SCA application and an authorization error occurs during processing of this request, the SCA component throws a runtime exception. This runtime exception must be propagated back to the calling client so it can act on the authorization request. We can use a wire format handler configured on the reference to propagate runtime exceptions back to the calling client application.

Service and reference exceptions

To handle both business exceptions and runtime exceptions, we can set up exception handling on the application bindings. Handling exceptions on either the reference or service on a binding is optional.

You likely create exception wire format handlers for the most common errors that occur at run time in the application:

• When the exception thrown by the SCA application service must be transformed to a value the client can understand.

• When the incoming exception received on a reference must be transformed to a value the client code can understand.

Exception handling from a wire format handler

An exception handler is a wire format handler. Business and runtime exception handling is done from the wire format handler An exception wire format handler transforms specific exceptions into objects that can be understood by the client application.

Both service and reference bindings can use an exception wire format handler. We can configure an exception wire format handler to do the following:

• Handle runtime exceptions that are received from external applications (reference)

• Send runtime exceptions that have occurred in the SCA application to the external applications (service)

On the service implementation of a wire format handler, the implementation can examine the WireFormatContext.INVOCATION value from the context to find that an exception was thrown. The wire format handler might handle normal invocations and exceptions differently. See the following sample code:

public Message transformIntoJMSMessage(Session session, Object source) 
   throws JMSException, WireFormatHandlerException {

   WireFormatContext.INVOCATION invocationType =
      (WireFormatContext.INVOCATION) context.get(WireFormatContext.INVOCATION_TYPE);

   if (invocationType == WireFormatContext.INVOCATION.TYPE_EXCEPTION) {
      return handleException(session, source); 
   } else if (invocationType == WireFormatContext.INVOCATION.TYPE_RESPONSE) {
      return handleResponse(session, source);
   } else {
      throw new WireFormatHandlerException("Unexpected Invocation Type.");
   }
}

On the reference implementation of a wire format handler, the implementation must determine at run time if the incoming response is of type fault. The WireFormatContext.INVOCATION value must be initially set to TYPE_RESPONSE. The implementation examines incoming messages. When an incoming message is an exception rather than a normal response, the implementation must set the invocation type to TYPE_EXCEPTION and throw an appropriate exception. See the following code sample:

// On Reference-side, this is for an incoming response 
public Object transformFromJMSMessage(Message source)
  throws WireFormatHandlerException {

  ObjectMessage msg = null;
  Object payload = null;
  Object[] payloadArray = null;
  Integer payloadInt = null;
  Object payloadItem = null;

  try {
    msg = (ObjectMessage)source;
  } catch (ClassCastException cce) {
      throw new WireFormatHandlerException("Did not receive ObjectMessage", cce);
  }
  try {
    payload = msg.getObject();
  } catch (JMSException e) {
      throw new WireFormatHandlerException("Cannot get Object from message using getObject()", e);
  }

  if (payload instanceof Integer) {
    // Expected type returned     payloadInt  = (Integer)payload;
    Integer code = new Integer(0);
    Integer one = new Integer(1);
    code = payloadInt + one;
    return code;
  } else { 
    // Response is some type of exception...

    // Change the response type to Exception
    context.put(WireFormatContext.INVOCATION_TYPE, WireFormatContext.INVOCATION.TYPE_EXCEPTION);

    if (payload instanceof Throwable) {
      Throwable thw = (Throwable) payload;

      ////////////////////////////////////////////////////////
      // TO DO: Map to checked business exception and throw it       ////////////////////////////////////////////////////////

    } else {
      return new ServiceRuntimeException(((Throwable) payload).getMessage()); 
      // Unchecked
    }
  } else {
    throw new WireFormatHandlerException("Unexpected Object returned: " + payload); 
    // Unexpected or unknown object returned.
    }
  }
}

Related tasks

Create wire format handlers