jca/README.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 Resource Adapter Installation/Configuration Instructions

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

 The following document explains general configuration information for the Qpid JCA RA. Details for
 specific application server platforms are provided in separate README files typically designated as
 README-<server-platform>.txt.

 Configuration
 =============
 As per the JCA specification, there are four main components of a JCA resource adapter:

     The ResourceAdapter JavaBean
     The ManagedConnectionFactory JavaBean
     The ActivationSpec JavaBean
     Administered Objects

 Each of these components provide configuration options in the form of properties. The Resource Adapter
 JavaBean provides a set of global configuration options while the ManagedConnectionFactory JavaBean allows
 for the configuration of outbound connectivity options. The ActivationSpec JavaBean provides configuration
 options for inbound connectivity.

 When a ManagedConnectionFactory JavaBean or ActivationSpec JavaBean are deployed they can choose to inherit
 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 components are specific to the JCA adapter, a majority of the
 properties directly correspond the the Apache Qpid JMS client for AMQP 0-9-1/0-10. As such, familiarity with it is strongly
 encouraged. Similarly, familiarity with the JCA 1.5 specification is encouraged though not strictly required.

 The ResourceAdapter JavaBean
 ============================

 The ResourceAdapter JavaBean provides global configuration options for both inbound and outbound
 connectivity. The set of ResourceAdapter properties are described below. The ResourceAdapter properties
 can be found in the META-INF/ra.xml deployment descriptor which is provided with the adapter. Note,
 deploying a ResourceAdapter, ManagedConnectionFactory or ActivationSpec is application server specific.
 As such, this document provides an explanation of these properties but not how they are configured.

 ResourceAdapter JavaBean Properties
 ===================================

 ClientId
    The unique client identifier. From the JMS API this is used only in the context of durable subscriptions.
 Default: client_id

 SetupAttempts
     The number of attempts the ResourceAdapter will make to successfully setup an inbound activation on deployment,
     or when an exception occurs at runtime.
 Default: 5

 SetupInterval
     The interval in milliseconds the adapter will wait between setup attempts.
 Default: 5000

 UseLocalTx
     Whether or not to use local transactions instead of XA.
 Default: false

 Host
     The hostname/ip address of the broker.
 Default: localhost

 Port
     The port of the broker.
 Default: 5672

 Path
    The virtual path for the connection factory.
 Default: test

 ConnectionURL
    The full connection URL to the broker.
 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,
     no default is provided.
 Default: none

 TransactionManagerLocatorMethod
     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

 UseConnectionPerHandler
     The Apache C++ Broker multiplexes on the physical connection rather than the session. As a result, performance
     improvements can be gained by allocating and assigning a connection per inbound listener. The alternative is
     to share a connection across each handler for a given endpoint (MDB).
 Default:false

 The ManagedConnectionFactory JavaBean
 =====================================

 The ManagedConnectionFactory JavaBean provides outbound connectivity for the Qpid JCA adapter. In addition to most of the properties
 inherited from the ResourceAdapter JavaBean, the ManagedConnectionFactory JavaBean provides specific properties only applicable
 to outbound connectivity.

 SessionDefaulType
     The default type of Session. Currently unused.
 Default: java.jms.Queue

 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

 The ActivationSpec JavaBean
 ===========================
 The ActivationSpec JavaBean provides inbound connectivity for the Qpid JCA adapter. In addition to most of the properties
 inherited from the ResourceAdapter JavaBean, the ActivationSpec JavaBean provides specific properties only applicable
 to inbound connectivity. As opposed to the ResourceAdapter and ManagedConnectionFactory JavaBean a majority of the
 ActivationSpec JavaBean properties have no default value. It is expected that these will be provided via Java annotations
 or deployment descriptor configuration properties. The Qpid JCA adapter provides inbound connectivity in conjunction
 with the Message Driven Bean architecture from the EJB 3.x specification.

 UseJNDI
     Whether or not to attempt looking up an inbound destination from JNDI. If false, an attempt will be made to construct
     the destination from the other ActivationSpec properties.
 Default: true

 Destination
     The JNDI name of the destination on which to listen for messages.
 Default:none

 DestinationType
     The type of destination on which to listen. Valid values are javax.jms.Queue or java.jms.Topic.
 Default:none

 MessageSelector
     The JMS properties that will be used in selecting specific message. Please see the JMS specification for further details.
 Default:none

 AcknowlegeMode
     Whether or not the client or consumer will acknowledge any messages it receives. Ignored in a transacted scenario.
     Please see the JMS specification for more details.
 Default:AUTO_ACKNOWLEDGE

 SubscriptionDurablity
     Whether or not the subscription is durable.
 Default:none

 SubscriptionName
     The name of the subscription.
 Default:none

 MaxSession
     The maximum number of sessions that this activation supports.
 Default:15

 TransactionTimeout
     The timeout for the XA transaction for inbound messages.
 Default:0

 PrefetchLow
     Qpid specific -- TODO more explanation

 PrefetchHigh
     Qpid specific -- TODO more explanation

 Setup
 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 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.

 QpidQueue/QpidTopic
 ====================
 The QpidQueue and QpidTopic AdminObjects allow binding JMS destintations into the JEE JNDI namespace. Both
 objects support one property:

 DestinationAddress
     The address string of the destination. For valid values please see documentation for
     the Apache Qpid JMS client for AMQP 0-9-1/0-10.

 Example:
    DestinationAddress=hello.Queue;{create:always, node:{type:queue, x-declare:{auto-delete:true}}}
    DestinationAddress=amq.topic/hello.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:


 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 non-managed clients not requiring JCA. The QpidConnectionFactoryProxy
 provides one property

 ConnectionURL
     This is the url used to configure the connection factory. Please see documentation for
     the Apache Qpid JMS client for AMQP 0-9-1/0-10.
     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 Java Swing or other non-managed clients not requiring JCA. One one property is
     required:

 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.

 XA recovery, that is being able to recover 'in-doubt' transactions for a given resource manager is non-standardized,
 and as such is application server specific. Currently, the Qpid JCA adapter only supports recovery for JBoss EAP 5.x
 as a separate module.

 Conclusion
 ==========
 The above documentation provides a general description of the capabilities and configuration properites of the
 Qpid JCA Resource Adapter. As previously mentioned, deploying an adapter in an application server requires
 specific descriptors and configuration mechanisms. Please see the accompanying doc for your application server
 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 Resource Adapter Installation/Configuration Instructions

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

	The following document explains general configuration information for the Qpid JCA RA. Details for
	specific application server platforms are provided in separate README files typically designated as
	README-<server-platform>.txt.

	Configuration
	=============
	As per the JCA specification, there are four main components of a JCA resource adapter:

	The ResourceAdapter JavaBean
	The ManagedConnectionFactory JavaBean
	The ActivationSpec JavaBean
	Administered Objects

	Each of these components provide configuration options in the form of properties. The Resource Adapter
	JavaBean provides a set of global configuration options while the ManagedConnectionFactory JavaBean allows
	for the configuration of outbound connectivity options. The ActivationSpec JavaBean provides configuration
	options for inbound connectivity.

	When a ManagedConnectionFactory JavaBean or ActivationSpec JavaBean are deployed they can choose to inherit
	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 components are specific to the JCA adapter, a majority of the
	properties directly correspond the the Apache Qpid JMS client for AMQP 0-9-1/0-10. As such, familiarity with it is strongly
	encouraged. Similarly, familiarity with the JCA 1.5 specification is encouraged though not strictly required.

	The ResourceAdapter JavaBean
	============================

	The ResourceAdapter JavaBean provides global configuration options for both inbound and outbound
	connectivity. The set of ResourceAdapter properties are described below. The ResourceAdapter properties
	can be found in the META-INF/ra.xml deployment descriptor which is provided with the adapter. Note,
	deploying a ResourceAdapter, ManagedConnectionFactory or ActivationSpec is application server specific.
	As such, this document provides an explanation of these properties but not how they are configured.

	ResourceAdapter JavaBean Properties
	===================================

	ClientId
	The unique client identifier. From the JMS API this is used only in the context of durable subscriptions.
	Default: client_id

	SetupAttempts
	The number of attempts the ResourceAdapter will make to successfully setup an inbound activation on deployment,
	or when an exception occurs at runtime.
	Default: 5

	SetupInterval
	The interval in milliseconds the adapter will wait between setup attempts.
	Default: 5000

	UseLocalTx
	Whether or not to use local transactions instead of XA.
	Default: false

	Host
	The hostname/ip address of the broker.
	Default: localhost

	Port
	The port of the broker.
	Default: 5672

	Path
	The virtual path for the connection factory.
	Default: test

	ConnectionURL
	The full connection URL to the broker.
	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,
	no default is provided.
	Default: none

	TransactionManagerLocatorMethod
	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

	UseConnectionPerHandler
	The Apache C++ Broker multiplexes on the physical connection rather than the session. As a result, performance
	improvements can be gained by allocating and assigning a connection per inbound listener. The alternative is
	to share a connection across each handler for a given endpoint (MDB).
	Default:false

	The ManagedConnectionFactory JavaBean
	=====================================

	The ManagedConnectionFactory JavaBean provides outbound connectivity for the Qpid JCA adapter. In addition to most of the properties
	inherited from the ResourceAdapter JavaBean, the ManagedConnectionFactory JavaBean provides specific properties only applicable
	to outbound connectivity.

	SessionDefaulType
	The default type of Session. Currently unused.
	Default: java.jms.Queue

	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

	The ActivationSpec JavaBean
	===========================
	The ActivationSpec JavaBean provides inbound connectivity for the Qpid JCA adapter. In addition to most of the properties
	inherited from the ResourceAdapter JavaBean, the ActivationSpec JavaBean provides specific properties only applicable
	to inbound connectivity. As opposed to the ResourceAdapter and ManagedConnectionFactory JavaBean a majority of the
	ActivationSpec JavaBean properties have no default value. It is expected that these will be provided via Java annotations
	or deployment descriptor configuration properties. The Qpid JCA adapter provides inbound connectivity in conjunction
	with the Message Driven Bean architecture from the EJB 3.x specification.

	UseJNDI
	Whether or not to attempt looking up an inbound destination from JNDI. If false, an attempt will be made to construct
	the destination from the other ActivationSpec properties.
	Default: true

	Destination
	The JNDI name of the destination on which to listen for messages.
	Default:none

	DestinationType
	The type of destination on which to listen. Valid values are javax.jms.Queue or java.jms.Topic.
	Default:none

	MessageSelector
	The JMS properties that will be used in selecting specific message. Please see the JMS specification for further details.
	Default:none

	AcknowlegeMode
	Whether or not the client or consumer will acknowledge any messages it receives. Ignored in a transacted scenario.
	Please see the JMS specification for more details.
	Default:AUTO_ACKNOWLEDGE

	SubscriptionDurablity
	Whether or not the subscription is durable.
	Default:none

	SubscriptionName
	The name of the subscription.
	Default:none

	MaxSession
	The maximum number of sessions that this activation supports.
	Default:15

	TransactionTimeout
	The timeout for the XA transaction for inbound messages.
	Default:0

	PrefetchLow
	Qpid specific -- TODO more explanation

	PrefetchHigh
	Qpid specific -- TODO more explanation

	Setup
	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 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.

	QpidQueue/QpidTopic
	====================
	The QpidQueue and QpidTopic AdminObjects allow binding JMS destintations into the JEE JNDI namespace. Both
	objects support one property:

	DestinationAddress
	The address string of the destination. For valid values please see documentation for
	the Apache Qpid JMS client for AMQP 0-9-1/0-10.

	Example:
	DestinationAddress=hello.Queue;{create:always, node:{type:queue, x-declare:{auto-delete:true}}}
	DestinationAddress=amq.topic/hello.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:


	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 non-managed clients not requiring JCA. The QpidConnectionFactoryProxy
	provides one property

	ConnectionURL
	This is the url used to configure the connection factory. Please see documentation for
	the Apache Qpid JMS client for AMQP 0-9-1/0-10.
	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 Java Swing or other non-managed clients not requiring JCA. One one property is
	required:

	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.

	XA recovery, that is being able to recover 'in-doubt' transactions for a given resource manager is non-standardized,
	and as such is application server specific. Currently, the Qpid JCA adapter only supports recovery for JBoss EAP 5.x
	as a separate module.

	Conclusion
	==========
	The above documentation provides a general description of the capabilities and configuration properites of the
	Qpid JCA Resource Adapter. As previously mentioned, deploying an adapter in an application server requires
	specific descriptors and configuration mechanisms. Please see the accompanying doc for your application server
	for further details.