Merge branch 'QPID-3957' into trunk

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1328987 13f79535-47bb-0310-9956-ffa450edef68

9 files changed, 648 insertions, 374 deletions

diff --git a/qpid/java/jca/README.txt b/qpid/java/jca/README.txt
index 29e6825c4c..6fdd028349 100644
--- a/qpid/java/jca/README.txt
+++ b/qpid/java/jca/README.txt
@@ -5,7 +5,7 @@ Overview
 The Qpid Resource Adapter is a JCA 1.5 compliant resource adapter that allows
 for JEE integration between EE applications and AMQP 0.10  message brokers.
 
-The adapter provides both outbound and inbound connectivity and
+The Qpid JCA adapter provides both outbound and inbound connectivity and
 exposes a variety of options to fine tune your messaging applications. Currently
 the adapter only supports C++ based brokers and has only been tested with Apache Qpid C++ broker.
 
@@ -31,10 +31,9 @@ When a ManagedConnectionFactory JavaBean or ActivationSpec JavaBean are deployed
 the configuration properties from the ResourceAdapter or provide specific properties which in turn will override
 the defaults.
 
-While some of the properties from the three componets are specific to the JCA adapter, a majority of the
-properties directly correspond the the Qpid JMS client. As such, it is strongly encouraged your familiarize
-yourself with the correct syntax, configuration options for the JMS client as well as the JCA adapter. Similarly,
-familiarity with the 1.5 JCA specification is encouraged though not strictly required.
+While some of the properties from the three components are specific to the JCA adapter, a majority of the
+properties directly correspond the the Qpid JMS client. As such, familiarity with the Qpid JMS Client is strongly
+encouraged. Similarly, familiarity with the JCA 1.5 specification is encouraged though not strictly required.
 
 The ResourceAdapter JavaBean
 ============================
@@ -65,14 +64,6 @@ UseLocalTx
     Whether or not to use local transactions instead of XA.
 Default: false
 
-DefaultUserName
-    The default user name to use.
-Default: guest
-
-DefaultPassword
-    The default password to use.
-Default: guest
-
 Host
     The hostname/ip address of the broker.
 Default: localhost
@@ -87,23 +78,23 @@ Default: test
 
 ConnectionURL
    The full connection URL to the broker.
-Default:amqp://guest:guest@/test?brokerlist='tcp://localhost:5672'
+Default: amqp://anonymous:passwd@client/test?brokerlist='tcp://localhost?sasl_mechs='PLAIN''
 
 TransactionManagerLocatorClass
-    The class responsible for locating the transaction manager within a specific application server. This is a ResourceAdapter
-    Java Bean specific property and is application server specific. As such, it is currently commented out. Two examples have
-    been provided.
+    The class responsible for locating the transaction manager within a specific application server.
+    This is a ResourceAdapter Java Bean specific property and is application server specific, as such,
+    no default is provided.
 Default: none
 
 TransactionManagerLocatorMethod
-    The specific method on the class above used to acquire a reference to the platform specific transaction manager.
-    This is a ResourceAdapter Java Bean specific property and is application server specific.
-    As such, it is currently commented out. Two examples have been provided.
+    The specific method on the TransactionManagerLocatorClass used to acquire a reference to the platform
+    specific transaction manager. This is a ResourceAdapter Java Bean specific property and is application
+    server specific as such, no default is provided.
 Default:none
 
-Note, if you require XA support, both the TransactionManagerLocatorClass and the TransactionManagerLocatorMethod
-properties MUST be set. While application servers typically provide a mechanism to do this in the form of a specific
-deployment descriptor, or GUI console, the ra.xml file can also be modified directly.
+Note, both the TransactionManagerLocatorClass and the TransactionManagerLocatorMethod
+properties must be set. While application servers typically provide a mechanism to do this in the form of
+a specific deployment descriptor, or GUI console, the ra.xml file can also be modified directly.
 
 The ManagedConnectionFactory JavaBean
 =====================================
@@ -112,28 +103,16 @@ The ManagedConnectionFactory JavaBean provides outbound connectivity for the Qpi
 inherited from the ResourceAdapter JavaBean, the ManagedConnectionFactory JavaBean provides specific properties only applicable
 to outbound connectivity.
 
-sessionDefaulType
+SessionDefaulType
     The default type of Session. Currently unused.
 Default: java.jms.Queue
 
