Configuring the SCA web service binding to transport SOAP messages over JMS (deprecated)

You can configure a Service Component Architecture (SCA) web service binding to transport SOAP messages over Java Message Service (JMS) protocol.

About this task

Web services technology plays an important role in most service-oriented architecture (SOA) solutions relevant today, including SCA. The web service binding type enables SCA applications to expose services as web services to external clients and gives SCA components access to external web services. Using JMS as a transport for web services provides a reliable asynchronous messaging transport for request and response.

The steps describe how to configure a web service binding to flow SOAP messages over JMS.

Note: The web service binding supports Web Services Description Language (WSDL) Version 1.1. Further, the web service binding supports industry standard SOAP/JMS protocol and IBM proprietary SOAP over JMS protocol.

Procedure

Identify and configure JMS resources using the administrative console or the wsadmin scripting tool.
Refer to topics on creating JMS resources based on different JMS providers.

For example, to identify and configure JMS resources based on the default JMS provider, do the following:
1. Create a service integration bus and associate a bus member.
2. Create destinations for the request and response for the service integration bus.
3. Create destinations for the request and response under JMS resources.
4. Create an activation specification that is associated with a request destination.
5. Create connection factories to process the request and to send the response.

Configure an SCA service with an SCA web service binding to transport SOAP messages over JMS.

Configure a web service binding with three additional attributes under the <binding.ws> element to use a JMS transport:

Web service binding endpoint uri attribute
@activationSpec attribute
Response @responseConnectionFactory attribute

Open an editor on the SCA composite definition file that specifies an SCA service with a web service binding.

In the composite definition file, configure the web service binding endpoint uri attribute.

Specify the uniform resource identifier (URI) in SOAP over JMS endpoint uniform resource locator (URL) syntax. A JMS endpoint URL accesses web services with a JMS transport. The URL specifies the JMS destinations, connection factory, and port component name for the web service request.

Specify the URI in syntax that supports either of the following protocols:

Industry standard SOAP/JMS protocol (recommended)
IBM proprietary SOAP over JMS protocol (deprecated)

URI based on industry standard SOAP over JMS protocol

The syntax for a URI based on industry standard SOAP over JMS protocol is as follows:

uri=jms:jndi:<destination_JNDI_name>?<property>=<value>&<property>=<value>& ...

The URL consists of the jms: transport type, followed by the jndi: variant type, followed by the Java Naming and Directory Interface (JNDI) name of the destination queue or topic, followed by the query string containing a list of property and value pairs that specify JMS endpoint information. The jndi: variant means that JNDI is used to locate object names in the endpoint URL string.

For property, you can specify URL properties such as the following:

Table 1. JMS endpoint URL properties typically used for a URI based on industry standard SOAP over JMS protocol. The properties are jndiConnectionFactoryName, targetService, and replyToName.
Property name	Description
jndiConnectionFactoryName	Specifies the JNDI name of the connection factory that is used by the client run time to establish a connection to the JMS messaging engine. jndiConnectionFactoryName is optional for the service `uri` attribute.
targetService	Specifies the target service to which to deliver the message. For a forward call from a service to a reference, targetService has the format `serviceComponentName/serviceName`. In a callback `uri`, targetService has the format `referenceComponentName/referenceName`.
replyToName	Specifies the JNDI name of the JMS destination to which the response message is sent. replyToName is a JMS-related property that enables the client to use a previously defined, permanent queue rather than a temporary queue, for receiving replies.

For a complete list of properties supported, refer to the topic on JMS endpoint URL syntax.

A URI based on industry standard SOAP over JMS protocol resembles the following:

uri="jms:jndi:jms/MyBankAccountService_Request?jndiConnectionFactoryName
 =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response
 &amp;targetService=AccountServiceComponent/AccountService"

URI based on IBM proprietary SOAP over JMS protocol

Deprecated feature: IBM proprietary SOAP over JMS protocol is deprecated.

The syntax for a URI based on IBM proprietary SOAP over JMS protocol is as follows:

