# # 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 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. Depending on a configuration option, once a message is received by the Hello component, the Hello component can also be sent to a GoodBye 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://:/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://:/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. ***Note*** Due to the way Ant handle XML escape characters in the Copy task, if you are attempting to deploy the examples to a clustered broker configuration, you will need to modify the resultant XML configuration file to remove the '&' character and replace it with the & character. This file varies by app server. Please see the app server specific documentation for your platform for further details.