Qpid JCA Example

Overview
=======
The Qpid JCA example provides a sample JEE application that demonstrates how to
configure, install and run applications using the Qpid JCA adapter for EE
connectivity and the Apache Qpid C++ Broker. This example code can be used as a
convenient starting point for your own development and deployment
efforts. Currently the example is supported on JBoss EAP 5.x, JBoss 6.x and
Apache Geronimo 2.x.

Example Components
===================
Currently the example application consists of the following components:

Destinations and ConnectionFactories

Any messaging application relies on destinations (queues or topics )
in order to produce or consume messages.The Qpid JCA example provides
five destinations by default:

   HelloTopic
   GoodByeTopic
   HelloGoodByeTopic
   HelloQueue
   GoodByeQueue
   QpidResponderQueue


Similar to destinations, ConnectionFactories are a core component of both JMS
and JCA. ConnectionFactories provide the necessary starting point to make a connection,
establish a session and produce or consume (or both) messages from your JMS provider.

The Qpid JCA example provides three connection factories by default:

    QpidJMSXA
    QpidJMS
    QpidConnectionFactory

Each of these ConnectionFactories varies in their capabilities and the context in which
they should be used. These concepts will be explained later in this document.

The deployment configuration for destinations, and ConnectionFactories varies by platform.
In JBossEAP, the configuration mechanism is a *-ds.xml file. Geronimo 2.2.x has the notion
of a deployment plan in the form of a geronimo-ra.xml file.

The Qpid JCA Example provides both a qpid-jca-ds.xml file as well as a geronimo-ra.xml deployment
plan. Both mechanisms provide a reasonable set of defaults to allow you to deploy the Qpid JCA
adapter in either environment and get up and running quickly.

EJB 3.x

There are a six EJB 3.x components provided as part of the example.

   QpidHelloSubscriberBean - MessageDrivenBean (MDB)
   QpidGoodByeSubscriberBean - (MDB)
   QpidHelloListenerBean - (MDB)
   QpidGoodByeListenerBean - (MDB)
   QpidJMSResponderBean - (MDB)
   QpidTestBean - Stateless Session Bean (SLSB)

Servlet 2.5

    QpidTestServlet

A sample EE 2.5 servlet is provided allowing testing from a browser versus a JNDI
client

EE EAR archive
    An EAR wrapper for the ejb and web components.


    An RMI client used to excercise the EJB 3.x component.

Sample *-ds.xml file
    A sample *-ds.xml file is provided to create destinations and ManagedConnectionFactories
    in the JBoss environment.

Sample geronimo-ra.xml
    A sample geronimo-ra.xml file is provided to create destinations and ManagedConnectionFactories
    in the Geronimo environment. This file is semantically equivalent to the JBoss *-ds.xml artifact.

A build.xml file
    An ant build.xml file to configure, install and deploy the aforementioned components.


Requirements
============

Depending upon your target platform (eg. JBoss EAP or Geronimo) you will need to set either
the JBOSS_HOME or GERONIMO_HOME property. By default, these properties are assumed to be
set from your environment. This can be modified in the build.xml file.

JBoss EAP 5.x, JBoss 6.x
    To use the sample application you will need to have JBoss EAP 5.x or JBoss 6.x running.

Geronimo 2.x
    To use the sample application you will need to have Geronimo 2.x running.

Apache Qpid Broker
    To run the sample it is assumed you have an Apache Qpid C++ broker configured and running.
    The example code assumes that the broker will run at localhost on port 5672. This can be
    modified within the build.xml file if this does not suit your particular environment.


Quickstart
==========
After satifsying the above requirements you are ready to deploy and run the example application.
The steps to deploy and run in the supported application servers are largely the same, however,
if you are targeting JBoss you will either need to modify the property in the example build.xml file


    <property name="target.platform" value="geronimo"/>

to be jboss

    <property name="target.platform" value="jboss"/>

or set this property via the command line.

Example:

    ant -Dtarget.platform=jboss <target>

**Note**
Any time you wish to change platforms, this property needs to be modified and a complete clean
and rebuild needs to be performed.

Step 1 -- Package, Deploy and configure the Qpid JCA adapter

The core component of the example is the Qpid JCA adapter. The following lists the steps
for the respective platforms

**Note**

Regardless of platform, if you are building the Qpid JCA adapter from source code
you will need to use to package the RAR file via the Ant build system. To do this, from
the example directory execute

    ant deploy-rar

This task packages the adapter and includes the necessary dependent jar files.


