Configure the SCA JMS binding
We can configure the Service Component Architecture (SCA) Java Message Service (JMS) binding for services and references to support messaging between SCA applications and JMS providers.
Use the console to enable the SIB service and Configuration reload enabled option on the application server where the application runs. Restart the server to enable the dynamic reloading of the SIB configuration files for this server. See the SIB service settings information to learn more about enabling the SIB service.
When you use the JMS binding, it is important that you follow best practice guidelines on design, configuration, and tuning of the messaging topology. Following these guidelines is especially important when you design systems for high throughput or high availability. Read the documentation on using JMS bindings in this information center, specifically "Multiple-server bus with clustering." The developerWorks articles "Configuring and tuning WebSphere MQ for performance on Windows and UNIX" and "Performance tuning for Java Messaging Service on WAS on z/OS" also provide useful information.
Bindings determine how a component communicates with the world outside its domain. SCA services use bindings to describe the access mechanism that clients must use to call the service. SCA references use bindings to describe the access mechanism used to call a service.
Using the SCA JMS binding, we can make SCA components available over JMS or we can use existing JMS applications within an SCA environment. We can use the SCA JMS binding element, <binding.jms>, within either a component service or a component reference definition. When a JMS binding is applied within a component service interface definition, the JMS binding enables clients to access an SCA service that is offered by a JMS provider. When the JMS binding is applied on a component reference, the SCA component can consume an external JMS application or another SCA component using JMS.
WebSphere Application Server supports asynchronous messaging using JMS. The default messaging provider enables enterprise applications deployed on WebSphere Application Server to perform asynchronous messaging without the need for you to install a JMS provider. The default messaging provider is installed and runs as part of WAS. The product supports the default messaging provider or WebSphere MQ as the messaging engine.
The SCA JMS Binding specification describes the <binding.jms> binding element and available attributes and options. The product supports both the OASIS and the OSOA SCA JMS binding specification. Unless otherwise specified, the information in this topic pertains to applications for both the OSOA and OASIS specifications. To learn more about the <binding.jms> binding element, see the SCA JMS Binding specification documentation.
SCA with JMS supports the following messaging exchange patterns:
- request-response messaging
- one-way messaging
- one-way messaging with callback
A request is a message sent to an SCA service or sent by an SCA reference. A response is a message that is received back at a reference or a message that is sent by a service in response to a previous request message. In SCA, a response is always a reply to a previous request. In a one-way message, a request message is sent and a response is not expected.
This task describes the steps necessary to enable SCA applications for JMS using request-response or one-way messaging.
- Identify the SCA business-level application to enable for JMS messaging.
- Identify and configure the JMS resources for the SCA application.
We can configure JMS resources for the default messaging provider before deployment of the SCA application. During deployment of the SCA application, the product can dynamically create any JMS resources that the JMS binding needs that do not exist if the composite definition file is configured for dynamic resource creation.
SCA applications are bound to JMS resources through their binding definitions in a corresponding composite definition file. The composite definition file for JMS uses Java Naming and Directory Interface (JNDI) names to identify JMS administered objects used by the SCA runtime environment on behalf of the SCA application to provide access over the specified binding.
We can configure the following JMS resource references in the JNDI directory or choose for the product to dynamically create the resources for you:
- a service integration bus
- a request queue and a response queue. A response queue is only required for request-response messaging. The physical queues and the logical queues must be defined.
- an activation specification to handle the request to the service
- a connection factory to process the response
To learn more about manually creating JMS resources, see the documentation on JMS resources for the default messaging provider. To learn more about dynamically creating JMS resources, see the dynamic JMS resource creation during deployment information.
- a service integration bus
- Configure an SCA service with the SCA JMS binding.
To expose an SCA service over the JMS binding, add the <binding.jms> element within the service definition.
Within the <binding.jms> element, define the following:
- an <activationSpec> element to identify the activation specification that the binding uses to connect to a JMS destination to process request messages
- a response <connectionFactory> element for request-response messaging patterns
- a response <destination> element that describes the JMS destination for responses from the JMS binding. Specifying the response destination is optional because the runtime environment obtains the JMSReplyTo destination set on the incoming request message to determine the response destination. If the JMSReplyTo attribute is not set on the request message, the response <destination> element is used to identify the response destination. This element is not applicable for one-way messaging patterns.
- an <activationSpec> element to identify the activation specification that the binding uses to connect to a JMS destination to process request messages
- Configure an SCA reference with the SCA JMS binding.
To consume or expose a JMS application or SCA reference with the JMS binding, add the <binding.jms> element within the SCA reference definition.
Within the <binding.jms> element, define the following:
- a <connectionFactory> element to identify the JNDI name of the connection factory used to process messages sent from the reference to the referenced service
- a <destination> element to identify the JMS queue or topic used to send messages to the referenced service
- a response <destination> element that describes the JMS destination queue used to process responses from the JMS binding. This element is optional for request-response messaging and not applicable for one-way messaging
For transitioning users: Differences between the OSOA and OASIS JMS binding specifications might affect migration of applications from OSOA to OASIS. Some commonly encountered differences include:
- The validation schemas used for the OASIS applications are defined by the OASIS SCA specification. The OASIS binding schema definition mandates that binding elements appear in the exact order as defined in the schema. For OSOA applications, element order does not affect
validation so, when migrating applications from OSOA, ensure the binding elements are in the order specified by the OASIS binding schema.
- For the <destination>, <connectionFactory>, and <activationSpec> elements, the name attribute is jndiName in OASIS.
- In OASIS composites, callback references must specify a destination element. The specified destination is used only if the destination cannot be determined from the scaCallbackDestination or JMSReplyTo properties of the service request message. In OSOA composites, callback references can omit the destination element if it is known that one of the properties is always set.
For information on other differences, consult the OASIS specification for additional information about specific elements.trns
- a <connectionFactory> element to identify the JNDI name of the connection factory used to process messages sent from the reference to the referenced service
- Optional: Configure JMS message correlation.
We can optionally configure a JMS correlation identification for a request message and its response. Because of the asynchronous nature of JMS, it is important to determine if message correlation is required. A request-response messaging pattern is not equivalent to synchronous messaging.
We can use the @correlationScheme element to identify the correlation scheme used when sending a reply or callback messages.
For OSOA, the valid values for this element are: RequestMsgIDToCorrelID, RequestCorrelIDToCorrelID, and none. The default value is RequestMsgIDToCorrelID.
For OASIS, the valid values for this element are: sca:messageID, sca:correlationID, and sca:none.
To configure JMS message correlation, we can specify a correlationID element within the composite definition file used within the JMS header to link two messages.
- Optional: Invoke an operation using JMS operation selection
- Use the default JMS binding operation selection.
- Use JMS user property operation selection.
- Use a JMS custom operation selector.
Use the @nativeOperation attribute in a composite definition, the application can override operation selection; for example, in OSOA:
<service> <binding.jms> ... <operationProperties name="operationToInvoke" nativeOperation="selectedOperation"/> ... </binding.jms> </service>Or, in OASIS:
<service> <binding.jms> ... <operationProperties name="operationToInvoke" selectedOperation="selectedOperation"/> ... </binding.jms> </service>In this example, when the configured operation selector selects the operation named selectedOperation, the run time invokes operation operationToInvoke on the target service implementation. The overriding occurs whether the service binding is configured using default JMS operation selection, JMS user property operation selection, or a JMS custom selector.
- Use the default JMS binding operation selection.
Results
You have defined the JMS resources we need for the SCA application, configured the SCA JMS binding for the SCA services and references, and deployed the application. Your application is now ready for use.
Example
The following example illustrates two SCA component implementations and the use of request-response and one-way messaging.
Figure 1. SCA JMS binding example
The HelloService component implementation illustrates the request-response message pattern. This HelloService component exposes the service interface with the name, getGreeting, used to illustrate a return response of hello plus the value of getGreeting.
The LoggingService component implementation is a logging service. This component exposes a one-way service interface with the name, log, that receives a message and logs the message in a repository.
The HelloService has an SCA reference to the LoggingService. Each time the HelloService service receives a message, it calls the LoggingService service to log the message.
In this example, a Thin Client for JMS application sends a message, formatted as a JMS ObjectMessage message type to the SCA HelloService using the jms/SCA_sample_Request queue. The ObjectMessage sets the scaOperationName property to the value, getGreetings. The HelloServiceComponent receives the message over the JMS HelloService binding. The HelloServiceComponent then sends a request to the referenced service, LoggingService, and the one-way operation is complete. HelloServiceComponent sends a response of hello plus the value of getGreetings to the client application using the jms/SCA_sample_Response queue to complete the request-response operation.
Configure an SCA JMS binding for a request-response service from a JMS client to SCA service
The following example describes a <binding.jms> element within the component definition file for a request-response message exchange pattern from a JMS client to an SCA service:
OSOA composite
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
targetNamespace="http://www.ibm.com/soa/sca/samples"
xmlns:hw="http://www.ibm.com/soa/sca/samples"
xmlns:ts="http://tuscany.apache.org/xmlns/sca/1.0"
name="HelloServiceComposite">
<component name="HelloServiceComponent">
<implementation.java class="soa.sca.samples.jms.HelloServiceImpl"/>
<service name="HelloService">
<interface.java interface="soa.sca.samples.jms.HelloService"/>
<binding.jms>
<ts:wireFormat.jmsObject/>
<destination name="jms/SCA_sample_Request" type="queue"/>
<activationSpec name="jms/SCA_sample_AS"/>
<response>
<destination name="jms/SCA_sample_Response" type="queue"/>
<connectionFactory name="jms/SCA_sample_CF"/>
</response>
</binding.jms> </service>
</component>
</composite>
OASIS composite
<composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"
targetNamespace="http://www.ibm.com/soa/sca/samples"
xmlns:hw="http://www.ibm.com/soa/sca/samples"
xmlns:ts="http://tuscany.apache.org/xmlns/sca/1.1"
name="HelloServiceComposite">
<component name="HelloServiceComponent">
<implementation.java class="soa.sca.samples.jms.HelloServiceImpl"/>
<service name="HelloService">
<interface.java interface="soa.sca.samples.jms.HelloService"/>
<binding.jms>
<ts:wireFormat.jmsObject/>
<destination jndiName="jms/SCA_sample_Request" type="queue"/>
<activationSpec jndiName="jms/SCA_sample_AS"/>
<response>
<destination jndiName="jms/SCA_sample_Response" type="queue"/>
<connectionFactory jndiName="jms/SCA_sample_CF"/>
</response>
</binding.jms> </service>
</component>
</composite>
- The <destination> describes the JMS destination.
The destination type is either a queue or topic.
This example illustrates the JMS destination queue type. The destination is used to process requests by the JMS binding to the component implementation containing the service interface
- The <activationSpec> element identifies
the activation specification that the binding uses to connect to a JMS destination to process request messages. The activation specification name must be a JNDI name. The <activationSpec> element is only supported within the SCA <service> tag.
- The <response> element defines the resources used for processing response messages. In this example, the response element specifies the resources for sending messages from the <service> back
to the client.
- The response <destination> element describes the JMS destination queue used to process responses from the service interface.
- The response <connectionFactory> element identifies the JNDI name of the connection factory that the binding uses to process response messages.
- The <ts:wireFormat.jmsObject/> specifies to the JMS binding that the payload of the message is of the type, javax.jms.Message (ObjectMessage).
The following example describes a <binding.jms> element within the component definition file for a one-way interaction from one SCA service to another SCA service. The <binding.jms> binding definition is similar to the HelloService; however, because the message operation is one-way, there is not a response definition.
OSOA composite
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
targetNamespace="http://www.ibm.com/soa/sca/samples"
xmlns:hw="http://www.ibm.com/soa/sca/samples"
xmlns:ts="http://tuscany.apache.org/xmlns/sca/1.0"
name="HelloServiceComposite">
<component name="LoggingService">
<implementation.java class="soa.sca.samples.jms.LoggingServiceImpl"/>
<service name="LoggingService">
<interface.java interface="soa.sca.samples.jms.LoggingService"/>
<binding.jms> <ts:wireFormat.jmsObject/> <destination name="jms/SCA_Logging_Request" type="queue"/>
<activationSpec name="jms/SCA_sample_AS"/>
</binding.jms> </service> </component>
</composite>
OASIS composite
<composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"
targetNamespace="http://www.ibm.com/soa/sca/samples"
xmlns:hw="http://www.ibm.com/soa/sca/samples"
xmlns:ts="http://tuscany.apache.org/xmlns/sca/1.1"
name="HelloServiceComposite">
<component name="LoggingService">
<implementation.java class="soa.sca.samples.jms.LoggingServiceImpl"/>
<service jndiName="LoggingService">
<interface.java interface="soa.sca.samples.jms.LoggingService"/>
<binding.jms> <ts:wireFormat.jmsObject/> <destination jndiName="jms/SCA_Logging_Request" type="queue"/>
<activationSpec jndiName="jms/SCA_sample_AS"/>
</binding.jms> </service> </component>
</composite>
Configure an SCA JMS binding for two-way service from a JMS client to SCA reference
The following example describes a <binding.jms> element within the component definition file for a request-response message exchange pattern from a JMS client to an SCA reference:
OSOA SCA reference
<reference name="helloWorldService">
<interface.java interface="my.HelloWorldService"/>
<binding.jms>
<connectionFactory name="jms/helloWorldServiceCF"/>
<destination name="jms/HelloWorldService"/>
<response>
<destination name="jms/SCA_sample_Response"/>
</response>
</binding.jms>
</reference>
OASIS SCA reference
<reference name="helloWorldService">
<interface.java interface="my.HelloWorldService"/>
<binding.jms>
<connectionFactory jndiName="jms/helloWorldServiceCF"/>
<destination jndiName="jms/HelloWorldService"/>
<response>
<destination jndiName="jms/SCA_sample_Response"/>
</response>
</binding.jms>
</reference>
- The <connectionFactory> element is used in the SCA reference to identify the JNDI name of the connection factory used to process messages sent from the reference to the referenced service. The <activationSpec> element is not supported in a reference.
- The <destination> element is the JMS queue
or topic used to send messages to the referenced component implementation.
- The response <destination> element is the JMS resource used to receive response messages to the SCA reference.
Authenticating with a secure bus
We can specify an authentication alias on the reference binding or service binding in the composite file to authenticate with a secure bus. Use the authentication-alias attribute to specify the predefined authentication alias instead of specifying it in the activation specification or connection factory settings.
A <binding.jms> element does not propagate the identity of the client. For details on creating a J2C authentication alias, see Managing Java 2 Connector Architecture authentication data entries for JAAS.
OSOA SCA composite
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
targetNamespace="http://www.ibm.com/soa/sca/samples"
xmlns:hw="http://www.ibm.com/soa/sca/samples"
xmlns:ts="http://tuscany.apache.org/xmlns/sca/1.0"
xmlns:websphere="http://www.ibm.com/xmlns/prod/websphere/sca/1.0/2007/06"
name="HelloServiceComposite">
<component name="HelloServiceComponent">
<implementation.java class="soa.sca.samples.jms.HelloServiceImpl"/>
<service name="HelloService">
<interface.java interface="soa.sca.samples.jms.HelloService"/>
<binding.jms websphere:authentication-alias="SCA_Auth_Alias">
<destination name="jms/SCA_sample_Request" type="queue"/>
<activationSpec name="jms/SCA_sample_AS"/>
<response>
<destination name="jms/SCA_sample_Response" type="queue"/>
<connectionFactory name="jms/SCA_sample_CF"/>
</response>
<ts:wireFormat.jmsObject/>
</binding.jms>
</service>
</component>
</composite>
OASIS SCA composite
<composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"
targetNamespace="http://www.ibm.com/soa/sca/samples"
xmlns:hw="http://www.ibm.com/soa/sca/samples"
xmlns:ts="http://tuscany.apache.org/xmlns/sca/1.1"
xmlns:websphere="http://www.ibm.com/xmlns/prod/websphere/sca/1.1"
name="HelloServiceComposite">
<component name="HelloServiceComponent">
<implementation.java class="soa.sca.samples.jms.HelloServiceImpl"/>
<service name="HelloService">
<interface.java interface="soa.sca.samples.jms.HelloService"/>
<binding.jms websphere:authentication-alias="SCA_Auth_Alias">
<destination jndiName="jms/SCA_sample_Request" type="queue"/>
<activationSpec jndiName="jms/SCA_sample_AS"/>
<response>
<destination jndiName="jms/SCA_sample_Response" type="queue"/>
<connectionFactory jndiName="jms/SCA_sample_CF"/>
</response>
<ts:wireFormat.jmsObject/>
</binding.jms>
</service>
</component>
</composite>
What to do next
Based on the business needs, we can configure an SCA JMS binding wire format or configure transactions for the SCA JMS binding.
Explore the JMS binding samples to better understand how to invoke an SCA component service using a JMS client. For information on JMS samples, see "SCA samples." To download JMS binding samples from a product website:
- Go to the Samples, v8.5 information center.
- On the Downloads tab, click FTP or HTTP in the Service Component Architecture section.
- In the authentication window, click OK.
- From the SCA.zip compressed file, download
the SCA/JMS directory and follow instructions in SCA/JMS/documentation/readme.html to build
the files.
Instead of building deployable files, we can use the prebuilt jms-callback-service.jar, jms-twoway-oneway-service.jar, and jms-twoway-service.jar files in the SCA/installableApps directory of the compressed file.
After you obtain the SCA components, deploy the components in an application and test the JMS binding.
Subtopics
- (dist)(zos) 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. - (dist)(zos) Configure transactions for the SCA JMS binding
We can configure the Service Component Architecture (SCA) Java Message Service (JMS) binding for services and references to take advantage of transaction quality of service behaviors. - (dist)(zos) Dynamic JMS resource creation during deployment
The product dynamically creates Java Message Service (JMS) resources necessary for a Service Component Architecture (SCA) composite, if those resources do not exist and relate to the WebSphere default messaging provider. The product creates the resources when adding the SCA composite to a business-level application. The dynamically created resources are created in a WebSphere default messaging provider service integration bus. The product does not create resources that relate to WebSphere MQ; those resources must exist. A dynamically created service integration bus resource is given a name specified in the JMS binding or, if the binding does not specify a resource name, is given a default name. When an SCA composite uses a mixture of existing and non-existent resources, the product dynamically creates the resources that do not exist. - (dist)(zos) Invoking operations using JMS binding operation selection
We can invoke an operation using JMS binding operation selection. By default, a JMS binding uses the JMS binding operation selection. - (dist)(zos) Invoking operations using JMS user property operation selection
We can invoke an operation using JMS user property operation selection. - (dist)(zos) Invoking operations using custom operation selectors
If the application cannot use a default JMS binding operation selection or JMS user property operation selection to determine the target operation, we can use a JMS custom operation selector to invoke operations.
Related concepts
Related tasks
Related information: