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 ?. \$
