Create wire format handlers

We can use a wire format handler to transform data between a Service Component Architecture (SCA) application and the application binding.

This topic assumes that we have an SCA application with a specified binding. The product supports wire format handling for a Java Message Service (JMS) binding.

Unless otherwise specified, the information in this topic pertains to both OSOA and OASIS applications.

We can implement a wire format handler that converts data between an application wire format and a JMS Message wire format used by the JMS destination of a JMS binding.

Creating a wire format handler consists of two main steps:

1. Implement a Java interface that defines the wire format handler.

2. Configure the wire format handler in the composite definition file of the SCA application.

1. Implement the wire format handler interface.

   The wire format handler provides function that transforms one form (source) to another. The result of a transformation is mapped into either object source or JMS message source. The wire format handler must implement the WireFormatHandler interface, which has methods that map into the two source types.

   See the following example wire format handler interface:

   package com.ibm.websphere.soa.sca.wireformat;
    public interface WireFormatHandler {
        /**
     * Transform.
     *    * @param source   *            the source   *    * @return the object   *    * @throws WireFormatHandlerException
     *             the wire format handler exception   */
       public Object transform(Object source)          throws WireFormatHandlerException;
        /**
     * Sets the wire format context.
     *    * @param ctx
     *            the new wire format context   */
       public void setWireFormatContext(WireFormatContext ctx);
        /**
     * Gets the wire format context.
     *    * @return the wire format context   */
       public WireFormatContext getWireFormatContext();}

   In the public Object transform method implementation, the wire format handler transforms data from the source object to a target object. If an error occurs during the transformation, the data handler implementation throws a WireFormatHandlerException.

   The public void setWireFormatContext method implementation sets the runtime context of the wire format handler. The public WireFormatContext getWireFormatContext method implementation gets the runtime context of the wire format handler. Even if we do not intend to use the context object, you must implement these methods.

   The wire format context contains runtime contextual information passed from the caller to the wire format handler. The WireFormatContext interface specifies the runtime context of the wire format handler. Each wire format handler implementation must implement the setWireFormatContext method of the WireFormatContext interface.

   The WireFormatContext class provides a java.util.Map interface where we can set property key and value pairs in the context. The WireFormatContext interface also provides several methods to extract useful information about the current context such as component and service names, invocation types, and the ability to mark exceptions. Refer to the Java documentation for the com.ibm.websphere.soa.sca.wireformat.WireFormatContext interface for a complete list of methods.

2. Configure the wire format handler in the SCA composite definition file.

   Configure a wire format handler consists of specifying the configuration properties at authoring time and then accessing the configuration properties at run time. Update the composite definition file of the SCA composite to instruct the component to use the wire format handler class; for example:

   OSOA

   xmlns:fep="http://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
    <component name="Account">
     <implementation.java class="helloworld.AccountComponent"/>
     <service name="Account">
       <binding.jms>
         <destination ...>
         <response>
           ...
         </response>
         <fep:wireFormat.jmsCustom class="helloworld.custom.FirstWFH"/>
       </binding.jms>
     </service>
   </component>

   OASIS

   xmlns:fep="http://www.ibm.com/xmlns/prod/websphere/sca/1.1"
    <component name="Account">
     <implementation.java class="helloworld.AccountComponent"/>
     <service name="Account">
       <binding.jms>
         <fep:wireFormat.jmsCustom class="helloworld.custom.FirstWFH"/>
         <destination ...>
         <response>
           ...
         </response>
       </binding.jms>
     </service>
   </component>

What to do next

Deploy the SCA application and test its behavior.

Subtopics

• (dist)(zos) 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.

Related tasks

Specify bindings in an SCA environment

Wire format handler errors