You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by cl...@apache.org on 2014/12/08 16:49:51 UTC
[20/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/appserver-integration.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/appserver-integration.xml b/docs/user-manual/en/appserver-integration.xml
deleted file mode 100644
index 897de10..0000000
--- a/docs/user-manual/en/appserver-integration.xml
+++ /dev/null
@@ -1,1338 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- 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. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="appserver-integration">
- <title>Application Server Integration and Java EE</title>
- <para>ActiveMQ can be easily installed in JBoss Application Server 4 or later. For details on
- installing ActiveMQ in the JBoss Application Server please refer to quick-start guide.</para>
- <para>Since ActiveMQ also provides a JCA adapter, it is also possible to integrate ActiveMQ
- as a JMS provider in other JEE compliant app servers. For instructions on how to integrate a
- remote JCA adaptor into another application sever, please consult the other application server's
- instructions.</para>
- <para>A JCA Adapter basically controls the inflow of messages to Message-Driven Beans (MDBs) and the
- outflow of messages sent from other JEE components, e.g. EJBs and Servlets.</para>
- <para>This section explains the basics behind configuring the different JEE components in the
- AS.</para>
- <section id="configuring-mdbs">
- <title>Configuring Message-Driven Beans</title>
- <para>The delivery of messages to an MDB using ActiveMQ is configured on the JCA Adapter via
- a configuration file <literal>ra.xml</literal> which can be found under the <literal
- >jms-ra.rar</literal> directory. By default this is configured to consume
- messages using an InVM connector from the instance of ActiveMQ running within the
- application server. The configuration properties are listed later in this chapter. </para>
- <para>All MDBs however need to have the destination type and the destination configured.
- The following example shows how this can be done using annotations:</para>
- <programlisting>
-@MessageDriven(name = "MDBExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
-})
-@ResourceAdapter("activemq-ra.rar")
-public class MDBExample implements MessageListener
-{
- public void onMessage(Message message)...
-}</programlisting>
- <para>In this example you can see that the MDB will consume messages from a queue that is
- mapped into JNDI with the binding <literal>queue/testQueue</literal>. This queue must be
- preconfigured in the usual way using the ActiveMQ configuration files.</para>
- <para>The <literal>ResourceAdapter</literal> annotation is used to specify which adaptor
- should be used. To use this you will need to import <literal
- >org.jboss.ejb3.annotation.ResourceAdapter</literal> for JBoss AS 5.X and later version which can be found in the
- <literal>jboss-ejb3-ext-api.jar</literal> which can be found in the JBoss
- repository. For JBoss AS 4.X, the annotation to use is <literal>org.jboss.annotation.ejb.ResourceAdaptor</literal>.</para>
- <para>
- Alternatively you can add use a deployment descriptor and add something like
- the following to <literal
- >jboss.xml</literal><programlisting><message-driven>
- <ejb-name>ExampleMDB</ejb-name>
- <resource-adapter-name>activemq-ra.rar</resource-adapter-name>
-</message-driven>
-</programlisting>You
- can also rename the activemq-ra.rar directory to jms-ra.rar and neither the annotation or
- the extra descriptor information will be needed. If you do this you will need to edit
- the <literal>jms-ds.xml</literal> datasource file and change <literal>rar-name</literal>
- element.</para>
- <note>
- <para>ActiveMQ is the default JMS provider for JBoss AS 6. Starting with this AS version, ActiveMQ resource
- adapter is named <literal>jms-ra.rar</literal> and you no longer need to annotate the MDB for the resource adapter name.</para>
- </note>
- <para>All the examples shipped with the ActiveMQ distribution use the annotation.</para>
- <section>
- <title>Using Container-Managed Transactions</title>
- <para>When an MDB is using Container-Managed Transactions (CMT), the delivery of the
- message is done within the scope of a JTA transaction. The commit or rollback of
- this transaction is controlled by the container itself. If the transaction is rolled
- back then the message delivery semantics will kick in (by default, it will try to
- redeliver the message up to 10 times before sending to a DLQ). Using annotations
- this would be configured as follows:</para>
- <programlisting>
-@MessageDriven(name = "MDB_CMP_TxRequiredExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
-})
-@TransactionManagement(value= TransactionManagementType.CONTAINER)
-@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
-@ResourceAdapter("activemq-ra.rar")
-public class MDB_CMP_TxRequiredExample implements MessageListener
-{
- public void onMessage(Message message)...
-}</programlisting>
- <para>The <literal>TransactionManagement</literal> annotation tells the container to manage the
- transaction. The <literal>TransactionAttribute</literal> annotation tells the container that a JTA
- transaction is required for this MDB. Note that the only other valid value for this
- is <literal>TransactionAttributeType.NOT_SUPPORTED</literal> which tells the
- container that this MDB does not support JTA transactions and one should not be
- created.</para>
- <para>It is also possible to inform the container that it must rollback the transaction
- by calling <literal>setRollbackOnly</literal> on the <literal
- >MessageDrivenContext</literal>. The code for this would look something
- like:</para>
- <programlisting>
-@Resource
-MessageDrivenContextContext ctx;
-
-public void onMessage(Message message)
-{
- try
- {
- //something here fails
- }
- catch (Exception e)
- {
- ctx.setRollbackOnly();
- }
-}</programlisting>
- <para>If you do not want the overhead of an XA transaction being created every time but
- you would still like the message delivered within a transaction (i.e. you are only
- using a JMS resource) then you can configure the MDB to use a local transaction.
- This would be configured as such:</para>
- <programlisting>
-@MessageDriven(name = "MDB_CMP_TxLocalExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
- @ActivationConfigProperty(propertyName = "useLocalTx", propertyValue = "true")
-})
-@TransactionManagement(value = TransactionManagementType.CONTAINER)
-@TransactionAttribute(value = TransactionAttributeType.NOT_SUPPORTED)
-@ResourceAdapter("activemq-ra.rar")
-public class MDB_CMP_TxLocalExample implements MessageListener
-{
- public void onMessage(Message message)...
-}</programlisting>
- </section>
- <section>
- <title>Using Bean-Managed Transactions</title>
- <para>Message-driven beans can also be configured to use Bean-Managed Transactions
- (BMT). In this case a User Transaction is created. This would be configured as
- follows:</para>
- <programlisting>
-@MessageDriven(name = "MDB_BMPExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
- @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Dups-ok-acknowledge")
-})
-@TransactionManagement(value= TransactionManagementType.BEAN)
-@ResourceAdapter("activemq-ra.rar")
-public class MDB_BMPExample implements MessageListener
-{
- public void onMessage(Message message)
-}</programlisting>
- <para>When using Bean-Managed Transactions the message delivery to the MDB will occur
- outside the scope of the user transaction and use the acknowledge mode specified by
- the user with the <literal>acknowledgeMode</literal> property. There are only 2
- acceptable values for this <literal>Auto-acknowledge</literal> and <literal
- >Dups-ok-acknowledge</literal>. Please note that because the message delivery is outside
- the scope of the transaction a failure within the MDB will not cause the message to
- be redelivered.</para>
- <para>A user would control the life-cycle of the transaction something like the
- following:</para>
- <programlisting>
-@Resource
-MessageDrivenContext ctx;
-
-public void onMessage(Message message)
-{
- UserTransaction tx;
- try
- {
- TextMessage textMessage = (TextMessage)message;
-
- String text = textMessage.getText();
-
- UserTransaction tx = ctx.getUserTransaction();
-
- tx.begin();
-
- //do some stuff within the transaction
-
- tx.commit();
-
- }
- catch (Exception e)
- {
- tx.rollback();
- }
-}</programlisting>
- </section>
- <section>
- <title>Using Message Selectors with Message-Driven Beans</title>
- <para>It is also possible to use MDBs with message selectors. To do this simple define
- your message selector as follows:</para>
- <programlisting>
-@MessageDriven(name = "MDBMessageSelectorExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
- @ActivationConfigProperty(propertyName = "messageSelector", propertyValue = "color = 'RED'")
-})
-@TransactionManagement(value= TransactionManagementType.CONTAINER)
-@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
-@ResourceAdapter("activemq-ra.rar")
-public class MDBMessageSelectorExample implements MessageListener
-{
- public void onMessage(Message message)....
-}</programlisting>
- </section>
- </section>
- <section>
- <title>Sending Messages from within JEE components</title>
- <para>The JCA adapter can also be used for sending messages. The Connection Factory to use
- is configured by default in the <literal>jms-ds.xml</literal> file and is mapped to
- <literal>java:/JmsXA</literal>. Using this from within a JEE component will mean
- that the sending of the message will be done as part of the JTA transaction being used
- by the component.</para>
- <para>This means that if the sending of the message fails the overall transaction would
- rollback and the message be re-sent. Heres an example of this from within an
- MDB:</para>
- <programlisting>
-@MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
-})
-@TransactionManagement(value= TransactionManagementType.CONTAINER)
-@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
-@ResourceAdapter("activemq-ra.rar")
-public class MDBMessageSendTxExample implements MessageListener
-{
- @Resource(mappedName = "java:/JmsXA")
- ConnectionFactory connectionFactory;
-
- @Resource(mappedName = "queue/replyQueue")
- Queue replyQueue;
-
- public void onMessage(Message message)
- {
- Connection conn = null;
- try
- {
- //Step 9. We know the client is sending a text message so we cast
- TextMessage textMessage = (TextMessage)message;
-
- //Step 10. get the text from the message.
- String text = textMessage.getText();
-
- System.out.println("message " + text);
-
- conn = connectionFactory.createConnection();
-
- Session sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
- MessageProducer producer = sess.createProducer(replyQueue);
-
- producer.send(sess.createTextMessage("this is a reply"));
-
- }
- catch (Exception e)
- {
- e.printStackTrace();
- }
- finally
- {
- if(conn != null)
- {
- try
- {
- conn.close();
- }
- catch (JMSException e)
- {
- }
- }
- }
- }
- }</programlisting>
- <para>In JBoss Application Server you can use the JMS JCA adapter for sending messages from
- EJBs (including Session, Entity and Message-Driven Beans), Servlets (including jsps) and
- custom MBeans.</para>
- </section>
- <section>
- <title>MDB and Consumer pool size</title>
- <para>Most application servers, including JBoss, allow you to configure how many MDB's there are in a pool. In
- JBoss this is configured via the <literal>MaxPoolSize</literal> parameter in the ejb3-interceptors-aop.xml file. Configuring
- this has no actual effect on how many sessions/consumers there actually are created. This is because the Resource
- Adaptor implementation knows nothing about the application servers MDB implementation. So even if you set the MDB
- pool size to 1, 15 sessions/consumers will be created (this is the default). If you want to limit how many
- sessions/consumers are created then you need to set the <literal>maxSession</literal> parameter either on the
- resource adapter itself or via an an Activation Config Property on the MDB itself</para>
- <programlisting>
-@MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
-{
- @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
- @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
- @ActivationConfigProperty(propertyName = "maxSession", propertyValue = "1")
-})
-@TransactionManagement(value= TransactionManagementType.CONTAINER)
-@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
-@ResourceAdapter("activemq-ra.rar")
-public class MyMDB implements MessageListener
-{ ....}
- </programlisting>
- </section>
- <section>
- <title>Configuring the JCA Adaptor</title>
- <para>The Java Connector Architecture (JCA) Adapter is what allows ActiveMQ to be integrated
- with JEE components such as MDBs and EJBs. It configures how components such as MDBs
- consume messages from the ActiveMQ server and also how components such as EJBs or
- Servlets can send messages.</para>
- <para>The ActiveMQ JCA adapter is deployed via the <literal>jms-ra.rar</literal> archive. The
- configuration of the adapter is found in this archive under <literal
- >META-INF/ra.xml</literal>.</para>
- <para>The configuration will look something like the following:</para>
- <programlisting>
-<resourceadapter>
- <resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
- <config-property>
- <description>The transport type. Multiple connectors can be configured by using a comma separated list,
- i.e. org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory,org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory.</description>
- <config-property-name>ConnectorClassName</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory</config-property-value>
- </config-property>
- <config-property>
- <description>The transport configuration. These values must be in the form of key=val;key=val;,
- if multiple connectors are used then each set must be separated by a comma i.e. host=host1;port=5445,host=host2;port=5446.
- Each set of parameters maps to the connector classname specified.</description>
- <config-property-name>ConnectionParameters</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>server-id=0</config-property-value>
- </config-property>
-
- <outbound-resourceadapter>
- <connection-definition>
- <managedconnectionfactory-class>org.apache.activemq.ra.ActiveMQRAManagedConnection
- Factory</managedconnectionfactory-class>
-
- <config-property>
- <description>The default session type</description>
- <config-property-name>SessionDefaultType</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>javax.jms.Queue</config-property-value>
- </config-property>
- <config-property>
- <description>Try to obtain a lock within specified number of seconds; less
- than or equal to 0 disable this functionality</description>
- <config-property-name>UseTryLock</config-property-name>
- <config-property-type>java.lang.Integer</config-property-type>
- <config-property-value>0</config-property-value>
- </config-property>
-
- <connectionfactory-interface>org.apache.activemq.ra.ActiveMQRAConnectionFactory
- </connectionfactory-interface>
- <connectionfactororg.apache.activemq.ra.ActiveMQConnectionFactoryImplonFactoryImpl
- </connectionfactory-impl-class>
- <connection-interface>javax.jms.Session</connection-interface>
- <connection-impl-class>org.apache.activemq.ra.ActiveMQRASession
- </connection-impl-class>
- </connection-definition>
- <transaction-support>XATransaction</transaction-support>
- <authentication-mechanism>
- <authentication-mechanism-type>BasicPassword
- </authentication-mechanism-type>
- <credential-interface>javax.resource.spi.security.PasswordCredential
- </credential-interface>
- </authentication-mechanism>
- <reauthentication-support>false</reauthentication-support>
- </outbound-resourceadapter>
-
- <inbound-resourceadapter>
- <messageadapter>
- <messagelistener>
- <messagelistener-type>javax.jms.MessageListener</messagelistener-type>
- <activationspec>
- <activationspec-class>org.apache.activemq.ra.inflow.ActiveMQActivationSpec
- </activationspec-class>
- <required-config-property>
- <config-property-name>destination</config-property-name>
- </required-config-property>
- </activationspec>
- </messagelistener>
- </messageadapter>
- </inbound-resourceadapter>
-</resourceadapter></programlisting>
- <para>There are three main parts to this configuration.</para>
- <orderedlist>
- <listitem>
- <para>A set of global properties for the adapter</para>
- </listitem>
- <listitem>
- <para>The configuration for the outbound part of the adapter. This is used for
- creating JMS resources within EE components. </para>
- </listitem>
- <listitem>
- <para>The configuration of the inbound part of the adapter. This is used for
- controlling the consumption of messages via MDBs. </para>
- </listitem>
- </orderedlist>
- <section>
- <title>Global Properties</title>
- <para>The first element you see is <literal>resourceadapter-class</literal> which should
- be left unchanged. This is the ActiveMQ resource adapter class.</para>
- <para>After that there is a list of configuration properties. This will be where most of
- the configuration is done. The first two properties configure the transport used by the adapter
- and the rest configure the connection factory itself.
- </para>
- <note>
- <para>All connection factory properties will use the defaults if they are not provided, except
- for the <literal>reconnectAttempts</literal> which will default to -1. This
- signifies that the connection should attempt to reconnect on connection
- failure indefinitely. This is only used when the adapter is configured to
- connect to a remote server as an InVM connector can never fail.
- </para>
- </note>
- <para>The following table explains what each property is for.</para>
- <table frame="topbot" border="2">
- <title>Global Configuration Properties</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Property Type</entry>
- <entry>Property Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>ConnectorClassName</entry>
- <entry>String</entry>
- <entry>The Connector class name (see <xref
- linkend="configuring-transports"/> for more information). If multiple connectors are
- needed this should be provided as a comma separated list.</entry>
- </row>
- <row>
- <entry>ConnectionParameters</entry>
- <entry>String</entry>
- <entry>The transport configuration. These parameters must be in the form of
- <literal>key1=val1;key2=val2;</literal> and will be specific to the connector used. If
- multiple connectors are configured then parameters should be supplied for each connector
- separated by a comma.
- </entry>
- </row>
- <row>
- <entry>ha</entry>
- <entry>boolean</entry>
- <entry>True if high availability is needed.</entry>
- </row>
- <row>
- <entry>useLocalTx</entry>
- <entry>boolean</entry>
- <entry>True will enable local transaction optimisation.</entry>
- </row>
- <row>
- <entry>UserName</entry>
- <entry>String</entry>
- <entry>The user name to use when making a connection </entry>
- </row>
- <row>
- <entry>Password</entry>
- <entry>String</entry>
- <entry>The password to use when making a connection</entry>
- </row>
- <row>
- <entry>
- <link linkend="configuration.discovery-group.group-address">DiscoveryAddress</link></entry>
- <entry>String</entry>
- <entry>The discovery group address to use to auto-detect a server</entry>
- </row>
- <row>
- <entry>
- <link linkend="configuration.discovery-group.group-port">DiscoveryPort</link></entry>
- <entry>Integer</entry>
- <entry>The port to use for discovery</entry>
- </row>
- <row>
- <entry>
- <link linkend="configuration.discovery-group.refresh-timeout">DiscoveryRefreshTimeout</link></entry>
- <entry>Long</entry>
- <entry>The timeout, in milliseconds, to refresh.</entry>
- </row>
- <row>
- <entry>
- DiscoveryInitialWaitTimeout
- </entry>
- <entry>Long</entry>
- <entry>The initial time to wait for discovery.</entry>
- </row>
- <row>
- <entry>
- ConnectionLoadBalancingPolicyClassName
- </entry>
- <entry>String</entry>
- <entry>The load balancing policy class to use.</entry>
- </row>
- <row>
- <entry>
- ConnectionTTL
- </entry>
- <entry>Long</entry>
- <entry>The time to live (in milliseconds) for the connection.</entry>
- </row>
- <row>
- <entry>
- CallTimeout
- </entry>
- <entry>Long</entry>
- <entry>the call timeout (in milliseconds) for each packet sent.</entry>
- </row>
- <row>
- <entry>
- DupsOKBatchSize
- </entry>
- <entry>Integer</entry>
- <entry>the batch size (in bytes) between acknowledgements when using
- DUPS_OK_ACKNOWLEDGE mode</entry>
- </row>
- <row>
- <entry>
- TransactionBatchSize
- </entry>
- <entry>Integer</entry>
- <entry>the batch size (in bytes) between acknowledgements when using a
- transactional session</entry>
- </row>
- <row>
- <entry>
- ConsumerWindowSize
- </entry>
- <entry>Integer</entry>
- <entry>the window size (in bytes) for consumer flow control</entry>
- </row>
- <row>
- <entry>
- ConsumerMaxRate
- </entry>
- <entry>Integer</entry>
- <entry>the fastest rate a consumer may consume messages per second</entry>
- </row>
- <row>
- <entry>
- ConfirmationWindowSize
- </entry>
- <entry>Integer</entry>
- <entry>the window size (in bytes) for reattachment confirmations</entry>
- </row>
- <row>
- <entry>
- ProducerMaxRate
- </entry>
- <entry>Integer</entry>
- <entry>the maximum rate of messages per second that can be sent</entry>
- </row>
- <row>
- <entry>
- MinLargeMessageSize
- </entry>
- <entry>Integer</entry>
- <entry>the size (in bytes) before a message is treated as large </entry>
- </row>
- <row>
- <entry>
- BlockOnAcknowledge
- </entry>
- <entry>Boolean</entry>
- <entry>whether or not messages are acknowledged synchronously</entry>
- </row>
- <row>
- <entry>
- BlockOnNonDurableSend
- </entry>
- <entry>Boolean</entry>
- <entry>whether or not non-durable messages are sent synchronously</entry>
- </row>
- <row>
- <entry>
- BlockOnDurableSend
- </entry>
- <entry>Boolean</entry>
- <entry>whether or not durable messages are sent synchronously</entry>
- </row>
- <row>
- <entry>
- AutoGroup
- </entry>
- <entry>Boolean</entry>
- <entry>whether or not message grouping is automatically used</entry>
- </row>
- <row>
- <entry>
- PreAcknowledge
- </entry>
- <entry>Boolean</entry>
- <entry>whether messages are pre acknowledged by the server before
- sending</entry>
- </row>
- <row>
- <entry>
- ReconnectAttempts
- </entry>
- <entry>Integer</entry>
- <entry>maximum number of retry attempts, default for the resource adapter is -1 (infinite attempts)</entry>
- </row>
- <row>
- <entry>
- RetryInterval
- </entry>
- <entry>Long</entry>
- <entry>the time (in milliseconds) to retry a connection after failing</entry>
- </row>
- <row>
- <entry>
- RetryIntervalMultiplier
- </entry>
- <entry>Double</entry>
- <entry>multiplier to apply to successive retry intervals</entry>
- </row>
- <row>
- <entry>
- FailoverOnServerShutdown
- </entry>
- <entry>Boolean</entry>
- <entry>If true client will reconnect to another server if
- available</entry>
- </row>
- <row>
- <entry>
- ClientID
- </entry>
- <entry>String</entry>
- <entry>the pre-configured client ID for the connection factory</entry>
- </row>
- <row>
- <entry>
- ClientFailureCheckPeriod
- </entry>
- <entry>Long</entry>
- <entry>the period (in ms) after which the client will consider the
- connection failed after not receiving packets from the
- server</entry>
- </row>
- <row>
- <entry>
- UseGlobalPools
- </entry>
- <entry>Boolean</entry>
- <entry>whether or not to use a global thread pool for threads</entry>
- </row>
- <row>
- <entry>
- ScheduledThreadPoolMaxSize
- </entry>
- <entry>Integer</entry>
- <entry>the size of the <emphasis>scheduled thread</emphasis> pool</entry>
- </row>
- <row>
- <entry>
- ThreadPoolMaxSize
- </entry>
- <entry>Integer</entry>
- <entry>the size of the thread pool</entry>
- </row>
- <row>
- <entry>SetupAttempts</entry>
- <entry>Integer</entry>
- <entry>Number of attempts to setup a JMS connection (default is 10, -1 means to attempt infinitely). It is possible
- that the MDB is deployed before the JMS resources are available. In that case, the resource
- adapter will try to setup several times until the resources are available. This applies only for inbound connections</entry>
- </row>
- <row>
- <entry>SetupInterval</entry>
- <entry>Long</entry>
- <entry>Interval in milliseconds between consecutive attempts to setup a JMS connection (default is 2000m). This applies only for inbound connections</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section>
- <title>Adapter Outbound Configuration</title>
- <para>The outbound configuration should remain unchanged as they define connection
- factories that are used by Java EE components. These Connection Factories can be
- defined inside a configuration file that matches the name <literal
- >*-ds.xml</literal>. You'll find a default <literal>jms-ds.xml</literal>
- configuration under the <literal>activemq</literal> directory in the JBoss AS
- deployment. The connection factories defined in this file inherit their
- properties from the main <literal>ra.xml</literal> configuration but can also be
- overridden. The following example shows how to override them.</para>
- <note>
- <para>Please note that this configuration only applies when ActiveMQ resource adapter is installed in
- JBoss Application Server. If you are using another JEE application
- server please refer to your application servers documentation for how to do
- this.</para>
- </note>
- <programlisting>
-<tx-connection-factory>
- <jndi-name>RemoteJmsXA</jndi-name>
- <xa-transaction/>
- <rar-name>jms-ra.rar</rar-name>
- <connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory
-</connection-definition>
-<config-property name="SessionDefaultType" type="String">javax.jms.Topic</config-property>
- <config-property name="ConnectorClassName" type="String">
- org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory
- </config-property>
- <config-property name="ConnectionParameters" type="String">
- port=5445</config-property>
- <max-pool-size>20</max-pool-size>
-</tx-connection-factory></programlisting>
- <warning>
- <title>overriding connectors</title>
- <para>If the connector class name is overridden the all parameters must also be supplied.</para>
- </warning>
- <para>In this example the connection factory will be bound to JNDI with the name
- <literal>RemoteJmsXA</literal> and can be looked up in the usual way using JNDI
- or defined within the EJB or MDB as such:</para>
- <programlisting>
-@Resource(mappedName="java:/RemoteJmsXA")
-private ConnectionFactory connectionFactory;</programlisting>
- <para>The <literal>config-property</literal> elements are what overrides those in the
- <literal>ra.xml</literal> configuration file. Any of the elements pertaining to the
- connection factory can be overridden here.</para>
- <para>The outbound configuration also defines additional properties in addition to the global configuration properties.</para>
-
- <table frame="topbot" border="2">
- <title>Outbound Configuration Properties</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Property Type</entry>
- <entry>Property Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>SessionDefaultType</entry>
- <entry>String</entry>
- <entry>the default session type</entry>
- </row>
- <row>
- <entry>UseTryLock</entry>
- <entry>Integer</entry>
- <entry>try to obtain a lock within specified number of seconds. less
- than or equal to 0 disable this functionality</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section>
- <title>Adapter Inbound Configuration</title>
- <para>The inbound configuration should again remain unchanged. This controls what
- forwards messages onto MDBs. It is possible to override properties on the MDB by
- adding an activation configuration to the MDB itself. This could be used to
- configure the MDB to consume from a different server.</para>
- <para>The inbound configuration also defines additional properties in addition to the global configuration properties.</para>
-
- <table frame="topbot" border="2">
- <title>Inbound Configuration Properties</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Property Type</entry>
- <entry>Property Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Destination</entry>
- <entry>String</entry>
- <entry>JNDI name of the destination</entry>
- </row>
- <row>
- <entry>DestinationType</entry>
- <entry>String</entry>
- <entry>type of the destination, either <literal>javax.jms.Queue</literal> or <literal>javax.jms.Topic</literal>
- (default is javax.jms.Queue)</entry>
- </row>
- <row>
- <entry>AcknowledgeMode</entry>
- <entry>String</entry>
- <entry>The Acknowledgment mode, either <literal>Auto-acknowledge</literal> or <literal>Dups-ok-acknowledge</literal>
- (default is Auto-acknowledge). <literal>AUTO_ACKNOWLEDGE</literal> and <literal>DUPS_OK_ACKNOWLEDGE</literal> are acceptable values.</entry>
- </row>
- <row>
- <entry>JndiParams</entry>
- <entry>String</entry>
- <entry>A semicolon (';') delimited string of name=value pairs which represent the properties to be used for the destination JNDI
- look up. The properties depends on the JNDI implementation of the server hosting ActiveMQ. Typically only be used when the MDB is
- configured to consume from a remote destination and needs to look up a JNDI reference rather than the ActiveMQ name of the
- destination. Only relevant when <literal>useJNDI</literal> is <literal>true</literal> (default is an empty string).</entry>
- </row>
- <row>
- <entry>MaxSession</entry>
- <entry>Integer</entry>
- <entry>Maximum number of session created by this inbound configuration (default is 15)</entry>
- </row>
- <row>
- <entry>MessageSelector</entry>
- <entry>String</entry>
- <entry>the message selector of the consumer</entry>
- </row>
- <row>
- <entry>SubscriptionDurability</entry>
- <entry>String</entry>
- <entry>Type of the subscription, either <literal>Durable</literal> or <literal>NonDurable</literal></entry>
- </row>
- <row>
- <entry>ShareSubscriptions</entry>
- <entry>Boolean</entry>
- <entry>When true, multiple MDBs can share the same <literal>Durable</literal> subscription</entry>
- </row>
- <row>
- <entry>SubscriptionName</entry>
- <entry>String</entry>
- <entry>Name of the subscription</entry>
- </row>
- <row>
- <entry>TransactionTimeout</entry>
- <entry>Long</entry>
- <entry>The transaction timeout in milliseconds (default is 0, the transaction does not timeout)</entry>
- </row>
- <row>
- <entry>UseJNDI</entry>
- <entry>Boolean</entry>
- <entry>Whether or not use JNDI to look up the destination (default is true)</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
- <section>
- <title>Configuring the adapter to use a standalone ActiveMQ Server</title>
- <para>Sometime you may want your messaging server on a different machine or separate from the application server.
- If this is the case you will only need the activemq client libs installed. This section explains what config to create
- and what jar dependencies are needed.</para>
- <section>
- <para>There are two configuration files needed to do this, one for the incoming adapter used for MDB's
- and one for outgoing connections managed by the JCA managed connection pool used by outgoing JEE components
- wanting outgoing connections.</para>
- <section>
- <title>Configuring the Incoming Adaptor</title>
- <para>Firstly you will need to create directory under the
- <literal>deploy</literal>
- directory ending in
- <literal>.rar.</literal>
- For this example we will name the directory <literal>activemq-ra.rar</literal>. This detail is
- important as
- the name of directory is referred to by the MDB's and the outgoing configuration.
-
- </para>
- <note>
- <para>The jboss default for this is <literal>jms-ra.rar</literal>, If you don't want to have to
- configure your
- MDB's you can use this but you may need to remove the generic adaptor that uses this.
- </para>
- </note>
- <para>Under the
- <literal>activemq-ra.rar</literal>
- directory you will need to create a
- <literal>META-INF</literal>
- directory into which you should create an
- <literal>ra.xml</literal>
- configuration file. You can find a template
- for the
- <literal>ra.xml</literal>
- under the config directory of the ActiveMQ distribution.
- </para>
- <para>To configure MDB's to consume messages from a remote ActiveMQ server you need to edit the
- <literal>ra.xml</literal>
- file under
- <literal>deploy/activemq-ra.rar/META-INF</literal>
- and change the transport type to
- use a netty connector (instead of the invm connector that is defined) and configure its transport
- parameters.
- Heres an example of what this would look like:
- </para>
- <programlisting>
-<resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
- <config-property>
- <description>The transport type</description>
- <config-property-name>ConnectorClassName</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
- </config-property>
- <config-property>
- <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
- <config-property-name>ConnectionParameters</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>host=127.0.0.1;port=5446</config-property-value>
-</config-property></programlisting>
- <para>
- If you want to provide a list of servers that the adapter can connect to you can provide a list of
- connectors, each separated by a comma.
- </para>
-
- <programlisting>
-<resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
- <config-property>
- <description>The transport type</description>
- <config-property-name>ConnectorClassName</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory,org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
- </config-property>
- <config-property>
- <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
- <config-property-name>ConnectionParameters</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>host=127.0.0.1;port=5446,host=127.0.0.2;port=5447</config-property-value>
-</config-property></programlisting>
- <warning>
- <title>provide all parameters</title>
- <para>
- Make sure you provide parameters for each connector configured. The position of the parameters in the
- list maps to each connector provided.
- </para>
- </warning>
- <para>This configures the resource adapter to connect to a server running on localhost listening on port
- 5446
- </para>
- </section>
-
- <section>
- <title>Configuring the outgoing adaptor</title>
- <para>You will also need to configure the outbound connection by creating a <literal>activemq-ds.xml</literal>
- and placing it under any directory that will be deployed under the <literal>deploy</literal> directory.
- In a standard ActiveMQ jboss configuration this would be under <literal>activemq</literal> or <literal>activemq.sar</literal>
- but you can place it where ever you like. Actually as long as it ends in <literal>-ds.xml</literal> you can
- call it anything you like. You can again find a template for this file under the config directory of the
- ActiveMQ distribution but called <literal>jms-ds.xml</literal> which is the jboss default.
- </para>
- <para>The following example shows a sample configuration</para>
- <programlisting>
-<tx-connection-factory>
- <jndi-name>RemoteJmsXA</jndi-name>
- <xa-transaction/>
- <rar-name>activemq-ra.rar</rar-name>
- <connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory</connection-definition>
- <config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic</config-property>
- <config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property>
- <config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5446</config-property>
- <max-pool-size>20</max-pool-size>
-</tx-connection-factory></programlisting>
- <para>Again you will see that this uses the netty connector type and will connect to the ActiveMQ server
- running on localhost and listening on port 5446. JEE components can access this by using JNDI and looking
- up the connection factory using JNDI using <literal>java:/RemoteJmsXA</literal>, you can see that this
- is defined under the<literal>jndi-name</literal> attribute. You will also note that the outgoing connection
- will be created by the resource adaptor configured under the directory <literal>activemq-ra.rar</literal>
- as explained in the last section.
- </para>
- <para>
- Also if you want to configure multiple connectors do this as a comma separated list as in the ra configuration.
- </para>
- </section>
-
- <section>
- <title>Jar dependencies</title>
- <para>This is a list of the ActiveMQ and third party jars needed</para>
- <table frame="topbot" border="2">
- <title>Jar Dependencies</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1"/>
- <colspec colname="c2" colnum="2"/>
- <colspec colname="c3" colnum="3"/>
- <thead>
- <row>
- <entry>Jar Name</entry>
- <entry>Description</entry>
- <entry>Location</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>activemq-ra.jar</entry>
- <entry>The ActiveMQ resource adaptor classes</entry>
- <entry>deploy/activemq-ra.rar or equivalent</entry>
- </row>
- <row>
- <entry>activemq-core-client.jar</entry>
- <entry>The ActiveMQ core client classes</entry>
- <entry>either in the config lib, i.e. default/lib or the common lib dir, i.e. $JBOSS_HOME/common lib </entry>
- </row>
- <row>
- <entry>activemq-jms-client.jar</entry>
- <entry>The ActiveMQ JMS classes</entry>
- <entry>as above</entry>
- </row>
- <row>
- <entry>netty.jar</entry>
- <entry>The Netty transport classes</entry>
- <entry>as above</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- </section>
- </section>
- </section>
- <section>
- <title>Configuring the JBoss Application Server to connect to Remote ActiveMQ Server</title>
- <para>This is a step by step guide on how to configure a JBoss application server that doesn't have ActiveMQ installed
- to use a remote instance of ActiveMQ</para>
- <section>
- <title>Configuring JBoss 5</title>
- <para>Firstly download and install JBoss AS 5 as per the JBoss installation guide and ActiveMQ as per the
- ActiveMQ installation guide. After that the following steps are required</para>
- <itemizedlist>
- <listitem>
- <para>Copy the following jars from the ActiveMQ distribution to the <literal>lib</literal> directory of
- which ever JBossAs configuration you have chosen, i.e. <literal>default</literal>.</para>
- <itemizedlist>
- <listitem>
- <para>activemq-core-client.jar</para>
- </listitem>
- <listitem>
- <para>activemq-jms-client.jar</para>
- </listitem>
- <listitem>
- <para>activemq-ra.jar (this can be found inside the <literal>activemq-ra.rar</literal> archive)</para>
- </listitem>
- <listitem>
- <para>netty.jar</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>create the directories <literal>activemq-ra.rar</literal> and <literal>activemq-ra.rar/META-INF</literal>
- under the <literal>deploy</literal> directory in your JBoss config directory</para>
- </listitem>
- <listitem>
- <para>under the <literal>activemq-ra.rar/META-INF</literal> create a <literal>ra.xml</literal> file or
- copy it from the ActiveMQ distribution (again it can be found in the <literal>activemq-ra.rar</literal> archive)
- and configure it as follows</para>
- <programlisting>
-<?xml version="1.0" encoding="UTF-8"?>
-
-<connector xmlns="http://java.sun.com/xml/ns/j2ee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
- http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd"
- version="1.5">
-
- <description>ActiveMQ 2.0 Resource Adapter Alternate Configuration</description>
- <display-name>ActiveMQ 2.0 Resource Adapter Alternate Configuration</display-name>
-
- <vendor-name>Red Hat Middleware LLC</vendor-name>
- <eis-type>JMS 1.1 Server</eis-type>
- <resourceadapter-version>1.0</resourceadapter-version>
-
- <license>
- <description>
-Copyright 2009 Red Hat, Inc.
- Red Hat 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.
- </description>
- <license-required>true</license-required>
- </license>
-
- <resourceadapter>
- <resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter</resourceadapter-class>
- <config-property>
- <description>The transport type</description>
- <config-property-name>ConnectorClassName</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
- </config-property>
- <config-property>
- <description>The transport configuration. These values must be in the form of key=val;key=val;</description>
- <config-property-name>ConnectionParameters</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <emphasis role="bold"> <config-property-value>host=127.0.0.1;port=5445</config-property-value></emphasis>
- </config-property>
-
- <outbound-resourceadapter>
- <connection-definition>
- <managedconnectionfactory-class>org.apache.activemq.ra.ActiveMQRAManagedConnectionFactory</managedconnectionfactory-class>
-
- <config-property>
- <description>The default session type</description>
- <config-property-name>SessionDefaultType</config-property-name>
- <config-property-type>java.lang.String</config-property-type>
- <config-property-value>javax.jms.Queue</config-property-value>
- </config-property>
- <config-property>
- <description>Try to obtain a lock within specified number of seconds; less than or equal to 0 disable this functionality</description>
- <config-property-name>UseTryLock</config-property-name>
- <config-property-type>java.lang.Integer</config-property-type>
- <config-property-value>0</config-property-value>
- </config-property>
-
- <connectionfactory-interface>org.apache.activemq.ra.ActiveMQRAConnectionFactory</connectionfactory-interface>
- <connectionfactory-impl-class>org.apache.activemq.ra.ActiveMQRAConnectionFactoryImpl</connectionfactory-impl-class>
- <connection-interface>javax.jms.Session</connection-interface>
- <connection-impl-class>org.apache.activemq.ra.ActiveMQRASession</connection-impl-class>
- </connection-definition>
- <transaction-support>XATransaction</transaction-support>
- <authentication-mechanism>
- <authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
- <credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface>
- </authentication-mechanism>
- <reauthentication-support>false</reauthentication-support>
- </outbound-resourceadapter>
-
- <inbound-resourceadapter>
- <messageadapter>
- <messagelistener>
- <messagelistener-type>javax.jms.MessageListener</messagelistener-type>
- <activationspec>
- <activationspec-class>org.apache.activemq.ra.inflow.ActiveMQActivationSpec</activationspec-class>
- <required-config-property>
- <config-property-name>destination</config-property-name>
- </required-config-property>
- </activationspec>
- </messagelistener>
- </messageadapter>
- </inbound-resourceadapter>
-
- </resourceadapter>
-</connector></programlisting>
- <para>The important part of this configuration is the part in bold, i.e. <config-property-value>host=127.0.0.1;port=5445</config-property-value>.
- This should be configured to the host and port of the remote ActiveMQ server.</para>
- </listitem>
- </itemizedlist>
- <para>At this point you should be able to now deploy MDB's that consume from the remote server. You will however,
- have to make sure that your MDB's have the annotation <literal>@ResourceAdapter("activemq-ra.rar")</literal>
- added, this is illustrated in the <xref linkend="configuring-mdbs">Configuring Message-Driven Beans</xref> section.
- If you don't want to add this annotation then you can delete the generic resource adapter <literal>jms-ra.rar</literal>
- and rename the <literal>activemq-ra.rar</literal> to this.</para>
- <para>If you also want to use the remote ActiveMQ server for outgoing connections, i.e. sending messages, then
- do the following:</para>
- <itemizedlist>
- <listitem>
- <para>Create a file called <literal>activemq-ds.xml</literal> in the <literal>deploy</literal> directory
- (in fact you can call this anything you want as long as it ends in <literal>-ds.xml</literal>). Then
- add the following:</para>
- <programlisting>
-<connection-factories>
- <!--
- JMS XA Resource adapter, use this for outbound JMS connections.
- Inbound connections are defined at the @MDB activation or at the resource-adapter properties.
- -->
- <tx-connection-factory>
- <jndi-name>RemoteJmsXA</jndi-name>
- <xa-transaction/>
- <rar-name>activemq-ra.rar</rar-name>
- <connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory</connection-definition>
- <config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic</config-property>
- <config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</config-property>
- <config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5445</config-property>
- <max-pool-size>20</max-pool-size>
- </tx-connection-factory>
-
-
-</connection-factories></programlisting>
- <para>Again you will see that the host and port are configured here to match the remote ActiveMQ servers
- configuration. The other important attributes are:</para>
- <itemizedlist>
- <listitem>
- <para>jndi-name - This is the name used to look up the JMS connection factory from within your JEE client</para>
- </listitem>
- <listitem>
- <para>rar-name - This should match the directory that you created to hold the Resource Adapter
- configuration</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- <para>Now you should be able to send messages using the JCA JMS connection pooling within an XA transaction.</para>
- </section>
- <section>
- <title>Configuring JBoss 5</title>
- <para>The steps to do this are exactly the same as for JBoss 4, you will have to create a jboss.xml definition
- file for your MDB with the following entry</para>
- <programlisting>
-<message-driven>
- <ejb-name>MyMDB</ejb-name>
- <resource-adapter-name>jms-ra.rar</resource-adapter-name>
- </message-driven></programlisting>
- <para>Also you will need to edit the <literal>standardjboss.xml</literal> and uncomment the section with the
- following 'Uncomment to use JMS message inflow from jmsra.rar' and then comment out the invoker-proxy-binding
- called 'message-driven-bean'</para>
- </section>
- </section>
- <section>
- <title>High Availability JNDI (HA-JNDI)</title>
- <para>If you are using JNDI to look-up JMS queues, topics and connection factories from a
- cluster of servers, it is likely you will want to use HA-JNDI so that your JNDI look-ups
- will continue to work if one or more of the servers in the cluster fail.</para>
- <para>HA-JNDI is a JBoss Application Server service which allows you to use JNDI from
- clients without them having to know the exact JNDI connection details of every server in
- the cluster. This service is only available if using a cluster of JBoss Application
- Server instances.</para>
- <para>To use it use the following properties when connecting to JNDI.</para>
- <programlisting>
-Hashtable<String, String> jndiParameters = new Hashtable<String, String>();
-jndiParameters.put("java.naming.factory.initial", "org.jnp.interfaces.NamingContextFactory");
-jndiParameters.put("java.naming.factory.url.pkgs=", "org.jboss.naming:org.jnp.interfaces");
-
-initialContext = new InitialContext(jndiParameters);</programlisting>
- <para>For more information on using HA-JNDI see the <ulink
- url="http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Clustering_Guide/5/html/clustering-jndi.html"
- >JBoss Application Server clustering documentation</ulink></para>
- </section>
- <section id="xa-recovery">
- <title>XA Recovery</title>
- <para><emphasis>XA recovery</emphasis> deals with system or application failures to ensure
- that of a transaction are applied consistently to all resources affected by the
- transaction, even if any of the application processes or the machine hosting them crash
- or lose network connectivity. For more information on XA Recovery,please refer to <ulink
- url="http://www.jboss.org/community/wiki/JBossTransactions">JBoss
- Transactions</ulink>.</para>
- <para>When ActiveMQ is integrated with JBoss AS, it can take advantage of JBoss Transactions
- to provide recovery of messaging resources. If messages are involved in a XA
- transaction, in the event of a server crash, the recovery manager will ensure that the
- transactions are recovered and the messages will either be committed or rolled back
- (depending on the transaction outcome) when the server is restarted.</para>
- <section>
- <title>XA Recovery Configuration</title>
- <para>To enable ActiveMQ's XA Recovery, the Recovery Manager must be configured to connect
- to ActiveMQ to recover its resources. The following property must be added to the
- <literal>jta</literal> section of <literal>conf/jbossts-properties.xml</literal>
- of JBoss AS profiles:</para>
- <programlisting>
-<properties depends="arjuna" name="jta">
- ...
-
- <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ActiveMQ1"
- value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;[connection configuration]"/>
- <property name="com.arjuna.ats.jta.xaRecoveryNode" value="1"/>
-</properties></programlisting>
- <para>The <literal>[connection configuration]</literal> contains all the information
- required to connect to ActiveMQ node under the form <literal>[connector factory class
- name],[user name], [password], [connector parameters]</literal>. </para>
- <itemizedlist>
- <listitem>
- <para><literal>[connector factory class name]</literal> corresponds to the name
- of the <literal>ConnectorFactory</literal> used to connect to ActiveMQ.
- Values can be <literal
- >org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory</literal> or
- <literal
- >org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</literal></para>
- </listitem>
- <listitem>
- <para><literal>[user name]</literal> is the user name to create a client
- session. It is optional</para>
- </listitem>
- <listitem>
- <para><literal>[password]</literal> is the password to create a client session.
- It is mandatory only if the user name is specified</para>
- </listitem>
- <listitem>
- <para><literal>[connector parameters]</literal> is a list of comma-separated
- key=value pair which are passed to the connector factory (see <xref
- linkend="configuring-transports"/> for a list of the transport
- parameters).</para>
- </listitem>
- </itemizedlist>
- <para>Also note the <literal>com.arjuna.ats.jta.xaRecoveryNode</literal> parameter. If you want recovery
- enabled then this must be configured to what ever the tx node id is set to, this is configured in the
- same file by the <literal>com.arjuna.ats.arjuna.xa.nodeIdentifier</literal> property.</para>
- <note>
- <para>ActiveMQ must have a valid acceptor which corresponds to the connector
- specified in <literal>conf/jbossts-properties.xml</literal>.</para>
- </note>
- <section>
- <title>Configuration Settings</title>
- <para>If ActiveMQ is configured with a default in-vm acceptor:</para>
- <programlisting>
-<acceptor name="in-vm">
- <factory-class>org.apache.activemq.core.remoting.impl.invm.InVMAcceptorFactory</factory-class>
-</acceptor></programlisting>
- <para>the corresponding configuration in <literal
- >conf/jbossts-properties.xml</literal> is:</para>
- <programlisting>
-<property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
- value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory"/></programlisting>
- <para>If it is now configured with a netty acceptor on a non-default port:</para>
- <programlisting>
-<acceptor name="netty">
- <factory-class>org.apache.activemq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
- <param key="port" value="8888"/>
-</acceptor></programlisting>
- <para>the corresponding configuration in <literal
- >conf/jbossts-properties.xml</literal> is:</para>
- <programlisting>
-<property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
- value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, , , port=8888"/></programlisting>
- <note>
- <para>Note the additional commas to skip the user and password before connector
- parameters</para>
- </note>
- <para>If the recovery must use <literal>admin, adminpass</literal>, the
- configuration would have been:</para>
- <programlisting>
-<property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
- value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, admin, adminpass, port=8888"/></programlisting>
- <para>Configuring ActiveMQ with an invm acceptor and configuring the Recovery Manager
- with an invm connector is the recommended way to enable XA Recovery.</para>
- </section>
- </section>
- <section>
- <title>Example</title>
- <para>See <xref linkend="xa-recovery-example"/> which shows how to configure XA Recovery
- and recover messages after a server crash.</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/architecture.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/architecture.md b/docs/user-manual/en/architecture.md
new file mode 100644
index 0000000..fe0eb7f
--- /dev/null
+++ b/docs/user-manual/en/architecture.md
@@ -0,0 +1,159 @@
+Architecture
+============
+
+In this section we will give an overview of the ActiveMQ high level
+architecture.
+
+Core Architecture
+=================
+
+ActiveMQ core is designed simply as set of Plain Old Java Objects
+(POJOs) - we hope you like its clean-cut design.
+
+We've also designed it to have as few dependencies on external jars as
+possible. In fact, ActiveMQ core has only one jar dependency, netty.jar,
+other than the standard JDK classes! This is because we use some of the
+netty buffer classes internally.
+
+This allows ActiveMQ to be easily embedded in your own project, or
+instantiated in any dependency injection framework such as JBoss
+Microcontainer, Spring or Google Guice.
+
+Each ActiveMQ server has its own ultra high performance persistent
+journal, which it uses for message and other persistence.
+
+Using a high performance journal allows outrageous persistence message
+performance, something not achievable when using a relational database
+for persistence.
+
+ActiveMQ clients, potentially on different physical machines interact
+with the ActiveMQ server. ActiveMQ currently provides two APIs for
+messaging at the client side:
+
+1. Core client API. This is a simple intuitive Java API that allows the
+ full set of messaging functionality without some of the complexities
+ of JMS.
+
+2. JMS client API. The standard JMS API is available at the client
+ side.
+
+JMS semantics are implemented by a thin JMS facade layer on the client
+side.
+
+The ActiveMQ server does not speak JMS and in fact does not know
+anything about JMS, it is a protocol agnostic messaging server designed
+to be used with multiple different protocols.
+
+When a user uses the JMS API on the client side, all JMS interactions
+are translated into operations on the ActiveMQ core client API before
+being transferred over the wire using the ActiveMQ wire format.
+
+The server always just deals with core API interactions.
+
+A schematic illustrating this relationship is shown in figure 3.1 below:
+
+
+
+Figure 3.1 shows two user applications interacting with a ActiveMQ
+server. User Application 1 is using the JMS API, while User Application
+2 is using the core client API directly.
+
+You can see from the diagram that the JMS API is implemented by a thin
+facade layer on the client side.
+
+ActiveMQ embedded in your own application
+=========================================
+
+ActiveMQ core is designed as a set of simple POJOs so if you have an
+application that requires messaging functionality internally but you
+don't want to expose that as a ActiveMQ server you can directly
+instantiate and embed ActiveMQ servers in your own application.
+
+For more information on embedding ActiveMQ, see ?.
+
+ActiveMQ integrated with a JEE application server
+=================================================
+
+ActiveMQ provides its own fully functional Java Connector Architecture
+(JCA) adaptor which enables it to be integrated easily into any JEE
+compliant application server or servlet engine.
+
+JEE application servers provide Message Driven Beans (MDBs), which are a
+special type of Enterprise Java Beans (EJBs) that can process messages
+from sources such as JMS systems or mail systems.
+
+Probably the most common use of an MDB is to consume messages from a JMS
+messaging system.
+
+According to the JEE specification, a JEE application server uses a JCA
+adapter to integrate with a JMS messaging system so it can consume
+messages for MDBs.
+
+However, the JCA adapter is not only used by the JEE application server
+for *consuming* messages via MDBs, it is also used when sending message
+to the JMS messaging system e.g. from inside an EJB or servlet.
+
+When integrating with a JMS messaging system from inside a JEE
+application server it is always recommended that this is done via a JCA
+adaptor. In fact, communicating with a JMS messaging system directly,
+without using JCA would be illegal according to the JEE specification.
+
+The application server's JCA service provides extra functionality such
+as connection pooling and automatic transaction enlistment, which are
+desirable when using messaging, say, from inside an EJB. It is possible
+to talk to a JMS messaging system directly from an EJB, MDB or servlet
+without going through a JCA adapter, but this is not recommended since
+you will not be able to take advantage of the JCA features, such as
+caching of JMS sessions, which can result in poor performance.
+
+Figure 3.2 below shows a JEE application server integrating with a
+ActiveMQ server via the ActiveMQ JCA adaptor. Note that all
+communication between EJB sessions or entity beans and Message Driven
+beans go through the adaptor and not directly to ActiveMQ.
+
+The large arrow with the prohibited sign shows an EJB session bean
+talking directly to the ActiveMQ server. This is not recommended as
+you'll most likely end up creating a new connection and session every
+time you want to interact from the EJB, which is an anti-pattern.
+
+
+
+For more information on using the JCA adaptor, please see ?.
+
+ActiveMQ stand-alone server
+===========================
+
+ActiveMQ can also be deployed as a stand-alone server. This means a
+fully independent messaging server not dependent on a JEE application
+server.
+
+The standard stand-alone messaging server configuration comprises a core
+messaging server, a JMS service and a JNDI service.
+
+The role of the JMS Service is to deploy any JMS Queue, Topic and
+ConnectionFactory instances from any server side `activemq-jms.xml`
+configuration files. It also provides a simple management API for
+creating and destroying Queues, Topics and ConnectionFactory instances
+which can be accessed via JMX or the connection. It is a separate
+service to the ActiveMQ core server, since the core server is JMS
+agnostic. If you don't want to deploy any JMS Queue, Topic or
+ConnectionFactory instances via server side XML configuration and don't
+require a JMS management API on the server side then you can disable
+this service.
+
+We also include a JNDI server since JNDI is a common requirement when
+using JMS to lookup Queues, Topics and ConnectionFactory instances. If
+you do not require JNDI then this service can also be disabled. ActiveMQ
+allows you to programmatically create JMS and core objects directly on
+the client side as opposed to looking them up from JNDI, so a JNDI
+server is not always a requirement.
+
+The stand-alone server configuration uses JBoss Microcontainer to
+instantiate and enforce dependencies between the components. JBoss
+Microcontainer is a very lightweight POJO bootstrapper.
+
+The stand-alone server architecture is shown in figure 3.3 below:
+
+
+
+For more information on server configuration files see ?. \$