uri=jms:/[queue|topic]?<property>=<value>&<property>=<value>& ...

The URL consists of the jms: transport type, followed by either /queue or /topic to specify the JMS destination type, followed by the query string containing a list of property and value pairs that specify the JMS endpoint information.

For property, you can specify URL properties such as the following:

Table 2. JMS endpoint URL properties typically used for a URI based on IBM proprietary SOAP over JMS protocol. The properties are destination, connectionFactory, replyToDestination, and targetService.
Property name	Description
destination	Specifies the JNDI name of the destination queue or topic.
connectionFactory	Specifies the JNDI name of the connection factory. connectionFactory is optional for the service `uri` attribute.
replyToDestination	Specifies the JNDI name to which a response is sent. replyToDestination is optional for the service `uri` attribute.
targetService	Specifies the target service to which to deliver the message. For a forward call from a service to a reference, targetService has the format `serviceComponentName/serviceName`. In a callback `uri`, targetService has the format `referenceComponentName/referenceName`.

For a complete list of properties supported, refer to the IBM proprietary SOAP over JMS protocol topic.

A URI based on IBM proprietary SOAP over JMS protocol resembles the following:

uri="jms:/queue?destination=jms/MyBankAccountService_Request&amp;connectionFactory
 =jms/MyBankAccountService_CF&amp;replyToDestination=jms/MyBankAccountService_Response
 &amp;targetService=AccountServiceComponent/AccountService"

In the composite definition file, configure an @activationSpec attribute under the <binding.ws> element.
The attribute identifies the activation specification that the service uses to connect to the JMS destination and to process incoming request messages.

For the destination associated with this activation specification, specify the request destination defined in the web service binding endpoint uri; for example:
```
soapjms:activationSpec="jms/AccountActivationSpec"
```
Qualify the OSOA SCA composite by setting xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06".

Qualify the OASIS SCA composite by setting xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.1".
In the composite definition file, configure a response @responseConnectionFactory attribute under the <binding.ws> element to send a response back to the client when request-response messaging pattern is used.
For example:
```
soapjms:responseConnectionFactory="jms/Account_Response_CF"
```
Qualify the OSOA SCA composite by setting xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06".

Qualify the OASIS SCA composite by setting xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.1".

After these updates are made to the <binding.ws> element, the OSOA SCA composite definition file resembles:

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="https://www.osoa.org/xmlns/sca/1.0"
 xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
 targetNamespace="https://www.ibm.com/samples/sca/mybank"
 name="MyBank">
  <component name="AccountServiceComponent">
    <implementation.java 
      class="samples.mybank.AccountServiceImpl"/>
    <service name="AccountService">
      <interface.wsdl 
      interface=
          "https://www.mybank.com/account#wsdl.interface(AccountService)" />
      <binding.ws 
          wsdlElement=
            "https://www.mybank.com/account#wsdl.port(AccountService/AccountServicePort)"

          uri="jms:jndi:jms/MyBankAccountService_Request?jndiConnectionFactoryName
              =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response
              &amp;targetService=AccountServiceComponent/AccountService"

          soapjms:activationSpec="jms/MyBankAccountService_AS"

          soapjms:responseConnectionFactory="jms/MyBankAccountService_CF"/>
    </service>
  </component>
</composite>

The OASIS SCA composite definition file is similar except for the namespace prefixes, which are:

xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"
xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.1"

Configure an SCA reference (client) with an SCA web service binding to transport SOAP message over JMS.

Configure a web service binding with a web service binding endpoint uri attribute specific to JMS transport under the <binding.ws> element.

Open an editor on the SCA composite definition file that specifies an SCA reference with a web service binding.
In the composite definition file, configure the web service binding endpoint uri.
Specify the URI in SOAP over JMS endpoint URL syntax. The URL specifies the JMS destinations, connection factory, and port component name for the web service request. A JMS endpoint URL can be based on industry standard SOAP/JMS protocol (recommended) or on IBM proprietary SOAP over JMS protocol. For a description of the URI syntax, see step 2(b). In SOAP over JMS support for web service bindings, you must use the <binding.ws> uri attribute for endpoint resolution to the target component; you cannot use the SCA reference @target attribute.

