|Home > Apache Tuscany Docs 2.x > Index > SCA Java Extensions Guide > SCA Java binding.jms|
|Apache Tuscany Docs 2.x > Index > SCA Java Extensions Guide > SCA Java binding.jms||Tuscany Home | User List | Dev List | Issue Tracker|
Apache Tuscany Docs 2.x
SCA Java binding.jms
The Tuscany Java SCA runtime supports the Java Messaging Service using the <binding.jms> SCDL extension. New JMS based service endpoints can be provided using a <binding.jms> element within a SCA <service>, existing JMS queues can be accessed using a <binding.jms> element within a SCA <reference>.
The JMS binding is one of the SCA extensions which is being formalized in the OASIS Open Composite Services Architecture with a published specifications document.
The simplest way to use the JMS binding is to use the URI syntax to configure the binding, for example:
This tells the binding to use a JMS destination named "RequestQueue", with all the other configuration options using default values.
By default Tuscany will use a JMS connection factory named 'ConnectionFactory', this can be changed by using a query parameter in the URI, for example, to use a connection factory named 'myCF' can be done as follows:
When using a SCA reference for RPC style requests and no response destination is defined in the SCDL then a temporary replyTo queue will automatically be created and used.
When using the JMS binding with SCA services the syntax can be simplified even further by letting the destination name default to the service name. For example, the following SCDL snippet creates a JMS service listening on a JMS destination named "MyService":
Tuscany performs two types of validation of the JMS Binding specified in a composite file.
Validation rules are taken from the binding schema and the OSOA and OASIS specs:
Invalid JMS bindings usually result in a JMSBindingException with error message and specific context of the error. See the JMSBindingProcessor for a complete list of validation rules.
The helloworld-jms sample demonstrates basic RPC style operations over JMS. The sample has one component exposing a JMS service on a queue name 'HelloWorldService' and another component which invokes the service by sending JMS messages to that queue. A temporary destination is used for the response messages. The .composite file for this is shown below, see the helloworld sample README for full details.
Operation selection extensions allow you to choose how the JMS bindings determines which service operation to call based on the incoming MS message.
While you can specify the default operation selector there is no need to as in lieu of other operation selectors being specified this one it assumed to be in force. You can add new operation selectors by adding the appropriate model objects, processors and providers.
Following operation selection the actual operation that is called may be further affected by operationProperties configuration.
Wire format extensions allow you to choose how message data is expected to appear inside the JMS message as it flows across the wire.
While you can specify this wire format there is no need to as in lieu of other operation selectors being specified this one it assumed to be in force. You can add new wire formats by adding the appropriate model objects, processors and providers.
The Tuscany JMS binding supports using SCA callbacks for creating asynchronous clients and services.
This is done by using a <callback> element in the SCDL for the service or reference as shown in the following example.
When no destination is defined on the callback binding of a <reference> then a JMS temporary queue will be used.
JMS headers and user properties can be set on JMS messages sent from Tuscany by using the <Headers> and <OperationProperties> elements of the JMS binding. The <Headers> element applies to all messages, the <OperationProperties> applies to individual operations and may override values set on the <Headers> element.
An example of using these is shown in the following snippet of SCDL:
A complete working example of using <Headers> and <OperationProperties> can be seen in the properties itest
Services using the JMS binding to receive messages may only want a subset of the messages arriving on a queue or topic. This can be done by using the <SubscriptionHeaders> element which enables defining a JMS message selector to filter the messages that will be received.
An example of using these is shown in the following snippet of SCDL:
A complete working example of using <SubscriptionHeaders> can be seen in the jms selectors itest .
It can be useful to define the details of the JMS resources separately from the SCA composite, to support this the SCA definitions.xml file can be used to define 'model' <binding.jms> elements which can then be referred to from the binding within the composite.
For example, the following shows a definitions.xml file defining a JMS queue and connection factory which are then used by a JMS binding within a composite.
The definitions.xml file:
and a binding which uses the definitions.xml binding:
A complete working example of using the requestConnection/responseConnection attributes can be seen in the jms definitions itest .
Tuscany locates all JMS resources from JNDI so the environment where Tuscany is running needs to have JNDI and JMS correctly configured in order to use the Tuscany JMS binding.
The following describes how to configure JMS in some common environments:
The Tuscany standalone runtime can use an embedded Apache ActiveMQ message broker. To use ActiveMQ the application needs to include the JMS API and ActiveMQ jars in the classpath and include a jndi.properties file to configure the ActiveMQ resources in JNDI.
For more information on using ActiveMQ see the Apache ActiveMQ website and specifically this page for information about configuring JNDI resources.
Tomcat does not include a JMS broker by default so you need to either embed one in each Tuscany application, install a broker into the tomcat installation, or use an external broker. Once that is done JNDI resources can be defined using the standard Tomcat facilities, see the Tomcat JNDI How-to.
The Tuscany samples that use JMS and Tomcat demonstrate how to embed a JMS broker within the application by including ActiveMQ and its dependencies within the sample WAR, and using the webapp META-INF/context.xml file to define the JMS resources in JNDI.
JEE Application servers such as Geronimo, WebSphere, WebLogic etc come with their own JMS broker that can be used by Tuscany. All the JMS resources used by a Tuscany application must be manually defined in the application server. Usually the application server has some sort of admin console where the resources can be defined using a web browser.
The Tuscany helloworld JMS sample README describes the specific details of how to do this for some common application servers.
When running Tuscany in a JEE environment it can be useful to use JEE resource references to map local application resource names to global JNDI names. This can be done by using <resource-ref> elements in the application deployment descriptor. If a <resource-ref> exists for a JMS binding resource then Tuscany will use that instead of looking up the resource directly in the global JNDI.
For example, adding the following definitions to the helloworld JMS sample web.xml will enable mapping the 'ConnectionFactory' and 'HelloWorldService' names used by the JMS binding into names for the actual resources used on the Application Server. This will normally occur when the application is dployed with the deploy tool asking what real resource names the resourecs should be mapped to.
When the Tuscany environment does not include a JMS broker then an external broker may be used by specifying the initialContextFactory and jndiURL attributes on the binding.jms element. Any JMS 1.1 compatible broker should work such as Apache ActiveMQ or any other proprietary broker. The Tuscany application classpath will need to include jars for the initial context factory and all of its dependencies.
An example of using the Tuscany JMS binding with an external ActiveMQ broker is as follows:
The Tuscany JMS binding now (post Tuscany SCA 1.2) works the WebSphere client for JMS which enables Tuscany applications running outside of WebSphere to use JMS resources defined within WebSphere. You need to include the JMS client jars in the Tuscany classpath and ensure that the JMS connection factory has the "endpoint providers" field configured in WebSphere. See this email thread for more information.
The SCA JMS specification only defines how to use JMS TextMessages which contain XML in the message body, however it is a common requirement to use alternative message types and body formats. Currently Tuscany defines an additional "messageProcessor" attribute on the binding.jms element to support additional message types and payload formats. For the time being this should be considered an interim solution which will be changed in future Tuscany releases.
The messageProcessor attribute value may be "XMLTextMessage", "TextMessage", "ObjectMessage", or the name of a Java class that implements the org.apache.tuscany.sca.binding.jms.provider.JMSMessageProcessor interface. For example:
For a complete example of using the messageProcessor attribute see the MessageProcessorTestCase itest.
The JMS binding is aware of the following policy implementations.
Intents and policy sets can be constructed to control the application of these policies. The following intents are defined by default
New intents and policy sets can be designed are required to provide the level of control you need over your application.
The priority intent provides a coarse grained approach to setting message priority. For example,
The values "priority.high", "priority.medium", "priority.low" are supported. It is the responsibility of the user to define a policy set to support these intents. The following policy set could be used to support these priority values.
The deliveryMode intent provides s simple way of specifying whether a message should be delivered persistently or non-persistently. For example,
The values "deliveryMode.persistent" and "deliveryMode.nonPersistent" are supported. It is the responsibility of the user to define a policy set to support these intents. The following policy set could be used to support these delivery mode values.
The complete JMS binding SCDL schema has the following format:
See the JMS Binding Specification 1.0 for full details of each of these configuration options.
Not all these elements are supported by Tuscany. Specifically, the <activationSpec> and <resourceAdapter> elements are not supported as Tuscany does not use JCA or MDBs for its JMS support.
The create attribute on the destination element is not supported in most environments and all JMS resources (connection factories, queues and topics) need to be pre-configured. An exception to this is when using Apache ActiveMQ as the JMS broker then Tuscany may be able to dynamically create queue and topic resources. This is mainly only useful for unit testing and it is recommended that user applications are designed with the expectation that JMS resources need to be preconfigured.
the "operationSelector" and "wireFormat" elements are declared in the tuscany namespace (http://tuscany.apache.org/xmlns/sca/1.0). The default operation selection and wire format behvaviour is defined in the JMS Binding Specification 1.0 but we have added a selection of other formats and selectors as alternatives.
The JMS binding is the first binding where we have started to exploit the binding wire concept. This affects how the JMS binding is implemented.
The addition of a binding wire to the infrastructure allows interceptors to be added that operate on message data in the context of the binding. This allows wire formats to be specified. This is important for bindings like JMS where the data format on the wire does not necessarily follow a well known specification. The default wire format in the Tuscany JMS binding is as described in the SCA JMS specification, i.e. a JMS text message containing XML. However JMS messages using any arbitrary format can be supported by constructing new wire format extensions.
The following diagram shows an overview of how a reference JMS binding may be configured to talk to a service JMS binding using the Text XML wire format.
In the above diagram,
An example of a composite file which results in this kind of configuration is as follows:
Note that <wireFormat.jmsTextXML/> is explicitly specified on the reference binding. As this is the default wire format it can be omitted as is the case on the service binding.
Of course Tuscany already has a databinding framework that is able to transform between datatypes generically. So think of the wire format functionality as performing binding specific transformations.
The following diagram gives an overview of the difference between the databinding and wireformat transformations on the reference side:
The following diagram gives an overview of the difference between the databinding and wireformat transformations on the service side:
When looking at the code itself you will see the following structure:
The providers can be replaced in order to change the way that the JMS binding is constructed.