You can use a wire format handler to transform data between
a Service Component Architecture (SCA) application and the application
binding.
Before you begin
This topic assumes that you 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.
About this task
You can implement a wire format handler that converts
data between an application wire format and a JMS Message wire format
that is used by the JMS destination of a JMS binding.
Creating
a wire format handler consists of two main steps:
- Implement
a Java interface that defines the wire format handler.
- Configure
the wire format handler in the composite definition file of the SCA
application.
Procedure
- 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 you 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 you 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.
- Configure the wire format handler
in the SCA composite definition file.
Configuring 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 your 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 your SCA application and test its behavior.