SCA Java binding.jms (TUSCANY) edited by Simon Laws
Page:
http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+binding.jms
Changes:
http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=57033&originalVersion=35&revisedVersion=36
Content:
---------------------------------------------------------------------
{section:border=false}
{column:width=15%}
{include: SCA Java Subproject Menu}
{include: Java SCA Menu New}
{column}
{column:width=85%}
h3. <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
|http://www.oasis-opencsa.org/sca-bindings] document.
(on) Not all function described here as been included in a Tuscany release yet.
It will be included in the next Tuscany SCA release.
h4. Using the JMS binding
The simplest way to use the JMS binding is to use the URI syntax to configure
the binding, for example:
{code}<binding.jms uri="jms:RequestQueue"/>{code}
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:
{code}<binding.jms uri="jms:RequestQueue?connectionFactoryName=myCF"/>{code}
(on) 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":
{code}
<service name="MyService">
<binding.jms />
</service>
{code}
h3. Some examples:
h4. HelloWorld
The
[helloworld-jms|https://svn.apache.org/repos/asf/incubator/tuscany/java/sca/samples/helloworld-jms-webapp/]
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|https://svn.apache.org/repos/asf/incubator/tuscany/java/sca/samples/helloworld-jms-webapp/README]
for full details.
{code}
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0";
targetNamespace="http://sample";
xmlns:sample="http://sample";
name="HelloWorld">
<component name="HelloWorldClient">
<implementation.java class="helloworld.HelloWorldClient"/>
<reference name="helloWorldRef">
<binding.jms uri="jms:HelloWorldService"/>
</reference>
</component>
<component name="HelloWorldServiceComponent">
<implementation.java class="helloworld.HelloWorldServiceImpl" />
<service name="HelloWorldService">
<binding.jms />
</service>
</component>
</composite>
{code}
h3. Using SCA callbacks with the JMS binding
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.
See the
[callbacks-jms|https://svn.apache.org/repos/asf/tuscany/java/sca/samples/callbacks-jms/]
sample for a complete example of using callbacks
{code}
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0";
targetNamespace="http://sample";
name="CallbacksComposite">
<component name="ClientComponent">
<implementation.java class="callbacks.OrderServiceClient" />
<reference name="orderService" target="ServiceComponent/OrderService">
<binding.jms uri="jms:OrderService"/>
<callback>
<binding.jms />
</callback>
</reference>
</component>
<component name="ServiceComponent">
<implementation.java class="callbacks.OrderServiceImpl" />
<service name="OrderService">
<binding.jms />
<callback>
<binding.jms />
</callback>
</service>
</component>
</composite>
{code}
(on) When no destination is defined on the callback binding of a <reference>
then a JMS temporary queue will be used.
h3. Setting JMS headers and user properties
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:
{code}
<binding.jms uri="jms:ServiceQueue">
<headers JMSType="someTypeValue" />
<operationProperties name="op2">
<headers JMSType="op2SpecificTypeValue" />
</operationProperties>
</binding.jms>
{code}
A complete working example of using <Headers> and <OperationProperties> can be
seen in the [properties itest |
https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms/src/test/java/org/apache/tuscany/sca/binding/jms/PropertiesTestCase.java]
h3. Using JMS message selectors
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 |
http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JMS4.html#wp79281] to filter the
messages that will be received.
An example of using these is shown in the following snippet of SCDL:
{code}
<binding.jms uri="jms:ServiceTopic" >
<SubscriptionHeaders JMSSelector="JMSType = 'type1'"/>
</binding.jms>
{code}
A complete working example of using <SubscriptionHeaders> can be seen in the
[jms selectors itest |
https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms-selectors].
h3. Using a definitions.xml file and the requestConnection/responseConnection
attributes
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:
{code}
<definitions xmlns="http://www.osoa.org/xmlns/sca/1.0";
xmlns:itest="http://jms";
targetNamespace="http://jms"; >
<binding.jms name="itest:TestService" >
<destination name="MyServiceQueue" create="never"/>
<connectionFactory name="MyConnectionFactory"/>
</binding.jms>
</definitions>
{code}
and a binding which uses the definitions.xml binding:
{code}<binding.jms requestConnection="itest:TestService" />{code}
A complete working example of using the requestConnection/responseConnection
attributes can be seen in the [jms definitions itest |
https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms-definitions].
h3. Configuring JMS resources
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:
h4. Tuscany J2SE standalone environment with ActiveMQ
The Tuscany standalone runtime can use an embedded [Apache
ActiveMQ|http://activemq.apache.org/] 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.
An example of this can be seen in the Tuscany [JMS
itest|https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms/] which uses
the [ActiveMQ
4.1.1|http://repo1.maven.org/maven2/org/apache/activemq/activemq-core/4.1.1/activemq-core-4.1.1.jar]
release and
[this|https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms/src/main/resources/jndi.properties]
jndi.properties file.
For more information on using ActiveMQ see the Apache ActiveMQ website and
specifically [this|http://activemq.apache.org/jndi-support.html] page for
information about configuring JNDI resources.
h4. Apache Tomcat
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|http://tomcat.apache.org/tomcat-6.0-doc/jndi-resources-howto.html].
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.
h4. JEE application servers such as Apache Geronimo, WebSphere etc
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|https://svn.apache.org/repos/asf/tuscany/java/sca/samples/helloworld-jms-webapp/README]
describes the specific details of how to do this for some common application
servers.
{note:title=ClassCastExceptions when using Tuscany applications in an
Application Server}
Tuscany applications, specifically the JMS samples, are built to work out
of-the-box on Tomcat by including a JMS broker embedded within the application.
This causes incompatibilities with some Application Servers because the Java
class of JMS resources may use different class loaders in the server and the
application. The solution is to delete any JMS API jar included in the
application WAR, for example, the geronimo-jms_1.1_spec-1.1.jar.
{note}
h4. (/) Using JEE resource references
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|https://svn.apache.org/repos/asf/incubator/tuscany/java/sca/samples/helloworld-jms-webapp/src/main/webapp/WEB-INF/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.
{code}
<resource-ref>
<res-ref-name>ConnectionFactory</res-ref-name>
<res-type>javax.jms.ConnectionFactory</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<resource-ref>
<res-ref-name>HelloWorldService</res-ref-name>
<res-type>javax.jms.Queue</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
{code}
h4. Using an external JMS broker
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:
{code}
<binding.jms
initialContextFactory="org.apache.activemq.jndi.ActiveMQInitialContextFactory"
jndiURL="tcp://localhost:61616">
<destination name="DestQueueA"/>
</binding.jms>
{code}
h4. Using the WebSphere client for JMS
The Tuscany JMS binding now (post Tuscany SCA 1.2) works the [WebSphere client
for JMS | http://www-1.ibm.com/support/docview.wss?uid=swg24012804] 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 |
http://apache.markmail.org/message/qufruqdwxuvaagev] for more information.
h3. JMS Message types and message body format
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:
{code}
<reference name="serviceA" promote="HelloWorldClient/serviceA">
<binding.jms messageProcessor="my.TestMessageProcessor" />
</reference>
{code}
For a complete example of using the messageProcessor attribute see the
[MessageProcessorTestCase|https://svn.apache.org/repos/asf/tuscany/java/sca/itest/jms/src/test/java/org/apache/tuscany/sca/binding/jms/MessageProcessorTestCase.java]
itest.
h3. Using policy to control the JMS binding
The JMS binding is aware of the following policy implementations.
- org.apache.tuscany.sca.binding.jms.policy.header.JMSHeaderPolicy
-- Used to set various JMS message headers including JMSType, JMSCorrelationID,
JMSDeliveryMode, JMSTimeToLive, JMSPriority and arbitrary user defined header
properties
-
org.apache.tuscany.sca.binding.jms.policy.authentication.token.JMSTokenAuthenticationPolicy
-- Used to insert a user defined authentication property into the JMS header.
Intents and policy sets can be constructed to control the application of these
policies. The following intents are defined by default
- pritority
- deliveryMode
New intents and policy sets can be designed are required to provide the level
of control you need over your application.
h4. Intent: priority
The priority intent provides a coarse grained approach to setting message
priority. For example,
{code}
<reference name="serviceA" promote="HelloWorldClient/serviceA"
requires="priotiry.meduim">
<binding.jms messageProcessor="my.TestMessageProcessor" />
</reference>
{code}
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.
{code}
<policySet name="JMSPolicySet1"
provides="priority"
appliesTo="sca:binding.jms">
<intentMap provides="priority" default="medium">
<qualifier name="high">
<tuscany:jmsHeader JMSPriority="9"/>
</qualifier>
<qualifier name="medium">
<tuscany:jmsHeader JMSPriority="4"/>
</qualifier>
<qualifier name="low">
<tuscany:jmsHeader JMSPriority="0"/>
</qualifier>
</intentMap>
</policySet>
{code}
h4. Intent: deliveryMode
The deliveryMode intent provides s simple way of specifying whether a message
should be delivered persistently or non-persistently. For example,
{code}
<reference name="serviceA" promote="HelloWorldClient/serviceA"
requires="deliveryMode.persistent">
<binding.jms messageProcessor="my.TestMessageProcessor" />
</reference>
{code}
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.
{code}
<policySet name="JMSPolicySet2"
provides="deliveryMode"
appliesTo="sca:binding.jms">
<intentMap provides="deliveryMode" default="nonPersistent">
<qualifier name="persistent">
<tuscany:jmsHeader JMSDeliveryMode="PERSISTENT"/>
</qualifier>
<qualifier name="nonPersistent">
<tuscany:jmsHeader JMSDeliveryMode="NON_PERSISTENT"/>
</qualifier>
</intentMap>
</policySet>
{code}
h4. Other header values
h3. JMS binding schema
The complete JMS binding SCDL schema has the following format:
{code}
<binding.jms correlationScheme="string"?
initialContextFactory="xs:anyURI"?
jndiURL="xs:anyURI"?
requestConnection="QName"?
responseConnection="QName"?
operationProperties="QName"?
... >
<destination name="xs:anyURI" type="string"? create="string"?>
<property name="NMTOKEN" type="NMTOKEN">*
</destination>?
<connectionFactory name="xs:anyURI" create="string"?>
<property name="NMTOKEN" type="NMTOKEN">*
</connectionFactory>?
<activationSpec name="xs:anyURI" create="string"?>
<property name="NMTOKEN" type="NMTOKEN">*
</activationSpec>?
<response>
<destination name="xs:anyURI" type="string"? create="string"?>
<property name="NMTOKEN" type="NMTOKEN">*
</destination>?
<connectionFactory name="xs:anyURI" create="string"?>
<property name="NMTOKEN" type="NMTOKEN">*
</connectionFactory>?
<activationSpec name="xs:anyURI" create="string"?>
<property name="NMTOKEN" type="NMTOKEN">*
</activationSpec>?
</response>?
<complexType name="SubscriptionHeaders">
<attribute name="JMSSelector" type="string"/>
</complexType>
<resourceAdapter name="NMTOKEN">?
<property name="NMTOKEN" type="NMTOKEN">*
</resourceAdapter>?
<headers JMSType="string"?
JMSCorrelationId="string"?
JMSDeliveryMode="string"?
JMSTimeToLive="int"?
JMSPriority="string"?>
<property name="NMTOKEN" type="NMTOKEN">*
</headers>?
<operationProperties name="string" nativeOperation="string"?>
<headers JMSType="string"?
JMSCorrelationId="string"?
JMSDeliveryMode="string"?
JMSTimeToLive="int"?
JMSPriority="string"?>
<property name="NMTOKEN" type="NMTOKEN">*
</headers>?
</operationProperties>*
</binding.jms>
{code}
(?) See the [JMS Binding Specification
1.0|http://www.osoa.org/download/attachments/35/SCA_JMSBinding_V100.pdf?version=2]
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.
{column}
{section}
---------------------------------------------------------------------
CONFLUENCE INFORMATION
This message is automatically generated by Confluence
Unsubscribe or edit your notifications preferences
http://cwiki.apache.org/confluence/users/viewnotifications.action
If you think it was sent incorrectly contact one of the administrators
http://cwiki.apache.org/confluence/administrators.action
If you want more information on Confluence, or have a bug to report see
http://www.atlassian.com/software/confluence
