| # |
| # Licensed to the Apache Software Foundation (ASF) under one |
| # or more contributor license agreements. See the NOTICE file |
| # distributed with this work for additional information |
| # regarding copyright ownership. The ASF licenses this file |
| # to you under the Apache License, Version 2.0 (the |
| # "License"); you may not use this file except in compliance |
| # with the License. You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, |
| # software distributed under the License is distributed on an |
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| # KIND, either express or implied. See the License for the |
| # specific language governing permissions and limitations |
| # under the License. |
| # |
| 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-<version>.rar file |
| to your JBoss deploy directory. By default this can be found at JBOSS_ROOT/server/<server-name>/deploy, |
| where JBOSS_ROOT denotes the root directory of your JBoss installation and <server-name> 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 |
| ==================== |
| <tx-connection-factory> |
| <jndi-name>QpidJMSXA</jndi-name> |
| <xa-transaction/> |
| <rar-name>qpid-ra-<ra-version>.rar</rar-name> |
| <connection-definition>org.apache.qpid.ra.QpidRAConnectionFactory</connection-definition> |
| <config-property name="ConnectionURL">amqp://guest:guest@/test?brokerlist='tcp://localhost:5672?sasl_mechs='PLAIN''</config-property> |
| <max-pool-size>20</max-pool-size> |
| </tx-connection-factory> |
| |
| 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:<jndi-name> |
| |
| For the previous example, this would resolve to |
| |
| java:QpidJMSXA |
| |
| Local ConnectionFactory |
| ======================= |
| <tx-connection-factory> |
| <jndi-name>QpidJMS</jndi-name> |
| <rar-name>qpid-ra-<ra-version>.rar</rar-name> |
| <local-transaction/> |
| <config-property name="UseLocalTx" type="java.lang.Boolean">true</config-property> |
| <config-property name="ConnectionURL">amqp://anonymous:@client/test?brokerlist='tcp://localhost:5672?sasl_mechs='PLAIN'' |
| </config-property> <connection-definition>org.apache.qpid.ra.QpidRAConnectionFactory</connection-definition> |
| <max-pool-size>20</max-pool-size> |
| </tx-connection-factory> |
| |
| 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 |
| |
| <mbean code="org.jboss.resource.deployment.AdminObject" |
| name="qpid.jca:name=HelloQueue"> |
| <attribute name="JNDIName">Hello</attribute> |
| <depends optional-attribute-name="RARName">jboss.jca:service=RARDeployment,name='qpid-ra-<ra-version>.rar'</depends> |
| <attribute name="Type">org.apache.qpid.ra.admin.QpidQueue/attribute> |
| <attribute name="Properties"> |
| DestinationAddress=amq.direct |
| </attribute> |
| </mbean> |
| |
| 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. For specific configuration options please see documentation for the Apache Qpid JMS Client for AMQP 0-9-1/0-10. |
| |
| <mbean code="org.jboss.resource.deployment.AdminObject" |
| name="qpid.jca:name=HelloTopic"> |
| <attribute name="JNDIName">HelloTopic</attribute> |
| <depends optional-attribute-name="RARName">jboss.jca:service=RARDeployment,name='qpid-ra-<ra-version>.rar'</depends> |
| <attribute name="Type">org.apache.qpid.ra.admin.QpidTopic</attribute> |
| <attribute name="Properties"> |
| DestinationAddress=amq.topic |
| </attribute> |
| </mbean> |
| |
| |
| 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. For specific configuration options please see documentation for Apache Qpid JMS Client for AMQP 0-9-1/0-10. |
| |
| |
| <mbean code="org.jboss.resource.deployment.AdminObject" |
| name="qpid.jca:name=QpidConnectionFactory"> |
| <attribute name="JNDIName">QpidConnectionFactory</attribute> |
| <depends optional-attribute-name="RARName">jboss.jca:service=RARDeployment,name='qpid-ra-<ra-version>.rar'</depends> |
| <attribute name="Type">javax.jms.ConnectionFactory</attribute> |
| <attribute name="Properties"> |
| ConnectionURL=amqp://anonymous:@client/test?brokerlist='tcp://localhost:5672?sasl_mechs='PLAIN'' |
| </attribute> |
| </mbean> |
| |
| 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. |
| |