Configure SCA JMS binding wire formats

We can configure the messaging data formats between an SCA application and a JMS producer or consumer, by configuring your SCA application to take advantage of a supported message type and data format.

Configure the JMS binding for the SCA application.

JMS producers and consumers use a variety of message types to hold application data payloads. We can use the JMS BytesMessage, ObjectMessage, or TextMessage message types. In some cases, the TextMessage message type might be expected to contain additional structure such as application data in serialized XML format.

Wire format describes the format of the data that is on the wire. For the SCA JMS binding, the wire format is the format of the data in the JMS message that flows through the JMS provider. Because of the variety of message types and formats, SCA services and references configured with a JMS binding might require additional configuration so that the runtime environment can perform the marshalling and unmarshalling required to translate between application data formats and the format of the JMS message on the wire. The additional configuration of message types is the specification of the wire format for message handling.

Whether you are configuring an SCA service or reference, it is important to recognize if the wire format is previously established by the existing messaging application infrastructure, or if you are selecting the wire format along with the SCA application. If we are starting with an application with a preexisting messaging infrastructure and you are adding the SCA application to this environment, the wire format is likely already determined by the messaging infrastructure. If we are starting with an SCA application and you intend for this application to interact with future JMS message producers or consumers, we can specify the wire format within the SCA application.

For the cases when the wire format is predetermined, it is expected behavior that the wire format enables a natural mapping to the format expected by the preexisting message producers and consumer when dealing with input and non-exception output. However, exception conditions might not be handled according to the convention for the wire format type in the existing messaging application infrastructure. If we want exceptions to flow over the JMS binding, we might need to adjust the producers or consumers interacting with the SCA application over the JMS binding according to the exception handling behavior.

JMS binding wire format is supported for applications coded to both the OSOA and OASIS specifications. Unless otherwise specified, the information in this topic pertains to both OSOA and OASIS applications.

1. Determine if you are using a wire format that is predetermined by the existing messaging infrastructure or if you are starting with an SCA application and defining the message wire format.

2. Determine the message type to use for the wire format.

   See Supported message types for SCA JMS binding wire formats.

3. For a wire format predetermined by the existing messaging infrastructure, add the corresponding wire format element into the composition definition file.

4. Ensure that the SCA service and service client implementation and interfaces map appropriately for the specific wire format selecteded.

5. Optional. If we want exception checking to occur over the JMS binding, ensure that the JMS producer and consumer that is interoperating with the SCA application follows the SCA JMS binding exception handling procedures described previously.

6. If we are starting with an SCA application and defining the message infrastructure, add the appropriate wire format element into the composition definition file, and ensure that the future JMS producer or consumer applications understand how to interoperate with this message data format.

Results

You have configured the messaging data format between an SCA application and a JMS producer or consumer.

Examples of configuring SCA JMS binding wire formats

The following examples illustrate the configuration of composite definition files using the various wire format schemes. Component references are configured in an analogous manner

TextMessage with serialized XML wire format that maps data using JAXB

This example illustrates the TextMessage with serialized XML wire format that maps data using JAXB, which is the default wire format:

OSOA

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"      targetNamespace="http://test/soa/sca/"      xmlns:ts="http://tuscany.apache.org/xmlns/sca/1.0"      name="JBC">
       <component name="JAXBComponent">
        <implementation.java class="test.backend.HelloWorldJAXBBackendImpl" />          <service name="HelloWorldJAXBService">            <interface.wsdl interface="http://test.hello#wsdl.interface(HelloWorld)"/>
          <binding.jms>               <destination name="jms/Request1" type="queue" create="never"/>              <activationSpec name="jms/AS1"/>              <response>                <destination name="jms/Response1" type="queue" create="never"/>                <connectionFactory name="jms/CF" create="never"/>              </response>             <!-- No wire format element is necessary, the default is used. -->           </binding.jms>
      </service>      </component>
</composite>

OASIS

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"      targetNamespace="http://test/soa/sca/"      xmlns:ts="http://tuscany.apache.org/xmlns/sca/1.1"      name="JBC">
       <component name="JAXBComponent">
        <implementation.java class="test.backend.HelloWorldJAXBBackendImpl" />          <service name="HelloWorldJAXBService">            <interface.wsdl interface="http://test.hello#wsdl.interface(HelloWorld)"/>
          <binding.jms>
            <!-- No wire format element is necessary, the default is used. -->
            <destination jndiName="jms/Request1" type="queue" create="never"/>              <activationSpec jndiName="jms/AS1"/>              <response>                <destination jndiName="jms/Response1" type="queue" create="never"/>                <connectionFactory jndiName="jms/CF" create="never"/>
            </response>           </binding.jms>
      </service>      </component>
</composite>

ObjectMessage wire format that maps to the java.lang.Object class

