diff options
Diffstat (limited to 'qpid/java/jca/example')
| -rw-r--r-- | qpid/java/jca/example/README-EXAMPLE.txt | 235 | ||||
| -rw-r--r-- | qpid/java/jca/example/README-GERONIMO.txt | 69 | ||||
| -rw-r--r-- | qpid/java/jca/example/README-GLASSFISH.txt | 84 | ||||
| -rw-r--r-- | qpid/java/jca/example/README-JBOSS.txt | 107 | ||||
| -rw-r--r-- | qpid/java/jca/example/README-JBOSS7.txt | 116 | ||||
| -rw-r--r-- | qpid/java/jca/example/README.txt | 316 | ||||
| -rw-r--r-- | qpid/java/jca/example/build.xml | 2 | ||||
| -rw-r--r-- | qpid/java/jca/example/conf/qpid-standalone.xml (renamed from qpid/java/jca/example/conf/standalone.xml) | 0 |
8 files changed, 612 insertions, 317 deletions
diff --git a/qpid/java/jca/example/README-EXAMPLE.txt b/qpid/java/jca/example/README-EXAMPLE.txt new file mode 100644 index 0000000000..3a2ee0c38e --- /dev/null +++ b/qpid/java/jca/example/README-EXAMPLE.txt @@ -0,0 +1,235 @@ +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 JEE +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. + +Example Components +=================== +Currently the example application consists of the following components: + +Destinations +============ +Any messaging application relies on destinations (queues or topics ) +in order to produce or consume messages.The Qpid JCA example provides +the following destinations: + + HelloTopic + GoodByeTopic + HelloQueue + GoodByeQueue + QpidRequestQueue + QpidResponseQueue + +Each destination is configured for the respective application server in which +the examples will be run. Generally the example application allows for sending +messages to a Hello<DestinationType>. Depending on a configuration option, once +a message is received by the Hello component, the Hello component can also be +sent to a GoodBye<DestinationType> component. + +The QpidRequest/Response destinations provide the destinations for the +request/reponse messaging pattern. + + +ConnectionFactories +=================== +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. By default, the Qpid JCA examples use the QpidJMSXA connection factory +which provides for full XA transaction support. The QpidJMS connection factory provides a +local JMS transaction CF and is currently deprecated, though it has been maintained for +backwards compatibility. The QpidConnectionFactory is a specialized ConnectionFactory designed +to be used outside of a JEE application server. This CF has been provided to support non-managed +clients that want to use the JNDI facilities of JEE. + +The deployment configuration for destinations, and ConnectionFactories varies by JEE platform. +Please see the application server specific documentation for specific instructions. + +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) + +Generally, the name of the EJB component corresponds to the aforementioned destinations +listed above in the consumption of messages. + +QpidTestServlet +A sample EE 2.5 servlet is provided allowing testing from a browser versus a RMI or JMS +based client. + +QpidTestClient +A Java based client allowing for both RMI or JMS access to the sample application. RMI or +JMS access is based on configuration options. + +QpidRequestResponseClient +A Java based client allowing for a request/response application. + +EE EAR archive + An EAR wrapper for the ejb and web components. + +A build.xml file + An ant build.xml file to configure, install and deploy the aforementioned components. + +Requirements +============ +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. The broker +address can be modified in the build-properties.xml file. + +Examples +=============== +Using the Qpid JCA examples is the same regardless of preferred JEE application server. +The provided clients and supported options are listed below. + +QpidTestClient +============== +As previously mentioned, the Qpid JCA example provides an RMI/JMS Java client to test +the application. Executing the command + +ant-run client + +will execute the QpidTestClient client with the default options. + +QpidTestClient Options + +client.use.ejb (build.xml) +Setting this value to false will result in the QpidTestClient using JMS to send messages to +the configured destination. +Default:true + +client.message +The text content of the JMS message sent to the configured destination. +Default: Hello Qpid World! + +client.message.count +The number of messages that will be sent to the configured destionation. +Default: 1 + +client.use.topic +Setting this value to true will send messages to HelloTopic versus HelloQueue. +Default:false + +client.say.goodbye +Setting this value to true will cause the listener on the Hello Queue/Topic to send a +message to the GoodBye Queue/Topic +Default:false + + +QpidRequestResponseClient +========================= +Similar to the QpidTestClient, the QpidRequestResponseClient is a Java based application that allows for +sending messages to a destination. The QpidRequestResponseClient also provides the capability for the +application to listen for a response. Executing the command + +ant run-reqresp + +will run the application with the default options. + +QpidRequestResponseClient Options + +QpidTestServlet +=============== +Similar to the QpidTestClient application, the Qpid JCA examples also provides a JEE Servlet to test and run the +application. This Servlet can be used as an alternative, or in conjunction with the Java application. The Servlet +can be reached via the following URL: + +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. + +QpidTestServlet Options + +The QpidTestServlet options can be configured by appending certain values to the above URL. These values are +listed below and generally correspond, both in name and purpose, to the Java application configuration options. + +message +The text content of the JMS message sent to the configured destination. +Default: Hello World! + +useEJB +Setting this value to true will result in the QpidTestServlet using the QpidTestBean SLSB to +send the message to the configured destination. By default the QpidTestServlet uses JMS. +Default:false + +count +The number of messages that will be sent to the configured destionation. +Default: 1 + +useTopic +Setting this value to true will send messages to HelloTopic versus HelloQueue. +Default:false + +sayGoodBye +Setting this value to true will cause the listener on the Hello Queue/Topic to send a +message to the GoodBye Queue/Topic +Default:false + +useXA +Setting this value to true will cause the QpidTestServlet to do all activity within the +context of an XA transaction. +Default:false + +useTX +Setting this value to true will cause the QpidTestServlet to do all activity within the +context of a JMS transation. +Default:false + + +Note, the useXA and useTX are mutually exclusive. Setting both to true, the QpidTestServlet +will choose XA over a JMS transaction. + +QpidRequestResponseServlet +========================== +Similar to the QpidRequestResponseClient application, the Qpid JCA examples also provides a JEE Servlet +to execute the request/response type messaging pattern. The Servlet can be reached via the following url: + +http://<server-host-name>:<server-port>/qpid-jca-web/qpid-reqresp + +where server-host and server-port are the host and port where you are running your application server. + +QpidRequestResponseServlet Options + +message +The text content of the JMS message sent to the configured destination. +Default: Hello World! + +count +The number of messages that will be sent to the configured destionation. +Default: 1 + +useXA +Setting this value to true will cause the QpidTestServlet to do all activity within the +context of an XA transaction. +Default:false + +Summary +======= +While conceptually simple, the Qpid JCA examples provide 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 work +to develop your own messaging applications. + + diff --git a/qpid/java/jca/example/README-GERONIMO.txt b/qpid/java/jca/example/README-GERONIMO.txt new file mode 100644 index 0000000000..d58d034c79 --- /dev/null +++ b/qpid/java/jca/example/README-GERONIMO.txt @@ -0,0 +1,69 @@ +Qpid JCA Example - Apache Geronimo 2.x + +Overview +======== +This document explains the steps required to configure and +deploy the Qpid JCA examples for the Apache Geronimo environment. +General information can be found in the README.txt file. + +The Apache Geronimo environment provides two methods for deploying +JEE application components: the web-based administration console and the +command line based deployment environment. This document only explains +the command line environment. Please see the Apache Geronimo 2.x +documentation for the web-based console. + +Requirements +============ +In order to deploy the Qpid JCA adapter, as well as the example application, +the GERONIMO_HOME environemnt variable must be set. The environment variable +should point to the root of your Apache Geronimo 2.x install directory. + +In order to automatically deploy the Qpid JCA Adapter, the QPID_JCA_HOME +environment variable needs to be set. The environment variable should point +to the directory which contains the Qpid JCA Adapter. If building from the +source tree, by default this can be found at + +QPID_ROOT/java/build/lib + +If installing from RPM or other binary distribution, this can vary by platform. + +Prior to deploying any application component, the Apache Geronimo application +should be started and available for requests. + + +Deploy the Qpid JCA Adapter +============================== +Once the above requirements are satisfied the command + +ant deploy-rar + +will attempt to use the Apache Geronimo deployer to install the Qpid JCA +adapter into the Apache Geronimo environment. Any errors will be reported +back to the client for further examination. Once the above command executes +successfully, the Qpid JCA adapter has been deployed, configured and is ready +for use. + + +Deploy the Qpid JCA Examples +============================ +After the Qpid JCA adapter is deployed, executing the command + +ant deploy-ear + +will attempt to use the Apache Geronimo deploy to install the Qpid JCA +example EAR into the Apache Geronimo environment. Any errors will be reported +back to the client for further examination. Once the above command executes +successfully, the Qpid JCA example application is deployed, configured and ready +for use. + +The build-geronimo-properties.xml file contain Apache Geronimo specific values +and Ant targets that can be used to suit your development requirements. + +The README.txt file in this directory provides the necessary instructions for using the Qpid JCA +adapter and example application. + + + + + + diff --git a/qpid/java/jca/example/README-GLASSFISH.txt b/qpid/java/jca/example/README-GLASSFISH.txt new file mode 100644 index 0000000000..1b73ba68fd --- /dev/null +++ b/qpid/java/jca/example/README-GLASSFISH.txt @@ -0,0 +1,84 @@ +Qpid JCA Example - Glassfish 3.x + +Overview +======== +This document explains the steps required to configure and +deploy the Qpid JCA examples for the Glassfish 3.x environment. + +The Glassfish environment provides two methods for deploying +JEE application components: the web-based administration console +and the asadmin command line utility. This document only explains +the command line utility. Please see the Glassfish 3.x +documentation for the web-based console approach. + +Requirements +============ +In order to deploy the Qpid JCA adapter, as well as the example application, +the GLASSFISH_HOME environemnt variable must be set. The environment variable +should point to the root of your Glassfish installation. + +In order to automatically deploy the Qpid JCA Adapter from the build system, +the QPID_JCA_HOME environment variable needs to be set. +The environment variable should point to the directory which contains the +Qpid JCA Adapter. If building from the source tree, by default this can be found at + +QPID_ROOT/java/build/lib + +If installing from RPM or other binary distribution, this can vary by OS platform. + +The Qpid JCA examples assume the Apache Geronimo application server as the default +target platform. This can be modified in two ways: + +1) Modify the build.xml file and change the target.platform property: + +Example: + + <!-- Valid target platforms are currently geronimo, jboss, jboss7, glassfish --> + <property name="target.platform" value="glassfish"/> + +2) Set the target.platform property via the command line: + +Example: + +ant -Dtarget.platform=glassfish <target> + +Note, if you choose the second method, all command line invocations must include +the target.platform variable. For the remainder of this document, we will assume +the second approach. + +Prior to deploying any application component, the Glassfish application server +should be started and available for requests. + + +Deploy and configure the Qpid JCA Adapter +============================== +Once the above requirements are satisfied the command + +ant -Dtarget.platform=glassfish deploy-rar + +will attempt to invoke the asadmin utility to deploy and configure the +Qpid JCA adapter. Once this step completes succesfully the Qpid JCA adapter +is deployed, configured and ready for use. + + +Deploy the Qpid JCA Examples +============================ +After the Qpid JCA adapter is deployed, executing the command + +ant -Dtarget.platform=glassfish deploy-ear + +will attempt to deploy the Qpid JCA example EAR into the Glassfish environment. +Once the above command executes successfully, the Qpid JCA example application +is deployed, configured and ready for use. + +The build-glassfish-properties.xml file contains Glassfish specific configuration options +and Ant targets that can be used to suit your development requirements. Executing + +ant -Dtarget.platform=glassfish -p + +will list the appropriate targets and provide a simple description for each. + +The README.txt file in this directory provides the necessary instructions for using +the Qpid JCA adapter and example application which is consistent across all supported +JEE platforms. + diff --git a/qpid/java/jca/example/README-JBOSS.txt b/qpid/java/jca/example/README-JBOSS.txt new file mode 100644 index 0000000000..e23b3ba308 --- /dev/null +++ b/qpid/java/jca/example/README-JBOSS.txt @@ -0,0 +1,107 @@ +Qpid JCA Example - JBoss EAP 5.x, JBoss 5.x, 6.x + +Overview +======== +This document explains the steps required to configure and +deploy the Qpid JCA examples for both the JBoss EAP 5.x +environment as well as the JBoss 5.x/6.x community edition +(herafter simply referred to as JBoss). General information +can be found in the README.txt file. + +Requirements +============ +In order to deploy the Qpid JCA adapter, as well as the example application, +the JBOSS_HOME environemnt variable must be set. The environment variable +should point to the root of your JBoss installation. + +In order to automatically deploy the Qpid JCA Adapter from the build system, +the QPID_JCA_HOME environment variable needs to be set. +The environment variable should point to the directory which contains the +Qpid JCA Adapter. If building from the source tree, by default this can be found at + +QPID_ROOT/java/build/lib + +If installing from RPM or other binary distribution, this can vary by platform. + +If you do not want to use the build system to deploy the Qpid JCA adapter, you +can simply copy the qpid-ra-0.<version>.rar file to the + +JBOSS_HOME/server/<server-name>/deploy + +directory. By default, the example assumes the JBoss 'default' server profile will +be used. This can be modified in the build-jboss-properties.xml file. + +The Qpid JCA examples assume the Apache Geronimo application server as the default +target platform. This can be modified in two ways: + +1) Modify the build.xml file and change the target.platform property: + +Example: + + <!-- Valid target platforms are currently geronimo, jboss, jboss7, glassfish --> + <property name="target.platform" value="jboss"/> + +2) Set the target.platform property via the command line: + +Example: + +ant -Dtarget.platform=jboss <target> + +Note, if you choose the second method, all command line invocations must include +the target.platform. For the remainder of this document, we will assume the second +approach. + +Prior to deploying any application component, the JBoss application server +should be started and available for requests. + + + + +Deploy and configure the Qpid JCA Adapter +============================== +Once the above requirements are satisfied the command + +ant -Dtarget.platform= jboss deploy-rar + +will copy the Qpid JCA adapter to JBoss server deploy directory. + +To configure JCA resources in the JBoss environment, the *-ds.xml configuration file +is used. The command + +ant -Dtarget.platform=jboss deploy-ds + +will accomplish this task using the defaults provided. Any errors will be reported +in the + +JBOSS_HOME/server/<server-name>/log/server.log + +file or on the console. + +Once the above commands execute successfully, the Qpid JCA adapter is deployed, configured +and ready for use. + + +Deploy the Qpid JCA Examples +============================ +After the Qpid JCA adapter is deployed, executing the command + +ant -Dtarget.platform=jboss deploy-ear + +will attempt to deploy the Qpid JCA example EAR into the JBoss environment. +Once the above command executes successfully, the Qpid JCA example application is deployed, +configured and ready for use. + +Note, if making modifications to either the Qpid JCA adapter or *-ds.xml configuration, the +EAR archive will need to be redeployed. This is a JBoss JCA issue and not due to the Qpid JCA +adapter. + +The build-jboss-properties.xml file contains JBoss specific configuration options +and Ant targets that can be used to suit your development requirements. + +The README.txt file in this directory provides the necessary instructions for using the Qpid JCA +adapter and example application which is consistent across all supported JEE platforms. + + + + + diff --git a/qpid/java/jca/example/README-JBOSS7.txt b/qpid/java/jca/example/README-JBOSS7.txt new file mode 100644 index 0000000000..7a3e0db01a --- /dev/null +++ b/qpid/java/jca/example/README-JBOSS7.txt @@ -0,0 +1,116 @@ +Qpid JCA Example - JBoss AS 7 + +Overview +======== +This document explains the steps required to configure and +deploy the Qpid JCA examples for the JBoss AS 7 environment. +General information about the example can be found in the +README-EXAMPLE.txt file. + +Requirements +============ +In order to deploy the Qpid JCA adapter, as well as the example application, +the JBOSS_HOME environemnt variable must be set. The environment variable +should point to the root of your JBoss installation. + +In order to automatically deploy the Qpid JCA Adapter from the build system, +the QPID_JCA_HOME environment variable needs to be set. +The environment variable should point to the directory which contains the +Qpid JCA Adapter. If building from the source tree, by default this can be found at + +QPID_ROOT/java/build/lib + +If installing from RPM or other binary distribution, this can vary by platform. + +If you do not want to use the build system to deploy the Qpid JCA adapter, you +can simply copy the qpid-ra-0.<version>.rar file to the + +JBOSS_HOME/<server-profile>/deployments + +directory. By default, the example assumes the JBoss 'standalone' server profile will +be used. This can be modified in the build-jboss7-properties.xml file. + +The Qpid JCA examples assume the Apache Geronimo application server as the default +target platform. This can be modified in two ways: + +1) Modify the build.xml file and change the target.platform property: + +Example: + + <!-- Valid target platforms are currently geronimo, jboss, jboss7, glassfish --> + <property name="target.platform" value="jboss7"/> + +2) Set the target.platform property via the command line: + +Example: + +ant -Dtarget.platform=jboss7 <target> + +Note, if you choose the second method, all command line invocations must include +the target.platform. For the remainder of this document, we will assume the second +approach. + +As opposed to earlier versions of JBoss AS, JBoss AS 7 uses a different approach for +configuring JCA resources. JBoss AS 7 provides support for different server profiles +each configured through an XML based configuration file. In order to configure the +Qpid JCA adapter for the JBoss AS 7 environment, a complete XML configuration has been +provided in the conf/ directory as conf/qpid-standalone.xml. In order to configure this +file execute the following command: + +ant -Dtarget.platform=jboss7 generate + +The result of this command will produce a file build/gen/qpid-standalone.xml file. To +deploy this file copy the file to: + +JBOSS_HOME/standalone/configuration + +directory. + +Prior to deploying any application component, the JBoss application server +should be started and available for requests. In order to use the qpid-standalone.xml +file generated in the previous step, when starting JBoss AS 7 invoke the following: + +./standalone.sh -c qpid-standalone.xml + + +Note, the above method completely replaces the default messaging provider in JBoss AS 7. +Currently there is no way to have two separate messaging providers deployed within the same +server. It assumed that this will be addressed in a later version of JBoss AS 7. + + +Deploy the Qpid JCA Adapter +============================== +Once the above requirements are satisfied the command + +ant -Dtarget.platform=jboss7 deploy-rar + +will copy the Qpid JCA adapter to JBoss AS 7 server deploy directory. + +Once the above commands execute successfully, the Qpid JCA adapter is deployed, configured +and ready for use. + + +Deploy the Qpid JCA Examples +============================ +After the Qpid JCA adapter is deployed, executing the command + +ant -Dtarget.platform=jboss7 deploy-ear + +will attempt to deploy the Qpid JCA example EAR into the JBoss AS 7 environment. +Once the above command executes successfully, the Qpid JCA example application is +deployed, configured and ready for use. + +Note, currently there is an issue with 'hot-deployment' in the JBoss AS 7 environment. +If you need to re-deploy the EAR file, restarting JBoss AS 7 is required. + +The build-jboss7-properties.xml file contains JBoss AS 7 specific configuration options +and Apache Ant targets that can be used to suit your development requirements. + +The README.txt file in this directory provides the necessary instructions for using the Qpid JCA +adapter and example application which is consistent across all supported JEE platforms. + + + + + + diff --git a/qpid/java/jca/example/README.txt b/qpid/java/jca/example/README.txt deleted file mode 100644 index eccdf1377f..0000000000 --- a/qpid/java/jca/example/README.txt +++ /dev/null @@ -1,316 +0,0 @@ -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, -Apache Geronimo 2.x and Glassfish 3.1.1. - -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. Similarly, Glassfish 3.1.1 uses -the glassfish-resources.xml file. - -The Qpid JCA Example provides a sample qpid-jca-ds.xml, geronimo-ra.xml and glassfish-resources.xml file. -Each file provides reasonable set of defaults to allow you to deploy the Qpid JCA -adapter in the supported environments 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. - -Sample glassfish-resources.xml - A sample glassfish-resources.xml file is provided to create JMS destinations and - ManagedConnectionFactories in the Glassfish environemnt. - -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, -you need to specify the target platform environment to which you are attempting to deploy. - - <property name="target.platform" value="jboss"/> - <property name="target.platform" value="geronimo"/> - <property name="target.platform" value="glassfish"/> - -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. - - -Glassfish - As previously mentioned, the Glassfish environment uses the glassfish-resources.xml file to configure AdminObjects and ManagedConnectionFactories. - A sample file is provided. To deploy the file simply execute: - - ant deploy-rar - - If building from the Qpid source tree, this will package and deploy the qpid-ra-<version>.rar file as well as configure the adapter. If you are - not building from source, the adapter will be configured correctly via the glassfish-resources.xml file. - - -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. - -JMS -If you do not want to use EJB and prefer to test the Qpid JCA adapter using the standard JMS API's, simply set the following property - - <property name="client.use.ejb" value="true"/> <!-- uses JNDI/JMS or JNDI/RMI --> - -as - - <property name="client.use.ejb" value="false"/> <!-- uses JNDI/JMS or JNDI/RMI --> - - -Request/Reply - -The EJB/JMS client simply sends a message to a destination and does not receive a response. The Qpid JCA examples includes a request-reply -example to allow you to receive a response. The following command: - -ant run-reqresp - -will execute this example. A variety of configuration options for both the EJB/JMS and Request/Reply are provided. Please see the build.xml file for more details. - -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. - - -Similar to the Request/Reply example, a Request/Reploy Servlet is provided as well. To access this servlet navigate to the above URL: - - -http://<server-host-name>:<server-port>/qpid-jca-web/qpid-reqresp - -A reasonable set of defaults is provided which can be further tuned and configured to suit your development needs. - - -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. - - diff --git a/qpid/java/jca/example/build.xml b/qpid/java/jca/example/build.xml index 64d70d3499..7a75f9abc6 100644 --- a/qpid/java/jca/example/build.xml +++ b/qpid/java/jca/example/build.xml @@ -20,7 +20,7 @@ --> <project name="qpid-jca-example" default="help" basedir=""> - <!-- Valid target platforms are currently geronimo & jboss --> + <!-- Valid target platforms are currently geronimo, jboss, jboss7, glassfish --> <property name="target.platform" value="geronimo"/> <!-- Change to BURL for older syntax support --> diff --git a/qpid/java/jca/example/conf/standalone.xml b/qpid/java/jca/example/conf/qpid-standalone.xml index 8d6137aea7..8d6137aea7 100644 --- a/qpid/java/jca/example/conf/standalone.xml +++ b/qpid/java/jca/example/conf/qpid-standalone.xml |