JBoss
    There are no additional steps to package the adapter for JBoss deployment. Simply copy
    the qpid-ra-<qpid.version>rar to your JBoss deploy directory.

    To configure the Qpid JCA Adapter in JBoss the *-ds.xml file mechanism is used. A sample
    file is provided in the conf directory.

    If the defaults are suitable, you can simply execute

    ant deploy-ds

    While any property can be modified in the qpid-jca-ds.xml file, typically you will want to
    change the URL of the broker to which you are trying to connect. Rather than modifying
    the qpid-jca-ds.xml file directly you can modify the

       <property name="broker.url" value="amqp://anonymous:@client/test?brokerlist='tcp://localhost:5672?sasl_mechs='ANONYMOUS''"/>

    line in the build.xml file. This will dynamically insert the broker.url value into the qpid-jca-ds.xml file.

    Once this file is copied to your JBoss deploy directory and you received no exceptions, the adapter is now deployed, configured
    and ready for use.

Geronimo
    By default, the Qpid JCA adapter ships with the geronimo-ra.xml deployment plan embedded
    in the RAR file. This file is located in the META-INF directory alongside the ra.xml file.
    By default the adapter is configured to access a broker located at localhost with the
    default port of 5672. The ANONYMOUS security mechanism is also in use. If this is not
    desirable, you have two approaches to configure the adapter.


    1) Extract the META-INF/ra.xml file from the RAR file, modify and recompress the RAR archive
       with the updated contents.

    2) Use the example build system to package the adapter. The example build.xml file includes
       a target

       package-rar

       that can be used to package the RAR file as well as allowing changes to the geronimo-ra.xml
       file without having to extract the RAR file by hand. The conf/geronimo-ra.xml file is used
       when you use the example build system.

       While any property can be modified in the geronimo-ra.xml file, typically you will want to
       change the URL of the broker to which you are trying to connect. Rather than modifying
       the geronimo-ra.xml file directly you can modify the


       <property name="broker.url" value="amqp://anonymous:@client/test?brokerlist='tcp://10.0.1.44:5672?sasl_mechs='ANONYMOUS''"/>

       line in the build.xml file. This will dynamically insert the broker.url value into the geronimo-ra.xml file.

       Once you have made your modifications you can execute


       ant clean package-rar deploy-rar

       Note, your Geronimo server must be running and your GERONIMO_HOME environment variable must be set. Barring any exceptions, the
       adapter is now deployed and ready for use in Geronimo.


Step 2 -- Deploy the application component(s).

As previously mentioned, the adapter comes with a variety of EE components for use in your respective application server. You can choose to deploy
these components individually, or as a single EAR archive. This document assumes that you will use the EAR to deploy and run the example.

The command to package and deploy the EAR archive is the same across application servers. Executing the following command

ant deploy-ear

will, depending upon platform, package the EAR and deploy the archive in your respective environment. Once this step is executed, the example
is ready for use.


Step 3 -- Test the Example

The Qpid JCA example provides an EJB application, as well as a Web application. Both can be used to test/run the example:

EJB
If you want to use the EJB application to test the example you can execute

    ant run-client

Running this command will perform a JNDI lookup of the SLSB in either JBoss or Geronimo and send a simple string to the SLSB. The SLSB will receive
this string, construct a JMS message and place this message on a configured queue. The MDB will in turn receive this message and print the contents
to the console.

The main properties involved in this task are

server.host
jndi.context

These vary depending upon which application server you are runnning. These can be modified to suit your environment. Looking at the run-client task you
will see the following:


            <sysproperty key="qpid.ejb.name" value="qpid-jcaex/QpidTestBean/remote"/>

This is the JNDI name of the SLSB component and it varies by application server. Typically you do not have to change this. Also, the task supports another property


            <sysproperty key="qpid.message" value="insert-value-here"/>

You can set this property if you want to modify the message contents being routed through the system.

Web
The Qpid JCA Example comes with a web application. To access the web component, simply use a browser of your choice and navigate to

http://<server-host-name>:<server-port>/qpid-jca-web/qpid

where server-host and server-port are the host and port where you are running your application server. By default this is localhost:8080. Similar to the EJB component,
the web application supports a few options:


http://<server-host-name>:<server-port>/qpid-jca-web/qpid?messsage=<yourmessage>

will allow you to customize the message contents that are routed through the system. By default, the Web application posts to a configured queue in the system. If you want to
test XA functionality, or use an alternate approach, you can specify


http://<server-host-name>:<server-port>/qpid-jca-web/qpid?useEJB=true

instead of posting to a queue, the web application will use the local interface of the EJB component to send the message. This is functionally equivalent to running the
RMI client.


Summary
=======
While conceptually simple, the Qpid JCA example provides a majority of the component types and messaging patterns you are most likely to use your development efforts.
With the Web and EJB components, you can experiment with various aspects of JCA as well as EE development in general using the Qpid Broker as your messaging provider.
While this documentation highlights the major components and steps needed to take to get the example running, the possiblities for modifcation are numerous. You are
encouraged to experiment with the example as you develop your own messaging applications.


