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 to be jboss or set this property via the command line. Example: ant -Dtarget.platform=jboss **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-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 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 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: 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 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://:/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://:/qpid-jca-web/qpid?messsage= 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://:/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.