The URI resembles the following:
```
uri="jms:jndi:jms/MyBankAccountService_Request?jndiConnectionFactoryName
 =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response
 &amp;targetService=AccountServiceComponent/AccountService"
```

After you define the URI in the <binding.ws> element, the OSOA SCA composite definition file resembles:

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="https://www.osoa.org/xmlns/sca/1.0" 
targetNamespace="https://www.ibm.com/samples/sca/mybank" 
name="MyBankClient">
  <component name="AccountSummaryService">
    <implementation.java 
      class="samples.mybank.AccountSummaryServiceImpl"/>
    <reference name="accountService">
    <interface.wsdl 
      interface=
        "https://www.mybank.com/account#wsdl.interface(AccountService)" />
    <binding.ws 
      wsdlElement=
        "https://www.mybank.com/account#wsdl.port(AccountService/AccountServicePort)"

       uri="jms:jndi:jms/MyBankAccountService_Request?jndiConnectionFactoryName
            =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response
            &amp;targetService=AccountServiceComponent/AccountService"/>
    </reference>
  </component>
</composite>

In an OASIS SCA composite definition file, the binding element cannot include both the uri and wsdlElement attributes. You must use one or the other. If you use wsdlElement, the WSDL port definition in the WSDL file specifies the URI as shown in the following example:

<wsdl:service name="AccountService">
  <wsdl:port binding="account:AccountServiceSOAP" name="AccountServicePort">
    <soap:address
      location="jms:jndi:jms/MyBankAccountService_Request?jndiConnectionFactoryName
        =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response
        &amp;targetService=AccountServiceComponent/AccountService"/>
  </wsdl:port>
</wsdl:service>

Results

You have a configured an SCA web service binding service or reference.

Example

Configuring a request-response Message Exchange Pattern for SOAP over JMS

This example describes a <binding.ws> element in the composite definition file for a request-response message exchange pattern from an SCA component reference to an SCA component service.

The following example shows an OSOA SCA component with a reference binding:

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="https://www.osoa.org/xmlns/sca/1.0"
           xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
           targetNamespace="https://www.ibm.com/samples/sca/mybank" name="MyBankClient">
  <component name="AccountSummaryService">
    <implementation.java class="samples.mybank.AccountSummaryServiceImpl"/>
    <reference name="accountService">
      <interface.wsdl interface="https://www.mybank.com/account#wsdl.interface(AccountService)"/>
      <binding.ws
        wsdlElement="https://www.mybank.com/account#wsdl.port(AccountService/AccountServicePort)"
        uri="jms:jndi:jms/MyBankAccountService_Request?jndiConnectionFactoryName
          =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response
          &amp;targetService=AccountServiceComponent/AccountService"/>
    </reference>
  </component>
</composite>

The following example shows an OSOA SCA component with a service binding:

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="https://www.osoa.org/xmlns/sca/1.0"
           xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
           targetNamespace="https://www.ibm.com/samples/sca/mybank" name="MyBank">
  <component name="AccountServiceComponent">
    <implementation.java class="samples.mybank.AccountServiceImpl"/>
    <service name="AccountService">
      <interface.wsdl interface="https://www.mybank.com/account#wsdl.interface(AccountService)"/>
        <binding.ws 
          wsdlElement="https://www.mybank.com/account#wsdl.port(AccountService/AccountServicePort)"
          uri="jms:jndi:jms/MyBankAccountService_Request?jndiConnectionFactoryName
            =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response
            &amp;targetService=AccountServiceComponent/AccountService"
          soapjms:activationSpec="jms/MyBankAccountService_AS"
          soapjms:responseConnectionFactory="jms/MyBankAccountService_CF"/>
    </service>
  </component>
</composite>

You can use these composite definition examples for @OneWay Message Exchange Pattern. When using @OneWay, the reference binding URI does not need to specify replyToName because there is no reply for the @OneWay call.

Configuring an SCA callback for SOAP over JMS