This example illustrates the ObjectMessage wire format that maps to the java.lang.Object class:

OSOA

<component name="SerializableComponent">
    <implementation.java class="test.backend.HelloWorldSerializableBackendImpl"/>
    <service name="HelloWorldSerializableService">
        <interface.java interface="test.HelloWorldSerializableService"/>
        <binding.jms>
          <destination name="jms/Request2" type="queue" create="never"/>            <activationSpec name="jms/AS2"/>            <response>
            <destination name="jms/Response2"/>
            <connectionFactory name="jms/CF" create="never"/>
          </response>
          <!-- The wire format element must appear last in the binding definition                to conform to the OSOA schema. -->
          <ts:wireFormat.jmsObject/>
        </binding.jms>
    </service>
</component>

OASIS

<component name="SerializableComponent">
    <implementation.java class="test.backend.HelloWorldSerializableBackendImpl"/>
    <service name="HelloWorldSerializableService">
        <interface.java interface="test.HelloWorldSerializableService"/>
        <binding.jms>
          <!-- The wire format element must appear first in the binding definition                to conform to the OASIS schema. -->
          <ts:wireFormat.jmsObject/>
          <destination jndiName="jms/Request2" type="queue" create="never"/>            <activationSpec jndiName="jms/AS2"/>            <response>
            <destination jndiName="jms/Response2"/>
            <connectionFactory jndiName="jms/CF" create="never"/>
          </response>
        </binding.jms>
    </service>
</component>

TextMessage wire format that maps to single string messages

This example illustrates the TextMessage wire format that maps to single string messages:

OSOA

<component name="JMSTextBackendComponent">
    <implementation.java class="test.backend.HelloWorldTextBackendImpl" />
    <service name="HelloWorldTextService">
       <interface.java interface="test.HelloWorldTextService"/>
       <binding.jms>
          <destination name="jms/Request3"/>
          <activationSpec name="jms/AS3"/>
          <response>
             <destination name="jms/Response3"/>
             <connectionFactory name="jms/CF" create="never"/>
          </response>
          <!-- The wire format element must appear last in the binding definition                 to conform to the OSOA schema. -->
          <ts:wireFormat.jmsText/>
      </binding.jms>      </service>
</component>

OASIS

<component name="JMSTextBackendComponent">
    <implementation.java class="test.backend.HelloWorldTextBackendImpl" />
    <service name="HelloWorldTextService">
       <interface.java interface="test.HelloWorldTextService"/>
       <binding.jms>
          <!-- The wire format element must appear first in the binding definition                 to conform to the OASIS schema. -->
          <ts:wireFormat.jmsText/>
          <destination jndiName="jms/Request3"/>
          <activationSpec jndiName="jms/AS3"/>
          <response>
             <destination jndiName="jms/Response3"/>
             <connectionFactory jndiName="jms/CF" create="never"/>
          </response>
      </binding.jms>      </service>
</component>

BytesMessage wire format that maps to single byte array messages

This example illustrates the BytesMessage wire format that maps to single byte array messages:

OSOA

<component name="JMSBytesBackendComponent">
    <implementation.java class="test.backend.HelloWorldBytesBackendImpl" />
    <service name="HelloWorldBytesService">
      <interface.java interface="test.HelloWorldBytesService"/>
      <binding.jms>
        <destination name="jms/Request4"/>
        <activationSpec name="jms/AS4"/>
        <response>
          <destination name="jms/Response4"/>
          <connectionFactory name="jms/CF" create="never"/>          </response>          <!-- The wire format element must appear last in the binding definition              to conform to the OSOA schema. -->
        <ts:wireFormat.jmsBytes/>        </binding.jms>
    </service>  </component>

OASIS

<component name="JMSBytesBackendComponent">
    <implementation.java class="test.backend.HelloWorldBytesBackendImpl" />
    <service name="HelloWorldBytesService">
      <interface.java interface="test.HelloWorldBytesService"/>
      <binding.jms>
        <!-- The wire format element must appear first in the binding definition              to conform to the OASIS schema. -->
        <ts:wireFormat.jmsBytes/>          <destination jndiName="jms/Request4"/>
        <activationSpec jndiName="jms/AS4"/>
        <response>
          <destination jndiName="jms/Response4"/>
          <connectionFactory jndiName="jms/CF" create="never"/>          </response>        </binding.jms>
    </service>  </component>

JMS message wire format that does not extract the message payload and maps to the javax.jms.Message class

This example illustrates the JMS Message wire format that does not extract the message payload and maps to the javax.jms.Message class:

OSOA

