| # |
| # 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<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 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. |
| |
| ***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. |
| |