-useTryLock
+UseTryLock
     Multi-purpose property used to specify both that a lock on the underlying managed connection should be used, as well as the
     wait duration to aquire the lock. Primarily used for transaction management. A null or zero value will atttempt to acquire
     the lock without a duration. Anything greater than zero will wait n number of seconds before failing to acquire the lock.
 Default:0
 
-KeyStorePassword
-    The KeyStore password for SSL
-Default:none
-
-KeyStorePath
-    The path to the KeyStore.
-Default:none
-
-CertType
-    The type of certificate.
-Default:SunX509
-
 The ActivationSpec JavaBean
 ===========================
 The ActivationSpec JavaBean provides inbound connectivity for the Qpid JCA adapter. In addition to most of the properties
@@ -149,7 +128,7 @@ UseJNDI
 Default: true
 
 Destination
-    The name of the destination on which to listen for messages.
+    The JNDI name of the destination on which to listen for messages.
 Default:none
 
 DestinationType
@@ -187,49 +166,49 @@ PrefetchLow
 PrefetchHigh
     Qpid specific -- TODO more explanation
 
-
+SetupA
 Administered Objects
 ======================
 The JCA specification provides for administered objects. Ass per the specification, administered objects are
-JavaBeans that specific to the messaging provider. The Qpid JCA Resource Adapter provides two administered
+JavaBeans that specific to the messaging provider. The Qpid JCA Resource Adapter provides three administered
 objects that can be used to configure JMS destinations and a specialized JMS Connection Factory respectively.
 Both these administered objects have properities to support configuration and deployment.
 
-QpidDestinationProxy
+QpidQueue/QpidTopic
 ====================
-    The QpidDestinationProxy allows a developer, deployer or adminstrator to create destinations (queues or topic) and
-    bind these destinations into JNDI. The following lists the properties applicable to the QpidDestinationProxy
-
-destinationType
-    The type of destination to create. Valid values are QUEUE or TOPIC.
+    The QpidQueue/QpidTopic AdminObjects allow a developer, deployer or adminstrator to create destinations
+    (queues or topic) and bind these destinations into JNDI. Only one property is required:
 
-destinationAddress
+DestinationAddress
     The address string of the destination. Please see the Qpid Java JMS client documentation for valid values.
 
+Example:
+   DestinationAddress=hello.Queue;{create:always, node:{type:queue, x-declare:{auto-delete:true}}}
+   DestinationAddress=amq.topic/hello.Topic
+
 QpidConnectionFactoryProxy
+==========================
     The QpidConnectionFactoryProxy allows for a non-JCA ConnectionFactory to be bound into the JNDI tree. This
     ConnectionFactory can in turn be used outside of the application server. Typically a ConnectionFactory of
-    this sort is used by Swing or other two-tier clients not requiring JCA. The QpidConnectionFactoryProxy provides
-    one property
+    this sort is used by Java Swing or other non-managed clients not requiring JCA. One one property is
+    required:
 
-connectionURL
+ConnectionURL
     This is the url used to configure the connection factory. Please see the Qpid Java Client documentation for
     further details.
 
+Example:
+    amqp://anonymous:passwd@client/test?brokerlist='tcp://localhost:5672?sasl_mechs='PLAIN''
 
 Transaction Support
 ===================
 The Qpid JCA Resource Adapter provides three levels of transaction support: XA, LocalTransactions and NoTransaction.
 Typical usage of the Qpid JCA Resource adapter implies the use of XA transactions, though there are certain scenarios
 where this is not preferred. Transaction support configuration is application server specific and as such, is explained
-in the corresponding documentation for each supported application server. However, there are two limitations with
-the Qpid JCA adapter at this time:
-
-1) Currently, the Qpid C++ broker does not support he use of XA within the context of clustered brokers. As such, if
-you are running in a cluster, you will need to configure the adapter to use LocalTransactions.
+in the corresponding documentation for each supported application server. Current limitations with XA are listed
+below:
 
-2)XARecovery is currently not implemented. In the case of a system failure, in doubt transactions will have to be
-manually resolved by and administrator or otherwise qualified personnel.
+1)XARecovery is currently only supported for JBoss EAP 5.x and is not supported for clustered broker configurations.
 
 Conclusion
 ==========
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