From 8581b766bdd0fe06b128ea0f4fdf814435e618cb Mon Sep 17 00:00:00 2001 From: Andrew Stitcher Date: Sun, 18 Dec 2011 05:09:07 +0000 Subject: QPID-3044: Implement JCA Adapter for Java JMS client - Large contributions from Weston Price & Kevin Conner git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1220336 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/java/jca/README-JBOSS.txt | 168 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 qpid/java/jca/README-JBOSS.txt (limited to 'qpid/java/jca/README-JBOSS.txt') diff --git a/qpid/java/jca/README-JBOSS.txt b/qpid/java/jca/README-JBOSS.txt new file mode 100644 index 0000000000..77bf91e6dd --- /dev/null +++ b/qpid/java/jca/README-JBOSS.txt @@ -0,0 +1,168 @@ +Qpid JCA Resource Adapter + +JBoss EAP 5.x Installation and Configuration Instructions + +Overview +======== +The Qpid Resource Adapter is a JCA 1.5 compliant resource adapter that allows +for JEE integration between EE applications and AMQP 0.10 message brokers. + +The adapter provides both outbound and inbound connectivity and +exposes a variety of options to fine tune your messaging applications. +Currently the adapter only supports C++ based brokers and has only been tested with Apache Qpid C++ broker. + +The following document explains how to configure the resource adapter for deployment in JBoss EAP 5.x. + + +Deployment +========== +To deploy the Qpid JCA adapter for either JBoss EAP, simply copy the qpid-ra-.rar file +to your JBoss deploy directory. By default this can be found at JBOSS_ROOT/server//deploy, +where JBOSS_ROOT denotes the root directory of your JBoss installation and denotes the +name of your deployment server. A successful adapter installation will be accompanied by the +following INFO message: + + INFO [QpidResourceAdapter] Qpid resource adaptor started + +At this point the adapter is deployed and ready for configuration. + +Configuration Overview +====================== +The standard configuration mechanism for 1.5 JCA adapters is the ra.xml +deployment descriptor. Like other EE based descriptors this file can be found +in the META-INF directory of the provided EE artifact (ie .rar file). A majority +of the properties in the ra.xml will seem familiar to anyone who has worked with +Apache Qpid in a standalone environment. A reasonable set of configuration defaults +have been provided. + +The resource adapter configuration properties provide generic properties for both +inbound and outbound connectivity. These properties can be overridden when deploying +managed connection factories as well as inbound activations using the standard JBoss +configuration artifacts, the *-ds.xml file and MDB activation spec . A sample *-ds.xml file, +qpid-jca-ds.xml, can be found in your Qpid JCA resource adapter directory. + +The general README.txt file provides a detailed description of all the properties associated +with the Qpid JCA Resource adapter. Please consult this file for further explanation of +how configuration properties are treated within the Qpid JCA adapter. + +ConnectionFactory Configuration +====================================== +As per the JCA specification, the standard outbound-connectivity component is the +ConnectionFactory. In EAP 5.x ConnectionFactories are configured +via the *-ds.xml file. As previously mentioned, a sample *-ds.xml file, qpid-jca-ds.xml +hasbeen provided with your distribution. This file can be easily modified to suit +your development/deployment needs. The following describes the ConnectionFactory +portion of the sample file. + +XA ConnectionFactory +==================== + + QpidJMSXA + + qpid-ra-.rar + org.apache.qpid.ra.QpidRAConnectionFactory + amqp://guest:guest@/test?brokerlist='tcp://localhost:5672?sasl_mechs='ANONYMOUS'' + 20 + + +The QpidJMSXA connection factory defines an XA capable ManagedConnectionFactory. You will need to insert your particular rar version for +the rar-name property. The jndi-name and connectionURL property are both configurable and can be modified for your environment. After deployment +the ConnectionFactory will be bound into JNDI under the name + +java: + +For the previous example, this would resolve to + +java:QpidJMSXA + +Local ConnectionFactory +======================= + + QpidJMS + qpid-ra-0.10.rar + + true + amqp://anonymous:@client/test?brokerlist='tcp://localhost:5672?sasl_mechs='ANONYMOUS'' + org.apache.qpid.ra.QpidRAConnectionFactory + 20 + + +The QpidJMS connection factory defines a non XA connection factory. Typically this is used as a specialized ConnectionFactory where either XA +is not desired, or you are running with a clustered Qpid Broker configuration which at this time, does not support XA. The configuration +properties mirror those of the XA ConnectionFactory. + +Admininstered Object Configuration +================================== +Destinations (queues, topics) are configured in EAP via JCA standard Administered Objects (AdminObjects). These objects +are placed within the *-ds.xml file alongside your ConnectionFactory configurations. The sample file qpid-jca-ds.xml +provides two such objects + + + Hello + jboss.jca:service=RARDeployment,name='qpid-ra-0.10.rar' + javax.jms.Destination + + destinationType=QUEUE + destinationAddress=amq.direct + + + +The above XML defines a JMS Queue which is bound into JNDI as + +queue/HelloQueue + +This destination can be retrieved from JNDI and be used for the consumption or production of messages. The desinationAddress property +can be customized for your environment. Please see the Qpid Java Client documentation for specific configuration options. + + + HelloTopic + jboss.jca:service=RARDeployment,name='qpid-ra-0.10.rar' + javax.jms.Destination + + destinationType=TOPIC + destinationAddress=amq.topic + + + + +The above XML defines a JMS Topic which is bound into JNDI as + +HelloTopic + +This destination can be retrieved from JNDI and be used for the consumption or production of messages. The desinationAddress property +can be customized for your environment. Please see the Qpid Java Client documentation for specific configuration options. + + + + QpidConnectionFactory + jboss.jca:service=RARDeployment,name='qpid-ra-0.10.rar' + javax.jms.ConnectionFactory + + connectionURL=amqp://anonymous:@client/test?brokerlist='tcp://localhost:5672?sasl_mechs='ANONYMOUS'' + + + +The above XML defines a ConnectionFactory that can be used external to EAP 5.x. Typically this connection factory +is used by standalone or 'thin' clients that do not require an application server. This object is bound into +the EAP 5.x JNDI tree as + +QpidConnectionFactory + +ActivationSpec Configuration +============================ +The standard method for inbound communication is the MessageDrivenBean architecture with is configured +via the ActivationSpec mechanism. Please see the general README.tx file for an explanation of the +QpidActivationSpec, as well as general inbound connectivity options. + +An ActivationSpec can either be configured via the Java Annotation mechanism, or in the ejb-jar.xml deployment +descriptor. + +Summary +======= +The above description for the Qpid JCA adapter for EAP 5.x is just a general guide for deploying and configuring +the Qpid JCA adapter. The sample file provided can be easily modified and it is expected you will do so to +conform to your own environment. + -- cgit v1.2.1