<component name="JMSTextBackendComponent">
    <implementation.java class="test.backend.HelloWorldTextBackendImpl" />
    <service name="HelloWorldTextService">
      <interface.java interface="test.HelloWorldTextService"/>
      <binding.jms>
        <destination name="jms/Request4"/>
        <activationSpec name="jms/AS4"/>
        <response>
          <destination name="jms/Response4"/>
          <connectionFactory name="jms/CF" create="never"/>
        </response>          <!-- The wire format element must appear last in the binding definition              to conform to the OSOA schema. -->
        <ts:wireFormat.jmsText/>        </binding.jms>
    </service>
</component>

OASIS

<component name="JMSTextBackendComponent">
    <implementation.java class="test.backend.HelloWorldTextBackendImpl" />
    <service name="HelloWorldTextService">
      <interface.java interface="test.HelloWorldTextService"/>
      <binding.jms>
        <!-- The wire format element must appear first in the binding definition              to conform to the OASIS schema. -->
        <ts:wireFormat.jmsText/>          <destination jndiName="jms/Request4"/>
        <activationSpec jndiName="jms/AS4"/>
        <response>
          <destination jndiName="jms/Response4"/>
          <connectionFactory jndiName="jms/CF" create="never"/>
        </response>        </binding.jms>
    </service>
</component>

Examples of TextMessage messages using JAXB

The following examples illustrate the contents of TextMessage messages produced by using JAXB marshalling in the default wire format. These examples are based on using the bottom-up approach of developing SCA applications starting with a Java interface, rather than the best practice of starting with a WSDL interface, such that the runtime environment generates the WSDL file.

• For a client invoking an SCA reference with the following interface method:

  package com.ibm.test.soa.sca;
  public String getGreetings(String name);

  The binding produces a TextMessage request message with XML payload similar to the following:

  <ns2:getGreetings xmlns:ns2="http://sca.soa.test.ibm.com/">
     <arg0>Mike</arg0>
  </ns2:getGreetings>

  The response message must be a TextMessage with XML payload similar to the following:

  <ns2:getGreetingsResponse xmlns:ns2="http://sca.soa.test.ibm.com/">
     <return>Hello Mike</return>
  </ns2:getGreetingsResponse>

  Similarly, an SCA service bound to a destination, from which TextMessage messages of this format were delivered, requires the same service interface method; for example:

  package com.ibm.test.soa.sca;
  public String getGreetings(String name);

• For a client invoking an SCA reference with the following interface method:

  package com.ibm.test.soa.sca;
  public void getGreeting(FullName name, String string);

  In this example, the FullName type is mapped to Java using JAXB using the following schema definition:

  <schema targetNamespace="http://www.ibm.com/test/soa/sca/"
      elementFormDefault="qualified"
      xmlns=http://www.w3.org/2001/XMLSchema>
       <complexType name="FullName">
        <sequence>          <element name="firstName" type="string"/>          <element name="lastName" type="string"/>        </sequence>
      </complexType>
  </schema>

  The binding produces a TextMessage request message with XML payload similar to the following:

  <ns2:getGreetings xmlns:ns2="http://sca.soa.test.ibm.com/">
     <arg0>Mike</arg0>
  </ns2:getGreetings>

  The response message must be a TextMessage request message with XML payload similar to the following:

  <ns3:getGreeting xmlns:ns3="http://sca.soa.test.ibm.com/"
     xmlns:ns2="http://www.ibm.com/test/soa/sca/">
     <arg0>
          <ns2:firstName>Bob</ns2:firstName>
          <ns2:lastName>Jones</ns2:lastName>
     </arg0>
     <arg1>home</arg1>
  </ns3:getGreeting>

  Similarly, an SCA service bound to a destination, from which TextMessage messages of this format were delivered, requires the same service interface method; for example:

  package com.ibm.test.soa.sca;
  public String getGreeting(FullName name, String string);

Subtopics

• (dist)(zos) Supported message types for SCA JMS binding wire formats
  For a Service Component Architecture (SCA) application that has a Java Message Service (JMS) binding to send and receive messages, the application must use a message type and data format that the JMS binding supports. Supported message types include JMS BytesMessage, ObjectMessage, and TextMessage. The message type to use depends on whether you are configuring an SCA service or reference and whether the JMS wire format of the service or reference is already determined.

• (dist)(zos) Configure JMS binding request and response wire formats
  We can configure the messaging data formats between an SCA application and a JMS producer or consumer, by configuring your SCA application to take advantage of a supported message type and data format. In general, each wire format can map to the service or reference side, and even into serialization and deserialization. As a result, we can configure each service or reference request and response to use different wire formats.

Related tasks

Configure JMS binding request and response wire formats

Use business exceptions with SCA interfaces

Develop SCA services from existing WSDL files

Specify bindings in an SCA environment

Configure the SCA JMS binding

Create wire format handlers

Supported message types for SCA JMS binding wire formats

Service Component Architecture specifications and APIs