diff options
Diffstat (limited to 'qpid/java/jca/example/README.txt')
| -rw-r--r-- | qpid/java/jca/example/README.txt | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/qpid/java/jca/example/README.txt b/qpid/java/jca/example/README.txt new file mode 100644 index 0000000000..d94bbfa7e5 --- /dev/null +++ b/qpid/java/jca/example/README.txt @@ -0,0 +1,277 @@ +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. + + |