jca/example/README-EXAMPLE.txt - qpid-broker-j - Git at Google

 #
 # 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 &amp; character. This file varies by app
 server. Please see the app server specific documentation for your platform for further details.
	#
	# 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.