Configure the SCA web services binding to transport SOAP messages over JMS

Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop SCA composites > Specify bindings in an SCA environment > Configure the SCA web services binding

Configure the SCA web services binding to transport SOAP messages over JMS

We can configure a Service Component Architecture (SCA) web service binding to transport SOAP messages over JMS (JMS) protocol.
For information about web service bindings, read Configure the SCA web services binding.
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.
This topic describes how to configure a web service binding to flow SOAP messages over JMS.
The web service binding supports Web Services Description Language (WSDL) v1.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 wsadmin.sh.
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:

Create a service integration bus and associate a bus member.

Create destinations for the request and response for the service integration bus.

Create destinations for the request and response under JMS resources.

Create an activation specification that is associated with a request destination.

Create connection factories to process the request and to send the response.
Configure an SCA service with an SCA web services binding to transport SOAP messages over JMS.
Configure a Web service binding as described in Configure the SCA web services 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.
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:

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 JNDI name of the connection factory used by the client run time to establish a connection to the JMS messaging engine. jndiConnectionFactoryName is optional for the service uri attribute.
targetService 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 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/AccountServicetDestination?jndiConnectionFactoryName=jms/AccountServiceCF
&amp;replyToName=jms/AccountServiceResponse&amp;targetService=AccountServicePort"
URI based on IBM proprietary SOAP over JMS protocol
Attention: 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:

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 JNDI name of the destination queue or topic.
connectionFactory JNDI name of the connection factory. connectionFactory is optional for the service uri attribute.
replyToDestination JNDI name to which a response is sent. replyToDestination is optional for the service uri attribute.
targetService 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/AccountServiceDestination&amp;connectionFactory=jms/AccountServiceCF
&amp;replyToDestination=AccountServiceResponse&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 composite by setting xmlns="http://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06".
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 composite by setting xmlns="http://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06".
After these updates are made to the <binding.ws> element, the composite definition file resembles:
<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
 xmlns:soapjms="http://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
 targetNamespace="http://www.ibm.com/samples/sca/mybank"
 name="MyBank">
<component name="AccountServiceComponent">
<implementation.java
      class="samples.mybank.AccountServiceImpl"/>
<service name="AccountService">
<interface.wsdl
      interface=
          "http://www.mybank.com/account#wsdl.interface(AccountService)" />
<binding.ws
          wsdlElement=
            "http://www.mybank.com/account#wsdl.port(AccountService/AccountServicePort)"

          uri=
            "jms:/queue?destination=jms/AccountRequestQueue&amp;connectionFactory=
             jms/Account_CF&amp;replyToDestination=jms/AccountResponseQueue&amp;targetService=AccountServiceComponent/AccountService"

          soapjms:activationSpec="jms/AccountActivationSpec"

          soapjms:responseConnectionFactory="jms/Account_Response_CF"/>
</service>
</component>
</composite> 
Configure an SCA reference (client) with an SCA web services 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, 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:/queue?destination=jms/AccountRequestQueue&amp;connectionFactory=jms/Account_CF
&amp;replyToDestination=jms/AccountResponseQueue&amp;targetService=AccountServiceComponent/AccountService"
After you define the URI in the <binding.ws> element, the composite definition file resembles:
<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
targetNamespace="http://www.ibm.com/samples/sca/mybank"
name="MyBankClient">
<component name="AccountSummaryService">
<implementation.java
      class="samples.mybank.AccountSummaryServiceImpl"/>
<reference name="accountService">
<interface.wsdl
      interface=
        "http://www.mybank.com/account#wsdl.interface(AccountService)" />
<binding.ws
      wsdlElement=
        "http://www.mybank.com/account#wsdl.port(AccountService/AccountServicePort)"

       uri=
         "jms:/queue?destination=jms/AccountRequestQueue&amp;connectionFactory=
          jms/Account_CF&amp;replyToDestination=jms/AccountResponseQueue&amp;targetService=AccountServiceComponent/AccountService"/>
</reference>
</component>
</composite> 
Results

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

Example

Configure 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 SCA component with a reference binding:
<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
           xmlns:soapjms="http://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
           targetNamespace="http://www.ibm.com/samples/sca/mybank" name="MyBankClient">
<component name="AccountSummaryService">
<implementation.java class="samples.mybank.AccountSummaryServiceImpl"/>
<reference name="accountService">
<interface.wsdl interface="http://www.mybank.com/account#wsdl.interface(AccountService)"/>       
<binding.ws
        wsdlElement="http://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 SCA component with a service binding:
<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
           xmlns:soapjms="http://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
           targetNamespace="http://www.ibm.com/samples/sca/mybank" name="MyBank">
<component name="AccountServiceComponent">
<implementation.java class="samples.mybank.AccountServiceImpl"/>
<service name="AccountService">
<interface.wsdl interface="http://www.mybank.com/account#wsdl.interface(AccountService)"/>         
<binding.ws
          wsdlElement="http://www.mybank.com/account#wsdl.port(AccountService/AccountServicePort)"
          uri="jms:jndi:jms/MyBankAccountService_Request?"
          soapjms:activationSpec="jms/MyBankAccountService_AS"
          soapjms:responseConnectionFactory="jms/MyBankAccountService_CF"/>

</service>
</component>
</composite> 
We 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.
Configure 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 SCA component with a reference binding:
<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
           xmlns:soapjms="http://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
           targetNamespace="http://www.ibm.com/samples/sca/mybank" name="MyBankClient">
<component name="AccountSummaryService">
<implementation.java class="samples.mybank.AccountSummaryServiceImpl"/>
<reference name="accountService">
<interface.wsdl
         interface="http://www.mybank.com/account#wsdl.interface(AccountService)"
         callbackInterface="http://www.mybank.com/account#wsdl.interface(AccountServiceCallback)" />       
<binding.ws
         wsdlElement="http://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="http://http://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> 
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 following example shows an SCA component with a service binding:
<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
           xmlns:soapjms="http://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
           targetNamespace="http://www.ibm.com/samples/sca/mybank" name="MyBank">
<component name="AccountServiceComponent">
<implementation.java class="samples.mybank.AccountServiceImpl"/>
<service name="AccountService">
<interface.wsdl interface="http://www.mybank.com/account#wsdl.interface(AccountService)"
           callbackInterface="http://www.mybank.com/account#wsdl.interface(AccountServiceCallback)"/>         
<binding.ws
           wsdlElement="http://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="http://http://www.mybank.com/account#wsdl.binding(AccountServiceCallback)"/>
   
</callback>
</service>
</component>
</composite> 
The service binding callback element does not need to specify a JMS endpoint URI because the callback URI is derived from the reference binding.
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.
Configure the SCA web services binding
Configure web service binding custom endpoints to support a proxy server
Resolve SCA references
Export WSDL and XSD documents using scripting

Related

Industry standard SOAP/JMS protocol (recommended)
IBM proprietary SOAP over JMS protocol (deprecated)
wsimport command for JAX-WS applications
Service Component Architecture specifications and APIs

+
Search Tips | Advanced Search

Property name	Description
jndiConnectionFactoryName	JNDI name of the connection factory used by the client run time to establish a connection to the JMS messaging engine. jndiConnectionFactoryName is optional for the service uri attribute.
targetService	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	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.

Property name	Description
destination	JNDI name of the destination queue or topic.
connectionFactory	JNDI name of the connection factory. connectionFactory is optional for the service uri attribute.
replyToDestination	JNDI name to which a response is sent. replyToDestination is optional for the service uri attribute.
targetService	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.