#
# 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.