This example describes a <binding.ws> element in the composite definition file for a callback message exchange pattern between an SCA component reference and an SCA component service.

The following example shows an OSOA SCA component with a reference binding:

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="https://www.osoa.org/xmlns/sca/1.0"
           xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
           targetNamespace="https://www.ibm.com/samples/sca/mybank" name="MyBankClient">
  <component name="AccountSummaryService">
    <implementation.java class="samples.mybank.AccountSummaryServiceImpl"/>
    <reference name="accountService">
      <interface.wsdl
         interface="https://www.mybank.com/account#wsdl.interface(AccountService)"
         callbackInterface="https://www.mybank.com/account#wsdl.interface(AccountServiceCallback)"/>
      <binding.ws
         wsdlElement="https://www.mybank.com/account#wsdl.port(AccountService/AccountServicePort)"
         uri="jms:jndi:jms/MyBankAccountService_Request?jndiConnectionFactoryName
            =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response&amp;
            targetService=AccountServiceComponent/AccountService"/>
        <callback>
          <binding.ws
             wsdlElement="https://www.mybank.com/account#wsdl.binding(AccountServiceCallback)"
             uri="jms:jndi:jms/MyBankAccountService_Callback?jndiConnectionFactoryName
              =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response&amp;
              targetService=AccountServiceComponent/AccountService"
             soapjms:activationSpec="jms/$MyBankAccountService_Callback_AS"
             soapjms:responseConnectionFactory="jms/MyBankAccountService_CF"/>
        </callback>
    </reference>
  </component>
</composite>

For the OASIS SCA composite, the soapjms namespace is:

xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.1"

targetService is the target service to which a message is delivered. In a forward call from a service to a reference, specify the targetService in the format serviceComponentName/serviceName. In the callback URI, specify the targetService in the format referenceComponentName/referenceName.

The callback binding on the reference becomes an SCA service binding for the callback call. Hence activationSpec and responseConnectionFactory must be defined.

The following example shows an OSOA SCA component with a service binding:

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="https://www.osoa.org/xmlns/sca/1.0"
           xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06" 
           targetNamespace="https://www.ibm.com/samples/sca/mybank" name="MyBank">
  <component name="AccountServiceComponent">
    <implementation.java class="samples.mybank.AccountServiceImpl"/>
    <service name="AccountService">
      <interface.wsdl interface="https://www.mybank.com/account#wsdl.interface(AccountService)"
           callbackInterface="https://www.mybank.com/account#wsdl.interface(AccountServiceCallback)"/>
        <binding.ws
           wsdlElement="https://www.mybank.com/account#wsdl.port(AccountService/AccountServicePort)"
           uri="jms:jndi:jms/MyBankAccountService_Request?jndiConnectionFactoryName
            =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response&amp;
            targetService=AccountServiceComponent/AccountService"
           soapjms:activationSpec="jms/MyBankAccountService_AS"
           soapjms:responseConnectionFactory="jms/MyBankAccountService_CF" />
          <callback>
            <binding.ws 
               wsdlElement="https://www.mybank.com/account#wsdl.binding(AccountServiceCallback)" 
               uri="jms:jndi:jms/MyBankAccountService_Callback?jndiConnectionFactoryName
                =jms/MyBankAccountService_CF&amp;replyToName=jms/MyBankAccountService_Response&amp;
                targetService=AccountServiceComponent/AccountService" />
          </callback>
    </service>
  </component>
</composite>

For the OASIS SCA composite, the soapjms namespace is:

xmlns:soapjms="https://www.ibm.com/xmlns/prod/websphere/sca/1.1"

The service binding callback element does not need to specify a JMS endpoint URI because the callback URI is derived from the reference binding.

The callback binding on the service becomes a SCA reference binding for the callback call from the service back to the reference. Hence activationSpec and responseConnectionFactory need not be defined.

In some examples, the uri value is shown on multiple lines for publication. In your composite definition, place the uri value on one line.

What to do next

Deploy the SCA composite in an application and test the flow of messages over the web service binding.