SCA Java binding.jms (TUSCANY) edited by ant
Page:
http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+binding.jms
Changes:
http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=57033&originalVersion=18&revisedVersion=19
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.
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 then 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 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 sample 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. 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.
(/) All JNDI lookups are first tried in the java:comp/env namespace so when
running Tuscany in a JEE environment resource aliases may be used to map
Tuscany JMS resources to actual resources.
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/incubator/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/incubator/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 META-INF/context.xml file to define the JMS
resources in JNDI.
h4. JEE application servers such as Apache Geronimo, WebSphere etc
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}
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>?
<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"?>
<property name="NMTOKEN" type="NMTOKEN">*
<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. Additionally, support for the
requestConnection, responseConnection, and operationProperties attributes has
not yet been implemented but this should get done shortly.
(!) 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
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
