Apache
/
activemq-artemis
mirror of https://github.com/apache/activemq-artemis.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

ACTIVEMQ6-9 Clean up docs

This commit is contained in:
jbertram 2014-11-17 21:39:49 -06:00
parent 079e4b2438
commit e7a3e7d25b
66 changed files with 1001 additions and 1004 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
activemq-server/src/main/java/org/apache/activemq/core/config/Configuration.java
View File

@ -998,7 +998,7 @@ public interface Configuration extends Serializable
/* /*
* @see #setResolveProtocols() * @see #setResolveProtocols()
* @return whether HornetQ should resolve and use any Protocols available on the classpath * @return whether HornetQ should resolve and use any Protocols available on the classpath
* Default value is {@value org.apache.activemq.api.config.HornetQDefaultConfiguration#DEFAULT_RESOLVE_PROTOCOLS}. * Default value is {@value org.apache.activemq.api.config.ActiveMQDefaultConfiguration#DEFAULT_RESOLVE_PROTOCOLS}.
* */ * */
boolean isResolveProtocols(); boolean isResolveProtocols();

12
activemq-server/src/main/resources/schema/activemq-configuration.xsd
View File

@ -20,7 +20,7 @@
minOccurs="0"> minOccurs="0">
<xsd:annotation amq:linkend="resolveProtocols"> <xsd:annotation amq:linkend="resolveProtocols">
<xsd:documentation> <xsd:documentation>
If true then the HornetQ Server will make use of any Protocol Managers that are in available on the If true then the ActiveMQ Server will make use of any Protocol Managers that are in available on the
classpath. If false then only the core protocol will be available, unless in Embedded mode where users classpath. If false then only the core protocol will be available, unless in Embedded mode where users
can inject their own Protocol Managers. can inject their own Protocol Managers.
</xsd:documentation> </xsd:documentation>
@ -31,7 +31,7 @@
minOccurs="0"> minOccurs="0">
<xsd:annotation amq:linkend="clusters"> <xsd:annotation amq:linkend="clusters">
<xsd:documentation> <xsd:documentation>
DEPRECATED. This option is deprecated and its value will be ignored (HQ221038). A HornetQ server will DEPRECATED. This option is deprecated and its value will be ignored (HQ221038). A ActiveMQ server will
be "clustered" when its configuration contain a cluster-configuration. be "clustered" when its configuration contain a cluster-configuration.
</xsd:documentation> </xsd:documentation>
</xsd:annotation> </xsd:annotation>
@ -112,7 +112,7 @@
</xsd:annotation> </xsd:annotation>
</xsd:element> </xsd:element>
<xsd:element name="management-address" type="xsd:string" default="jms.queue.hornetq.management" maxOccurs="1" <xsd:element name="management-address" type="xsd:string" default="jms.queue.activemq.management" maxOccurs="1"
minOccurs="0"> minOccurs="0">
<xsd:annotation amq:linkend="management.core.configuration" <xsd:annotation amq:linkend="management.core.configuration"
amq:type="SimpleString"> amq:type="SimpleString">
@ -123,7 +123,7 @@
</xsd:annotation> </xsd:annotation>
</xsd:element> </xsd:element>
<xsd:element name="management-notification-address" type="xsd:string" default="hornetq.notifications" <xsd:element name="management-notification-address" type="xsd:string" default="activemq.notifications"
maxOccurs="1" minOccurs="0"> maxOccurs="1" minOccurs="0">
<xsd:annotation amq:linkend="management.notifications.core.configuration" <xsd:annotation amq:linkend="management.notifications.core.configuration"
amq:type="SimpleString"> amq:type="SimpleString">
@ -133,7 +133,7 @@
</xsd:annotation> </xsd:annotation>
</xsd:element> </xsd:element>
<xsd:element name="cluster-user" type="xsd:string" default="HORNETQ.CLUSTER.ADMIN.USER" maxOccurs="1" <xsd:element name="cluster-user" type="xsd:string" default="ACTIVEMQ.CLUSTER.ADMIN.USER" maxOccurs="1"
minOccurs="0"> minOccurs="0">
<xsd:annotation amq:linkend="clusters"> <xsd:annotation amq:linkend="clusters">
<xsd:documentation> <xsd:documentation>
@ -221,7 +221,7 @@
<xsd:element name="jmx-domain" type="xsd:string" default="org.apache.activemq" maxOccurs="1" minOccurs="0"> <xsd:element name="jmx-domain" type="xsd:string" default="org.apache.activemq" maxOccurs="1" minOccurs="0">
<xsd:annotation amq:linkend="management.jmx.configuration"> <xsd:annotation amq:linkend="management.jmx.configuration">
<xsd:documentation> <xsd:documentation>
the JMX domain used to registered HornetQ MBeans in the MBeanServer the JMX domain used to registered ActiveMQ MBeans in the MBeanServer
</xsd:documentation> </xsd:documentation>
</xsd:annotation> </xsd:annotation>
</xsd:element> </xsd:element>

5
distribution/activemq/pom.xml
View File

@ -73,11 +73,6 @@
<artifactId>activemq-ra</artifactId> <artifactId>activemq-ra</artifactId>
<version>${project.version}</version> <version>${project.version}</version>
</dependency> </dependency>
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>activemq-service-sar</artifactId>
<version>${project.version}</version>
</dependency>
<dependency> <dependency>
<groupId>org.apache.activemq</groupId> <groupId>org.apache.activemq</groupId>
<artifactId>activemq-spring-integration</artifactId> <artifactId>activemq-spring-integration</artifactId>

4
docs/user-manual/en/HornetQ_User_Manual.ent → docs/user-manual/en/ActiveMQ_User_Manual.ent
View File

@ -1,5 +1,5 @@
<!ENTITY PRODUCT "HornetQ"> <!ENTITY PRODUCT "ActiveMQ">
<!ENTITY BOOKID "HornetQ_QuickStart_Guide"> <!ENTITY BOOKID "ActiveMQ_QuickStart_Guide">
<!ENTITY YEAR "2011"> <!ENTITY YEAR "2011">
<!ENTITY HOLDER "Red Hat Inc."> <!ENTITY HOLDER "Red Hat Inc.">
<!ENTITY semi ";"><!-- <!ENTITY semi ";"><!--

4
docs/user-manual/en/HornetQ_User_Manual.xml → docs/user-manual/en/ActiveMQ_User_Manual.xml
View File

@ -13,7 +13,7 @@
--> -->
<!-- This document was created with Syntext Serna Free. --><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!-- This document was created with Syntext Serna Free. --><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
@ -63,7 +63,7 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="thread-pooling.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="thread-pooling.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="rest.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="rest.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="embedding-hornetq.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="embedding-activemq.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="spring-integration.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="spring-integration.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="aerogear-integration.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="aerogear-integration.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="vertx-integration.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="vertx-integration.xml"/>

2
docs/user-manual/en/Author_Group.xml
View File

@ -13,7 +13,7 @@
--> -->
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<authorgroup> <authorgroup>

16
docs/user-manual/en/Book_Info.xml
View File

@ -13,29 +13,29 @@
--> -->
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<bookinfo id="HornetQ_User_Manual"> <bookinfo id="ActiveMQ_User_Manual">
<title>HornetQ User Manual</title> <title>ActiveMQ User Manual</title>
<subtitle>Putting the buzz in messaging</subtitle> <subtitle>Putting the buzz in messaging</subtitle>
<productname>HornetQ</productname> <productname>ActiveMQ</productname>
<productnumber>2</productnumber> <productnumber>2</productnumber>
<edition>2.1.0</edition> <edition>2.1.0</edition>
<pubsnumber>1</pubsnumber> <pubsnumber>1</pubsnumber>
<abstract> <abstract>
<para>The User manual is an in depth manual on all aspects of HornetQ</para> <para>The User manual is an in depth manual on all aspects of ActiveMQ</para>
</abstract> </abstract>
<corpauthor> <!--corpauthor>
<inlinemediaobject> <inlinemediaobject>
<imageobject> <imageobject>
<imagedata fileref="images/hornetQ_logo_600px.png" format="PNG"/> <imagedata fileref="images/hornetQ_logo_600px.png" format="PNG"/>
</imageobject> </imageobject>
<textobject> <textobject>
<phrase>HornetQ Logo</phrase> <phrase>ActiveMQ Logo</phrase>
</textobject> </textobject>
</inlinemediaobject> </inlinemediaobject>
</corpauthor> </corpauthor-->
<copyright> <copyright>
<year>&YEAR;</year> <year>&YEAR;</year>
<holder>&HOLDER;</holder> <holder>&HOLDER;</holder>

6
docs/user-manual/en/aerogear-integration.xml
View File

@ -18,13 +18,13 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="aerogear-integration"> <chapter id="aerogear-integration">
<title>AeroGear Integration</title> <title>AeroGear Integration</title>
<para>AeroGears push technology provides support for different push notification technologies like Google Cloud Messaging, <para>AeroGears push technology provides support for different push notification technologies like Google Cloud Messaging,
Apple's APNs or Mozilla's SimplePush. HornetQ allows you to configure a Connector Service that will consume messages Apple's APNs or Mozilla's SimplePush. ActiveMQ allows you to configure a Connector Service that will consume messages
from a queue and forward them to an AeroGear push server and subsequently sent as notifications to mobile devices.</para> from a queue and forward them to an AeroGear push server and subsequently sent as notifications to mobile devices.</para>
<section> <section>
<title>Configuring an AeroGear Connector Service</title> <title>Configuring an AeroGear Connector Service</title>
@ -96,7 +96,7 @@
<programlisting> <programlisting>
Message message = session.createMessage(); Message message = session.createMessage();
message.setStringProperty("AEROGEAR_ALERT", "Hello this is a notification from HornetQ"); message.setStringProperty("AEROGEAR_ALERT", "Hello this is a notification from ActiveMQ");
producer.send(message); producer.send(message);
</programlisting> </programlisting>

202
docs/user-manual/en/appserver-integration.xml
View File

@ -18,14 +18,14 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="appserver-integration"> <chapter id="appserver-integration">
<title>Application Server Integration and Java EE</title> <title>Application Server Integration and Java EE</title>
<para>HornetQ can be easily installed in JBoss Application Server 4 or later. For details on <para>ActiveMQ can be easily installed in JBoss Application Server 4 or later. For details on
installing HornetQ in the JBoss Application Server please refer to quick-start guide.</para> installing ActiveMQ in the JBoss Application Server please refer to quick-start guide.</para>
<para>Since HornetQ also provides a JCA adapter, it is also possible to integrate HornetQ <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 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 remote JCA adaptor into another application sever, please consult the other application server's
instructions.</para> instructions.</para>
@ -35,10 +35,10 @@
AS.</para> AS.</para>
<section id="configuring-mdbs"> <section id="configuring-mdbs">
<title>Configuring Message-Driven Beans</title> <title>Configuring Message-Driven Beans</title>
<para>The delivery of messages to an MDB using HornetQ is configured on the JCA Adapter via <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 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 >jms-ra.rar</literal> directory. By default this is configured to consume
messages using an InVM connector from the instance of HornetQ running within the 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> 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. <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> The following example shows how this can be done using annotations:</para>
@ -48,14 +48,14 @@
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"), @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue") @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
}) })
@ResourceAdapter("hornetq-ra.rar") @ResourceAdapter("activemq-ra.rar")
public class MDBExample implements MessageListener public class MDBExample implements MessageListener
{ {
public void onMessage(Message message)... public void onMessage(Message message)...
}</programlisting> }</programlisting>
<para>In this example you can see that the MDB will consume messages from a queue that is <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 mapped into JNDI with the binding <literal>queue/testQueue</literal>. This queue must be
preconfigured in the usual way using the HornetQ configuration files.</para> preconfigured in the usual way using the ActiveMQ configuration files.</para>
<para>The <literal>ResourceAdapter</literal> annotation is used to specify which adaptor <para>The <literal>ResourceAdapter</literal> annotation is used to specify which adaptor
should be used. To use this you will need to import <literal 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 >org.jboss.ejb3.annotation.ResourceAdapter</literal> for JBoss AS 5.X and later version which can be found in the
@ -66,18 +66,18 @@ public class MDBExample implements MessageListener
the following to <literal the following to <literal
>jboss.xml</literal><programlisting>&lt;message-driven> >jboss.xml</literal><programlisting>&lt;message-driven>
&lt;ejb-name>ExampleMDB&lt;/ejb-name> &lt;ejb-name>ExampleMDB&lt;/ejb-name>
&lt;resource-adapter-name>hornetq-ra.rar&lt;/resource-adapter-name> &lt;resource-adapter-name>activemq-ra.rar&lt;/resource-adapter-name>
&lt;/message-driven> &lt;/message-driven>
</programlisting>You </programlisting>You
can also rename the hornetq-ra.rar directory to jms-ra.rar and neither the annotation or 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 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> the <literal>jms-ds.xml</literal> datasource file and change <literal>rar-name</literal>
element.</para> element.</para>
<note> <note>
<para>HornetQ is the default JMS provider for JBoss AS 6. Starting with this AS version, HornetQ resource <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> adapter is named <literal>jms-ra.rar</literal> and you no longer need to annotate the MDB for the resource adapter name.</para>
</note> </note>
<para>All the examples shipped with the HornetQ distribution use the annotation.</para> <para>All the examples shipped with the ActiveMQ distribution use the annotation.</para>
<section> <section>
<title>Using Container-Managed Transactions</title> <title>Using Container-Managed Transactions</title>
<para>When an MDB is using Container-Managed Transactions (CMT), the delivery of the <para>When an MDB is using Container-Managed Transactions (CMT), the delivery of the
@ -94,7 +94,7 @@ public class MDBExample implements MessageListener
}) })
@TransactionManagement(value= TransactionManagementType.CONTAINER) @TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED) @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("hornetq-ra.rar") @ResourceAdapter("activemq-ra.rar")
public class MDB_CMP_TxRequiredExample implements MessageListener public class MDB_CMP_TxRequiredExample implements MessageListener
{ {
public void onMessage(Message message)... public void onMessage(Message message)...
@ -137,7 +137,7 @@ public void onMessage(Message message)
}) })
@TransactionManagement(value = TransactionManagementType.CONTAINER) @TransactionManagement(value = TransactionManagementType.CONTAINER)
@TransactionAttribute(value = TransactionAttributeType.NOT_SUPPORTED) @TransactionAttribute(value = TransactionAttributeType.NOT_SUPPORTED)
@ResourceAdapter("hornetq-ra.rar") @ResourceAdapter("activemq-ra.rar")
public class MDB_CMP_TxLocalExample implements MessageListener public class MDB_CMP_TxLocalExample implements MessageListener
{ {
public void onMessage(Message message)... public void onMessage(Message message)...
@ -156,7 +156,7 @@ public class MDB_CMP_TxLocalExample implements MessageListener
@ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Dups-ok-acknowledge") @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Dups-ok-acknowledge")
}) })
@TransactionManagement(value= TransactionManagementType.BEAN) @TransactionManagement(value= TransactionManagementType.BEAN)
@ResourceAdapter("hornetq-ra.rar") @ResourceAdapter("activemq-ra.rar")
public class MDB_BMPExample implements MessageListener public class MDB_BMPExample implements MessageListener
{ {
public void onMessage(Message message) public void onMessage(Message message)
@ -211,7 +211,7 @@ public void onMessage(Message message)
}) })
@TransactionManagement(value= TransactionManagementType.CONTAINER) @TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED) @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("hornetq-ra.rar") @ResourceAdapter("activemq-ra.rar")
public class MDBMessageSelectorExample implements MessageListener public class MDBMessageSelectorExample implements MessageListener
{ {
public void onMessage(Message message).... public void onMessage(Message message)....
@ -236,7 +236,7 @@ public class MDBMessageSelectorExample implements MessageListener
}) })
@TransactionManagement(value= TransactionManagementType.CONTAINER) @TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED) @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("hornetq-ra.rar") @ResourceAdapter("activemq-ra.rar")
public class MDBMessageSendTxExample implements MessageListener public class MDBMessageSendTxExample implements MessageListener
{ {
@Resource(mappedName = "java:/JmsXA") @Resource(mappedName = "java:/JmsXA")
@ -308,24 +308,24 @@ public class MDBMessageSendTxExample implements MessageListener
}) })
@TransactionManagement(value= TransactionManagementType.CONTAINER) @TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED) @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("hornetq-ra.rar") @ResourceAdapter("activemq-ra.rar")
public class MyMDB implements MessageListener public class MyMDB implements MessageListener
{ ....} { ....}
</programlisting> </programlisting>
</section> </section>
<section> <section>
<title>Configuring the JCA Adaptor</title> <title>Configuring the JCA Adaptor</title>
<para>The Java Connector Architecture (JCA) Adapter is what allows HornetQ to be integrated <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 with JEE components such as MDBs and EJBs. It configures how components such as MDBs
consume messages from the HornetQ server and also how components such as EJBs or consume messages from the ActiveMQ server and also how components such as EJBs or
Servlets can send messages.</para> Servlets can send messages.</para>
<para>The HornetQ JCA adapter is deployed via the <literal>jms-ra.rar</literal> archive. The <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 configuration of the adapter is found in this archive under <literal
>META-INF/ra.xml</literal>.</para> >META-INF/ra.xml</literal>.</para>
<para>The configuration will look something like the following:</para> <para>The configuration will look something like the following:</para>
<programlisting> <programlisting>
&lt;resourceadapter> &lt;resourceadapter>
&lt;resourceadapter-class>org.apache.activemq.ra.HornetQResourceAdapter&lt;/resourceadapter-class> &lt;resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter&lt;/resourceadapter-class>
&lt;config-property> &lt;config-property>
&lt;description>The transport type. Multiple connectors can be configured by using a comma separated list, &lt;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.&lt;/description> i.e. org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory,org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory.&lt;/description>
@ -344,7 +344,7 @@ public class MyMDB implements MessageListener
&lt;outbound-resourceadapter> &lt;outbound-resourceadapter>
&lt;connection-definition> &lt;connection-definition>
&lt;managedconnectionfactory-class>org.apache.activemq.ra.HornetQRAManagedConnection &lt;managedconnectionfactory-class>org.apache.activemq.ra.ActiveMQRAManagedConnection
Factory&lt;/managedconnectionfactory-class> Factory&lt;/managedconnectionfactory-class>
&lt;config-property> &lt;config-property>
@ -361,12 +361,12 @@ public class MyMDB implements MessageListener
&lt;config-property-value>0&lt;/config-property-value> &lt;config-property-value>0&lt;/config-property-value>
&lt;/config-property> &lt;/config-property>
&lt;connectionfactory-interface>org.apache.activemq.ra.HornetQRAConnectionFactory &lt;connectionfactory-interface>org.apache.activemq.ra.ActiveMQRAConnectionFactory
&lt;/connectionfactory-interface> &lt;/connectionfactory-interface>
&lt;connectionfactororg.apache.activemq.ra.HornetQConnectionFactoryImplonFactoryImpl &lt;connectionfactororg.apache.activemq.ra.ActiveMQConnectionFactoryImplonFactoryImpl
&lt;/connectionfactory-impl-class> &lt;/connectionfactory-impl-class>
&lt;connection-interface>javax.jms.Session&lt;/connection-interface> &lt;connection-interface>javax.jms.Session&lt;/connection-interface>
&lt;connection-impl-class>org.apache.activemq.ra.HornetQRASession &lt;connection-impl-class>org.apache.activemq.ra.ActiveMQRASession
&lt;/connection-impl-class> &lt;/connection-impl-class>
&lt;/connection-definition> &lt;/connection-definition>
&lt;transaction-support>XATransaction&lt;/transaction-support> &lt;transaction-support>XATransaction&lt;/transaction-support>
@ -384,7 +384,7 @@ public class MyMDB implements MessageListener
&lt;messagelistener> &lt;messagelistener>
&lt;messagelistener-type>javax.jms.MessageListener&lt;/messagelistener-type> &lt;messagelistener-type>javax.jms.MessageListener&lt;/messagelistener-type>
&lt;activationspec> &lt;activationspec>
&lt;activationspec-class>org.apache.activemq.ra.inflow.HornetQActivationSpec &lt;activationspec-class>org.apache.activemq.ra.inflow.ActiveMQActivationSpec
&lt;/activationspec-class> &lt;/activationspec-class>
&lt;required-config-property> &lt;required-config-property>
&lt;config-property-name>destination&lt;/config-property-name> &lt;config-property-name>destination&lt;/config-property-name>
@ -411,7 +411,7 @@ public class MyMDB implements MessageListener
<section> <section>
<title>Global Properties</title> <title>Global Properties</title>
<para>The first element you see is <literal>resourceadapter-class</literal> which should <para>The first element you see is <literal>resourceadapter-class</literal> which should
be left unchanged. This is the HornetQ resource adapter class.</para> 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 <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 the configuration is done. The first two properties configure the transport used by the adapter
and the rest configure the connection factory itself. and the rest configure the connection factory itself.
@ -699,12 +699,12 @@ public class MyMDB implements MessageListener
factories that are used by Java EE components. These Connection Factories can be factories that are used by Java EE components. These Connection Factories can be
defined inside a configuration file that matches the name <literal defined inside a configuration file that matches the name <literal
>*-ds.xml</literal>. You'll find a default <literal>jms-ds.xml</literal> >*-ds.xml</literal>. You'll find a default <literal>jms-ds.xml</literal>
configuration under the <literal>hornetq</literal> directory in the JBoss AS configuration under the <literal>activemq</literal> directory in the JBoss AS
deployment. The connection factories defined in this file inherit their deployment. The connection factories defined in this file inherit their
properties from the main <literal>ra.xml</literal> configuration but can also be properties from the main <literal>ra.xml</literal> configuration but can also be
overridden. The following example shows how to override them.</para> overridden. The following example shows how to override them.</para>
<note> <note>
<para>Please note that this configuration only applies when HornetQ resource adapter is installed in <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 JBoss Application Server. If you are using another JEE application
server please refer to your application servers documentation for how to do server please refer to your application servers documentation for how to do
this.</para> this.</para>
@ -714,7 +714,7 @@ public class MyMDB implements MessageListener
&lt;jndi-name>RemoteJmsXA&lt;/jndi-name> &lt;jndi-name>RemoteJmsXA&lt;/jndi-name>
&lt;xa-transaction/> &lt;xa-transaction/>
&lt;rar-name>jms-ra.rar&lt;/rar-name> &lt;rar-name>jms-ra.rar&lt;/rar-name>
&lt;connection-definition>org.apache.activemq.ra.HornetQRAConnectionFactory &lt;connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory
&lt;/connection-definition> &lt;/connection-definition>
&lt;config-property name="SessionDefaultType" type="String">javax.jms.Topic&lt;/config-property> &lt;config-property name="SessionDefaultType" type="String">javax.jms.Topic&lt;/config-property>
&lt;config-property name="ConnectorClassName" type="String"> &lt;config-property name="ConnectorClassName" type="String">
@ -811,8 +811,8 @@ private ConnectionFactory connectionFactory;</programlisting>
<entry>JndiParams</entry> <entry>JndiParams</entry>
<entry>String</entry> <entry>String</entry>
<entry>A semicolon (';') delimited string of name=value pairs which represent the properties to be used for the destination JNDI <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 HornetQ. Typically only be used when the MDB is 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 HornetQ name of the 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> destination. Only relevant when <literal>useJNDI</literal> is <literal>true</literal> (default is an empty string).</entry>
</row> </row>
<row> <row>
@ -856,9 +856,9 @@ private ConnectionFactory connectionFactory;</programlisting>
</section> </section>
<section> <section>
<title>Configuring the adapter to use a standalone HornetQ Server</title> <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. <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 hornetq client libs installed. This section explains what config to create 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> and what jar dependencies are needed.</para>
<section> <section>
<para>There are two configuration files needed to do this, one for the incoming adapter used for MDB's <para>There are two configuration files needed to do this, one for the incoming adapter used for MDB's
@ -870,7 +870,7 @@ private ConnectionFactory connectionFactory;</programlisting>
<literal>deploy</literal> <literal>deploy</literal>
directory ending in directory ending in
<literal>.rar.</literal> <literal>.rar.</literal>
For this example we will name the directory <literal>hornetq-ra.rar</literal>. This detail is For this example we will name the directory <literal>activemq-ra.rar</literal>. This detail is
important as important as
the name of directory is referred to by the MDB's and the outgoing configuration. the name of directory is referred to by the MDB's and the outgoing configuration.
@ -882,7 +882,7 @@ private ConnectionFactory connectionFactory;</programlisting>
</para> </para>
</note> </note>
<para>Under the <para>Under the
<literal>hornetq-ra.rar</literal> <literal>activemq-ra.rar</literal>
directory you will need to create a directory you will need to create a
<literal>META-INF</literal> <literal>META-INF</literal>
directory into which you should create an directory into which you should create an
@ -890,19 +890,19 @@ private ConnectionFactory connectionFactory;</programlisting>
configuration file. You can find a template configuration file. You can find a template
for the for the
<literal>ra.xml</literal> <literal>ra.xml</literal>
under the config directory of the HornetQ distribution. under the config directory of the ActiveMQ distribution.
</para> </para>
<para>To configure MDB's to consume messages from a remote HornetQ server you need to edit the <para>To configure MDB's to consume messages from a remote ActiveMQ server you need to edit the
<literal>ra.xml</literal> <literal>ra.xml</literal>
file under file under
<literal>deploy/hornet-ra.rar/META-INF</literal> <literal>deploy/activemq-ra.rar/META-INF</literal>
and change the transport type to and change the transport type to
use a netty connector (instead of the invm connector that is defined) and configure its transport use a netty connector (instead of the invm connector that is defined) and configure its transport
parameters. parameters.
Heres an example of what this would look like: Heres an example of what this would look like:
</para> </para>
<programlisting> <programlisting>
&lt;resourceadapter-class>org.apache.activemq.ra.HornetQResourceAdapter&lt;/resourceadapter-class> &lt;resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter&lt;/resourceadapter-class>
&lt;config-property> &lt;config-property>
&lt;description>The transport type&lt;/description> &lt;description>The transport type&lt;/description>
&lt;config-property-name>ConnectorClassName&lt;/config-property-name> &lt;config-property-name>ConnectorClassName&lt;/config-property-name>
@ -921,7 +921,7 @@ private ConnectionFactory connectionFactory;</programlisting>
</para> </para>
<programlisting> <programlisting>
&lt;resourceadapter-class>org.apache.activemq.ra.HornetQResourceAdapter&lt;/resourceadapter-class> &lt;resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter&lt;/resourceadapter-class>
&lt;config-property> &lt;config-property>
&lt;description>The transport type&lt;/description> &lt;description>The transport type&lt;/description>
&lt;config-property-name>ConnectorClassName&lt;/config-property-name> &lt;config-property-name>ConnectorClassName&lt;/config-property-name>
@ -948,30 +948,30 @@ private ConnectionFactory connectionFactory;</programlisting>
<section> <section>
<title>Configuring the outgoing adaptor</title> <title>Configuring the outgoing adaptor</title>
<para>You will also need to configure the outbound connection by creating a <literal>hornetq-ds.xml</literal> <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. and placing it under any directory that will be deployed under the <literal>deploy</literal> directory.
In a standard HornetQ jboss configuration this would be under <literal>hornetq</literal> or <literal>hornetq.sar</literal> 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 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 call it anything you like. You can again find a template for this file under the config directory of the
HornetQ distribution but called <literal>jms-ds.xml</literal> which is the jboss default. ActiveMQ distribution but called <literal>jms-ds.xml</literal> which is the jboss default.
</para> </para>
<para>The following example shows a sample configuration</para> <para>The following example shows a sample configuration</para>
<programlisting> <programlisting>
&lt;tx-connection-factory> &lt;tx-connection-factory>
&lt;jndi-name>RemoteJmsXA&lt;/jndi-name> &lt;jndi-name>RemoteJmsXA&lt;/jndi-name>
&lt;xa-transaction/> &lt;xa-transaction/>
&lt;rar-name>hornetq-ra.rar&lt;/rar-name> &lt;rar-name>activemq-ra.rar&lt;/rar-name>
&lt;connection-definition>org.apache.activemq.ra.HornetQRAConnectionFactory&lt;/connection-definition> &lt;connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory&lt;/connection-definition>
&lt;config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic&lt;/config-property> &lt;config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic&lt;/config-property>
&lt;config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory&lt;/config-property> &lt;config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory&lt;/config-property>
&lt;config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5446&lt;/config-property> &lt;config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5446&lt;/config-property>
&lt;max-pool-size>20&lt;/max-pool-size> &lt;max-pool-size>20&lt;/max-pool-size>
&lt;/tx-connection-factory></programlisting> &lt;/tx-connection-factory></programlisting>
<para>Again you will see that this uses the netty connector type and will connect to the HornetQ server <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 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 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 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>hornetq-ra.rar</literal> will be created by the resource adaptor configured under the directory <literal>activemq-ra.rar</literal>
as explained in the last section. as explained in the last section.
</para> </para>
<para> <para>
@ -981,7 +981,7 @@ private ConnectionFactory connectionFactory;</programlisting>
<section> <section>
<title>Jar dependencies</title> <title>Jar dependencies</title>
<para>This is a list of the HornetQ and third party jars needed</para> <para>This is a list of the ActiveMQ and third party jars needed</para>
<table frame="topbot" border="2"> <table frame="topbot" border="2">
<title>Jar Dependencies</title> <title>Jar Dependencies</title>
<tgroup cols="3"> <tgroup cols="3">
@ -997,18 +997,18 @@ private ConnectionFactory connectionFactory;</programlisting>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>hornetq-ra.jar</entry> <entry>activemq-ra.jar</entry>
<entry>The HornetQ resource adaptor classes</entry> <entry>The ActiveMQ resource adaptor classes</entry>
<entry>deploy/hornetq-ra.rar or equivalent</entry> <entry>deploy/activemq-ra.rar or equivalent</entry>
</row> </row>
<row> <row>
<entry>hornetq-core-client.jar</entry> <entry>activemq-core-client.jar</entry>
<entry>The HornetQ core client classes</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> <entry>either in the config lib, i.e. default/lib or the common lib dir, i.e. $JBOSS_HOME/common lib </entry>
</row> </row>
<row> <row>
<entry>hornetq-jms-client.jar</entry> <entry>activemq-jms-client.jar</entry>
<entry>The HornetQ JMS classes</entry> <entry>The ActiveMQ JMS classes</entry>
<entry>as above</entry> <entry>as above</entry>
</row> </row>
<row> <row>
@ -1025,26 +1025,26 @@ private ConnectionFactory connectionFactory;</programlisting>
</section> </section>
</section> </section>
<section> <section>
<title>Configuring the JBoss Application Server to connect to Remote HornetQ Server</title> <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 HornetQ installed <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 HornetQ</para> to use a remote instance of ActiveMQ</para>
<section> <section>
<title>Configuring JBoss 5</title> <title>Configuring JBoss 5</title>
<para>Firstly download and install JBoss AS 5 as per the JBoss installation guide and HornetQ as per the <para>Firstly download and install JBoss AS 5 as per the JBoss installation guide and ActiveMQ as per the
HornetQ installation guide. After that the following steps are required</para> ActiveMQ installation guide. After that the following steps are required</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Copy the following jars from the HornetQ distribution to the <literal>lib</literal> directory of <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> which ever JBossAs configuration you have chosen, i.e. <literal>default</literal>.</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>hornetq-core-client.jar</para> <para>activemq-core-client.jar</para>
</listitem> </listitem>
<listitem> <listitem>
<para>hornetq-jms-client.jar</para> <para>activemq-jms-client.jar</para>
</listitem> </listitem>
<listitem> <listitem>
<para>hornetq-ra.jar (this can be found inside the <literal>hornetq-ra.rar</literal> archive)</para> <para>activemq-ra.jar (this can be found inside the <literal>activemq-ra.rar</literal> archive)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>netty.jar</para> <para>netty.jar</para>
@ -1052,12 +1052,12 @@ private ConnectionFactory connectionFactory;</programlisting>
</itemizedlist> </itemizedlist>
</listitem> </listitem>
<listitem> <listitem>
<para>create the directories <literal>hornetq-ra.rar</literal> and <literal>hornetq-ra.rar/META-INF</literal> <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> under the <literal>deploy</literal> directory in your JBoss config directory</para>
</listitem> </listitem>
<listitem> <listitem>
<para>under the <literal>hornetq-ra.rar/META-INF</literal> create a <literal>ra.xml</literal> file or <para>under the <literal>activemq-ra.rar/META-INF</literal> create a <literal>ra.xml</literal> file or
copy it from the HornetQ distribution (again it can be found in the <literal>hornetq-ra.rar</literal> archive) 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> and configure it as follows</para>
<programlisting> <programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?> &lt;?xml version="1.0" encoding="UTF-8"?>
@ -1068,8 +1068,8 @@ private ConnectionFactory connectionFactory;</programlisting>
http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd" http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd"
version="1.5"> version="1.5">
&lt;description>HornetQ 2.0 Resource Adapter Alternate Configuration&lt;/description> &lt;description>ActiveMQ 2.0 Resource Adapter Alternate Configuration&lt;/description>
&lt;display-name>HornetQ 2.0 Resource Adapter Alternate Configuration&lt;/display-name> &lt;display-name>ActiveMQ 2.0 Resource Adapter Alternate Configuration&lt;/display-name>
&lt;vendor-name>Red Hat Middleware LLC&lt;/vendor-name> &lt;vendor-name>Red Hat Middleware LLC&lt;/vendor-name>
&lt;eis-type>JMS 1.1 Server&lt;/eis-type> &lt;eis-type>JMS 1.1 Server&lt;/eis-type>
@ -1092,7 +1092,7 @@ Copyright 2009 Red Hat, Inc.
&lt;/license> &lt;/license>
&lt;resourceadapter> &lt;resourceadapter>
&lt;resourceadapter-class>org.apache.activemq.ra.HornetQResourceAdapter&lt;/resourceadapter-class> &lt;resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter&lt;/resourceadapter-class>
&lt;config-property> &lt;config-property>
&lt;description>The transport type&lt;/description> &lt;description>The transport type&lt;/description>
&lt;config-property-name>ConnectorClassName&lt;/config-property-name> &lt;config-property-name>ConnectorClassName&lt;/config-property-name>
@ -1108,7 +1108,7 @@ Copyright 2009 Red Hat, Inc.
&lt;outbound-resourceadapter> &lt;outbound-resourceadapter>
&lt;connection-definition> &lt;connection-definition>
&lt;managedconnectionfactory-class>org.apache.activemq.ra.HornetQRAManagedConnectionFactory&lt;/managedconnectionfactory-class> &lt;managedconnectionfactory-class>org.apache.activemq.ra.ActiveMQRAManagedConnectionFactory&lt;/managedconnectionfactory-class>
&lt;config-property> &lt;config-property>
&lt;description>The default session type&lt;/description> &lt;description>The default session type&lt;/description>
@ -1123,10 +1123,10 @@ Copyright 2009 Red Hat, Inc.
&lt;config-property-value>0&lt;/config-property-value> &lt;config-property-value>0&lt;/config-property-value>
&lt;/config-property> &lt;/config-property>
&lt;connectionfactory-interface>org.apache.activemq.ra.HornetQRAConnectionFactory&lt;/connectionfactory-interface> &lt;connectionfactory-interface>org.apache.activemq.ra.ActiveMQRAConnectionFactory&lt;/connectionfactory-interface>
&lt;connectionfactory-impl-class>org.apache.activemq.ra.HornetQRAConnectionFactoryImpl&lt;/connectionfactory-impl-class> &lt;connectionfactory-impl-class>org.apache.activemq.ra.ActiveMQRAConnectionFactoryImpl&lt;/connectionfactory-impl-class>
&lt;connection-interface>javax.jms.Session&lt;/connection-interface> &lt;connection-interface>javax.jms.Session&lt;/connection-interface>
&lt;connection-impl-class>org.apache.activemq.ra.HornetQRASession&lt;/connection-impl-class> &lt;connection-impl-class>org.apache.activemq.ra.ActiveMQRASession&lt;/connection-impl-class>
&lt;/connection-definition> &lt;/connection-definition>
&lt;transaction-support>XATransaction&lt;/transaction-support> &lt;transaction-support>XATransaction&lt;/transaction-support>
&lt;authentication-mechanism> &lt;authentication-mechanism>
@ -1141,7 +1141,7 @@ Copyright 2009 Red Hat, Inc.
&lt;messagelistener> &lt;messagelistener>
&lt;messagelistener-type>javax.jms.MessageListener&lt;/messagelistener-type> &lt;messagelistener-type>javax.jms.MessageListener&lt;/messagelistener-type>
&lt;activationspec> &lt;activationspec>
&lt;activationspec-class>org.apache.activemq.ra.inflow.HornetQActivationSpec&lt;/activationspec-class> &lt;activationspec-class>org.apache.activemq.ra.inflow.ActiveMQActivationSpec&lt;/activationspec-class>
&lt;required-config-property> &lt;required-config-property>
&lt;config-property-name>destination&lt;/config-property-name> &lt;config-property-name>destination&lt;/config-property-name>
&lt;/required-config-property> &lt;/required-config-property>
@ -1153,19 +1153,19 @@ Copyright 2009 Red Hat, Inc.
&lt;/resourceadapter> &lt;/resourceadapter>
&lt;/connector></programlisting> &lt;/connector></programlisting>
<para>The important part of this configuration is the part in bold, i.e. &lt;config-property-value>host=127.0.0.1;port=5445&lt;/config-property-value>. <para>The important part of this configuration is the part in bold, i.e. &lt;config-property-value>host=127.0.0.1;port=5445&lt;/config-property-value>.
This should be configured to the host and port of the remote HornetQ server.</para> This should be configured to the host and port of the remote ActiveMQ server.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>At this point you should be able to now deploy MDB's that consume from the remote server. You will however, <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("hornetq-ra.rar")</literal> 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. 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> 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>hornetq-ra.rar</literal> to this.</para> and rename the <literal>activemq-ra.rar</literal> to this.</para>
<para>If you also want to use the remote HornetQ server for outgoing connections, i.e. sending messages, then <para>If you also want to use the remote ActiveMQ server for outgoing connections, i.e. sending messages, then
do the following:</para> do the following:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Create a file called <literal>hornetq-ds.xml</literal> in the <literal>deploy</literal> directory <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 (in fact you can call this anything you want as long as it ends in <literal>-ds.xml</literal>). Then
add the following:</para> add the following:</para>
<programlisting> <programlisting>
@ -1177,8 +1177,8 @@ Copyright 2009 Red Hat, Inc.
&lt;tx-connection-factory> &lt;tx-connection-factory>
&lt;jndi-name>RemoteJmsXA&lt;/jndi-name> &lt;jndi-name>RemoteJmsXA&lt;/jndi-name>
&lt;xa-transaction/> &lt;xa-transaction/>
&lt;rar-name>hornetq-ra.rar&lt;/rar-name> &lt;rar-name>activemq-ra.rar&lt;/rar-name>
&lt;connection-definition>org.apache.activemq.ra.HornetQRAConnectionFactory&lt;/connection-definition> &lt;connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory&lt;/connection-definition>
&lt;config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic&lt;/config-property> &lt;config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic&lt;/config-property>
&lt;config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory&lt;/config-property> &lt;config-property name="ConnectorClassName" type="java.lang.String">org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory&lt;/config-property>
&lt;config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5445&lt;/config-property> &lt;config-property name="ConnectionParameters" type="java.lang.String">host=127.0.0.1;port=5445&lt;/config-property>
@ -1187,7 +1187,7 @@ Copyright 2009 Red Hat, Inc.
&lt;/connection-factories></programlisting> &lt;/connection-factories></programlisting>
<para>Again you will see that the host and port are configured here to match the remote HornetQ servers <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> configuration. The other important attributes are:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -1244,32 +1244,32 @@ initialContext = new InitialContext(jndiParameters);</programlisting>
or lose network connectivity. For more information on XA Recovery,please refer to <ulink or lose network connectivity. For more information on XA Recovery,please refer to <ulink
url="http://www.jboss.org/community/wiki/JBossTransactions">JBoss url="http://www.jboss.org/community/wiki/JBossTransactions">JBoss
Transactions</ulink>.</para> Transactions</ulink>.</para>
<para>When HornetQ is integrated with JBoss AS, it can take advantage of JBoss Transactions <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 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 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 transactions are recovered and the messages will either be committed or rolled back
(depending on the transaction outcome) when the server is restarted.</para> (depending on the transaction outcome) when the server is restarted.</para>
<section> <section>
<title>XA Recovery Configuration</title> <title>XA Recovery Configuration</title>
<para>To enable HornetQ's XA Recovery, the Recovery Manager must be configured to connect <para>To enable ActiveMQ's XA Recovery, the Recovery Manager must be configured to connect
to HornetQ to recover its resources. The following property must be added to the 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> <literal>jta</literal> section of <literal>conf/jbossts-properties.xml</literal>
of JBoss AS profiles:</para> of JBoss AS profiles:</para>
<programlisting> <programlisting>
&lt;properties depends="arjuna" name="jta"> &lt;properties depends="arjuna" name="jta">
... ...
&lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.HornetQ1" &lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ActiveMQ1"
value="org.apache.activemq.jms.server.recovery.HornetQXAResourceRecovery;[connection configuration]"/> value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;[connection configuration]"/>
&lt;property name="com.arjuna.ats.jta.xaRecoveryNode" value="1"/> &lt;property name="com.arjuna.ats.jta.xaRecoveryNode" value="1"/>
&lt;/properties></programlisting> &lt;/properties></programlisting>
<para>The <literal>[connection configuration]</literal> contains all the information <para>The <literal>[connection configuration]</literal> contains all the information
required to connect to HornetQ node under the form <literal>[connector factory class required to connect to ActiveMQ node under the form <literal>[connector factory class
name],[user name], [password], [connector parameters]</literal>. </para> name],[user name], [password], [connector parameters]</literal>. </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>[connector factory class name]</literal> corresponds to the name <para><literal>[connector factory class name]</literal> corresponds to the name
of the <literal>ConnectorFactory</literal> used to connect to HornetQ. of the <literal>ConnectorFactory</literal> used to connect to ActiveMQ.
Values can be <literal Values can be <literal
>org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory</literal> or >org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory</literal> or
<literal <literal
@ -1294,12 +1294,12 @@ initialContext = new InitialContext(jndiParameters);</programlisting>
enabled then this must be configured to what ever the tx node id is set to, this is configured in the 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> same file by the <literal>com.arjuna.ats.arjuna.xa.nodeIdentifier</literal> property.</para>
<note> <note>
<para>HornetQ must have a valid acceptor which corresponds to the connector <para>ActiveMQ must have a valid acceptor which corresponds to the connector
specified in <literal>conf/jbossts-properties.xml</literal>.</para> specified in <literal>conf/jbossts-properties.xml</literal>.</para>
</note> </note>
<section> <section>
<title>Configuration Settings</title> <title>Configuration Settings</title>
<para>If HornetQ is configured with a default in-vm acceptor:</para> <para>If ActiveMQ is configured with a default in-vm acceptor:</para>
<programlisting> <programlisting>
&lt;acceptor name="in-vm"> &lt;acceptor name="in-vm">
&lt;factory-class>org.apache.activemq.core.remoting.impl.invm.InVMAcceptorFactory&lt;/factory-class> &lt;factory-class>org.apache.activemq.core.remoting.impl.invm.InVMAcceptorFactory&lt;/factory-class>
@ -1307,8 +1307,8 @@ initialContext = new InitialContext(jndiParameters);</programlisting>
<para>the corresponding configuration in <literal <para>the corresponding configuration in <literal
>conf/jbossts-properties.xml</literal> is:</para> >conf/jbossts-properties.xml</literal> is:</para>
<programlisting> <programlisting>
&lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.HORNETQ1" &lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
value="org.apache.activemq.jms.server.recovery.HornetQXAResourceRecovery;org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory"/></programlisting> 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> <para>If it is now configured with a netty acceptor on a non-default port:</para>
<programlisting> <programlisting>
&lt;acceptor name="netty"> &lt;acceptor name="netty">
@ -1318,8 +1318,8 @@ initialContext = new InitialContext(jndiParameters);</programlisting>
<para>the corresponding configuration in <literal <para>the corresponding configuration in <literal
>conf/jbossts-properties.xml</literal> is:</para> >conf/jbossts-properties.xml</literal> is:</para>
<programlisting> <programlisting>
&lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.HORNETQ1" &lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
value="org.apache.activemq.jms.server.recovery.HornetQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, , , port=8888"/></programlisting> value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, , , port=8888"/></programlisting>
<note> <note>
<para>Note the additional commas to skip the user and password before connector <para>Note the additional commas to skip the user and password before connector
parameters</para> parameters</para>
@ -1327,9 +1327,9 @@ initialContext = new InitialContext(jndiParameters);</programlisting>
<para>If the recovery must use <literal>admin, adminpass</literal>, the <para>If the recovery must use <literal>admin, adminpass</literal>, the
configuration would have been:</para> configuration would have been:</para>
<programlisting> <programlisting>
&lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.HORNETQ1" &lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ACTIVEMQ1"
value="org.apache.activemq.jms.server.recovery.HornetQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, admin, adminpass, port=8888"/></programlisting> value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, admin, adminpass, port=8888"/></programlisting>
<para>Configuring HornetQ with an invm acceptor and configuring the Recovery Manager <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> with an invm connector is the recommended way to enable XA Recovery.</para>
</section> </section>
</section> </section>

54
docs/user-manual/en/architecture.xml
View File

@ -18,29 +18,29 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="architecture"> <chapter id="architecture">
<title>Architecture</title> <title>Architecture</title>
<para>In this section we will give an overview of the HornetQ high level architecture.</para> <para>In this section we will give an overview of the ActiveMQ high level architecture.</para>
<section> <section>
<title>Core Architecture</title> <title>Core Architecture</title>
<para>HornetQ core is designed simply as set of Plain Old Java Objects (POJOs) - we hope you <para>ActiveMQ core is designed simply as set of Plain Old Java Objects (POJOs) - we hope you
like its clean-cut design.</para> like its clean-cut design.</para>
<para>We've also designed it to have as few dependencies on external jars as possible. In <para>We've also designed it to have as few dependencies on external jars as possible. In
fact, HornetQ core has only one jar dependency, netty.jar, 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 other than the standard JDK classes! This is because we use some of the netty buffer classes
internally.</para> internally.</para>
<para>This allows HornetQ to be easily embedded in your own project, or instantiated in any <para>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 dependency injection framework such as JBoss Microcontainer, Spring or Google
Guice.</para> Guice.</para>
<para>Each HornetQ server has its own ultra high performance persistent journal, which it <para>Each ActiveMQ server has its own ultra high performance persistent journal, which it
uses for message and other persistence.</para> uses for message and other persistence.</para>
<para>Using a high performance journal allows outrageous persistence message performance, <para>Using a high performance journal allows outrageous persistence message performance,
something not achievable when using a relational database for persistence.</para> something not achievable when using a relational database for persistence.</para>
<para>HornetQ clients, potentially on different physical machines interact with the HornetQ <para>ActiveMQ clients, potentially on different physical machines interact with the ActiveMQ
server. HornetQ currently provides two APIs for messaging at the client side:</para> server. ActiveMQ currently provides two APIs for messaging at the client side:</para>
<para> <para>
<orderedlist> <orderedlist>
<listitem> <listitem>
@ -55,35 +55,35 @@
</orderedlist> </orderedlist>
</para> </para>
<para>JMS semantics are implemented by a thin JMS facade layer on the client side.</para> <para>JMS semantics are implemented by a thin JMS facade layer on the client side.</para>
<para>The HornetQ server does not speak JMS and in fact does not know anything about JMS, <para>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 it is a protocol agnostic messaging server designed to be used with multiple different
protocols.</para> protocols.</para>
<para>When a user uses the JMS API on the client side, all JMS interactions are translated <para>When a user uses the JMS API on the client side, all JMS interactions are translated
into operations on the HornetQ core client API before being transferred over the wire into operations on the ActiveMQ core client API before being transferred over the wire
using the HornetQ wire format.</para> using the ActiveMQ wire format.</para>
<para>The server always just deals with core API interactions.</para> <para>The server always just deals with core API interactions.</para>
<para>A schematic illustrating this relationship is shown in figure 3.1 below:</para> <para>A schematic illustrating this relationship is shown in figure 3.1 below:</para>
<para> <para>
<graphic fileref="images/architecture1.jpg" align="center"/> <graphic fileref="images/architecture1.jpg" align="center"/>
</para> </para>
<para>Figure 3.1 shows two user applications interacting with a HornetQ server. User <para>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 Application 1 is using the JMS API, while User Application 2 is using the core client
API directly.</para> API directly.</para>
<para>You can see from the diagram that the JMS API is implemented by a thin facade layer on <para>You can see from the diagram that the JMS API is implemented by a thin facade layer on
the client side.</para> the client side.</para>
</section> </section>
<section> <section>
<title>HornetQ embedded in your own application</title> <title>ActiveMQ embedded in your own application</title>
<para>HornetQ core is designed as a set of simple POJOs so if you have an application that <para>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 requires messaging functionality internally but you don't want to expose that as a
HornetQ server you can directly instantiate and embed HornetQ servers in your own ActiveMQ server you can directly instantiate and embed ActiveMQ servers in your own
application.</para> application.</para>
<para>For more information on embedding HornetQ, see <xref linkend="embedding-hornetq" <para>For more information on embedding ActiveMQ, see <xref linkend="embedding-activemq"
/>.</para> />.</para>
</section> </section>
<section> <section>
<title>HornetQ integrated with a JEE application server</title> <title>ActiveMQ integrated with a JEE application server</title>
<para>HornetQ provides its own fully functional Java Connector Architecture (JCA) adaptor <para>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 which enables it to be integrated easily into any JEE compliant application server or
servlet engine.</para> servlet engine.</para>
<para>JEE application servers provide Message Driven Beans (MDBs), which are a special type <para>JEE application servers provide Message Driven Beans (MDBs), which are a special type
@ -106,12 +106,12 @@
an EJB, MDB or servlet without going through a JCA adapter, but this is not recommended 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 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.</para> sessions, which can result in poor performance.</para>
<para>Figure 3.2 below shows a JEE application server integrating with a HornetQ server via <para>Figure 3.2 below shows a JEE application server integrating with a ActiveMQ server via
the HornetQ JCA adaptor. Note that all communication between EJB sessions or entity 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 beans and Message Driven beans go through the adaptor and not directly to
HornetQ.</para> ActiveMQ.</para>
<para>The large arrow with the prohibited sign shows an EJB session bean talking directly to <para>The large arrow with the prohibited sign shows an EJB session bean talking directly to
the HornetQ server. This is not recommended as you'll most likely end up creating a new 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 connection and session every time you want to interact from the EJB, which is an
anti-pattern.</para> anti-pattern.</para>
<para> <para>
@ -121,22 +121,22 @@
linkend="appserver-integration"/>.</para> linkend="appserver-integration"/>.</para>
</section> </section>
<section> <section>
<title>HornetQ stand-alone server</title> <title>ActiveMQ stand-alone server</title>
<para>HornetQ can also be deployed as a stand-alone server. This means a fully independent <para>ActiveMQ can also be deployed as a stand-alone server. This means a fully independent
messaging server not dependent on a JEE application server.</para> messaging server not dependent on a JEE application server.</para>
<para>The standard stand-alone messaging server configuration comprises a core messaging <para>The standard stand-alone messaging server configuration comprises a core messaging
server, a JMS service and a JNDI service.</para> server, a JMS service and a JNDI service.</para>
<para>The role of the JMS Service is to deploy any JMS Queue, Topic and ConnectionFactory <para>The role of the JMS Service is to deploy any JMS Queue, Topic and ConnectionFactory
instances from any server side <literal>hornetq-jms.xml</literal> configuration files. instances from any server side <literal>activemq-jms.xml</literal> configuration files.
It also provides a simple management API for creating and destroying Queues, Topics and 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 ConnectionFactory instances which can be accessed via JMX or the connection. It is a
separate service to the HornetQ core server, since the core server is JMS agnostic. If 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 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 side XML configuration and don't require a JMS management API on the server side then
you can disable this service.</para> you can disable this service.</para>
<para>We also include a JNDI server since JNDI is a common requirement when using JMS to <para>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 lookup Queues, Topics and ConnectionFactory instances. If you do not require JNDI then
this service can also be disabled. HornetQ allows you to programmatically create JMS and 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 core objects directly on the client side as opposed to looking them up from JNDI, so a
JNDI server is not always a requirement.</para> JNDI server is not always a requirement.</para>
<para>The stand-alone server configuration uses JBoss Microcontainer to instantiate and <para>The stand-alone server configuration uses JBoss Microcontainer to instantiate and

20
docs/user-manual/en/client-classpath.xml
View File

@ -18,30 +18,30 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="client-classpath"> <chapter id="client-classpath">
<title>The Client Classpath</title> <title>The Client Classpath</title>
<para>HornetQ requires several jars on the <emphasis>Client Classpath</emphasis> depending on <para>ActiveMQ requires several jars on the <emphasis>Client Classpath</emphasis> depending on
whether the client uses HornetQ Core API, JMS, and JNDI.</para> whether the client uses ActiveMQ Core API, JMS, and JNDI.</para>
<warning> <warning>
<para>All the jars mentioned here can be found in the <literal>lib</literal> directory of <para>All the jars mentioned here can be found in the <literal>lib</literal> directory of
the HornetQ distribution. Be sure you only use the jars from the correct version of the the ActiveMQ distribution. Be sure you only use the jars from the correct version of the
release, you <emphasis>must not</emphasis> mix and match versions of jars from different release, you <emphasis>must not</emphasis> mix and match versions of jars from different
HornetQ versions. Mixing and matching different jar versions may cause subtle errors and ActiveMQ versions. Mixing and matching different jar versions may cause subtle errors and
failures to occur.</para> failures to occur.</para>
</warning> </warning>
<section> <section>
<title>HornetQ Core Client</title> <title>ActiveMQ Core Client</title>
<para>If you are using just a pure HornetQ Core client (i.e. no JMS) then you need <literal <para>If you are using just a pure ActiveMQ Core client (i.e. no JMS) then you need <literal
>hornetq-core-client.jar</literal>, <literal>hornetq-commons.jar</literal>, and >activemq-core-client.jar</literal>, <literal>activemq-commons.jar</literal>, and
<literal>netty.jar</literal> on your client classpath.</para> <literal>netty.jar</literal> on your client classpath.</para>
</section> </section>
<section> <section>
<title>JMS Client</title> <title>JMS Client</title>
<para>If you are using JMS on the client side, then you will also need to include <literal <para>If you are using JMS on the client side, then you will also need to include <literal
>hornetq-jms-client.jar</literal> and <literal>jboss-jms-api.jar</literal>.</para> >activemq-jms-client.jar</literal> and <literal>jboss-jms-api.jar</literal>.</para>
<note> <note>
<para><literal>jboss-jms-api.jar</literal> just contains Java EE API interface classes <para><literal>jboss-jms-api.jar</literal> just contains Java EE API interface classes
@ -52,7 +52,7 @@
</section> </section>
<section> <section>
<title>JMS Client with JNDI</title> <title>JMS Client with JNDI</title>
<para>If you are looking up JMS resources from the JNDI server co-located with the HornetQ <para>If you are looking up JMS resources from the JNDI server co-located with the ActiveMQ
standalone server, you will also need the jar <literal>jnp-client.jar</literal> jar on standalone server, you will also need the jar <literal>jnp-client.jar</literal> jar on
your client classpath as well as any other jars mentioned previously.</para> your client classpath as well as any other jars mentioned previously.</para>
</section> </section>

18
docs/user-manual/en/client-reconnection.xml
View File

@ -18,12 +18,12 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="client-reconnection"> <chapter id="client-reconnection">
<title>Client Reconnection and Session Reattachment</title> <title>Client Reconnection and Session Reattachment</title>
<para>HornetQ clients can be configured to automatically reconnect or re-attach to the server in <para>ActiveMQ clients can be configured to automatically reconnect or re-attach to the server in
the event that a failure is detected in the connection between the client and the server. </para> the event that a failure is detected in the connection between the client and the server. </para>
<section> <section>
<title>100% Transparent session re-attachment</title> <title>100% Transparent session re-attachment</title>
@ -31,11 +31,11 @@
and the target server was not restarted, then the sessions will still be existent on the and the target server was not restarted, then the sessions will still be existent on the
server, assuming the client hasn't been disconnected for more than connection-ttl <xref server, assuming the client hasn't been disconnected for more than connection-ttl <xref
linkend="connection-ttl"/>.</para> linkend="connection-ttl"/>.</para>
<para>In this scenario, HornetQ will automatically re-attach the client sessions to the <para>In this scenario, ActiveMQ will automatically re-attach the client sessions to the
server sessions when the connection reconnects. This is done 100% transparently and the server sessions when the connection reconnects. This is done 100% transparently and the
client can continue exactly as if nothing had happened.</para> client can continue exactly as if nothing had happened.</para>
<para>The way this works is as follows:</para> <para>The way this works is as follows:</para>
<para>As HornetQ clients send commands to their servers they store each sent command in an <para>As ActiveMQ clients send commands to their servers they store each sent command in an
in-memory buffer. In the case that connection failure occurs and the client subsequently in-memory buffer. In the case that connection failure occurs and the client subsequently
reattaches to the same server, as part of the reattachment protocol the server informs reattaches to the same server, as part of the reattachment protocol the server informs
the client during reattachment with the id of the last command it successfully received the client during reattachment with the id of the last command it successfully received
@ -49,9 +49,9 @@
and the client can then free up space in the buffer.</para> and the client can then free up space in the buffer.</para>
<para>If you are using JMS and you're using the JMS service on the server to load your JMS <para>If you are using JMS and you're using the JMS service on the server to load your JMS
connection factory instances into JNDI then this parameter can be configured in <literal connection factory instances into JNDI then this parameter can be configured in <literal
>hornetq-jms.xml</literal> using the element <literal >activemq-jms.xml</literal> using the element <literal
>confirmation-window-size</literal> a. If you're using JMS but not using JNDI then >confirmation-window-size</literal> a. If you're using JMS but not using JNDI then
you can set these values directly on the <literal>HornetQConnectionFactory</literal> you can set these values directly on the <literal>ActiveMQConnectionFactory</literal>
instance using the appropriate setter method.</para> instance using the appropriate setter method.</para>
<para>If you're using the core API you can set these values directly on the <literal <para>If you're using the core API you can set these values directly on the <literal
>ServerLocator</literal> instance using the appropriate setter method.</para> >ServerLocator</literal> instance using the appropriate setter method.</para>
@ -65,7 +65,7 @@
<para>Alternatively, the server might have actually been restarted after crashing or being <para>Alternatively, the server might have actually been restarted after crashing or being
stopped. In this case any sessions will no longer be existent on the server and it won't stopped. In this case any sessions will no longer be existent on the server and it won't
be possible to 100% transparently re-attach to them.</para> be possible to 100% transparently re-attach to them.</para>
<para>In this case, HornetQ will automatically reconnect the connection and <emphasis <para>In this case, ActiveMQ will automatically reconnect the connection and <emphasis
role="italic">recreate</emphasis> any sessions and consumers on the server role="italic">recreate</emphasis> any sessions and consumers on the server
corresponding to the sessions and consumers on the client. This process is exactly the corresponding to the sessions and consumers on the client. This process is exactly the
same as what happens during failover onto a backup server.</para> same as what happens during failover onto a backup server.</para>
@ -118,7 +118,7 @@
</itemizedlist> </itemizedlist>
<para>If you're using JMS, and you're using the JMS Service on the server to load your JMS <para>If you're using JMS, and you're using the JMS Service on the server to load your JMS
connection factory instances directly into JNDI, then you can specify these parameters connection factory instances directly into JNDI, then you can specify these parameters
in the xml configuration in <literal>hornetq-jms.xml</literal>, for example:</para> in the xml configuration in <literal>activemq-jms.xml</literal>, for example:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;connectors> &lt;connectors>
@ -135,7 +135,7 @@
&lt;/connection-factory></programlisting> &lt;/connection-factory></programlisting>
<para>If you're using JMS, but instantiating your JMS connection factory directly, you can <para>If you're using JMS, but instantiating your JMS connection factory directly, you can
specify the parameters using the appropriate setter methods on the <literal specify the parameters using the appropriate setter methods on the <literal
>HornetQConnectionFactory</literal> immediately after creating it.</para> >ActiveMQConnectionFactory</literal> immediately after creating it.</para>
<para>If you're using the core API and instantiating the <literal <para>If you're using the core API and instantiating the <literal
>ServerLocator</literal> instance directly you can also specify the >ServerLocator</literal> instance directly you can also specify the
parameters using the appropriate setter methods on the <literal parameters using the appropriate setter methods on the <literal

110
docs/user-manual/en/clusters.xml
View File

@ -18,15 +18,15 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="clusters"> <chapter id="clusters">
<title>Clusters</title> <title>Clusters</title>
<section> <section>
<title>Clusters Overview</title> <title>Clusters Overview</title>
<para>HornetQ clusters allow groups of HornetQ servers to be grouped together in order to <para>ActiveMQ clusters allow groups of ActiveMQ servers to be grouped together in order to
share message processing load. Each active node in the cluster is an active HornetQ share message processing load. Each active node in the cluster is an active ActiveMQ
server which manages its own messages and handles its own connections. </para> server which manages its own messages and handles its own connections. </para>
<note id="clustered-deprecation"> <note id="clustered-deprecation">
<para>The <emphasis>clustered</emphasis> parameter is deprecated and no longer needed for <para>The <emphasis>clustered</emphasis> parameter is deprecated and no longer needed for
@ -35,7 +35,7 @@
</note> </note>
<para>The cluster is formed by each node declaring <emphasis>cluster connections</emphasis> <para>The cluster is formed by each node declaring <emphasis>cluster connections</emphasis>
to other nodes in the core configuration file <literal to other nodes in the core configuration file <literal
>hornetq-configuration.xml</literal>. When a node forms a cluster connection to >activemq-configuration.xml</literal>. When a node forms a cluster connection to
another node, internally it creates a <emphasis>core bridge</emphasis> (as described in another node, internally it creates a <emphasis>core bridge</emphasis> (as described in
<xref linkend="core-bridges"/>) connection between it and the other node, this is <xref linkend="core-bridges"/>) connection between it and the other node, this is
done transparently behind the scenes - you don't have to declare an explicit bridge for done transparently behind the scenes - you don't have to declare an explicit bridge for
@ -44,7 +44,7 @@
<para>Nodes can be connected together to form a cluster in many different topologies, we <para>Nodes can be connected together to form a cluster in many different topologies, we
will discuss a couple of the more common topologies later in this chapter.</para> will discuss a couple of the more common topologies later in this chapter.</para>
<para>We'll also discuss client side load balancing, where we can balance client connections <para>We'll also discuss client side load balancing, where we can balance client connections
across the nodes of the cluster, and we'll consider message redistribution where HornetQ across the nodes of the cluster, and we'll consider message redistribution where ActiveMQ
will redistribute messages between nodes to avoid starvation.</para> will redistribute messages between nodes to avoid starvation.</para>
<para>Another important part of clustering is <emphasis>server discovery</emphasis> where <para>Another important part of clustering is <emphasis>server discovery</emphasis> where
servers can broadcast their connection details so clients or other servers can connect servers can broadcast their connection details so clients or other servers can connect
@ -52,7 +52,7 @@
<warning id="copy-warning"> <warning id="copy-warning">
<para>Once a cluster node has been configured it is common to simply copy that configuration <para>Once a cluster node has been configured it is common to simply copy that configuration
to other nodes to produce a symmetric cluster. However, care must be taken when copying the to other nodes to produce a symmetric cluster. However, care must be taken when copying the
HornetQ files. Do not copy the HornetQ <emphasis>data</emphasis> (i.e. the ActiveMQ files. Do not copy the ActiveMQ <emphasis>data</emphasis> (i.e. the
<literal>bindings</literal>, <literal>journal</literal>, and <literal>large-messages</literal> <literal>bindings</literal>, <literal>journal</literal>, and <literal>large-messages</literal>
directories) from one node to another. When a node is started for the first time and initializes directories) from one node to another. When a node is started for the first time and initializes
its journal files it also persists a special identifier to the <literal>journal</literal> its journal files it also persists a special identifier to the <literal>journal</literal>
@ -78,7 +78,7 @@
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para> <para>
This information, let's call it the Cluster Topology, is actually sent around normal HornetQ This information, let's call it the Cluster Topology, is actually sent around normal ActiveMQ
connections to clients and to other servers over cluster connections. This being the case we need a connections to clients and to other servers over cluster connections. This being the case we need a
way of establishing the initial first connection. This can be done using way of establishing the initial first connection. This can be done using
dynamic discovery techniques like <ulink url="http://en.wikipedia.org/wiki/User_Datagram_Protocol" >UDP</ulink> dynamic discovery techniques like <ulink url="http://en.wikipedia.org/wiki/User_Datagram_Protocol" >UDP</ulink>
@ -102,11 +102,11 @@
the network. Depending on which broadcasting technique you configure the cluster, it the network. Depending on which broadcasting technique you configure the cluster, it
uses either UDP or JGroups to broadcast connector pairs information.</para> uses either UDP or JGroups to broadcast connector pairs information.</para>
<para>Broadcast groups are defined in the server configuration file <literal <para>Broadcast groups are defined in the server configuration file <literal
>hornetq-configuration.xml</literal>. There can be many broadcast groups per >activemq-configuration.xml</literal>. There can be many broadcast groups per
HornetQ server. All broadcast groups must be defined in a <literal ActiveMQ server. All broadcast groups must be defined in a <literal
>broadcast-groups</literal> element.</para> >broadcast-groups</literal> element.</para>
<para>Let's take a look at an example broadcast group from <literal <para>Let's take a look at an example broadcast group from <literal
>hornetq-configuration.xml</literal> that defines a UDP broadcast group:</para> >activemq-configuration.xml</literal> that defines a UDP broadcast group:</para>
<programlisting> <programlisting>
&lt;broadcast-groups> &lt;broadcast-groups>
&lt;broadcast-group name="my-broadcast-group"> &lt;broadcast-group name="my-broadcast-group">
@ -171,7 +171,7 @@
&lt;broadcast-groups> &lt;broadcast-groups>
&lt;broadcast-group name="my-broadcast-group"> &lt;broadcast-group name="my-broadcast-group">
&lt;jgroups-file>test-jgroups-file_ping.xml&lt;/jgroups-file> &lt;jgroups-file>test-jgroups-file_ping.xml&lt;/jgroups-file>
&lt;jgroups-channel>hornetq_broadcast_channel&lt;/jgroups-channel> &lt;jgroups-channel>activemq_broadcast_channel&lt;/jgroups-channel>
&lt;broadcast-period>2000&lt;/broadcast-period> &lt;broadcast-period>2000&lt;/broadcast-period>
&lt;connector-ref connector-name="netty-connector"/> &lt;connector-ref connector-name="netty-connector"/>
&lt;/broadcast-group> &lt;/broadcast-group>
@ -183,7 +183,7 @@
<listitem> <listitem>
<para><literal>jgroups-file</literal> attribute. This is the name of JGroups configuration <para><literal>jgroups-file</literal> attribute. This is the name of JGroups configuration
file. It will be used to initialize JGroups channels. Make sure the file is in the file. It will be used to initialize JGroups channels. Make sure the file is in the
java resource path so that HornetQ can load it. </para> java resource path so that ActiveMQ can load it. </para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>jgroups-channel</literal> attribute. The name that JGroups channels connect <para><literal>jgroups-channel</literal> attribute. The name that JGroups channels connect
@ -251,7 +251,7 @@
&lt;/config></programlisting> &lt;/config></programlisting>
</para> </para>
<para> <para>
As it shows, the file content defines a jgroups protocol stacks. If you want hornetq As it shows, the file content defines a jgroups protocol stacks. If you want activemq
to use this stacks for channel creation, you have to make sure the value of to use this stacks for channel creation, you have to make sure the value of
<literal>jgroups-file</literal> in your broadcast-group/discovery-group configuration <literal>jgroups-file</literal> in your broadcast-group/discovery-group configuration
to be the name of this jgroups configuration file. For example if the above stacks to be the name of this jgroups configuration file. For example if the above stacks
@ -271,7 +271,7 @@
particular server it updates its entry in the list for that server.</para> particular server it updates its entry in the list for that server.</para>
<para>If it has not received a broadcast from a particular server for a length of time <para>If it has not received a broadcast from a particular server for a length of time
it will remove that server's entry from its list.</para> it will remove that server's entry from its list.</para>
<para>Discovery groups are used in two places in HornetQ:</para> <para>Discovery groups are used in two places in ActiveMQ:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>By cluster connections so they know how to obtain an initial connection to download the topology</para> <para>By cluster connections so they know how to obtain an initial connection to download the topology</para>
@ -283,7 +283,7 @@
<para> <para>
Although a discovery group will always accept broadcasts, its current list of available live and Although a discovery group will always accept broadcasts, its current list of available live and
backup servers is only ever used when an initial connection is made, from then server discovery is backup servers is only ever used when an initial connection is made, from then server discovery is
done over the normal HornetQ connections. done over the normal ActiveMQ connections.
</para> </para>
<note> <note>
<para> <para>
@ -296,9 +296,9 @@
<section> <section>
<title>Defining Discovery Groups on the Server</title> <title>Defining Discovery Groups on the Server</title>
<para>For cluster connections, discovery groups are defined in the server side <para>For cluster connections, discovery groups are defined in the server side
configuration file <literal>hornetq-configuration.xml</literal>. All discovery configuration file <literal>activemq-configuration.xml</literal>. All discovery
groups must be defined inside a <literal>discovery-groups</literal> element. There groups must be defined inside a <literal>discovery-groups</literal> element. There
can be many discovery groups defined by HornetQ server. Let's look at an can be many discovery groups defined by ActiveMQ server. Let's look at an
example:</para> example:</para>
<programlisting> <programlisting>
&lt;discovery-groups> &lt;discovery-groups>
@ -348,7 +348,7 @@
&lt;discovery-groups> &lt;discovery-groups>
&lt;discovery-group name="my-broadcast-group"> &lt;discovery-group name="my-broadcast-group">
&lt;jgroups-file>test-jgroups-file_ping.xml&lt;/jgroups-file> &lt;jgroups-file>test-jgroups-file_ping.xml&lt;/jgroups-file>
&lt;jgroups-channel>hornetq_broadcast_channel&lt;/jgroups-channel> &lt;jgroups-channel>activemq_broadcast_channel&lt;/jgroups-channel>
&lt;refresh-timeout>10000&lt;/refresh-timeout> &lt;refresh-timeout>10000&lt;/refresh-timeout>
&lt;/discovery-group> &lt;/discovery-group>
&lt;/discovery-groups></programlisting> &lt;/discovery-groups></programlisting>
@ -359,7 +359,7 @@
<listitem> <listitem>
<para><literal>jgroups-file</literal> attribute. This is the name of JGroups configuration <para><literal>jgroups-file</literal> attribute. This is the name of JGroups configuration
file. It will be used to initialize JGroups channels. Make sure the file is in the file. It will be used to initialize JGroups channels. Make sure the file is in the
java resource path so that HornetQ can load it. </para> java resource path so that ActiveMQ can load it. </para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>jgroups-channel</literal> attribute. The name that JGroups channels connect <para><literal>jgroups-channel</literal> attribute. The name that JGroups channels connect
@ -374,7 +374,7 @@
</section> </section>
<section id="clusters-discovery.groups.clientside"> <section id="clusters-discovery.groups.clientside">
<title>Discovery Groups on the Client Side</title> <title>Discovery Groups on the Client Side</title>
<para>Let's discuss how to configure a HornetQ client to use discovery to discover a <para>Let's discuss how to configure a ActiveMQ client to use discovery to discover a
list of servers to which it can connect. The way to do this differs depending on list of servers to which it can connect. The way to do this differs depending on
whether you're using JMS or the core API.</para> whether you're using JMS or the core API.</para>
<section> <section>
@ -382,7 +382,7 @@
<para>If you're using JMS and you're also using the JMS Service on the server to <para>If you're using JMS and you're also using the JMS Service on the server to
load your JMS connection factory instances into JNDI, then you can specify which load your JMS connection factory instances into JNDI, then you can specify which
discovery group to use for your JMS connection factory in the server side xml discovery group to use for your JMS connection factory in the server side xml
configuration <literal>hornetq-jms.xml</literal>. Let's take a look at an configuration <literal>activemq-jms.xml</literal>. Let's take a look at an
example:</para> example:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
@ -392,7 +392,7 @@
&lt;/entries> &lt;/entries>
&lt;/connection-factory></programlisting> &lt;/connection-factory></programlisting>
<para>The element <literal>discovery-group-ref</literal> specifies the name of a <para>The element <literal>discovery-group-ref</literal> specifies the name of a
discovery group defined in <literal>hornetq-configuration.xml</literal>.</para> discovery group defined in <literal>activemq-configuration.xml</literal>.</para>
<para>When this connection factory is downloaded from JNDI by a client application <para>When this connection factory is downloaded from JNDI by a client application
and JMS connections are created from it, those connections will be load-balanced and JMS connections are created from it, those connections will be load-balanced
across the list of servers that the discovery group maintains by listening on across the list of servers that the discovery group maintains by listening on
@ -408,7 +408,7 @@ final String groupAddress = "231.7.7.7";
final int groupPort = 9876; final int groupPort = 9876;
ConnectionFactory jmsConnectionFactory = ConnectionFactory jmsConnectionFactory =
HornetQJMSClient.createConnectionFactory(new DiscoveryGroupConfiguration(groupAddress, groupPort, ActiveMQJMSClient.createConnectionFactory(new DiscoveryGroupConfiguration(groupAddress, groupPort,
new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1)), JMSFactoryType.CF); new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1)), JMSFactoryType.CF);
Connection jmsConnection1 = jmsConnectionFactory.createConnection(); Connection jmsConnection1 = jmsConnectionFactory.createConnection();
@ -434,7 +434,7 @@ Connection jmsConnection2 = jmsConnectionFactory.createConnection();</programlis
<programlisting> <programlisting>
final String groupAddress = "231.7.7.7"; final String groupAddress = "231.7.7.7";
final int groupPort = 9876; final int groupPort = 9876;
ServerLocator factory = HornetQClient.createServerLocatorWithHA(new DiscoveryGroupConfiguration(groupAddress, groupPort, ServerLocator factory = ActiveMQClient.createServerLocatorWithHA(new DiscoveryGroupConfiguration(groupAddress, groupPort,
new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1)))); new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1))));
ClientSessionFactory factory = locator.createSessionFactory(); ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session1 = factory.createSession(); ClientSession session1 = factory.createSession();
@ -475,7 +475,7 @@ ClientSession session2 = factory.createSession();</programlisting>
<para>If you're using JMS and you're also using the JMS Service on the server to <para>If you're using JMS and you're also using the JMS Service on the server to
load your JMS connection factory instances into JNDI, then you can specify which load your JMS connection factory instances into JNDI, then you can specify which
connectors to use for your JMS connection factory in the server side xml connectors to use for your JMS connection factory in the server side xml
configuration <literal>hornetq-jms.xml</literal>. Let's take a look at an configuration <literal>activemq-jms.xml</literal>. Let's take a look at an
example:</para> example:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
@ -490,7 +490,7 @@ ClientSession session2 = factory.createSession();</programlisting>
&lt;/connection-factory></programlisting> &lt;/connection-factory></programlisting>
<para> <para>
The element <literal>connectors</literal> contains a list of pre defined connectors in the The element <literal>connectors</literal> contains a list of pre defined connectors in the
<literal>hornetq-configuration.xml</literal> file. When this connection factory is downloaded <literal>activemq-configuration.xml</literal> file. When this connection factory is downloaded
from JNDI by a client application and JMS connections are created from it, those connections will from JNDI by a client application and JMS connections are created from it, those connections will
be load-balanced across the list of servers defined by these connectors. be load-balanced across the list of servers defined by these connectors.
</para> </para>
@ -509,7 +509,7 @@ map2.put("host", "myhost2");
map2.put("port", "5446"); map2.put("port", "5446");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2); TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
HornetQConnectionFactory cf = HornetQJMSClient.createConnectionFactoryWithHA(JMSFactoryType.CF, server1, server2);</programlisting> ActiveMQConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithHA(JMSFactoryType.CF, server1, server2);</programlisting>
</section> </section>
<section> <section>
<title>Configuring client discovery using Core</title> <title>Configuring client discovery using Core</title>
@ -524,7 +524,7 @@ map2.put("host", "myhost2");
map2.put("port", "5446"); map2.put("port", "5446");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2); TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
ServerLocator locator = HornetQClient.createServerLocatorWithHA(server1, server2); ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
ClientSessionFactory factory = locator.createSessionFactory(); ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session = factory.createSession();</programlisting> ClientSession session = factory.createSession();</programlisting>
</section> </section>
@ -533,7 +533,7 @@ ClientSession session = factory.createSession();</programlisting>
</section> </section>
<section> <section>
<title>Server-Side Message Load Balancing</title> <title>Server-Side Message Load Balancing</title>
<para>If cluster connections are defined between nodes of a cluster, then HornetQ will load <para>If cluster connections are defined between nodes of a cluster, then ActiveMQ will load
balance messages arriving at a particular node from a client.</para> balance messages arriving at a particular node from a client.</para>
<para>Let's take a simple example of a cluster of four nodes A, B, C, and D arranged in a <para>Let's take a simple example of a cluster of four nodes A, B, C, and D arranged in a
<emphasis>symmetric cluster</emphasis> (described in <emphasis>symmetric cluster</emphasis> (described in
@ -552,7 +552,7 @@ ClientSession session = factory.createSession();</programlisting>
<para>For example, messages arriving on node A might be distributed in the following order <para>For example, messages arriving on node A might be distributed in the following order
between the nodes: B, D, C, A, B, D, C, A, B, D. The exact order depends on the order between the nodes: B, D, C, A, B, D, C, A, B, D. The exact order depends on the order
the nodes started up, but the algorithm used is round robin.</para> the nodes started up, but the algorithm used is round robin.</para>
<para>HornetQ cluster connections can be configured to always blindly load balance messages <para>ActiveMQ cluster connections can be configured to always blindly load balance messages
in a round robin fashion irrespective of whether there are any matching consumers on in a round robin fashion irrespective of whether there are any matching consumers on
other nodes, but they can be a bit cleverer than that and also be configured to only other nodes, but they can be a bit cleverer than that and also be configured to only
distribute to other nodes if they have matching consumers. We'll look at both these distribute to other nodes if they have matching consumers. We'll look at both these
@ -563,9 +563,9 @@ ClientSession session = factory.createSession();</programlisting>
<para>Cluster connections group servers into clusters so that messages can be load <para>Cluster connections group servers into clusters so that messages can be load
balanced between the nodes of the cluster. Let's take a look at a typical cluster balanced between the nodes of the cluster. Let's take a look at a typical cluster
connection. Cluster connections are always defined in <literal connection. Cluster connections are always defined in <literal
>hornetq-configuration.xml</literal> inside a <literal >activemq-configuration.xml</literal> inside a <literal
>cluster-connection</literal> element. There can be zero or more cluster >cluster-connection</literal> element. There can be zero or more cluster
connections defined per HornetQ server.</para> connections defined per ActiveMQ server.</para>
<programlisting> <programlisting>
&lt;cluster-connections> &lt;cluster-connections>
&lt;cluster-connection name="my-cluster"> &lt;cluster-connection name="my-cluster">
@ -607,7 +607,7 @@ ClientSession session = factory.createSession();</programlisting>
with different values of <literal>address</literal>, simultaneously with different values of <literal>address</literal>, simultaneously
balancing messages for those addresses, potentially to different clusters of balancing messages for those addresses, potentially to different clusters of
servers. By having multiple cluster connections on different addresses a servers. By having multiple cluster connections on different addresses a
single HornetQ Server can effectively take part in multiple clusters single ActiveMQ Server can effectively take part in multiple clusters
simultaneously.</para> simultaneously.</para>
<para>Be careful not to have multiple cluster connections with overlapping <para>Be careful not to have multiple cluster connections with overlapping
values of <literal>address</literal>, e.g. "europe" and "europe.news" since values of <literal>address</literal>, e.g. "europe" and "europe.news" since
@ -708,11 +708,11 @@ ClientSession session = factory.createSession();</programlisting>
<para>If this is set to <literal>true</literal> then each incoming message will <para>If this is set to <literal>true</literal> then each incoming message will
be round robin'd even though the same queues on the other nodes of the be round robin'd even though the same queues on the other nodes of the
cluster may have no consumers at all, or they may have consumers that have cluster may have no consumers at all, or they may have consumers that have
non matching message filters (selectors). Note that HornetQ will non matching message filters (selectors). Note that ActiveMQ will
<emphasis>not</emphasis> forward messages to other nodes if there are no <emphasis>not</emphasis> forward messages to other nodes if there are no
<emphasis>queues</emphasis> of the same name on the other nodes, even if <emphasis>queues</emphasis> of the same name on the other nodes, even if
this parameter is set to <literal>true</literal>.</para> this parameter is set to <literal>true</literal>.</para>
<para>If this is set to <literal>false</literal> then HornetQ will only forward <para>If this is set to <literal>false</literal> then ActiveMQ will only forward
messages to other nodes of the cluster if the address to which they are messages to other nodes of the cluster if the address to which they are
being forwarded has queues which have consumers, and if those consumers have being forwarded has queues which have consumers, and if those consumers have
message filters (selectors) at least one of those selectors must match the message filters (selectors) at least one of those selectors must match the
@ -722,15 +722,15 @@ ClientSession session = factory.createSession();</programlisting>
<listitem> <listitem>
<para><literal>max-hops</literal>. When a cluster connection decides the set of <para><literal>max-hops</literal>. When a cluster connection decides the set of
nodes to which it might load balance a message, those nodes do not have to nodes to which it might load balance a message, those nodes do not have to
be directly connected to it via a cluster connection. HornetQ can be be directly connected to it via a cluster connection. ActiveMQ can be
configured to also load balance messages to nodes which might be connected configured to also load balance messages to nodes which might be connected
to it only indirectly with other HornetQ servers as intermediates in a to it only indirectly with other ActiveMQ servers as intermediates in a
chain.</para> chain.</para>
<para>This allows HornetQ to be configured in more complex topologies and still <para>This allows ActiveMQ to be configured in more complex topologies and still
provide message load balancing. We'll discuss this more later in this provide message load balancing. We'll discuss this more later in this
chapter.</para> chapter.</para>
<para>The default value for this parameter is <literal>1</literal>, which means <para>The default value for this parameter is <literal>1</literal>, which means
messages are only load balanced to other HornetQ serves which are directly messages are only load balanced to other ActiveMQ serves which are directly
connected to this server. This parameter is optional.</para> connected to this server. This parameter is optional.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -777,26 +777,26 @@ ClientSession session = factory.createSession();</programlisting>
<section id="clusters.clusteruser"> <section id="clusters.clusteruser">
<title>Cluster User Credentials</title> <title>Cluster User Credentials</title>
<para>When creating connections between nodes of a cluster to form a cluster connection, <para>When creating connections between nodes of a cluster to form a cluster connection,
HornetQ uses a cluster user and cluster password which is defined in <literal ActiveMQ uses a cluster user and cluster password which is defined in <literal
>hornetq-configuration.xml</literal>:</para> >activemq-configuration.xml</literal>:</para>
<programlisting> <programlisting>
&lt;cluster-user>HORNETQ.CLUSTER.ADMIN.USER&lt;/cluster-user> &lt;cluster-user>ACTIVEMQ.CLUSTER.ADMIN.USER&lt;/cluster-user>
&lt;cluster-password>CHANGE ME!!&lt;/cluster-password></programlisting> &lt;cluster-password>CHANGE ME!!&lt;/cluster-password></programlisting>
<warning> <warning>
<para>It is imperative that these values are changed from their default, or remote <para>It is imperative that these values are changed from their default, or remote
clients will be able to make connections to the server using the default values. clients will be able to make connections to the server using the default values.
If they are not changed from the default, HornetQ will detect this and pester If they are not changed from the default, ActiveMQ will detect this and pester
you with a warning on every start-up.</para> you with a warning on every start-up.</para>
</warning> </warning>
</section> </section>
</section> </section>
<section id="clusters.client.loadbalancing"> <section id="clusters.client.loadbalancing">
<title>Client-Side Load balancing</title> <title>Client-Side Load balancing</title>
<para>With HornetQ client-side load balancing, subsequent sessions created using a single <para>With ActiveMQ client-side load balancing, subsequent sessions created using a single
session factory can be connected to different nodes of the cluster. This allows sessions session factory can be connected to different nodes of the cluster. This allows sessions
to spread smoothly across the nodes of a cluster and not be "clumped" on any particular to spread smoothly across the nodes of a cluster and not be "clumped" on any particular
node.</para> node.</para>
<para>The load balancing policy to be used by the client factory is configurable. HornetQ <para>The load balancing policy to be used by the client factory is configurable. ActiveMQ
provides four out-of-the-box load balancing policies, and you can also implement your own provides four out-of-the-box load balancing policies, and you can also implement your own
and use that.</para> and use that.</para>
<para>The out-of-the-box policies are</para> <para>The out-of-the-box policies are</para>
@ -833,7 +833,7 @@ ClientSession session = factory.createSession();</programlisting>
>org.apache.activemq.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy</literal>.</para> >org.apache.activemq.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy</literal>.</para>
<para>If you're using JMS, and you're using JNDI on the server to put your JMS connection <para>If you're using JMS, and you're using JNDI on the server to put your JMS connection
factories into JNDI, then you can specify the load balancing policy directly in the factories into JNDI, then you can specify the load balancing policy directly in the
<literal>hornetq-jms.xml</literal> configuration file on the server as follows:</para> <literal>activemq-jms.xml</literal> configuration file on the server as follows:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;discovery-group-ref discovery-group-name="my-discovery-group"/> &lt;discovery-group-ref discovery-group-name="my-discovery-group"/>
@ -848,14 +848,14 @@ ClientSession session = factory.createSession();</programlisting>
balancing policy. </para> balancing policy. </para>
<para>If you're using JMS but you're instantiating your connection factory directly on the <para>If you're using JMS but you're instantiating your connection factory directly on the
client side then you can set the load balancing policy using the setter on the client side then you can set the load balancing policy using the setter on the
<literal>HornetQConnectionFactory</literal> before using it:</para> <literal>ActiveMQConnectionFactory</literal> before using it:</para>
<programlisting> <programlisting>
ConnectionFactory jmsConnectionFactory = HornetQJMSClient.createConnectionFactory(...); ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactory(...);
jmsConnectionFactory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</programlisting> jmsConnectionFactory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</programlisting>
<para>If you're using the core API, you can set the load balancing policy directly on the <para>If you're using the core API, you can set the load balancing policy directly on the
<literal>ServerLocator</literal> instance you are using:</para> <literal>ServerLocator</literal> instance you are using:</para>
<programlisting> <programlisting>
ServerLocator locator = HornetQClient.createServerLocatorWithHA(server1, server2); ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</programlisting> locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</programlisting>
<para>The set of servers over which the factory load balances can be determined in one of <para>The set of servers over which the factory load balances can be determined in one of
two ways:</para> two ways:</para>
@ -904,7 +904,7 @@ locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</prog
it doesn't solve: What happens if the consumers on a queue close after the messages have it doesn't solve: What happens if the consumers on a queue close after the messages have
been sent to the node? If there are no consumers on the queue the message won't get been sent to the node? If there are no consumers on the queue the message won't get
consumed and we have a <emphasis>starvation</emphasis> situation.</para> consumed and we have a <emphasis>starvation</emphasis> situation.</para>
<para>This is where message redistribution comes in. With message redistribution HornetQ can <para>This is where message redistribution comes in. With message redistribution ActiveMQ can
be configured to automatically <emphasis>redistribute</emphasis> messages from queues be configured to automatically <emphasis>redistribute</emphasis> messages from queues
which have no consumers back to other nodes in the cluster which do have matching which have no consumers back to other nodes in the cluster which do have matching
consumers.</para> consumers.</para>
@ -915,7 +915,7 @@ locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</prog
<para>Message redistribution can be configured on a per address basis, by specifying the <para>Message redistribution can be configured on a per address basis, by specifying the
redistribution delay in the address settings, for more information on configuring redistribution delay in the address settings, for more information on configuring
address settings, please see <xref linkend="queue-attributes"/>.</para> address settings, please see <xref linkend="queue-attributes"/>.</para>
<para>Here's an address settings snippet from <literal>hornetq-configuration.xml</literal> <para>Here's an address settings snippet from <literal>activemq-configuration.xml</literal>
showing how message redistribution is enabled for a set of queues:</para> showing how message redistribution is enabled for a set of queues:</para>
<programlisting> <programlisting>
&lt;address-settings> &lt;address-settings>
@ -929,7 +929,7 @@ locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</prog
to addresses that start with "jms.", so the above would enable instant (no delay) to addresses that start with "jms.", so the above would enable instant (no delay)
redistribution for all JMS queues and topic subscriptions.</para> redistribution for all JMS queues and topic subscriptions.</para>
<para>The attribute <literal>match</literal> can be an exact match or it can be a string <para>The attribute <literal>match</literal> can be an exact match or it can be a string
that conforms to the HornetQ wildcard syntax (described in <xref that conforms to the ActiveMQ wildcard syntax (described in <xref
linkend="wildcard-syntax"/>).</para> linkend="wildcard-syntax"/>).</para>
<para>The element <literal>redistribution-delay</literal> defines the delay in milliseconds <para>The element <literal>redistribution-delay</literal> defines the delay in milliseconds
after the last consumer is closed on a queue before redistributing messages from that after the last consumer is closed on a queue before redistributing messages from that
@ -944,7 +944,7 @@ locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</prog
</section> </section>
<section> <section>
<title>Cluster topologies</title> <title>Cluster topologies</title>
<para>HornetQ clusters can be connected together in many different topologies, let's <para>ActiveMQ clusters can be connected together in many different topologies, let's
consider the two most common ones here</para> consider the two most common ones here</para>
<section id="symmetric-cluster"> <section id="symmetric-cluster">
<title>Symmetric cluster</title> <title>Symmetric cluster</title>
@ -994,11 +994,11 @@ locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");</prog
</section> </section>
<section> <section>
<title>Scaling Down</title> <title>Scaling Down</title>
<para>HornetQ supports scaling down a cluster with no message loss (even for non-durable messages). This is especially <para>ActiveMQ supports scaling down a cluster with no message loss (even for non-durable messages). This is especially
useful in certain environments (e.g. the cloud) where the size of a cluster may change relatively frequently. useful in certain environments (e.g. the cloud) where the size of a cluster may change relatively frequently.
When scaling up a cluster (i.e. adding nodes) there is no risk of message loss, but when scaling down a cluster When scaling up a cluster (i.e. adding nodes) there is no risk of message loss, but when scaling down a cluster
(i.e. removing nodes) the messages on those nodes would be lost unless the broker sent them to another node in (i.e. removing nodes) the messages on those nodes would be lost unless the broker sent them to another node in
the cluster. HornetQ can be configured to do just that.</para> the cluster. ActiveMQ can be configured to do just that.</para>
<para>The simplest way to enable this behavior is to set <literal>scale-down</literal> to <para>The simplest way to enable this behavior is to set <literal>scale-down</literal> to
<literal>true</literal>. If the server is clustered and <literal>scale-down</literal> is <literal>true</literal>. If the server is clustered and <literal>scale-down</literal> is
<literal>true</literal> then when the server is shutdown gracefully (i.e. stopped without crashing) it will find <literal>true</literal> then when the server is shutdown gracefully (i.e. stopped without crashing) it will find

40
docs/user-manual/en/configuration-index.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="configuration-index"> <chapter id="configuration-index">
@ -28,7 +28,7 @@
<section id="server.configuration"> <section id="server.configuration">
<title>Server Configuration</title> <title>Server Configuration</title>
<section> <section>
<title>hornetq-configuration.xml</title> <title>activemq-configuration.xml</title>
<para>This is the main core server configuration file.</para> <para>This is the main core server configuration file.</para>
<table frame="topbot" border="2"> <table frame="topbot" border="2">
<title>Server Configuration</title> <title>Server Configuration</title>
@ -54,7 +54,7 @@
</table> </table>
</section> </section>
<section> <section>
<title>hornetq-jms.xml</title> <title>activemq-jms.xml</title>
<para>This is the configuration file used by the server side JMS service to load JMS <para>This is the configuration file used by the server side JMS service to load JMS
Queues, Topics and Connection Factories.</para> Queues, Topics and Connection Factories.</para>
<table frame="topbot" border="2"> <table frame="topbot" border="2">
@ -436,16 +436,16 @@
<section id="configuration.masked-password"> <section id="configuration.masked-password">
<title>Using Masked Passwords in Configuration Files</title> <title>Using Masked Passwords in Configuration Files</title>
<para>By default all passwords in HornetQ server's configuration files are in plain text form. This usually poses no security issues as those <para>By default all passwords in ActiveMQ server's configuration files are in plain text form. This usually poses no security issues as those
files should be well protected from unauthorized accessing. However, in some circumstances a user doesn't want to expose its passwords to more files should be well protected from unauthorized accessing. However, in some circumstances a user doesn't want to expose its passwords to more
eyes than necessary. </para> eyes than necessary. </para>
<para>HornetQ can be configured to use 'masked' passwords in its configuration files. A masked password is an obscure string representation <para>ActiveMQ can be configured to use 'masked' passwords in its configuration files. A masked password is an obscure string representation
of a real password. To mask a password a user will use an 'encoder'. The encoder takes in the real password and outputs the masked version. of a real password. To mask a password a user will use an 'encoder'. The encoder takes in the real password and outputs the masked version.
A user can then replace the real password in the configuration files with the new masked password. A user can then replace the real password in the configuration files with the new masked password.
When HornetQ loads a masked password, it uses a suitable 'decoder' to decode it into real password.</para> When ActiveMQ loads a masked password, it uses a suitable 'decoder' to decode it into real password.</para>
<para>HornetQ provides a default password encoder and decoder. Optionally users can use or implement their own encoder and decoder for <para>ActiveMQ provides a default password encoder and decoder. Optionally users can use or implement their own encoder and decoder for
masking the passwords.</para> masking the passwords.</para>
<section> <title>Password Masking in Server Configuration File</title> <section> <title>Password Masking in Server Configuration File</title>
@ -472,9 +472,9 @@
if a users wants to use an SSL-enabled NettyAcceptor, it can specify a key-store-password and a trust-store-password. Because if a users wants to use an SSL-enabled NettyAcceptor, it can specify a key-store-password and a trust-store-password. Because
Acceptors and Connectors are pluggable implementations, each transport will have different password masking needs.</para> Acceptors and Connectors are pluggable implementations, each transport will have different password masking needs.</para>
<para>When a Connector or Acceptor configuration is initialised, HornetQ will add the "mask-password" and <para>When a Connector or Acceptor configuration is initialised, ActiveMQ will add the "mask-password" and
"password-codec" values to the Connector or Acceptors params using the keys <literal>hornetq.usemaskedpassword</literal> "password-codec" values to the Connector or Acceptors params using the keys <literal>activemq.usemaskedpassword</literal>
and <literal>hornetq.passwordcodec</literal> respectively. The Netty and InVM implementations will use these and <literal>activemq.passwordcodec</literal> respectively. The Netty and InVM implementations will use these
as needed and any other implementations will have access to these to use if they so wish.</para> as needed and any other implementations will have access to these to use if they so wish.</para>
</section> </section>
@ -543,7 +543,7 @@
&lt;mask-password>true&lt;/mask-password> &lt;mask-password>true&lt;/mask-password>
&lt;cluster-password>80cf731af62c290&lt;/cluster-password></programlisting> &lt;cluster-password>80cf731af62c290&lt;/cluster-password></programlisting>
<para>This indicates the cluster password is a masked value and HornetQ will use its built-in decoder to decode it. All other <para>This indicates the cluster password is a masked value and ActiveMQ will use its built-in decoder to decode it. All other
passwords in the configuration file, Connectors, Acceptors and Bridges, will also use masked passwords.</para> passwords in the configuration file, Connectors, Acceptors and Bridges, will also use masked passwords.</para>
</section> </section>
</section> </section>
@ -565,12 +565,12 @@
<literal> <literal>
&lt;property name="passwordCodec">com.foo.FooDecoder;key=value&lt;/property> &lt;property name="passwordCodec">com.foo.FooDecoder;key=value&lt;/property>
</literal> </literal>
<para>HornetQ will load this property and initialize the class with a parameter map containing the "key"->"value" pair. <para>ActiveMQ will load this property and initialize the class with a parameter map containing the "key"->"value" pair.
If <literal>passwordCodec</literal> is not specified, the built-in decoder is used.</para> If <literal>passwordCodec</literal> is not specified, the built-in decoder is used.</para>
</section> </section>
<section> <title>Masking passwords in HornetQ ResourceAdapters and MDB activation configurations</title> <section> <title>Masking passwords in ActiveMQ ResourceAdapters and MDB activation configurations</title>
<para>Both ra.xml and MDB activation configuration have a 'password' property that can be masked. They are controlled by the following two <para>Both ra.xml and MDB activation configuration have a 'password' property that can be masked. They are controlled by the following two
optional Resource Adapter properties in ra.xml:</para> optional Resource Adapter properties in ra.xml:</para>
@ -596,9 +596,9 @@
</section> </section>
<section> <title>Masking passwords in hornetq-users.xml</title> <section> <title>Masking passwords in activemq-users.xml</title>
<para>HornetQ's built-in security manager uses plain configuration files where the user passwords are specified in plaintext <para>ActiveMQ's built-in security manager uses plain configuration files where the user passwords are specified in plaintext
forms by default. To mask those parameters the following two properties are needed:</para> forms by default. To mask those parameters the following two properties are needed:</para>
<para> <literal>mask-password</literal> -- If set to "true" all the passwords are masked. Default is false.</para> <para> <literal>mask-password</literal> -- If set to "true" all the passwords are masked. Default is false.</para>
@ -610,7 +610,7 @@
&lt;mask-password>true&lt;/mask-password> &lt;mask-password>true&lt;/mask-password>
&lt;password-codec>org.apache.activemq.utils.DefaultSensitiveStringCodec;key=hello world&lt;/password-codec></programlisting> &lt;password-codec>org.apache.activemq.utils.DefaultSensitiveStringCodec;key=hello world&lt;/password-codec></programlisting>
<para>When so configured, the HornetQ security manager will initialize a DefaultSensitiveStringCodec with the parameters <para>When so configured, the ActiveMQ security manager will initialize a DefaultSensitiveStringCodec with the parameters
"key"->"hello world", then use it to decode all the masked passwords in this configuration file.</para> "key"->"hello world", then use it to decode all the masked passwords in this configuration file.</para>
</section> </section>
@ -621,7 +621,7 @@
convert a masked password into its original clear text form in order to be used in various security operations. The algorithm convert a masked password into its original clear text form in order to be used in various security operations. The algorithm
used for decoding must match that for encoding. Otherwise the decoding may not be successful.</para> used for decoding must match that for encoding. Otherwise the decoding may not be successful.</para>
<para>For user's convenience HornetQ provides a default built-in Decoder. However a user can if they so wish implement their own.</para> <para>For user's convenience ActiveMQ provides a default built-in Decoder. However a user can if they so wish implement their own.</para>
<section><title>The built-in Decoder</title> <section><title>The built-in Decoder</title>
@ -644,7 +644,7 @@ Encoded password: 80cf731af62c290</programlisting>
<section><title>Using a different decoder</title> <section><title>Using a different decoder</title>
<para>It is possible to use a different decoder rather than the built-in one. Simply make sure the decoder <para>It is possible to use a different decoder rather than the built-in one. Simply make sure the decoder
is in HornetQ's classpath and configure the server to use it as follows:</para> is in ActiveMQ's classpath and configure the server to use it as follows:</para>
<programlisting> <programlisting>
&lt;password-codec>com.foo.SomeDecoder;key1=value1;key2=value2&lt;/password-codec></programlisting> &lt;password-codec>com.foo.SomeDecoder;key1=value1;key2=value2&lt;/password-codec></programlisting>
@ -661,7 +661,7 @@ Encoded password: 80cf731af62c290</programlisting>
&lt;mask-password>true&lt;/mask-password> &lt;mask-password>true&lt;/mask-password>
&lt;cluster-password>masked_password&lt;/cluster-password></programlisting> &lt;cluster-password>masked_password&lt;/cluster-password></programlisting>
<para>When HornetQ reads the cluster-password it will initialize the NewDecoder and use it to decode "mask_password". <para>When ActiveMQ reads the cluster-password it will initialize the NewDecoder and use it to decode "mask_password".
It also process all passwords using the new defined decoder.</para> It also process all passwords using the new defined decoder.</para>
</section> </section>
@ -696,7 +696,7 @@ public class MyNewDecoder implements SensitiveDataCodec&lt;String>
} }
}</programlisting> }</programlisting>
<para>Last but not least, once you get your own decoder, please add it to the classpath. Otherwise HornetQ will <para>Last but not least, once you get your own decoder, please add it to the classpath. Otherwise ActiveMQ will
fail to load it!</para> fail to load it!</para>
</section> </section>
</section> </section>

58
docs/user-manual/en/configuring-transports.xml
View File

@ -18,22 +18,22 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="configuring-transports"> <chapter id="configuring-transports">
<title>Configuring the Transport</title> <title>Configuring the Transport</title>
<para>HornetQ has a fully pluggable and highly flexible transport layer and defines its own <para>ActiveMQ has a fully pluggable and highly flexible transport layer and defines its own
Service Provider Interface (SPI) to make plugging in a new transport provider relatively Service Provider Interface (SPI) to make plugging in a new transport provider relatively
straightforward.</para> straightforward.</para>
<para>In this chapter we'll describe the concepts required for understanding HornetQ transports <para>In this chapter we'll describe the concepts required for understanding ActiveMQ transports
and where and how they're configured.</para> and where and how they're configured.</para>
<section id="configuring-transports.acceptors"> <section id="configuring-transports.acceptors">
<title>Understanding Acceptors</title> <title>Understanding Acceptors</title>
<para>One of the most important concepts in HornetQ transports is the <para>One of the most important concepts in ActiveMQ transports is the
<emphasis>acceptor</emphasis>. Let's dive straight in and take a look at an acceptor <emphasis>acceptor</emphasis>. Let's dive straight in and take a look at an acceptor
defined in xml in the configuration file <literal defined in xml in the configuration file <literal
>hornetq-configuration.xml</literal>.</para> >activemq-configuration.xml</literal>.</para>
<programlisting> <programlisting>
&lt;acceptors> &lt;acceptors>
&lt;acceptor name="netty"> &lt;acceptor name="netty">
@ -46,7 +46,7 @@
<para>Acceptors are always defined inside an <literal>acceptors</literal> element. There can <para>Acceptors are always defined inside an <literal>acceptors</literal> element. There can
be one or more acceptors defined in the <literal>acceptors</literal> element. There's no be one or more acceptors defined in the <literal>acceptors</literal> element. There's no
upper limit to the number of acceptors per server.</para> upper limit to the number of acceptors per server.</para>
<para>Each acceptor defines a way in which connections can be made to the HornetQ <para>Each acceptor defines a way in which connections can be made to the ActiveMQ
server.</para> server.</para>
<para>In the above example we're defining an acceptor that uses <ulink <para>In the above example we're defining an acceptor that uses <ulink
url="http://jboss.org/netty">Netty</ulink> to listen for connections at port url="http://jboss.org/netty">Netty</ulink> to listen for connections at port
@ -72,7 +72,7 @@
<title>Understanding Connectors</title> <title>Understanding Connectors</title>
<para>Whereas acceptors are used on the server to define how we accept connections, <para>Whereas acceptors are used on the server to define how we accept connections,
connectors are used by a client to define how it connects to a server.</para> connectors are used by a client to define how it connects to a server.</para>
<para>Let's look at a connector defined in our <literal>hornetq-configuration.xml</literal> <para>Let's look at a connector defined in our <literal>activemq-configuration.xml</literal>
file:</para> file:</para>
<programlisting> <programlisting>
&lt;connectors> &lt;connectors>
@ -99,13 +99,13 @@
<listitem> <listitem>
<para>If you're using JMS and the server side JMS service to instantiate JMS <para>If you're using JMS and the server side JMS service to instantiate JMS
ConnectionFactory instances and bind them in JNDI, then when creating the ConnectionFactory instances and bind them in JNDI, then when creating the
<literal>HornetQConnectionFactory</literal> it needs to know what server <literal>ActiveMQConnectionFactory</literal> it needs to know what server
that connection factory will create connections to.</para> that connection factory will create connections to.</para>
<para>That's defined by the <literal>connector-ref</literal> element in the <literal <para>That's defined by the <literal>connector-ref</literal> element in the <literal
>hornetq-jms.xml</literal> file on the server side. Let's take a look at a >activemq-jms.xml</literal> file on the server side. Let's take a look at a
snipped from a <literal>hornetq-jms.xml</literal> file that shows a JMS snipped from a <literal>activemq-jms.xml</literal> file that shows a JMS
connection factory that references our netty connector defined in our <literal connection factory that references our netty connector defined in our <literal
>hornetq-configuration.xml</literal> file:</para> >activemq-configuration.xml</literal> file:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;connectors> &lt;connectors>
@ -143,7 +143,7 @@ TransportConfiguration transportConfiguration =
"org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory", "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
connectionParams); connectionParams);
ServerLocator locator = HornetQClient.createServerLocatorWithoutHA(transportConfiguration); ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(transportConfiguration);
ClientSessionFactory sessionFactory = locator.createClientSessionFactory(); ClientSessionFactory sessionFactory = locator.createClientSessionFactory();
@ -152,7 +152,7 @@ ClientSession session = sessionFactory.createSession(...);
etc</programlisting> etc</programlisting>
<para>Similarly, if you're using JMS, you can configure the JMS connection factory directly <para>Similarly, if you're using JMS, you can configure the JMS connection factory directly
on the client side without having to define a connector on the server side or define a on the client side without having to define a connector on the server side or define a
connection factory in <literal>hornetq-jms.xml</literal>:</para> connection factory in <literal>activemq-jms.xml</literal>:</para>
<programlisting> <programlisting>
Map&lt;String, Object> connectionParams = new HashMap&lt;String, Object>(); Map&lt;String, Object> connectionParams = new HashMap&lt;String, Object>();
@ -163,7 +163,7 @@ TransportConfiguration transportConfiguration =
"org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory", "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
connectionParams); connectionParams);
ConnectionFactory connectionFactory = HornetQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF, transportConfiguration); ConnectionFactory connectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF, transportConfiguration);
Connection jmsConnection = connectionFactory.createConnection(); Connection jmsConnection = connectionFactory.createConnection();
@ -171,7 +171,7 @@ etc</programlisting>
</section> </section>
<section> <section>
<title>Configuring the Netty transport</title> <title>Configuring the Netty transport</title>
<para>Out of the box, HornetQ currently uses <ulink url="http://www.jboss.org/netty/" <para>Out of the box, ActiveMQ currently uses <ulink url="http://www.jboss.org/netty/"
>Netty</ulink>, a high performance low level network library.</para> >Netty</ulink>, a high performance low level network library.</para>
<para>Our Netty transport can be configured in several different ways; to use old (blocking) <para>Our Netty transport can be configured in several different ways; to use old (blocking)
Java IO, or NIO (non-blocking), also to use straightforward TCP sockets, SSL, or to Java IO, or NIO (non-blocking), also to use straightforward TCP sockets, SSL, or to
@ -179,8 +179,8 @@ etc</programlisting>
<para>We believe this caters for the vast majority of transport requirements.</para> <para>We believe this caters for the vast majority of transport requirements.</para>
<section id="configuring-transports.single-port"> <section id="configuring-transports.single-port">
<title>Single Port Support</title> <title>Single Port Support</title>
<para>As of version 2.4 HornetQ now supports using a single port for all protocols, HornetQ will automatically <para>As of version 2.4 ActiveMQ now supports using a single port for all protocols, ActiveMQ will automatically
detect which protocol is being used CORE, AMQP, STOMP or OPENWIRE and use the appropriate HornetQ handler. It will also detect detect which protocol is being used CORE, AMQP, STOMP or OPENWIRE and use the appropriate ActiveMQ handler. It will also detect
whether protocols such as HTTP or Web Sockets are being used and also use the appropriate decoders</para> whether protocols such as HTTP or Web Sockets are being used and also use the appropriate decoders</para>
<para>It is possible to limit which protocols are supported by using the <literal>protocols</literal> parameter <para>It is possible to limit which protocols are supported by using the <literal>protocols</literal> parameter
on the Acceptor like so:</para> on the Acceptor like so:</para>
@ -275,7 +275,7 @@ buffer_size = bandwidth * RTT.</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>batch-delay</literal>. Before writing packets to the transport, <para><literal>batch-delay</literal>. Before writing packets to the transport,
HornetQ can be configured to batch up writes for a maximum of <literal ActiveMQ can be configured to batch up writes for a maximum of <literal
>batch-delay</literal> milliseconds. This can increase overall >batch-delay</literal> milliseconds. This can increase overall
throughput for very small messages. It does so at the expense of an increase throughput for very small messages. It does so at the expense of an increase
in average latency for message transfer. The default value for this property in average latency for message transfer. The default value for this property
@ -295,7 +295,7 @@ buffer_size = bandwidth * RTT.</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>nio-remoting-threads</literal>. When configured to use NIO, <para><literal>nio-remoting-threads</literal>. When configured to use NIO,
HornetQ will, by default, use a number of threads equal to three times the ActiveMQ will, by default, use a number of threads equal to three times the
number of cores (or hyper-threads) as reported by <literal number of cores (or hyper-threads) as reported by <literal
>Runtime.getRuntime().availableProcessors()</literal> for processing >Runtime.getRuntime().availableProcessors()</literal> for processing
incoming packets. If you want to override this value, you can set the number incoming packets. If you want to override this value, you can set the number
@ -341,8 +341,8 @@ buffer_size = bandwidth * RTT.</programlisting>
authentication). Although this value is configured on the server, it is authentication). Although this value is configured on the server, it is
downloaded and used by the client. If the client needs to use a different path downloaded and used by the client. If the client needs to use a different path
from that set on the server then it can override the server-side setting by either from that set on the server then it can override the server-side setting by either
using the customary "javax.net.ssl.keyStore" system property or the HornetQ-specific using the customary "javax.net.ssl.keyStore" system property or the ActiveMQ-specific
"org.apache.activemq.ssl.keyStore" system property. The HornetQ-specific system property "org.apache.activemq.ssl.keyStore" system property. The ActiveMQ-specific system property
is useful if another component on client is already making use of the standard, Java is useful if another component on client is already making use of the standard, Java
system property.</para> system property.</para>
</listitem> </listitem>
@ -356,8 +356,8 @@ buffer_size = bandwidth * RTT.</programlisting>
be configured on the server, it is downloaded and used by the client. If the client be configured on the server, it is downloaded and used by the client. If the client
needs to use a different password from that set on the server then it can override needs to use a different password from that set on the server then it can override
the server-side setting by either using the customary "javax.net.ssl.keyStorePassword" the server-side setting by either using the customary "javax.net.ssl.keyStorePassword"
system property or the HornetQ-specific "org.apache.activemq.ssl.keyStorePassword" system system property or the ActiveMQ-specific "org.apache.activemq.ssl.keyStorePassword" system
property. The HornetQ-specific system property is useful if another component on client property. The ActiveMQ-specific system property is useful if another component on client
is already making use of the standard, Java system property.</para> is already making use of the standard, Java system property.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -371,8 +371,8 @@ buffer_size = bandwidth * RTT.</programlisting>
trusts. Although this value can be configured on the server, it is downloaded and trusts. Although this value can be configured on the server, it is downloaded and
used by the client. If the client needs to use a different path used by the client. If the client needs to use a different path
from that set on the server then it can override the server-side setting by either from that set on the server then it can override the server-side setting by either
using the customary "javax.net.ssl.trustStore" system property or the HornetQ-specific using the customary "javax.net.ssl.trustStore" system property or the ActiveMQ-specific
"org.apache.activemq.ssl.trustStore" system property. The HornetQ-specific system property "org.apache.activemq.ssl.trustStore" system property. The ActiveMQ-specific system property
is useful if another component on client is already making use of the standard, Java is useful if another component on client is already making use of the standard, Java
system property.</para> system property.</para>
</listitem> </listitem>
@ -386,8 +386,8 @@ buffer_size = bandwidth * RTT.</programlisting>
downloaded and used by the client. If the client downloaded and used by the client. If the client
needs to use a different password from that set on the server then it can override needs to use a different password from that set on the server then it can override
the server-side setting by either using the customary "javax.net.ssl.trustStorePassword" the server-side setting by either using the customary "javax.net.ssl.trustStorePassword"
system property or the HornetQ-specific "org.apache.activemq.ssl.trustStorePassword" system system property or the ActiveMQ-specific "org.apache.activemq.ssl.trustStorePassword" system
property. The HornetQ-specific system property is useful if another component on client property. The ActiveMQ-specific system property is useful if another component on client
is already making use of the standard, Java system property.</para> is already making use of the standard, Java system property.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -420,7 +420,7 @@ buffer_size = bandwidth * RTT.</programlisting>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>http-enabled</literal>. This is now no longer needed as of version 2.4. With single <para><literal>http-enabled</literal>. This is now no longer needed as of version 2.4. With single
port support HornetQ will now automatically detect if http is being used and configure itself.</para> port support ActiveMQ will now automatically detect if http is being used and configure itself.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>http-client-idle-time</literal>. How long a client can be idle <para><literal>http-client-idle-time</literal>. How long a client can be idle
@ -447,7 +447,7 @@ buffer_size = bandwidth * RTT.</programlisting>
</section> </section>
<section> <section>
<title>Configuring Netty Servlet</title> <title>Configuring Netty Servlet</title>
<para>As of 2.4 HornetQ Servlet support will be provided via Undertow in Wildfly</para> <para>As of 2.4 ActiveMQ Servlet support will be provided via Undertow in Wildfly</para>
</section> </section>
</section> </section>
</chapter> </chapter>

26
docs/user-manual/en/connection-ttl.xml
View File

@ -18,17 +18,17 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="connection-ttl"> <chapter id="connection-ttl">
<title>Detecting Dead Connections</title> <title>Detecting Dead Connections</title>
<para>In this section we will discuss connection time-to-live (TTL) and explain how HornetQ <para>In this section we will discuss connection time-to-live (TTL) and explain how ActiveMQ
deals with crashed clients and clients which have exited without cleanly closing their deals with crashed clients and clients which have exited without cleanly closing their
resources.</para> resources.</para>
<section id="dead.connections"> <section id="dead.connections">
<title>Cleaning up Dead Connection Resources on the Server</title> <title>Cleaning up Dead Connection Resources on the Server</title>
<para>Before a HornetQ client application exits it is considered good practice that it <para>Before a ActiveMQ client application exits it is considered good practice that it
should close its resources in a controlled manner, using a <literal>finally</literal> should close its resources in a controlled manner, using a <literal>finally</literal>
block.</para> block.</para>
<para>Here's an example of a well behaved core client application closing its session and <para>Here's an example of a well behaved core client application closing its session and
@ -40,7 +40,7 @@ ClientSession session = null;
try try
{ {
locator = HornetQClient.createServerLocatorWithoutHA(..); locator = ActiveMQClient.createServerLocatorWithoutHA(..);
sf = locator.createClientSessionFactory();; sf = locator.createClientSessionFactory();;
@ -71,7 +71,7 @@ Connection jmsConnection = null;
try try
{ {
ConnectionFactory jmsConnectionFactory = HornetQJMSClient.createConnectionFactoryWithoutHA(...); ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(...);
jmsConnection = jmsConnectionFactory.createConnection(); jmsConnection = jmsConnectionFactory.createConnection();
@ -91,11 +91,11 @@ finally
over time this result in the server running out of memory or other resources.</para> over time this result in the server running out of memory or other resources.</para>
<para>We have to balance the requirement for cleaning up dead client resources with the fact <para>We have to balance the requirement for cleaning up dead client resources with the fact
that sometimes the network between the client and the server can fail and then come that sometimes the network between the client and the server can fail and then come
back, allowing the client to reconnect. HornetQ supports client reconnection, so we back, allowing the client to reconnect. ActiveMQ supports client reconnection, so we
don't want to clean up "dead" server side resources too soon or this will prevent any don't want to clean up "dead" server side resources too soon or this will prevent any
client from reconnecting, as it won't be able to find its old sessions on the client from reconnecting, as it won't be able to find its old sessions on the
server.</para> server.</para>
<para>HornetQ makes all of this configurable. For each <literal <para>ActiveMQ makes all of this configurable. For each <literal
>ClientSessionFactory</literal> we define a <emphasis>connection TTL</emphasis>. >ClientSessionFactory</literal> we define a <emphasis>connection TTL</emphasis>.
Basically, the TTL determines how long the server will keep a connection alive in the Basically, the TTL determines how long the server will keep a connection alive in the
absence of any data arriving from the client. The client will automatically send "ping" absence of any data arriving from the client. The client will automatically send "ping"
@ -104,7 +104,7 @@ finally
automatically close all the sessions on the server that relate to that automatically close all the sessions on the server that relate to that
connection.</para> connection.</para>
<para>If you're using JMS, the connection TTL is defined by the <literal <para>If you're using JMS, the connection TTL is defined by the <literal
>ConnectionTTL</literal> attribute on a <literal>HornetQConnectionFactory</literal> >ConnectionTTL</literal> attribute on a <literal>ActiveMQConnectionFactory</literal>
instance, or if you're deploying JMS connection factory instances direct into JNDI on instance, or if you're deploying JMS connection factory instances direct into JNDI on
the server side, you can specify it in the xml config, using the parameter <literal the server side, you can specify it in the xml config, using the parameter <literal
>connection-ttl</literal>.</para> >connection-ttl</literal>.</para>
@ -124,7 +124,7 @@ finally
<para>As previously discussed, it's important that all core client sessions and JMS <para>As previously discussed, it's important that all core client sessions and JMS
connections are always closed explicitly in a <literal>finally</literal> block when connections are always closed explicitly in a <literal>finally</literal> block when
you are finished using them. </para> you are finished using them. </para>
<para>If you fail to do so, HornetQ will detect this at garbage collection time, and log <para>If you fail to do so, ActiveMQ will detect this at garbage collection time, and log
a warning similar to the following in the logs (If you are using JMS the warning a warning similar to the following in the logs (If you are using JMS the warning
will involve a JMS connection not a client session):</para> will involve a JMS connection not a client session):</para>
<programlisting> <programlisting>
@ -134,7 +134,7 @@ ting them go out of scope!
java.lang.Exception java.lang.Exception
at org.apache.activemq.core.client.impl.DelegatingSession.&lt;init>(DelegatingSession.java:83) at org.apache.activemq.core.client.impl.DelegatingSession.&lt;init>(DelegatingSession.java:83)
at org.acme.yourproject.YourClass (YourClass.java:666)</programlisting> at org.acme.yourproject.YourClass (YourClass.java:666)</programlisting>
<para>HornetQ will then close the connection / client session for you.</para> <para>ActiveMQ will then close the connection / client session for you.</para>
<para>Note that the log will also tell you the exact line of your user code where you <para>Note that the log will also tell you the exact line of your user code where you
created the JMS connection / client session that you later did not close. This will created the JMS connection / client session that you later did not close. This will
enable you to pinpoint the error in your code and correct it appropriately.</para> enable you to pinpoint the error in your code and correct it appropriately.</para>
@ -154,9 +154,9 @@ java.lang.Exception
>FailureListener</literal> instances (or <literal>ExceptionListener</literal> >FailureListener</literal> instances (or <literal>ExceptionListener</literal>
instances if you are using JMS) depending on how it has been configured.</para> instances if you are using JMS) depending on how it has been configured.</para>
<para>If you're using JMS it's defined by the <literal>ClientFailureCheckPeriod</literal> <para>If you're using JMS it's defined by the <literal>ClientFailureCheckPeriod</literal>
attribute on a <literal>HornetQConnectionFactory</literal> instance, or if you're attribute on a <literal>ActiveMQConnectionFactory</literal> instance, or if you're
deploying JMS connection factory instances direct into JNDI on the server side, you can deploying JMS connection factory instances direct into JNDI on the server side, you can
specify it in the <literal>hornetq-jms.xml </literal> configuration file, using the specify it in the <literal>activemq-jms.xml </literal> configuration file, using the
parameter <literal>client-failure-check-period</literal>.</para> parameter <literal>client-failure-check-period</literal>.</para>
<para>The default value for client failure check period on an "unreliable" connection (e.g. <para>The default value for client failure check period on an "unreliable" connection (e.g.
a Netty connection) is <literal>30000</literal>ms, i.e. 30 seconds. The default value a Netty connection) is <literal>30000</literal>ms, i.e. 30 seconds. The default value
@ -197,7 +197,7 @@ java.lang.Exception
</itemizedlist> </itemizedlist>
<para>To disable asynchronous connection execution, set the parameter <para>To disable asynchronous connection execution, set the parameter
<literal>async-connection-execution-enabled</literal> in <literal>async-connection-execution-enabled</literal> in
<literal>hornetq-configuration.xml</literal> to <literal>false</literal> (default value is <literal>activemq-configuration.xml</literal> to <literal>false</literal> (default value is
<literal>true</literal>).</para> <literal>true</literal>).</para>
</section> </section>
</chapter> </chapter>

22
docs/user-manual/en/core-bridges.xml
View File

@ -18,28 +18,28 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="core-bridges"> <chapter id="core-bridges">
<title>Core Bridges</title> <title>Core Bridges</title>
<para>The function of a bridge is to consume messages from a source queue, and forward them to a <para>The function of a bridge is to consume messages from a source queue, and forward them to a
target address, typically on a different HornetQ server.</para> target address, typically on a different ActiveMQ server.</para>
<para>The source and target servers do not have to be in the same cluster which makes bridging <para>The source and target servers do not have to be in the same cluster which makes bridging
suitable for reliably sending messages from one cluster to another, for instance across a suitable for reliably sending messages from one cluster to another, for instance across a
WAN, or internet and where the connection may be unreliable.</para> WAN, or internet and where the connection may be unreliable.</para>
<para>The bridge has built in resilience to failure so if the target server connection is lost, <para>The bridge has built in resilience to failure so if the target server connection is lost,
e.g. due to network failure, the bridge will retry connecting to the target until it comes e.g. due to network failure, the bridge will retry connecting to the target until it comes
back online. When it comes back online it will resume operation as normal.</para> back online. When it comes back online it will resume operation as normal.</para>
<para>In summary, bridges are a way to reliably connect two separate HornetQ servers together. <para>In summary, bridges are a way to reliably connect two separate ActiveMQ servers together.
With a core bridge both source and target servers must be HornetQ servers.</para> With a core bridge both source and target servers must be ActiveMQ servers.</para>
<para>Bridges can be configured to provide <emphasis>once and only once</emphasis> delivery <para>Bridges can be configured to provide <emphasis>once and only once</emphasis> delivery
guarantees even in the event of the failure of the source or the target server. They do this guarantees even in the event of the failure of the source or the target server. They do this
by using duplicate detection (described in <xref linkend="duplicate-detection"/>).</para> by using duplicate detection (described in <xref linkend="duplicate-detection"/>).</para>
<note> <note>
<para>Although they have similar function, don't confuse core bridges with JMS <para>Although they have similar function, don't confuse core bridges with JMS
bridges!</para> bridges!</para>
<para>Core bridges are for linking a HornetQ node with another HornetQ node and do not use <para>Core bridges are for linking a ActiveMQ node with another ActiveMQ node and do not use
the JMS API. A JMS Bridge is used for linking any two JMS 1.1 compliant JMS providers. the JMS API. A JMS Bridge is used for linking any two JMS 1.1 compliant JMS providers.
So, a JMS Bridge could be used for bridging to or from different JMS compliant messaging So, a JMS Bridge could be used for bridging to or from different JMS compliant messaging
system. It's always preferable to use a core bridge if you can. Core bridges use system. It's always preferable to use a core bridge if you can. Core bridges use
@ -49,7 +49,7 @@
</note> </note>
<section> <section>
<title>Configuring Bridges</title> <title>Configuring Bridges</title>
<para>Bridges are configured in <literal>hornetq-configuration.xml</literal>. Let's kick off <para>Bridges are configured in <literal>activemq-configuration.xml</literal>. Let's kick off
with an example (this is actually from the bridge example):</para> with an example (this is actually from the bridge example):</para>
<programlisting> <programlisting>
&lt;bridge name="my-bridge"> &lt;bridge name="my-bridge">
@ -92,8 +92,8 @@
start-up.</para> start-up.</para>
<note> <note>
<para>If you're using JMS then normally the JMS configuration <literal <para>If you're using JMS then normally the JMS configuration <literal
>hornetq-jms.xml</literal> is loaded after the core configuration file >activemq-jms.xml</literal> is loaded after the core configuration file
<literal>hornetq-configuration.xml</literal> is loaded. If your bridge <literal>activemq-configuration.xml</literal> is loaded. If your bridge
is consuming from a JMS queue then you'll need to make sure the JMS queue is is consuming from a JMS queue then you'll need to make sure the JMS queue is
also deployed as a core queue in the core configuration. Take a look at the also deployed as a core queue in the core configuration. Take a look at the
bridge example for an example of how this is done.</para> bridge example for an example of how this is done.</para>
@ -107,7 +107,7 @@
<listitem> <listitem>
<para><literal>filter-string</literal>. An optional filter string can be supplied. <para><literal>filter-string</literal>. An optional filter string can be supplied.
If specified then only messages which match the filter expression specified in If specified then only messages which match the filter expression specified in
the filter string will be forwarded. The filter string follows the HornetQ the filter string will be forwarded. The filter string follows the ActiveMQ
filter expression syntax described in <xref linkend="filter-expressions" filter expression syntax described in <xref linkend="filter-expressions"
/>.</para> />.</para>
</listitem> </listitem>
@ -210,13 +210,13 @@
<para><literal>user</literal>. This optional parameter determines the user name to <para><literal>user</literal>. This optional parameter determines the user name to
use when creating the bridge connection to the remote server. If it is not use when creating the bridge connection to the remote server. If it is not
specified the default cluster user specified by <literal>cluster-user</literal> specified the default cluster user specified by <literal>cluster-user</literal>
in <literal>hornetq-configuration.xml</literal> will be used. </para> in <literal>activemq-configuration.xml</literal> will be used. </para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>password</literal>. This optional parameter determines the password <para><literal>password</literal>. This optional parameter determines the password
to use when creating the bridge connection to the remote server. If it is not to use when creating the bridge connection to the remote server. If it is not
specified the default cluster password specified by <literal specified the default cluster password specified by <literal
>cluster-password</literal> in <literal>hornetq-configuration.xml</literal> >cluster-password</literal> in <literal>activemq-configuration.xml</literal>
will be used. </para> will be used. </para>
</listitem> </listitem>
<listitem> <listitem>

8
docs/user-manual/en/diverts.xml
View File

@ -19,13 +19,13 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="diverts"> <chapter id="diverts">
<title>Diverting and Splitting Message Flows</title> <title>Diverting and Splitting Message Flows</title>
<para>HornetQ allows you to configure objects called <emphasis>diverts</emphasis> with <para>ActiveMQ allows you to configure objects called <emphasis>diverts</emphasis> with
some simple server configuration.</para> some simple server configuration.</para>
<para>Diverts allow you to transparently divert messages routed to one address to some other <para>Diverts allow you to transparently divert messages routed to one address to some other
address, without making any changes to any client application logic.</para> address, without making any changes to any client application logic.</para>
@ -49,7 +49,7 @@
thought of as a type of routing table for messages. Combining diverts with bridges allows thought of as a type of routing table for messages. Combining diverts with bridges allows
you to create a distributed network of reliable routing connections between multiple you to create a distributed network of reliable routing connections between multiple
geographically distributed servers, creating your global messaging mesh.</para> geographically distributed servers, creating your global messaging mesh.</para>
<para>Diverts are defined as xml in the <literal>hornetq-configuration.xml</literal> file. There can <para>Diverts are defined as xml in the <literal>activemq-configuration.xml</literal> file. There can
be zero or more diverts in the file.</para> be zero or more diverts in the file.</para>
<para>Please see <xref linkend="divert-example" /> for a full working <para>Please see <xref linkend="divert-example" /> for a full working
example showing you how to configure and use diverts.</para> example showing you how to configure and use diverts.</para>
@ -86,7 +86,7 @@
change the messages body or properties before it is diverted. In this example the change the messages body or properties before it is diverted. In this example the
transformer simply adds a header that records the time the divert happened.</para> transformer simply adds a header that records the time the divert happened.</para>
<para>This example is actually diverting messages to a local store and forward queue, which <para>This example is actually diverting messages to a local store and forward queue, which
is configured with a bridge which forwards the message to an address on another HornetQ is configured with a bridge which forwards the message to an address on another ActiveMQ
server. Please see the example for more details.</para> server. Please see the example for more details.</para>
</section> </section>
<section> <section>

16
docs/user-manual/en/duplicate-detection.xml
View File

@ -19,15 +19,15 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="duplicate-detection"> <chapter id="duplicate-detection">
<title>Duplicate Message Detection</title> <title>Duplicate Message Detection</title>
<para>HornetQ includes powerful automatic duplicate message detection, filtering out <para>ActiveMQ includes powerful automatic duplicate message detection, filtering out
duplicate messages without you having to code your own fiddly duplicate detection logic at duplicate messages without you having to code your own fiddly duplicate detection logic at
the application level. This chapter will explain what duplicate detection is, how HornetQ the application level. This chapter will explain what duplicate detection is, how ActiveMQ
uses it and how and where to configure it.</para> uses it and how and where to configure it.</para>
<para>When sending messages from a client to a server, or indeed from a server to another <para>When sending messages from a client to a server, or indeed from a server to another
server, if the target server or connection fails sometime after sending the message, but server, if the target server or connection fails sometime after sending the message, but
@ -48,7 +48,7 @@
<para>Sending the message(s) in a transaction does not help out either. If the server or <para>Sending the message(s) in a transaction does not help out either. If the server or
connection fails while the transaction commit is being processed it is also indeterminate connection fails while the transaction commit is being processed it is also indeterminate
whether the transaction was successfully committed or not!</para> whether the transaction was successfully committed or not!</para>
<para>To solve these issues HornetQ provides automatic duplicate messages detection for <para>To solve these issues ActiveMQ provides automatic duplicate messages detection for
messages sent to addresses.</para> messages sent to addresses.</para>
<section> <section>
<title>Using Duplicate Detection for Message Sending</title> <title>Using Duplicate Detection for Message Sending</title>
@ -107,11 +107,11 @@ message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);
>n</literal> elements, then the <literal>n + 1</literal>th id stored will overwrite >n</literal> elements, then the <literal>n + 1</literal>th id stored will overwrite
the <literal>0</literal>th element in the cache.</para> the <literal>0</literal>th element in the cache.</para>
<para>The maximum size of the cache is configured by the parameter <literal <para>The maximum size of the cache is configured by the parameter <literal
>id-cache-size</literal> in <literal>hornetq-configuration.xml</literal>, the default >id-cache-size</literal> in <literal>activemq-configuration.xml</literal>, the default
value is <literal>2000</literal> elements.</para> value is <literal>2000</literal> elements.</para>
<para>The caches can also be configured to persist to disk or not. This is configured by the <para>The caches can also be configured to persist to disk or not. This is configured by the
parameter <literal>persist-id-cache</literal>, also in <literal parameter <literal>persist-id-cache</literal>, also in <literal
>hornetq-configuration.xml</literal>. If this is set to <literal>true</literal> then >activemq-configuration.xml</literal>. If this is set to <literal>true</literal> then
each id will be persisted to permanent storage as they are received. The default value each id will be persisted to permanent storage as they are received. The default value
for this parameter is <literal>true</literal>.</para> for this parameter is <literal>true</literal>.</para>
<note> <note>
@ -129,7 +129,7 @@ message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);
it will be ignored.</para> it will be ignored.</para>
<para>To configure a core bridge to add the duplicate id header, simply set the <parameter <para>To configure a core bridge to add the duplicate id header, simply set the <parameter
>use-duplicate-detection</parameter> to <literal>true</literal> when configuring a >use-duplicate-detection</parameter> to <literal>true</literal> when configuring a
bridge in <literal>hornetq-configuration.xml</literal>.</para> bridge in <literal>activemq-configuration.xml</literal>.</para>
<para>The default value for this parameter is <literal>true</literal>.</para> <para>The default value for this parameter is <literal>true</literal>.</para>
<para>For more information on core bridges and how to configure them, please see <para>For more information on core bridges and how to configure them, please see
<xref linkend="core-bridges" />.</para> <xref linkend="core-bridges" />.</para>
@ -141,7 +141,7 @@ message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);
id header for each message they move using their internal bridges.</para> id header for each message they move using their internal bridges.</para>
<para>To configure a cluster connection to add the duplicate id header, simply set the <para>To configure a cluster connection to add the duplicate id header, simply set the
<parameter>use-duplicate-detection</parameter> to <literal>true</literal> when <parameter>use-duplicate-detection</parameter> to <literal>true</literal> when
configuring a cluster connection in <literal>hornetq-configuration.xml</literal>.</para> configuring a cluster connection in <literal>activemq-configuration.xml</literal>.</para>
<para>The default value for this parameter is <literal>true</literal>.</para> <para>The default value for this parameter is <literal>true</literal>.</para>
<para>For more information on cluster connections and how to configure them, please see <xref <para>For more information on cluster connections and how to configure them, please see <xref
linkend="clusters"/>.</para> linkend="clusters"/>.</para>

88
docs/user-manual/en/embedding-hornetq.xml → docs/user-manual/en/embedding-activemq.xml
View File

@ -20,52 +20,52 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="embedding-hornetq"> <chapter id="embedding-activemq">
<title>Embedding HornetQ</title> <title>Embedding ActiveMQ</title>
<para>HornetQ is designed as set of simple Plain Old Java Objects (POJOs). <para>ActiveMQ is designed as set of simple Plain Old Java Objects (POJOs).
This means HornetQ can be instantiated and run in any dependency injection This means ActiveMQ can be instantiated and run in any dependency injection
framework such as JBoss Microcontainer, Spring or Google Guice. It also framework such as JBoss Microcontainer, Spring or Google Guice. It also
means that if you have an application that could use messaging functionality means that if you have an application that could use messaging functionality
internally, then it can <emphasis>directly instantiate</emphasis> HornetQ internally, then it can <emphasis>directly instantiate</emphasis> ActiveMQ
clients and servers in its own application code to perform that clients and servers in its own application code to perform that
functionality. We call this <emphasis>embedding</emphasis> HornetQ.</para> functionality. We call this <emphasis>embedding</emphasis> ActiveMQ.</para>
<para>Examples of applications that might want to do this include any <para>Examples of applications that might want to do this include any
application that needs very high performance, transactional, persistent application that needs very high performance, transactional, persistent
messaging but doesn't want the hassle of writing it all from scratch.</para> messaging but doesn't want the hassle of writing it all from scratch.</para>
<para>Embedding HornetQ can be done in very few easy steps. Instantiate the <para>Embedding ActiveMQ can be done in very few easy steps. Instantiate the
configuration object, instantiate the server, start it, and you have a configuration object, instantiate the server, start it, and you have a
HornetQ running in your virtual machine. It's as simple and easy as ActiveMQ running in your virtual machine. It's as simple and easy as
that.</para> that.</para>
<section> <section>
<title>Simple Config File Embedding</title> <title>Simple Config File Embedding</title>
<para>The simplest way to embed HornetQ is to use the embedded wrapper <para>The simplest way to embed ActiveMQ is to use the embedded wrapper
classes and configure HornetQ through its configuration files. There are classes and configure ActiveMQ through its configuration files. There are
two different helper classes for this depending on whether your using the two different helper classes for this depending on whether your using the
HornetQ Core API or JMS.</para> ActiveMQ Core API or JMS.</para>
<section> <section>
<title>Core API Only</title> <title>Core API Only</title>
<para>For instantiating a core HornetQ Server only, the steps are pretty <para>For instantiating a core ActiveMQ Server only, the steps are pretty
simple. The example requires that you have defined a configuration file simple. The example requires that you have defined a configuration file
<literal>hornetq-configuration.xml</literal> in your <literal>activemq-configuration.xml</literal> in your
classpath:</para> classpath:</para>
<programlisting> <programlisting>
import org.apache.activemq.core.server.embedded.EmbeddedHornetQ; import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
... ...
EmbeddedHornetQ embedded = new EmbeddedHornetQ(); EmbeddedActiveMQ embedded = new EmbeddedActiveMQ();
embedded.start(); embedded.start();
ClientSessionFactory nettyFactory = HornetQClient.createClientSessionFactory( ClientSessionFactory nettyFactory = ActiveMQClient.createClientSessionFactory(
new TransportConfiguration( new TransportConfiguration(
InVMConnectorFactory.class.getName())); InVMConnectorFactory.class.getName()));
@ -91,7 +91,7 @@ System.out.println("message = " + msgReceived.getBody().readString());
session.close();</programlisting> session.close();</programlisting>
<para>The <literal>EmbeddedHornetQ</literal> class has a <para>The <literal>EmbeddedActiveMQ</literal> class has a
few additional setter methods that allow you to specify a different few additional setter methods that allow you to specify a different
config file name as well as other properties. See the javadocs for this config file name as well as other properties. See the javadocs for this
class for more details.</para> class for more details.</para>
@ -102,11 +102,11 @@ session.close();</programlisting>
<para>JMS embedding is simple as well. This example requires that you <para>JMS embedding is simple as well. This example requires that you
have defined the config files have defined the config files
<literal>hornetq-configuration.xml</literal>, <literal>activemq-configuration.xml</literal>,
<literal>hornetq-jms.xml</literal>, and a <literal>activemq-jms.xml</literal>, and a
<literal>hornetq-users.xml</literal> if you have security enabled. Let's <literal>activemq-users.xml</literal> if you have security enabled. Let's
also assume that a queue and connection factory has been defined in the also assume that a queue and connection factory has been defined in the
<literal>hornetq-jms.xml</literal> config file.</para> <literal>activemq-jms.xml</literal> config file.</para>
<programlisting> <programlisting>
import org.apache.activemq.jms.server.embedded.EmbeddedJMS; import org.apache.activemq.jms.server.embedded.EmbeddedJMS;
@ -116,14 +116,14 @@ import org.apache.activemq.jms.server.embedded.EmbeddedJMS;
EmbeddedJMS jms = new EmbeddedJMS(); EmbeddedJMS jms = new EmbeddedJMS();
jms.start(); jms.start();
// This assumes we have configured hornetq-jms.xml with the appropriate config information // This assumes we have configured activemq-jms.xml with the appropriate config information
ConnectionFactory connectionFactory = jms.lookup("ConnectionFactory"); ConnectionFactory connectionFactory = jms.lookup("ConnectionFactory");
Destination destination = jms.lookup("/example/queue"); Destination destination = jms.lookup("/example/queue");
... regular JMS code ...</programlisting> ... regular JMS code ...</programlisting>
<para>By default, the <literal>EmbeddedJMS</literal> <para>By default, the <literal>EmbeddedJMS</literal>
class will store component entries defined within your class will store component entries defined within your
<literal>hornetq-jms.xml</literal> file in an internal concurrent hash <literal>activemq-jms.xml</literal> file in an internal concurrent hash
map. The <literal>EmbeddedJMS.lookup()</literal> method returns map. The <literal>EmbeddedJMS.lookup()</literal> method returns
components stored in this map. If you want to use JNDI, call the components stored in this map. If you want to use JNDI, call the
<literal>EmbeddedJMS.setContext()</literal> method with the root JNDI <literal>EmbeddedJMS.setContext()</literal> method with the root JNDI
@ -136,10 +136,10 @@ Destination destination = jms.lookup("/example/queue");
<title>POJO instantiation - Embedding Programmatically</title> <title>POJO instantiation - Embedding Programmatically</title>
<para>You can follow this step-by-step guide to programmatically embed the <para>You can follow this step-by-step guide to programmatically embed the
core, non-JMS HornetQ Server instance:</para> core, non-JMS ActiveMQ Server instance:</para>
<para>Create the configuration object - this contains configuration <para>Create the configuration object - this contains configuration
information for a HornetQ instance. The setter methods of this class allow information for a ActiveMQ instance. The setter methods of this class allow
you to programmatically set configuration options as describe in the <xref you to programmatically set configuration options as describe in the <xref
linkend="server.configuration" /> section.</para> linkend="server.configuration" /> section.</para>
@ -163,25 +163,25 @@ transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));
config.setAcceptorConfigurations(transports);</programlisting> config.setAcceptorConfigurations(transports);</programlisting>
<para>You need to instantiate an instance of <para>You need to instantiate an instance of
<literal>org.apache.activemq.api.core.server.embedded.EmbeddedHornetQ</literal> <literal>org.apache.activemq.api.core.server.embedded.EmbeddedActiveMQ</literal>
and add the configuration object to it.</para> and add the configuration object to it.</para>
<programlisting> <programlisting>
import org.apache.activemq.api.core.server.HornetQ; import org.apache.activemq.api.core.server.ActiveMQ;
import org.apache.activemq.core.server.embedded.EmbeddedHornetQ; import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
... ...
EmbeddedHornetQ server = new EmbeddedHornetQ(); EmbeddedActiveMQ server = new EmbeddedActiveMQ();
server.setConfiguration(config); server.setConfiguration(config);
server.start();</programlisting> server.start();</programlisting>
<para>You also have the option of instantiating <para>You also have the option of instantiating
<literal>HornetQServerImpl</literal> directly:</para> <literal>ActiveMQServerImpl</literal> directly:</para>
<programlisting> <programlisting>
HornetQServer server = new HornetQServerImpl(config); ActiveMQServer server = new ActiveMQServerImpl(config);
server.start();</programlisting> server.start();</programlisting>
<para>For JMS POJO instantiation, you work with the EmbeddedJMS class <para>For JMS POJO instantiation, you work with the EmbeddedJMS class
@ -191,7 +191,7 @@ server.start();</programlisting>
example of this:</para> example of this:</para>
<programlisting> <programlisting>
// Step 1. Create HornetQ core configuration, and set the properties accordingly // Step 1. Create ActiveMQ core configuration, and set the properties accordingly
Configuration configuration = new ConfigurationImpl(); Configuration configuration = new ConfigurationImpl();
configuration.setPersistenceEnabled(false); configuration.setPersistenceEnabled(false);
configuration.setSecurityEnabled(false); configuration.setSecurityEnabled(false);
@ -209,14 +209,14 @@ jmsConfig.getConnectionFactoryConfigurations().add(cfConfig);
JMSQueueConfiguration queueConfig = new JMSQueueConfigurationImpl("queue1", null, false, "/queue/queue1"); JMSQueueConfiguration queueConfig = new JMSQueueConfigurationImpl("queue1", null, false, "/queue/queue1");
jmsConfig.getQueueConfigurations().add(queueConfig); jmsConfig.getQueueConfigurations().add(queueConfig);
// Step 5. Start the JMS Server using the HornetQ core server and the JMS configuration // Step 5. Start the JMS Server using the ActiveMQ core server and the JMS configuration
EmbeddedJMS jmsServer = new EmbeddedJMS(); EmbeddedJMS jmsServer = new EmbeddedJMS();
jmsServer.setConfiguration(configuration); jmsServer.setConfiguration(configuration);
jmsServer.setJmsConfiguration(jmsConfig); jmsServer.setJmsConfiguration(jmsConfig);
jmsServer.start();</programlisting> jmsServer.start();</programlisting>
<para>Please see <xref linkend="examples.embedded.jms" /> for an example which <para>Please see <xref linkend="examples.embedded.jms" /> for an example which
shows how to setup and run HornetQ embedded with JMS.</para> shows how to setup and run ActiveMQ embedded with JMS.</para>
</section> </section>
<section> <section>
@ -225,17 +225,17 @@ jmsServer.start();</programlisting>
<para>You may also choose to use a dependency injection framework such as <para>You may also choose to use a dependency injection framework such as
<trademark>JBoss Micro Container</trademark> or <trademark>Spring <trademark>JBoss Micro Container</trademark> or <trademark>Spring
Framework</trademark>. See <xref linkend="spring.integration" /> for more Framework</trademark>. See <xref linkend="spring.integration" /> for more
details on Spring and HornetQ, but here's how you would do things with the details on Spring and ActiveMQ, but here's how you would do things with the
JBoss Micro Container.</para> JBoss Micro Container.</para>
<para>HornetQ standalone uses JBoss Micro Container as the injection <para>ActiveMQ standalone uses JBoss Micro Container as the injection
framework. <literal>HornetQBootstrapServer</literal> and framework. <literal>ActiveMQBootstrapServer</literal> and
<literal>hornetq-beans.xml</literal> which are part of the HornetQ <literal>activemq-beans.xml</literal> which are part of the ActiveMQ
distribution provide a very complete implementation of what's needed to distribution provide a very complete implementation of what's needed to
bootstrap the server using JBoss Micro Container.</para> bootstrap the server using JBoss Micro Container.</para>
<para>When using JBoss Micro Container, you need to provide an XML file <para>When using JBoss Micro Container, you need to provide an XML file
declaring the <literal>HornetQServer</literal> and declaring the <literal>ActiveMQServer</literal> and
<literal>Configuration</literal> object, you can also inject a security <literal>Configuration</literal> object, you can also inject a security
manager and a MBean server if you want, but those are optional.</para> manager and a MBean server if you want, but those are optional.</para>
@ -251,8 +251,8 @@ jmsServer.start();</programlisting>
&lt;/bean> &lt;/bean>
&lt;!-- The core server --> &lt;!-- The core server -->
&lt;bean name="HornetQServer" &lt;bean name="ActiveMQServer"
class="org.apache.activemq.core.server.impl.HornetQServerImpl"> class="org.apache.activemq.core.server.impl.ActiveMQServerImpl">
&lt;constructor> &lt;constructor>
&lt;parameter> &lt;parameter>
&lt;inject bean="Configuration"/> &lt;inject bean="Configuration"/>
@ -261,11 +261,11 @@ jmsServer.start();</programlisting>
&lt;/bean> &lt;/bean>
&lt;/deployment></programlisting> &lt;/deployment></programlisting>
<para><literal>HornetQBootstrapServer</literal> provides an easy <para><literal>ActiveMQBootstrapServer</literal> provides an easy
encapsulation of JBoss Micro Container.</para> encapsulation of JBoss Micro Container.</para>
<programlisting> <programlisting>
HornetQBootstrapServer bootStrap = new HornetQBootstrapServer(new String[] {"hornetq-beans.xml"}); ActiveMQBootstrapServer bootStrap = new ActiveMQBootstrapServer(new String[] {"activemq-beans.xml"});
bootStrap.run();</programlisting> bootStrap.run();</programlisting>
</section> </section>
</chapter> </chapter>

154
docs/user-manual/en/examples.xml
View File

@ -18,12 +18,12 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="examples"> <chapter id="examples">
<title>Examples</title> <title>Examples</title>
<para>The HornetQ distribution comes with over 70 run out-of-the-box examples demonstrating many <para>The ActiveMQ distribution comes with over 70 run out-of-the-box examples demonstrating many
of the features.</para> of the features.</para>
<para>The examples are available in the distribution, in the <literal>examples</literal> <para>The examples are available in the distribution, in the <literal>examples</literal>
directory. Examples are split into JMS and core examples. JMS examples show how a particular directory. Examples are split into JMS and core examples. JMS examples show how a particular
@ -49,11 +49,11 @@
</section> </section>
<section id="application-level-failover"> <section id="application-level-failover">
<title>Application-Layer Failover</title> <title>Application-Layer Failover</title>
<para>HornetQ also supports Application-Layer failover, useful in the case that <para>ActiveMQ also supports Application-Layer failover, useful in the case that
replication is not enabled on the server side.</para> replication is not enabled on the server side.</para>
<para>With Application-Layer failover, it's up to the application to register a JMS <para>With Application-Layer failover, it's up to the application to register a JMS
<literal>ExceptionListener</literal> with HornetQ which will be called by <literal>ExceptionListener</literal> with ActiveMQ which will be called by
HornetQ in the event that connection failure is detected.</para> ActiveMQ in the event that connection failure is detected.</para>
<para>The code in the <literal>ExceptionListener</literal> then recreates the JMS <para>The code in the <literal>ExceptionListener</literal> then recreates the JMS
connection, session, etc on another node and the application can continue.</para> connection, session, etc on another node and the application can continue.</para>
<para>Application-layer failover is an alternative approach to High Availability (HA). <para>Application-layer failover is an alternative approach to High Availability (HA).
@ -68,7 +68,7 @@
<para>The <literal>bridge</literal> example demonstrates a core bridge deployed on one <para>The <literal>bridge</literal> example demonstrates a core bridge deployed on one
server, which consumes messages from a local queue and forwards them to an address server, which consumes messages from a local queue and forwards them to an address
on a second server.</para> on a second server.</para>
<para>Core bridges are used to create message flows between any two HornetQ servers <para>Core bridges are used to create message flows between any two ActiveMQ servers
which are remotely separated. Core bridges are resilient and will cope with which are remotely separated. Core bridges are resilient and will cope with
temporary connection failure allowing them to be an ideal choice for forwarding over temporary connection failure allowing them to be an ideal choice for forwarding over
unreliable connections, e.g. a WAN.</para> unreliable connections, e.g. a WAN.</para>
@ -76,7 +76,7 @@
<section id="examples.browsers"> <section id="examples.browsers">
<title>Browser</title> <title>Browser</title>
<para>The <literal>browser</literal> example shows you how to use a JMS <literal <para>The <literal>browser</literal> example shows you how to use a JMS <literal
>QueueBrowser</literal> with HornetQ.</para> >QueueBrowser</literal> with ActiveMQ.</para>
<para>Queues are a standard part of JMS, please consult the JMS 1.1 specification for <para>Queues are a standard part of JMS, please consult the JMS 1.1 specification for
full details.</para> full details.</para>
<para> A <literal>QueueBrowser</literal> is used to look at messages on the queue <para> A <literal>QueueBrowser</literal> is used to look at messages on the queue
@ -98,7 +98,7 @@
<para>The <literal>client-side-load-balancing</literal> example demonstrates how <para>The <literal>client-side-load-balancing</literal> example demonstrates how
sessions created from a single JMS <literal>Connection</literal> can sessions created from a single JMS <literal>Connection</literal> can
be created to different nodes of the cluster. In other words it demonstrates how be created to different nodes of the cluster. In other words it demonstrates how
HornetQ does client-side load-balancing of sessions across the cluster.</para> ActiveMQ does client-side load-balancing of sessions across the cluster.</para>
</section> </section>
<section id="examples.clustered.durable"> <section id="examples.clustered.durable">
<title>Clustered Durable Subscription</title> <title>Clustered Durable Subscription</title>
@ -154,10 +154,10 @@
</section> </section>
<section id="examples.consumer-rate-limit"> <section id="examples.consumer-rate-limit">
<title>Message Consumer Rate Limiting</title> <title>Message Consumer Rate Limiting</title>
<para>With HornetQ you can specify a maximum consume rate at which a JMS MessageConsumer <para>With ActiveMQ you can specify a maximum consume rate at which a JMS MessageConsumer
will consume messages. This can be specified when creating or deploying the will consume messages. This can be specified when creating or deploying the
connection factory.</para> connection factory.</para>
<para>If this value is specified then HornetQ will ensure that messages are never <para>If this value is specified then ActiveMQ will ensure that messages are never
consumed at a rate higher than the specified rate. This is a form of consumer consumed at a rate higher than the specified rate. This is a form of consumer
throttling.</para> throttling.</para>
</section> </section>
@ -176,7 +176,7 @@
</section> </section>
<section id="examples.delayed-redelivery"> <section id="examples.delayed-redelivery">
<title>Delayed Redelivery</title> <title>Delayed Redelivery</title>
<para>The <literal>delayed-redelivery</literal> example demonstrates how HornetQ can be <para>The <literal>delayed-redelivery</literal> example demonstrates how ActiveMQ can be
configured to provide a delayed redelivery in the case a message needs to be configured to provide a delayed redelivery in the case a message needs to be
redelivered.</para> redelivered.</para>
<para>Delaying redelivery can often be useful in the case that clients regularly fail or <para>Delaying redelivery can often be useful in the case that clients regularly fail or
@ -187,14 +187,14 @@
</section> </section>
<section id="divert-example"> <section id="divert-example">
<title>Divert</title> <title>Divert</title>
<para>HornetQ diverts allow messages to be transparently "diverted" or copied from one <para>ActiveMQ diverts allow messages to be transparently "diverted" or copied from one
address to another with just some simple configuration defined on the server address to another with just some simple configuration defined on the server
side.</para> side.</para>
</section> </section>
<section> <section>
<title>Durable Subscription</title> <title>Durable Subscription</title>
<para>The <literal>durable-subscription</literal> example shows you how to use a durable <para>The <literal>durable-subscription</literal> example shows you how to use a durable
subscription with HornetQ. Durable subscriptions are a standard part of JMS, please subscription with ActiveMQ. Durable subscriptions are a standard part of JMS, please
consult the JMS 1.1 specification for full details.</para> consult the JMS 1.1 specification for full details.</para>
<para>Unlike non-durable subscriptions, the key function of durable subscriptions is <para>Unlike non-durable subscriptions, the key function of durable subscriptions is
that the messages contained in them persist longer than the lifetime of the that the messages contained in them persist longer than the lifetime of the
@ -210,7 +210,7 @@
</section> </section>
<section id="examples.embedded.jms.simple"> <section id="examples.embedded.jms.simple">
<title>Embedded Simple</title> <title>Embedded Simple</title>
<para>The <literal>embedded</literal> example shows how to embed JMS within your own code using regular HornetQ XML files.</para> <para>The <literal>embedded</literal> example shows how to embed JMS within your own code using regular ActiveMQ XML files.</para>
</section> </section>
<section id="examples.expiry"> <section id="examples.expiry">
<title>Message Expiration</title> <title>Message Expiration</title>
@ -219,19 +219,19 @@
period of time before being removed. JMS specification states that clients should period of time before being removed. JMS specification states that clients should
not receive messages that have been expired (but it does not guarantee this will not not receive messages that have been expired (but it does not guarantee this will not
happen).</para> happen).</para>
<para>HornetQ can assign an expiry address to a given queue so that when messages <para>ActiveMQ can assign an expiry address to a given queue so that when messages
are expired, they are removed from the queue and sent to the expiry address. are expired, they are removed from the queue and sent to the expiry address.
These "expired" messages can later be consumed from the expiry address for These "expired" messages can later be consumed from the expiry address for
further inspection.</para> further inspection.</para>
</section> </section>
<section id="examples.hornetq-ra-rar"> <section id="examples.activemq-ra-rar">
<title>HornetQ Resource Adapter example</title> <title>ActiveMQ Resource Adapter example</title>
<para>This examples shows how to build the hornetq resource adapters a rar for deployment in other Application <para>This examples shows how to build the activemq resource adapters a rar for deployment in other Application
Server's</para> Server's</para>
</section> </section>
<section> <section>
<title>HTTP Transport</title> <title>HTTP Transport</title>
<para>The <literal>http-transport</literal> example shows you how to configure HornetQ <para>The <literal>http-transport</literal> example shows you how to configure ActiveMQ
to use the HTTP protocol as its transport layer.</para> to use the HTTP protocol as its transport layer.</para>
</section> </section>
<section> <section>
@ -241,18 +241,18 @@
before being used by the client code. This objects are called "administered objects" before being used by the client code. This objects are called "administered objects"
in JMS terminology.</para> in JMS terminology.</para>
<para>However, in some cases a JNDI server may not be available or desired. To come to <para>However, in some cases a JNDI server may not be available or desired. To come to
the rescue HornetQ also supports the direct instantiation of these administered the rescue ActiveMQ also supports the direct instantiation of these administered
objects on the client side so you don't have to use JNDI for JMS.</para> objects on the client side so you don't have to use JNDI for JMS.</para>
</section> </section>
<section id="examples.interceptor"> <section id="examples.interceptor">
<title>Interceptor</title> <title>Interceptor</title>
<para>HornetQ allows an application to use an interceptor to hook into the messaging <para>ActiveMQ allows an application to use an interceptor to hook into the messaging
system. Interceptors allow you to handle various message events in HornetQ.</para> system. Interceptors allow you to handle various message events in ActiveMQ.</para>
</section> </section>
<section id="examples.jaas"> <section id="examples.jaas">
<title>JAAS</title> <title>JAAS</title>
<para>The <literal>jaas</literal> example shows you how to configure HornetQ to use JAAS <para>The <literal>jaas</literal> example shows you how to configure ActiveMQ to use JAAS
for security. HornetQ can leverage JAAS to delegate user authentication and for security. ActiveMQ can leverage JAAS to delegate user authentication and
authorization to existing security infrastructure.</para> authorization to existing security infrastructure.</para>
</section> </section>
<section id="examples.jms.auto-closeable"> <section id="examples.jms.auto-closeable">
@ -263,18 +263,18 @@
<section id="examples.jms.completion-listener"> <section id="examples.jms.completion-listener">
<title>JMS Completion Listener</title> <title>JMS Completion Listener</title>
<para>The <literal>jms-completion-listener</literal> example shows how to send a message <para>The <literal>jms-completion-listener</literal> example shows how to send a message
asynchronously to HornetQ and use a CompletionListener to be notified of the Broker asynchronously to ActiveMQ and use a CompletionListener to be notified of the Broker
receiving it.</para> receiving it.</para>
</section> </section>
<section id="examples.jms.jms-bridge"> <section id="examples.jms.jms-bridge">
<title>JMS Bridge</title> <title>JMS Bridge</title>
<para>The <literal>jms-brige</literal> example shows how to setup a bridge <para>The <literal>jms-brige</literal> example shows how to setup a bridge
between two standalone HornetQ servers.</para> between two standalone ActiveMQ servers.</para>
</section> </section>
<section id="examples.jms.jms-context"> <section id="examples.jms.jms-context">
<title>JMS Context</title> <title>JMS Context</title>
<para>The <literal>jms-context</literal> example shows how to send and receive a message <para>The <literal>jms-context</literal> example shows how to send and receive a message
to a JMS Queue using HornetQ by using a JMS Context.</para> to a JMS Queue using ActiveMQ by using a JMS Context.</para>
<para>A JMSContext is part of JMS 2.0 and combines the JMS Connection and Session Objects <para>A JMSContext is part of JMS 2.0 and combines the JMS Connection and Session Objects
into a simple Interface.</para> into a simple Interface.</para>
</section> </section>
@ -287,17 +287,17 @@
</section> </section>
<section id="examples.jmx"> <section id="examples.jmx">
<title>JMX Management</title> <title>JMX Management</title>
<para>The <literal>jmx</literal> example shows how to manage HornetQ using JMX.</para> <para>The <literal>jmx</literal> example shows how to manage ActiveMQ using JMX.</para>
</section> </section>
<section id="examples.large-message"> <section id="examples.large-message">
<title>Large Message</title> <title>Large Message</title>
<para>The <literal>large-message</literal> example shows you how to send and receive <para>The <literal>large-message</literal> example shows you how to send and receive
very large messages with HornetQ. HornetQ supports the sending and receiving of huge very large messages with ActiveMQ. ActiveMQ supports the sending and receiving of huge
messages, much larger than can fit in available RAM on the client or server. messages, much larger than can fit in available RAM on the client or server.
Effectively the only limit to message size is the amount of disk space you have on Effectively the only limit to message size is the amount of disk space you have on
the server.</para> the server.</para>
<para>Large messages are persisted on the server so they can survive a server restart. <para>Large messages are persisted on the server so they can survive a server restart.
In other words HornetQ doesn't just do a simple socket stream from the sender to the In other words ActiveMQ doesn't just do a simple socket stream from the sender to the
consumer.</para> consumer.</para>
</section> </section>
<section id="examples.last-value-queue"> <section id="examples.last-value-queue">
@ -312,13 +312,13 @@
</section> </section>
<section id="examples.management"> <section id="examples.management">
<title>Management</title> <title>Management</title>
<para>The <literal>management</literal> example shows how to manage HornetQ using JMS <para>The <literal>management</literal> example shows how to manage ActiveMQ using JMS
Messages to invoke management operations on the server.</para> Messages to invoke management operations on the server.</para>
</section> </section>
<section id="examples.management-notifications"> <section id="examples.management-notifications">
<title>Management Notification</title> <title>Management Notification</title>
<para>The <literal>management-notification</literal> example shows how to receive <para>The <literal>management-notification</literal> example shows how to receive
management notifications from HornetQ using JMS messages. HornetQ servers emit management notifications from ActiveMQ using JMS messages. ActiveMQ servers emit
management notifications when events of interest occur (consumers are created or management notifications when events of interest occur (consumers are created or
closed, addresses are created or deleted, security authentication fails, closed, addresses are created or deleted, security authentication fails,
etc.).</para> etc.).</para>
@ -331,7 +331,7 @@
<section id="examples.message-group"> <section id="examples.message-group">
<title>Message Group</title> <title>Message Group</title>
<para>The <literal>message-group</literal> example shows you how to configure and use <para>The <literal>message-group</literal> example shows you how to configure and use
message groups with HornetQ. Message groups allow you to pin messages so they are message groups with ActiveMQ. Message groups allow you to pin messages so they are
only consumed by a single consumer. Message groups are sets of messages that has the only consumed by a single consumer. Message groups are sets of messages that has the
following characteristics:</para> following characteristics:</para>
<para> <para>
@ -350,7 +350,7 @@
<section id="examples.message-group2"> <section id="examples.message-group2">
<title>Message Group</title> <title>Message Group</title>
<para>The <literal>message-group2</literal> example shows you how to configure and use <para>The <literal>message-group2</literal> example shows you how to configure and use
message groups with HornetQ via a connection factory.</para> message groups with ActiveMQ via a connection factory.</para>
</section> </section>
<section id="examples.message-priority"> <section id="examples.message-priority">
<title>Message Priority</title> <title>Message Priority</title>
@ -376,16 +376,16 @@
</section> </section>
<section id="examples.no-consumer-buffering"> <section id="examples.no-consumer-buffering">
<title>No Consumer Buffering</title> <title>No Consumer Buffering</title>
<para>By default, HornetQ consumers buffer messages from the server in a client side <para>By default, ActiveMQ consumers buffer messages from the server in a client side
buffer before you actually receive them on the client side. This improves buffer before you actually receive them on the client side. This improves
performance since otherwise every time you called receive() or had processed the performance since otherwise every time you called receive() or had processed the
last message in a <literal>MessageListener onMessage()</literal> method, the HornetQ last message in a <literal>MessageListener onMessage()</literal> method, the ActiveMQ
client would have to go the server to request the next message, which would then get client would have to go the server to request the next message, which would then get
sent to the client side, if one was available.</para> sent to the client side, if one was available.</para>
<para>This would involve a network round trip for every message and reduce performance. <para>This would involve a network round trip for every message and reduce performance.
Therefore, by default, HornetQ pre-fetches messages into a buffer on each Therefore, by default, ActiveMQ pre-fetches messages into a buffer on each
consumer.</para> consumer.</para>
<para>In some case buffering is not desirable, and HornetQ allows it to be switched off. <para>In some case buffering is not desirable, and ActiveMQ allows it to be switched off.
This example demonstrates that.</para> This example demonstrates that.</para>
</section> </section>
<section id="examples.non-transaction-failover"> <section id="examples.non-transaction-failover">
@ -394,7 +394,7 @@
as a live-backup pair for high availability (HA), and a client using a <emphasis>non-transacted as a live-backup pair for high availability (HA), and a client using a <emphasis>non-transacted
</emphasis> JMS session failing over from live to backup when the live server is </emphasis> JMS session failing over from live to backup when the live server is
crashed.</para> crashed.</para>
<para>HornetQ implements failover of client connections between <para>ActiveMQ implements failover of client connections between
live and backup servers. This is implemented by the replication of state between live and backup servers. This is implemented by the replication of state between
live and backup nodes. When replication is configured and a live node crashes, the live and backup nodes. When replication is configured and a live node crashes, the
client connections can carry and continue to send and consume messages. When non-transacted client connections can carry and continue to send and consume messages. When non-transacted
@ -403,12 +403,12 @@
</section> </section>
<section id="examples.openwire"> <section id="examples.openwire">
<title>OpenWire</title> <title>OpenWire</title>
<para>The <literal>Openwire</literal> example shows how to configure a HornetQ <para>The <literal>Openwire</literal> example shows how to configure a ActiveMQ
server to communicate with an ActiveMQ JMS client that uses open-wire protocol.</para> server to communicate with an ActiveMQ JMS client that uses open-wire protocol.</para>
</section> </section>
<section id="examples.paging"> <section id="examples.paging">
<title>Paging</title> <title>Paging</title>
<para>The <literal>paging</literal> example shows how HornetQ can support huge queues <para>The <literal>paging</literal> example shows how ActiveMQ can support huge queues
even when the server is running in limited RAM. It does this by transparently even when the server is running in limited RAM. It does this by transparently
<emphasis>paging</emphasis> messages to disk, and <emphasis>depaging</emphasis> <emphasis>paging</emphasis> messages to disk, and <emphasis>depaging</emphasis>
them when they are required.</para> them when they are required.</para>
@ -422,24 +422,24 @@
<para>All of these standard modes involve sending acknowledgements from the client to <para>All of these standard modes involve sending acknowledgements from the client to
the server. However in some cases, you really don't mind losing messages in event of the server. However in some cases, you really don't mind losing messages in event of
failure, so it would make sense to acknowledge the message on the server before failure, so it would make sense to acknowledge the message on the server before
delivering it to the client. This example demonstrates how HornetQ allows this with delivering it to the client. This example demonstrates how ActiveMQ allows this with
an extra acknowledgement mode.</para> an extra acknowledgement mode.</para>
</section> </section>
<section id="producer-rate-limiting-example"> <section id="producer-rate-limiting-example">
<title>Message Producer Rate Limiting</title> <title>Message Producer Rate Limiting</title>
<para>The <literal>producer-rte-limit</literal> example demonstrates how, with HornetQ, <para>The <literal>producer-rte-limit</literal> example demonstrates how, with ActiveMQ,
you can specify a maximum send rate at which a JMS message producer will send you can specify a maximum send rate at which a JMS message producer will send
messages.</para> messages.</para>
</section> </section>
<section id="examples.proton-qpid"> <section id="examples.proton-qpid">
<title>Proton Qpid</title> <title>Proton Qpid</title>
<para>HornetQ can be configured to accept requests from any AMQP client that supports the <para>ActiveMQ can be configured to accept requests from any AMQP client that supports the
1.0 version of the protocol. This <literal>proton-j</literal> example shows a simply 1.0 version of the protocol. This <literal>proton-j</literal> example shows a simply
qpid java 1.0 client example.</para> qpid java 1.0 client example.</para>
</section> </section>
<section id="examples.proton-ruby"> <section id="examples.proton-ruby">
<title>Proton Ruby</title> <title>Proton Ruby</title>
<para>HornetQ can be configured to accept requests from any AMQP client that supports the <para>ActiveMQ can be configured to accept requests from any AMQP client that supports the
1.0 version of the protocol. This example shows a simply proton ruby client 1.0 version of the protocol. This example shows a simply proton ruby client
that sends and receives messages</para> that sends and receives messages</para>
</section> </section>
@ -466,7 +466,7 @@
<title>Reattach Node example</title> <title>Reattach Node example</title>
<para>The <literal>Reattach Node</literal> example shows how a client can try to reconnect to <para>The <literal>Reattach Node</literal> example shows how a client can try to reconnect to
the same server instead of failing the connection immediately and the same server instead of failing the connection immediately and
notifying any user ExceptionListener objects. HornetQ can be configured to automatically notifying any user ExceptionListener objects. ActiveMQ can be configured to automatically
retry the connection, and reattach to the server when it becomes available again across retry the connection, and reattach to the server when it becomes available again across
the network.</para> the network.</para>
</section> </section>
@ -494,71 +494,71 @@
</section> </section>
<section id="examples.rest"> <section id="examples.rest">
<title>Rest example</title> <title>Rest example</title>
<para>An example showing how to use the HornetQ Rest API</para> <para>An example showing how to use the ActiveMQ Rest API</para>
</section> </section>
<section id="examples.scheduled-message"> <section id="examples.scheduled-message">
<title>Scheduled Message</title> <title>Scheduled Message</title>
<para>The <literal>scheduled-message</literal> example shows you how to send a scheduled <para>The <literal>scheduled-message</literal> example shows you how to send a scheduled
message to a JMS Queue with HornetQ. Scheduled messages won't get delivered until a message to a JMS Queue with ActiveMQ. Scheduled messages won't get delivered until a
specified time in the future.</para> specified time in the future.</para>
</section> </section>
<section id="examples.security"> <section id="examples.security">
<title>Security</title> <title>Security</title>
<para>The <literal>security</literal> example shows you how configure and use role based <para>The <literal>security</literal> example shows you how configure and use role based
queue security with HornetQ.</para> queue security with ActiveMQ.</para>
</section> </section>
<section id="asynchronous-send-acknowledgements-example"> <section id="asynchronous-send-acknowledgements-example">
<title>Send Acknowledgements</title> <title>Send Acknowledgements</title>
<para>The <literal>send-acknowledgements</literal> example shows you how to use <para>The <literal>send-acknowledgements</literal> example shows you how to use
HornetQ's advanced <emphasis>asynchronous send acknowledgements</emphasis> feature ActiveMQ's advanced <emphasis>asynchronous send acknowledgements</emphasis> feature
to obtain acknowledgement from the server that sends have been received and to obtain acknowledgement from the server that sends have been received and
processed in a separate stream to the sent messages. </para> processed in a separate stream to the sent messages. </para>
</section> </section>
<section id="examples.jms.spring.integration"> <section id="examples.jms.spring.integration">
<title>Spring Integration</title> <title>Spring Integration</title>
<para>This example shows how to use embedded JMS using HornetQ's Spring integration.</para> <para>This example shows how to use embedded JMS using ActiveMQ's Spring integration.</para>
</section> </section>
<section id="examples.ssl-transport"> <section id="examples.ssl-transport">
<title>SSL Transport</title> <title>SSL Transport</title>
<para>The <literal>ssl-enabled</literal> shows you how to configure SSL with HornetQ to <para>The <literal>ssl-enabled</literal> shows you how to configure SSL with ActiveMQ to
send and receive message.</para> send and receive message.</para>
</section> </section>
<section id="examples.static-message-selector"> <section id="examples.static-message-selector">
<title>Static Message Selector</title> <title>Static Message Selector</title>
<para>The <literal>static-selector</literal> example shows you how to configure a <para>The <literal>static-selector</literal> example shows you how to configure a
HornetQ core queue with static message selectors (filters).</para> ActiveMQ core queue with static message selectors (filters).</para>
</section> </section>
<section id="examples.static-message-selector-jms"> <section id="examples.static-message-selector-jms">
<title>Static Message Selector Using JMS</title> <title>Static Message Selector Using JMS</title>
<para>The <literal>static-selector-jms</literal> example shows you how to configure a <para>The <literal>static-selector-jms</literal> example shows you how to configure a
HornetQ queue with static message selectors (filters) using JMS.</para> ActiveMQ queue with static message selectors (filters) using JMS.</para>
</section> </section>
<section id="examples.stomp"> <section id="examples.stomp">
<title>Stomp</title> <title>Stomp</title>
<para>The <literal>stomp</literal> example shows you how to configure a <para>The <literal>stomp</literal> example shows you how to configure a
HornetQ server to send and receive Stomp messages.</para> ActiveMQ server to send and receive Stomp messages.</para>
</section> </section>
<section id="examples.stomp1.1"> <section id="examples.stomp1.1">
<title>Stomp1.1</title> <title>Stomp1.1</title>
<para>The <literal>stomp</literal> example shows you how to configure a <para>The <literal>stomp</literal> example shows you how to configure a
HornetQ server to send and receive Stomp messages via a Stomp 1.1 connection.</para> ActiveMQ server to send and receive Stomp messages via a Stomp 1.1 connection.</para>
</section> </section>
<section id="examples.stomp1.2"> <section id="examples.stomp1.2">
<title>Stomp1.2</title> <title>Stomp1.2</title>
<para>The <literal>stomp</literal> example shows you how to configure a <para>The <literal>stomp</literal> example shows you how to configure a
HornetQ server to send and receive Stomp messages via a Stomp 1.2 connection.</para> ActiveMQ server to send and receive Stomp messages via a Stomp 1.2 connection.</para>
</section> </section>
<section id="examples.stomp-web-socket"> <section id="examples.stomp-web-socket">
<title>Stomp Over Web Sockets</title> <title>Stomp Over Web Sockets</title>
<para>The <literal>stomp-websockets</literal> example shows you how to configure a <para>The <literal>stomp-websockets</literal> example shows you how to configure a
HornetQ server to send and receive Stomp messages directly from Web browsers (provided ActiveMQ server to send and receive Stomp messages directly from Web browsers (provided
they support Web Sockets).</para> they support Web Sockets).</para>
</section> </section>
<section id="examples.symmetric-cluster"> <section id="examples.symmetric-cluster">
<title>Symmetric Cluster</title> <title>Symmetric Cluster</title>
<para>The <literal>symmetric-cluster</literal> example demonstrates a symmetric cluster <para>The <literal>symmetric-cluster</literal> example demonstrates a symmetric cluster
set-up with HornetQ.</para> set-up with ActiveMQ.</para>
<para>HornetQ has extremely flexible clustering which allows you to set-up servers in <para>ActiveMQ has extremely flexible clustering which allows you to set-up servers in
many different topologies. The most common topology that you'll perhaps be familiar many different topologies. The most common topology that you'll perhaps be familiar
with if you are used to application server clustering is a symmetric cluster.</para> with if you are used to application server clustering is a symmetric cluster.</para>
<para>With a symmetric cluster, the cluster is homogeneous, i.e. each node is configured <para>With a symmetric cluster, the cluster is homogeneous, i.e. each node is configured
@ -575,14 +575,14 @@
</section> </section>
<section id="topic-hierarchy-example"> <section id="topic-hierarchy-example">
<title>Topic Hierarchy</title> <title>Topic Hierarchy</title>
<para>HornetQ supports topic hierarchies. With a topic hierarchy you can register a <para>ActiveMQ supports topic hierarchies. With a topic hierarchy you can register a
subscriber with a wild-card and that subscriber will receive any messages sent to an subscriber with a wild-card and that subscriber will receive any messages sent to an
address that matches the wild card.</para> address that matches the wild card.</para>
</section> </section>
<section id="examples.topic-selector-1"> <section id="examples.topic-selector-1">
<title>Topic Selector 1</title> <title>Topic Selector 1</title>
<para>The <literal>topic-selector-example1</literal> example shows you how to send <para>The <literal>topic-selector-example1</literal> example shows you how to send
message to a JMS Topic, and subscribe them using selectors with HornetQ.</para> message to a JMS Topic, and subscribe them using selectors with ActiveMQ.</para>
</section> </section>
<section id="examples.topic-selector-2"> <section id="examples.topic-selector-2">
<title>Topic Selector 2</title> <title>Topic Selector 2</title>
@ -595,7 +595,7 @@
as a live-backup pair for high availability (HA), and a client using a transacted JMS as a live-backup pair for high availability (HA), and a client using a transacted JMS
session failing over from live to backup when the live server is session failing over from live to backup when the live server is
crashed.</para> crashed.</para>
<para>HornetQ implements failover of client connections between <para>ActiveMQ implements failover of client connections between
live and backup servers. This is implemented by the sharing of a journal between the live and backup servers. This is implemented by the sharing of a journal between the
servers. When a live node crashes, the servers. When a live node crashes, the
client connections can carry and continue to send and consume messages. When transacted client connections can carry and continue to send and consume messages. When transacted
@ -610,29 +610,29 @@
<section id="examples.transactional-session"> <section id="examples.transactional-session">
<title>Transactional Session</title> <title>Transactional Session</title>
<para>The <literal>transactional</literal> example shows you how to use a transactional <para>The <literal>transactional</literal> example shows you how to use a transactional
Session with HornetQ.</para> Session with ActiveMQ.</para>
</section> </section>
<section> <section>
<title>XA Heuristic</title> <title>XA Heuristic</title>
<para>The <literal>xa-heuristic</literal> example shows you how to make an XA heuristic <para>The <literal>xa-heuristic</literal> example shows you how to make an XA heuristic
decision through HornetQ Management Interface. A heuristic decision is a unilateral decision through ActiveMQ Management Interface. A heuristic decision is a unilateral
decision to commit or rollback an XA transaction branch after it has been decision to commit or rollback an XA transaction branch after it has been
prepared.</para> prepared.</para>
</section> </section>
<section> <section>
<title>XA Receive</title> <title>XA Receive</title>
<para>The <literal>xa-receive</literal> example shows you how message receiving behaves <para>The <literal>xa-receive</literal> example shows you how message receiving behaves
in an XA transaction in HornetQ.</para> in an XA transaction in ActiveMQ.</para>
</section> </section>
<section> <section>
<title>XA Send</title> <title>XA Send</title>
<para>The <literal>xa-send</literal> example shows you how message sending behaves in an <para>The <literal>xa-send</literal> example shows you how message sending behaves in an
XA transaction in HornetQ.</para> XA transaction in ActiveMQ.</para>
</section> </section>
<section> <section>
<title>XA with Transaction Manager</title> <title>XA with Transaction Manager</title>
<para>The <literal>xa-with-jta</literal> example shows you how to use JTA interfaces to <para>The <literal>xa-with-jta</literal> example shows you how to use JTA interfaces to
control transactions with HornetQ.</para> control transactions with ActiveMQ.</para>
</section> </section>
</section> </section>
<section> <section>
@ -641,7 +641,7 @@
directory and type <literal>ant</literal></para> directory and type <literal>ant</literal></para>
<section id="examples.embedded"> <section id="examples.embedded">
<title>Embedded</title> <title>Embedded</title>
<para>The <literal>embedded</literal> example shows how to embed the HornetQ server <para>The <literal>embedded</literal> example shows how to embed the ActiveMQ server
within your own code.</para> within your own code.</para>
</section> </section>
</section> </section>
@ -653,8 +653,8 @@
variable set. Please refer to the examples documentation for further instructions.</para> variable set. Please refer to the examples documentation for further instructions.</para>
<note> <note>
<para>When running the Java EE examples you may see warning messages in the WildFly log about incompatible client and <para>When running the Java EE examples you may see warning messages in the WildFly log about incompatible client and
server versions. This is normal if a newer version of the HornetQ project is being used with a version of WildFly that server versions. This is normal if a newer version of the ActiveMQ project is being used with a version of WildFly that
ships an older version of HornetQ. These examples should still complete without any functional errors.</para> ships an older version of ActiveMQ. These examples should still complete without any functional errors.</para>
</note> </note>
<section> <section>
<title>EJB/JMS Transaction</title> <title>EJB/JMS Transaction</title>
@ -662,16 +662,16 @@
</section> </section>
<section> <section>
<title>Resource Adapter Configuration</title> <title>Resource Adapter Configuration</title>
<para>This example demonstrates how to configure several properties on the HornetQ JCA <para>This example demonstrates how to configure several properties on the ActiveMQ JCA
resource adaptor.</para> resource adaptor.</para>
</section> </section>
<section> <section>
<title>Resource Adapter Remote Server Configuration</title> <title>Resource Adapter Remote Server Configuration</title>
<para>This example demonstrates how to configure the HornetQ resource adapter to talk to a remote HornetQ server</para> <para>This example demonstrates how to configure the ActiveMQ resource adapter to talk to a remote ActiveMQ server</para>
</section> </section>
<section id="examples.javaee.jms-bridge"> <section id="examples.javaee.jms-bridge">
<title>JMS Bridge</title> <title>JMS Bridge</title>
<para>An example demonstrating the use of the HornetQ JMS bridge.</para> <para>An example demonstrating the use of the ActiveMQ JMS bridge.</para>
</section> </section>
<section> <section>
<title>MDB (Message Driven Bean)</title> <title>MDB (Message Driven Bean)</title>
@ -679,16 +679,16 @@
</section> </section>
<section> <section>
<title>Servlet Transport</title> <title>Servlet Transport</title>
<para>An example of how to use the HornetQ servlet transport.</para> <para>An example of how to use the ActiveMQ servlet transport.</para>
</section> </section>
<section> <section>
<title>Servlet SSL Transport</title> <title>Servlet SSL Transport</title>
<para>An example of how to use the HornetQ servlet transport over SSL.</para> <para>An example of how to use the ActiveMQ servlet transport over SSL.</para>
</section> </section>
<section id="xa-recovery-example"> <section id="xa-recovery-example">
<title>XA Recovery</title> <title>XA Recovery</title>
<para>An example of how XA recovery works within the JBoss Application server using <para>An example of how XA recovery works within the JBoss Application server using
HornetQ.</para> ActiveMQ.</para>
</section> </section>
</section> </section>
</chapter> </chapter>

12
docs/user-manual/en/filter-expressions.xml
View File

@ -19,23 +19,23 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="filter-expressions"> <chapter id="filter-expressions">
<title>Filter Expressions</title> <title>Filter Expressions</title>
<para>HornetQ provides a powerful filter language based on a subset of the SQL 92 <para>ActiveMQ provides a powerful filter language based on a subset of the SQL 92
expression syntax.</para> expression syntax.</para>
<para>It is the same as the syntax used for JMS selectors, but the predefined identifiers are <para>It is the same as the syntax used for JMS selectors, but the predefined identifiers are
different. For documentation on JMS selector syntax please the JMS javadoc for <ulink different. For documentation on JMS selector syntax please the JMS javadoc for <ulink
url="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html" url="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html"
>javax.jms.Message</ulink>.</para> >javax.jms.Message</ulink>.</para>
<para>Filter expressions are used in several places in HornetQ</para> <para>Filter expressions are used in several places in ActiveMQ</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Predefined Queues. When pre-defining a queue, either in <literal <para>Predefined Queues. When pre-defining a queue, either in <literal
>hornetq-configuration.xml</literal> or <literal>hornetq-jms.xml</literal> a filter >activemq-configuration.xml</literal> or <literal>activemq-jms.xml</literal> a filter
expression can be defined for a queue. Only messages that match the filter expression can be defined for a queue. Only messages that match the filter
expression will enter the queue.</para> expression will enter the queue.</para>
</listitem> </listitem>
@ -52,8 +52,8 @@
several places as described in <xref linkend="management"/>.</para> several places as described in <xref linkend="management"/>.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>There are some differences between JMS selector expressions and HornetQ core <para>There are some differences between JMS selector expressions and ActiveMQ core
filter expressions. Whereas JMS selector expressions operate on a JMS message, HornetQ filter expressions. Whereas JMS selector expressions operate on a JMS message, ActiveMQ
core filter expressions operate on a core message.</para> core filter expressions operate on a core message.</para>
<para>The following identifiers can be used in a core filter expressions to refer to attributes <para>The following identifiers can be used in a core filter expressions to refer to attributes
of the core message in an expression:</para> of the core message in an expression:</para>

44
docs/user-manual/en/flow-control.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="flow-control"> <chapter id="flow-control">
@ -36,14 +36,14 @@
in time.</para> in time.</para>
<section id="flow-control.consumer.window"> <section id="flow-control.consumer.window">
<title>Window-Based Flow Control</title> <title>Window-Based Flow Control</title>
<para>By default, HornetQ consumers buffer messages from the server in a client side buffer <para>By default, ActiveMQ consumers buffer messages from the server in a client side buffer
before the client consumes them. This improves performance: otherwise every time the before the client consumes them. This improves performance: otherwise every time the
client consumes a message, HornetQ would have to go the server to request the next client consumes a message, ActiveMQ would have to go the server to request the next
message. In turn, this message would then get sent to the client side, if one was message. In turn, this message would then get sent to the client side, if one was
available.</para> available.</para>
<para>A network round trip would be involved for <emphasis>every</emphasis> message and <para>A network round trip would be involved for <emphasis>every</emphasis> message and
considerably reduce performance.</para> considerably reduce performance.</para>
<para>To prevent this, HornetQ pre-fetches messages into a buffer on each consumer. The <para>To prevent this, ActiveMQ pre-fetches messages into a buffer on each consumer. The
total maximum size of messages (in bytes) that will be buffered on each consumer is total maximum size of messages (in bytes) that will be buffered on each consumer is
determined by the <literal>consumer-window-size</literal> parameter.</para> determined by the <literal>consumer-window-size</literal> parameter.</para>
<para>By default, the <literal>consumer-window-size</literal> is set to 1 MiB (1024 * 1024 <para>By default, the <literal>consumer-window-size</literal> is set to 1 MiB (1024 * 1024
@ -106,14 +106,14 @@
find the optimal value, but a value of 1MiB is fine in most cases.</para> find the optimal value, but a value of 1MiB is fine in most cases.</para>
<section id="flow-control.core.api"> <section id="flow-control.core.api">
<title>Using Core API</title> <title>Using Core API</title>
<para>If HornetQ Core API is used, the consumer window size is specified by <literal <para>If ActiveMQ Core API is used, the consumer window size is specified by <literal
>ServerLocator.setConsumerWindowSize()</literal> method and some of the >ServerLocator.setConsumerWindowSize()</literal> method and some of the
<literal>ClientSession.createConsumer()</literal> methods.</para> <literal>ClientSession.createConsumer()</literal> methods.</para>
</section> </section>
<section> <section>
<title>Using JMS</title> <title>Using JMS</title>
<para>if JNDI is used to look up the connection factory, the consumer window size is <para>if JNDI is used to look up the connection factory, the consumer window size is
configured in <literal>hornetq-jms.xml</literal>:</para> configured in <literal>activemq-jms.xml</literal>:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;connectors> &lt;connectors>
@ -127,10 +127,10 @@
&lt;consumer-window-size>0&lt;/consumer-window-size> &lt;consumer-window-size>0&lt;/consumer-window-size>
&lt;/connection-factory></programlisting> &lt;/connection-factory></programlisting>
<para>If the connection factory is directly instantiated, the consumer window size is <para>If the connection factory is directly instantiated, the consumer window size is
specified by <literal>HornetQConnectionFactory.setConsumerWindowSize()</literal> specified by <literal>ActiveMQConnectionFactory.setConsumerWindowSize()</literal>
method.</para> method.</para>
<para>Please see <xref linkend="examples.no-consumer-buffering"/> for an example which <para>Please see <xref linkend="examples.no-consumer-buffering"/> for an example which
shows how to configure HornetQ to prevent consumer buffering when dealing with slow shows how to configure ActiveMQ to prevent consumer buffering when dealing with slow
consumers.</para> consumers.</para>
</section> </section>
</section> </section>
@ -147,7 +147,7 @@
limiting consumer rate.</para> limiting consumer rate.</para>
<section id="flow-control.rate.core.api"> <section id="flow-control.rate.core.api">
<title>Using Core API</title> <title>Using Core API</title>
<para>If the HornetQ core API is being used the rate can be set via the <literal <para>If the ActiveMQ core API is being used the rate can be set via the <literal
>ServerLocator.setConsumerMaxRate(int consumerMaxRate)</literal> method or >ServerLocator.setConsumerMaxRate(int consumerMaxRate)</literal> method or
alternatively via some of the <literal>ClientSession.createConsumer()</literal> alternatively via some of the <literal>ClientSession.createConsumer()</literal>
methods. </para> methods. </para>
@ -155,7 +155,7 @@
<section> <section>
<title>Using JMS</title> <title>Using JMS</title>
<para>If JNDI is used to look up the connection factory, the max rate can be configured <para>If JNDI is used to look up the connection factory, the max rate can be configured
in <literal>hornetq-jms.xml</literal>:</para> in <literal>activemq-jms.xml</literal>:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;connectors> &lt;connectors>
@ -169,7 +169,7 @@
&lt;consumer-max-rate>10&lt;/consumer-max-rate> &lt;consumer-max-rate>10&lt;/consumer-max-rate>
&lt;/connection-factory></programlisting> &lt;/connection-factory></programlisting>
<para>If the connection factory is directly instantiated, the max rate size can be set <para>If the connection factory is directly instantiated, the max rate size can be set
via the <literal>HornetQConnectionFactory.setConsumerMaxRate(int via the <literal>ActiveMQConnectionFactory.setConsumerMaxRate(int
consumerMaxRate)</literal> method.</para> consumerMaxRate)</literal> method.</para>
<note> <note>
<para>Rate limited flow control can be used in conjunction with window based flow <para>Rate limited flow control can be used in conjunction with window based flow
@ -179,18 +179,18 @@
soon fill up with messages.</para> soon fill up with messages.</para>
</note> </note>
<para>Please see <xref linkend="examples.consumer-rate-limit"/> for an example which <para>Please see <xref linkend="examples.consumer-rate-limit"/> for an example which
shows how to configure HornetQ to prevent consumer buffering when dealing with slow shows how to configure ActiveMQ to prevent consumer buffering when dealing with slow
consumers.</para> consumers.</para>
</section> </section>
</section> </section>
</section> </section>
<section> <section>
<title>Producer flow control</title> <title>Producer flow control</title>
<para>HornetQ also can limit the amount of data sent from a client to a server to prevent the <para>ActiveMQ also can limit the amount of data sent from a client to a server to prevent the
server being overwhelmed.</para> server being overwhelmed.</para>
<section> <section>
<title>Window based flow control</title> <title>Window based flow control</title>
<para>In a similar way to consumer window based flow control, HornetQ producers, by <para>In a similar way to consumer window based flow control, ActiveMQ producers, by
default, can only send messages to an address as long as they have sufficient credits to default, can only send messages to an address as long as they have sufficient credits to
do so. The amount of credits required to send a message is given by the size of the do so. The amount of credits required to send a message is given by the size of the
message.</para> message.</para>
@ -203,14 +203,14 @@
getting overloaded.</para> getting overloaded.</para>
<section> <section>
<title>Using Core API</title> <title>Using Core API</title>
<para>If the HornetQ core API is being used, window size can be set via the <literal <para>If the ActiveMQ core API is being used, window size can be set via the <literal
>ServerLocator.setProducerWindowSize(int producerWindowSize)</literal> >ServerLocator.setProducerWindowSize(int producerWindowSize)</literal>
method.</para> method.</para>
</section> </section>
<section> <section>
<title>Using JMS</title> <title>Using JMS</title>
<para>If JNDI is used to look up the connection factory, the producer window size can be <para>If JNDI is used to look up the connection factory, the producer window size can be
configured in <literal>hornetq-jms.xml</literal>:</para> configured in <literal>activemq-jms.xml</literal>:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;connectors> &lt;connectors>
@ -222,7 +222,7 @@
&lt;producer-window-size>10&lt;/producer-window-size> &lt;producer-window-size>10&lt;/producer-window-size>
&lt;/connection-factory></programlisting> &lt;/connection-factory></programlisting>
<para>If the connection factory is directly instantiated, the producer window size can <para>If the connection factory is directly instantiated, the producer window size can
be set via the <literal>HornetQConnectionFactory.setProducerWindowSize(int be set via the <literal>ActiveMQConnectionFactory.setProducerWindowSize(int
producerWindowSize)</literal> method.</para> producerWindowSize)</literal> method.</para>
</section> </section>
<section> <section>
@ -275,8 +275,8 @@
</section> </section>
<section> <section>
<title>Rate limited flow control</title> <title>Rate limited flow control</title>
<para>HornetQ also allows the rate a producer can emit message to be limited, in units of <para>ActiveMQ also allows the rate a producer can emit message to be limited, in units of
messages per second. By specifying such a rate, HornetQ will ensure that producer never messages per second. By specifying such a rate, ActiveMQ will ensure that producer never
produces messages at a rate higher than that specified.</para> produces messages at a rate higher than that specified.</para>
<para>The rate must be a positive integer to enable this functionality and is the maximum <para>The rate must be a positive integer to enable this functionality and is the maximum
desired message consumption rate specified in units of messages per second. Setting this desired message consumption rate specified in units of messages per second. Setting this
@ -286,7 +286,7 @@
of limiting producer rate.</para> of limiting producer rate.</para>
<section id="flow-control.producer.rate.core.api"> <section id="flow-control.producer.rate.core.api">
<title>Using Core API</title> <title>Using Core API</title>
<para>If the HornetQ core API is being used the rate can be set via the <literal <para>If the ActiveMQ core API is being used the rate can be set via the <literal
>ServerLocator.setProducerMaxRate(int consumerMaxRate)</literal> method or >ServerLocator.setProducerMaxRate(int consumerMaxRate)</literal> method or
alternatively via some of the <literal>ClientSession.createProducer()</literal> alternatively via some of the <literal>ClientSession.createProducer()</literal>
methods. </para> methods. </para>
@ -294,7 +294,7 @@
<section> <section>
<title>Using JMS</title> <title>Using JMS</title>
<para>If JNDI is used to look up the connection factory, the max rate can be configured <para>If JNDI is used to look up the connection factory, the max rate can be configured
in <literal>hornetq-jms.xml</literal>:</para> in <literal>activemq-jms.xml</literal>:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;connectors> &lt;connectors>
@ -308,7 +308,7 @@
&lt;producer-max-rate>10&lt;/producer-max-rate> &lt;producer-max-rate>10&lt;/producer-max-rate>
&lt;/connection-factory></programlisting> &lt;/connection-factory></programlisting>
<para>If the connection factory is directly instantiated, the max rate size can be set <para>If the connection factory is directly instantiated, the max rate size can be set
via the <literal>HornetQConnectionFactory.setProducerMaxRate(int via the <literal>ActiveMQConnectionFactory.setProducerMaxRate(int
consumerMaxRate)</literal> method.</para> consumerMaxRate)</literal> method.</para>
</section> </section>
</section> </section>

50
docs/user-manual/en/ha.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="ha"> <chapter id="ha">
@ -33,13 +33,13 @@
<section> <section>
<title>Live - Backup Groups</title> <title>Live - Backup Groups</title>
<para>HornetQ allows servers to be linked together as <emphasis>live - backup</emphasis> <para>ActiveMQ allows servers to be linked together as <emphasis>live - backup</emphasis>
groups where each live server can have 1 or more backup servers. A backup server is owned by groups where each live server can have 1 or more backup servers. A backup server is owned by
only one live server. Backup servers are not operational until failover occurs, however 1 only one live server. Backup servers are not operational until failover occurs, however 1
chosen backup, which will be in passive mode, announces its status and waits to take over chosen backup, which will be in passive mode, announces its status and waits to take over
the live servers work</para> the live servers work</para>
<para>Before failover, only the live server is serving the HornetQ clients while the backup <para>Before failover, only the live server is serving the ActiveMQ clients while the backup
servers remain passive or awaiting to become a backup server. When a live server crashes or servers remain passive or awaiting to become a backup server. When a live server crashes or
is brought down in the correct mode, the backup server currently in passive mode will become is brought down in the correct mode, the backup server currently in passive mode will become
live and another backup server will become passive. If a live server restarts after a live and another backup server will become passive. If a live server restarts after a
@ -49,7 +49,7 @@
<section id="ha.policies"> <section id="ha.policies">
<title>HA Policies</title> <title>HA Policies</title>
<para>HornetQ supports two different strategies for backing up a server <emphasis>shared <para>ActiveMQ supports two different strategies for backing up a server <emphasis>shared
store</emphasis> and <emphasis>replication</emphasis>. Which is configured via the store</emphasis> and <emphasis>replication</emphasis>. Which is configured via the
<literal>ha-policy</literal> configuration element.</para> <literal>ha-policy</literal> configuration element.</para>
<programlisting> <programlisting>
@ -73,7 +73,7 @@
<note> <note>
<para> <para>
The <literal>ha-policy</literal> configurations replaces any current HA configuration in the root of the The <literal>ha-policy</literal> configurations replaces any current HA configuration in the root of the
<literal>hornetq-configuration.xml</literal> configuration. All old configuration is now deprecated altho <literal>activemq-configuration.xml</literal> configuration. All old configuration is now deprecated altho
best efforts will be made to honour it if configured this way. best efforts will be made to honour it if configured this way.
</para> </para>
</note> </note>
@ -162,7 +162,7 @@
<para><literal>specifying a node group</literal>. You can specify a group of live servers that a backup <para><literal>specifying a node group</literal>. You can specify a group of live servers that a backup
server can connect to. This is done by configuring <literal>group-name</literal> in either the <literal>master</literal> server can connect to. This is done by configuring <literal>group-name</literal> in either the <literal>master</literal>
or the <literal>slave</literal> element of the or the <literal>slave</literal> element of the
<literal>hornetq-configuration.xml</literal>. A Backup server will only connect to a live server that <literal>activemq-configuration.xml</literal>. A Backup server will only connect to a live server that
shares the same node group name</para> shares the same node group name</para>
</listitem> </listitem>
<listitem> <listitem>
@ -226,7 +226,7 @@
<title>Configuration</title> <title>Configuration</title>
<para>To configure the live and backup servers to be a replicating pair, configure <para>To configure the live and backup servers to be a replicating pair, configure
the live server in ' <literal>hornetq-configuration.xml</literal> to have:</para> the live server in ' <literal>activemq-configuration.xml</literal> to have:</para>
<programlisting> <programlisting>
&lt;ha-policy> &lt;ha-policy>
@ -362,7 +362,7 @@
<section id="ha/mode.shared.configuration"> <section id="ha/mode.shared.configuration">
<title>Configuration</title> <title>Configuration</title>
<para>To configure the live and backup servers to share their store, configure <para>To configure the live and backup servers to share their store, configure
id via the <literal>ha-policy</literal> configuration in <literal>hornetq-configuration.xml</literal>:</para> id via the <literal>ha-policy</literal> configuration in <literal>activemq-configuration.xml</literal>:</para>
<programlisting> <programlisting>
&lt;ha-policy> &lt;ha-policy>
&lt;shared-store> &lt;shared-store>
@ -427,7 +427,7 @@
request the other server (which it assumes it is a back that has assumed its duties) to shutdown for it to request the other server (which it assumes it is a back that has assumed its duties) to shutdown for it to
take over. This is necessary because otherwise the live server has no means to know whether there was a take over. This is necessary because otherwise the live server has no means to know whether there was a
fail-over or not, and if there was if the server that took its duties is still running or not. fail-over or not, and if there was if the server that took its duties is still running or not.
To configure this option at your <literal>hornetq-configuration.xml</literal> configuration file as follows:</para> To configure this option at your <literal>activemq-configuration.xml</literal> configuration file as follows:</para>
<programlisting> <programlisting>
&lt;ha-policy> &lt;ha-policy>
&lt;replication> &lt;replication>
@ -459,7 +459,7 @@
API as explained at <xref linkend="management.core.server"/></para> API as explained at <xref linkend="management.core.server"/></para>
<para>You can also force the running live server to shutdown when the old live server comes back up allowing <para>You can also force the running live server to shutdown when the old live server comes back up allowing
the original live server to take over automatically by setting the following property in the the original live server to take over automatically by setting the following property in the
<literal>hornetq-configuration.xml</literal> configuration file as follows:</para> <literal>activemq-configuration.xml</literal> configuration file as follows:</para>
<programlisting> <programlisting>
&lt;ha-policy> &lt;ha-policy>
&lt;shared-store> &lt;shared-store>
@ -550,7 +550,7 @@
and its Connectors and Acceptors which are discussed later on in this chapter. A live server can also and its Connectors and Acceptors which are discussed later on in this chapter. A live server can also
be configured to allow requests from backups and also how many backups a live server can start. this way be configured to allow requests from backups and also how many backups a live server can start. this way
you can evenly distribute backups around the cluster. This is configured via the <literal>ha-policy</literal> you can evenly distribute backups around the cluster. This is configured via the <literal>ha-policy</literal>
element in the <literal>hornetq-configuration.xml</literal> file like so:</para> element in the <literal>activemq-configuration.xml</literal> file like so:</para>
<programlisting> <programlisting>
&lt;ha-policy> &lt;ha-policy>
&lt;replication> &lt;replication>
@ -741,7 +741,7 @@
</section> </section>
<section id="failover"> <section id="failover">
<title>Failover Modes</title> <title>Failover Modes</title>
<para>HornetQ defines two types of client failover:</para> <para>ActiveMQ defines two types of client failover:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Automatic client failover</para> <para>Automatic client failover</para>
@ -750,7 +750,7 @@
<para>Application-level client failover</para> <para>Application-level client failover</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>HornetQ also provides 100% transparent automatic reattachment of connections to the <para>ActiveMQ also provides 100% transparent automatic reattachment of connections to the
same server (e.g. in case of transient network problems). This is similar to failover, same server (e.g. in case of transient network problems). This is similar to failover,
except it is reconnecting to the same server and is discussed in except it is reconnecting to the same server and is discussed in
<xref linkend="client-reconnection"/></para> <xref linkend="client-reconnection"/></para>
@ -759,20 +759,20 @@
since the backup node will not have any knowledge of non persistent queues.</para> since the backup node will not have any knowledge of non persistent queues.</para>
<section id="ha.automatic.failover"> <section id="ha.automatic.failover">
<title>Automatic Client Failover</title> <title>Automatic Client Failover</title>
<para>HornetQ clients can be configured to receive knowledge of all live and backup servers, so <para>ActiveMQ clients can be configured to receive knowledge of all live and backup servers, so
that in event of connection failure at the client - live server connection, the that in event of connection failure at the client - live server connection, the
client will detect this and reconnect to the backup server. The backup server will client will detect this and reconnect to the backup server. The backup server will
then automatically recreate any sessions and consumers that existed on each then automatically recreate any sessions and consumers that existed on each
connection before failover, thus saving the user from having to hand-code manual connection before failover, thus saving the user from having to hand-code manual
reconnection logic.</para> reconnection logic.</para>
<para>HornetQ clients detect connection failure when it has not received packets from <para>ActiveMQ clients detect connection failure when it has not received packets from
the server within the time given by <literal>client-failure-check-period</literal> the server within the time given by <literal>client-failure-check-period</literal>
as explained in section <xref linkend="connection-ttl"/>. If the client does not as explained in section <xref linkend="connection-ttl"/>. If the client does not
receive data in good time, it will assume the connection has failed and attempt receive data in good time, it will assume the connection has failed and attempt
failover. Also if the socket is closed by the OS, usually if the server process is failover. Also if the socket is closed by the OS, usually if the server process is
killed rather than the machine itself crashing, then the client will failover straight away. killed rather than the machine itself crashing, then the client will failover straight away.
</para> </para>
<para>HornetQ clients can be configured to discover the list of live-backup server groups in a <para>ActiveMQ clients can be configured to discover the list of live-backup server groups in a
number of different ways. They can be configured explicitly or probably the most number of different ways. They can be configured explicitly or probably the most
common way of doing this is to use <emphasis>server discovery</emphasis> for the common way of doing this is to use <emphasis>server discovery</emphasis> for the
client to automatically discover the list. For full details on how to configure client to automatically discover the list. For full details on how to configure
@ -794,7 +794,7 @@
connection is made there is a window where it does not know about the backup. If a failure happens at connection is made there is a window where it does not know about the backup. If a failure happens at
this point the client can only try reconnecting to the original live server. To configure this point the client can only try reconnecting to the original live server. To configure
how many attempts the client will make you can set the property <literal>initialConnectAttempts</literal> how many attempts the client will make you can set the property <literal>initialConnectAttempts</literal>
on the <literal>ClientSessionFactoryImpl</literal> or <literal >HornetQConnectionFactory</literal> or on the <literal>ClientSessionFactoryImpl</literal> or <literal >ActiveMQConnectionFactory</literal> or
<literal>initial-connect-attempts</literal> in xml. The default for this is <literal>0</literal>, that <literal>initial-connect-attempts</literal> in xml. The default for this is <literal>0</literal>, that
is try only once. Once the number of attempts has been made an exception will be thrown. is try only once. Once the number of attempts has been made an exception will be thrown.
</para> </para>
@ -804,7 +804,7 @@
linkend="examples.non-transaction-failover"/>.</para> linkend="examples.non-transaction-failover"/>.</para>
<section id="ha.automatic.failover.noteonreplication"> <section id="ha.automatic.failover.noteonreplication">
<title>A Note on Server Replication</title> <title>A Note on Server Replication</title>
<para>HornetQ does not replicate full server state between live and backup servers. <para>ActiveMQ does not replicate full server state between live and backup servers.
When the new session is automatically recreated on the backup it won't have any When the new session is automatically recreated on the backup it won't have any
knowledge of messages already sent or acknowledged in that session. Any knowledge of messages already sent or acknowledged in that session. Any
in-flight sends or acknowledgements at the time of failover might also be in-flight sends or acknowledgements at the time of failover might also be
@ -838,14 +838,14 @@
to continue its execution, when failover occurs, the new session will not have to continue its execution, when failover occurs, the new session will not have
any knowledge of the call that was in progress. This call might otherwise hang any knowledge of the call that was in progress. This call might otherwise hang
for ever, waiting for a response that will never come.</para> for ever, waiting for a response that will never come.</para>
<para>To prevent this, HornetQ will unblock any blocking calls that were in progress <para>To prevent this, ActiveMQ will unblock any blocking calls that were in progress
at the time of failover by making them throw a <literal at the time of failover by making them throw a <literal
>javax.jms.JMSException</literal> (if using JMS), or a <literal >javax.jms.JMSException</literal> (if using JMS), or a <literal
>ActiveMQException</literal> with error code <literal >ActiveMQException</literal> with error code <literal
>ActiveMQException.UNBLOCKED</literal>. It is up to the client code to catch >ActiveMQException.UNBLOCKED</literal>. It is up to the client code to catch
this exception and retry any operations if desired.</para> this exception and retry any operations if desired.</para>
<para>If the method being unblocked is a call to commit(), or prepare(), then the <para>If the method being unblocked is a call to commit(), or prepare(), then the
transaction will be automatically rolled back and HornetQ will throw a <literal transaction will be automatically rolled back and ActiveMQ will throw a <literal
>javax.jms.TransactionRolledBackException</literal> (if using JMS), or a >javax.jms.TransactionRolledBackException</literal> (if using JMS), or a
<literal>ActiveMQException</literal> with error code <literal <literal>ActiveMQException</literal> with error code <literal
>ActiveMQException.TRANSACTION_ROLLED_BACK</literal> if using the core >ActiveMQException.TRANSACTION_ROLLED_BACK</literal> if using the core
@ -879,7 +879,7 @@
rollback code as necessary. There is no need to manually rollback the session - rollback code as necessary. There is no need to manually rollback the session -
it is already rolled back. The user can then just retry the transactional it is already rolled back. The user can then just retry the transactional
operations again on the same session.</para> operations again on the same session.</para>
<para>HornetQ ships with a fully functioning example demonstrating how to do this, <para>ActiveMQ ships with a fully functioning example demonstrating how to do this,
please see <xref linkend="examples.transaction-failover"/></para> please see <xref linkend="examples.transaction-failover"/></para>
<para>If failover occurs when a commit call is being executed, the server, as <para>If failover occurs when a commit call is being executed, the server, as
previously described, will unblock the call to prevent a hang, since no response previously described, will unblock the call to prevent a hang, since no response
@ -925,10 +925,10 @@
connection failure: <literal>java.jms.ExceptionListener</literal>. Please consult connection failure: <literal>java.jms.ExceptionListener</literal>. Please consult
the JMS javadoc or any good JMS tutorial for more information on how to use the JMS javadoc or any good JMS tutorial for more information on how to use
this.</para> this.</para>
<para>The HornetQ core API also provides a similar feature in the form of the class <para>The ActiveMQ core API also provides a similar feature in the form of the class
<literal>org.hornet.core.client.SessionFailureListener</literal></para> <literal>org.apache.activemq.core.client.SessionFailureListener</literal></para>
<para>Any ExceptionListener or SessionFailureListener instance will always be called by <para>Any ExceptionListener or SessionFailureListener instance will always be called by
HornetQ on event of connection failure, <emphasis role="bold" ActiveMQ on event of connection failure, <emphasis role="bold"
>irrespective</emphasis> of whether the connection was successfully failed over, >irrespective</emphasis> of whether the connection was successfully failed over,
reconnected or reattached, however you can find out if reconnect or reattach has happened reconnected or reattached, however you can find out if reconnect or reattach has happened
by either the <literal>failedOver</literal> flag passed in on the <literal>connectionFailed</literal> by either the <literal>failedOver</literal> flag passed in on the <literal>connectionFailed</literal>
@ -970,7 +970,7 @@
failover, since the failover is handled at the user application level.</para> failover, since the failover is handled at the user application level.</para>
<para>To implement application-level failover, if you're using JMS then you need to set <para>To implement application-level failover, if you're using JMS then you need to set
an <literal>ExceptionListener</literal> class on the JMS connection. The an <literal>ExceptionListener</literal> class on the JMS connection. The
<literal>ExceptionListener</literal> will be called by HornetQ in the event that <literal>ExceptionListener</literal> will be called by ActiveMQ in the event that
connection failure is detected. In your <literal>ExceptionListener</literal>, you connection failure is detected. In your <literal>ExceptionListener</literal>, you
would close your old JMS connections, potentially look up new connection factory would close your old JMS connections, potentially look up new connection factory
instances from JNDI and creating new connections. In this case you may well be using instances from JNDI and creating new connections. In this case you may well be using

BIN
docs/user-manual/en/images/hornetQ-banner_final.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 107 KiB

BIN
docs/user-manual/en/images/hornetQ_logo_600px.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 23 KiB

6
docs/user-manual/en/intercepting-operations.xml
View File

@ -19,13 +19,13 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="intercepting-operations"> <chapter id="intercepting-operations">
<title>Intercepting Operations</title> <title>Intercepting Operations</title>
<para>HornetQ supports <emphasis>interceptors</emphasis> to intercept packets entering <para>ActiveMQ supports <emphasis>interceptors</emphasis> to intercept packets entering
and exiting the server. Incoming and outgoing interceptors are be called for any packet and exiting the server. Incoming and outgoing interceptors are be called for any packet
entering or exiting the server respectively. This allows custom code to be executed, entering or exiting the server respectively. This allows custom code to be executed,
e.g. for auditing packets, filtering or other reasons. Interceptors can change the e.g. for auditing packets, filtering or other reasons. Interceptors can change the
@ -55,7 +55,7 @@ public interface Interceptor
<section> <section>
<title>Configuring The Interceptors</title> <title>Configuring The Interceptors</title>
<para>Both incoming and outgoing interceptors are configured in <para>Both incoming and outgoing interceptors are configured in
<literal>hornetq-configuration.xml</literal>:</para> <literal>activemq-configuration.xml</literal>:</para>
<programlisting> <programlisting>
&lt;remoting-incoming-interceptors> &lt;remoting-incoming-interceptors>
&lt;class-name>org.apache.activemq.jms.example.LoginInterceptor&lt;/class-name> &lt;class-name>org.apache.activemq.jms.example.LoginInterceptor&lt;/class-name>

74
docs/user-manual/en/interoperability.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="interoperability"> <chapter id="interoperability">
@ -26,12 +26,12 @@
<section id="stomp"> <section id="stomp">
<title>Stomp</title> <title>Stomp</title>
<para><ulink url="http://stomp.github.com/">Stomp</ulink> is a text-orientated wire protocol that allows <para><ulink url="http://stomp.github.com/">Stomp</ulink> is a text-orientated wire protocol that allows
Stomp clients to communicate with Stomp Brokers. HornetQ now supports Stomp 1.0, 1.1 and 1.2.</para> Stomp clients to communicate with Stomp Brokers. ActiveMQ now supports Stomp 1.0, 1.1 and 1.2.</para>
<para>Stomp clients are available for <para>Stomp clients are available for
several languages and platforms making it a good choice for interoperability.</para> several languages and platforms making it a good choice for interoperability.</para>
<section id="stomp.native"> <section id="stomp.native">
<title>Native Stomp support</title> <title>Native Stomp support</title>
<para>HornetQ provides native support for Stomp. To be able to send and receive Stomp messages, <para>ActiveMQ provides native support for Stomp. To be able to send and receive Stomp messages,
you must configure a <literal>NettyAcceptor</literal> with a <literal>protocols</literal> you must configure a <literal>NettyAcceptor</literal> with a <literal>protocols</literal>
parameter set to have <literal>stomp</literal>:</para> parameter set to have <literal>stomp</literal>:</para>
<programlisting> <programlisting>
@ -40,9 +40,9 @@
&lt;param key="protocols" value="STOMP"/> &lt;param key="protocols" value="STOMP"/>
&lt;param key="port" value="61613"/> &lt;param key="port" value="61613"/>
&lt;/acceptor></programlisting> &lt;/acceptor></programlisting>
<para>With this configuration, HornetQ will accept Stomp connections on <para>With this configuration, ActiveMQ will accept Stomp connections on
the port <literal>61613</literal> (which is the default port of the Stomp brokers).</para> the port <literal>61613</literal> (which is the default port of the Stomp brokers).</para>
<para>See the <literal>stomp</literal> example which shows how to configure a HornetQ server with Stomp.</para> <para>See the <literal>stomp</literal> example which shows how to configure a ActiveMQ server with Stomp.</para>
<section> <section>
<title>Limitations</title> <title>Limitations</title>
<para>Message acknowledgements are not transactional. The ACK frame can not be part of a transaction <para>Message acknowledgements are not transactional. The ACK frame can not be part of a transaction
@ -52,12 +52,12 @@
<title>Stomp 1.1/1.2 Notes</title> <title>Stomp 1.1/1.2 Notes</title>
<section> <section>
<title>Virtual Hosting</title> <title>Virtual Hosting</title>
<para>HornetQ currently doesn't support virtual hosting, which means the 'host' header <para>ActiveMQ currently doesn't support virtual hosting, which means the 'host' header
in CONNECT fram will be ignored.</para> in CONNECT fram will be ignored.</para>
</section> </section>
<section> <section>
<title>Heart-beating</title> <title>Heart-beating</title>
<para>HornetQ specifies a minimum value for both client and server heart-beat intervals. <para>ActiveMQ specifies a minimum value for both client and server heart-beat intervals.
The minimum interval for both client and server heartbeats is 500 milliseconds. That means if The minimum interval for both client and server heartbeats is 500 milliseconds. That means if
a client sends a CONNECT frame with heartbeat values lower than 500, the server will defaults a client sends a CONNECT frame with heartbeat values lower than 500, the server will defaults
the value to 500 milliseconds regardless the values of the 'heart-beat' header in the frame.</para> the value to 500 milliseconds regardless the values of the 'heart-beat' header in the frame.</para>
@ -66,15 +66,15 @@
</section> </section>
<section> <section>
<title>Mapping Stomp destinations to HornetQ addresses and queues</title> <title>Mapping Stomp destinations to ActiveMQ addresses and queues</title>
<para>Stomp clients deals with <emphasis>destinations</emphasis> when sending messages and subscribing. <para>Stomp clients deals with <emphasis>destinations</emphasis> when sending messages and subscribing.
Destination names are simply strings which are mapped to some form of destination on the Destination names are simply strings which are mapped to some form of destination on the
server - how the server translates these is left to the server implementation.</para> server - how the server translates these is left to the server implementation.</para>
<para>In HornetQ, these destinations are mapped to <emphasis>addresses</emphasis> and <emphasis>queues</emphasis>. <para>In ActiveMQ, these destinations are mapped to <emphasis>addresses</emphasis> and <emphasis>queues</emphasis>.
When a Stomp client sends a message (using a <literal>SEND</literal> frame), the specified destination is mapped When a Stomp client sends a message (using a <literal>SEND</literal> frame), the specified destination is mapped
to an address. to an address.
When a Stomp client subscribes (or unsubscribes) for a destination (using a <literal>SUBSCRIBE</literal> When a Stomp client subscribes (or unsubscribes) for a destination (using a <literal>SUBSCRIBE</literal>
or <literal>UNSUBSCRIBE</literal> frame), the destination is mapped to a HornetQ queue.</para> or <literal>UNSUBSCRIBE</literal> frame), the destination is mapped to a ActiveMQ queue.</para>
</section> </section>
<section> <section>
<title>STOMP and connection-ttl</title> <title>STOMP and connection-ttl</title>
@ -108,7 +108,7 @@
<title>Stomp and JMS interoperability</title> <title>Stomp and JMS interoperability</title>
<section> <section>
<title>Using JMS destinations</title> <title>Using JMS destinations</title>
<para>As explained in <xref linkend="jms-core-mapping" />, JMS destinations are also mapped to HornetQ addresses and queues. <para>As explained in <xref linkend="jms-core-mapping" />, JMS destinations are also mapped to ActiveMQ addresses and queues.
If you want to use Stomp to send messages to JMS destinations, the Stomp destinations must follow the same convention:</para> If you want to use Stomp to send messages to JMS destinations, the Stomp destinations must follow the same convention:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -134,8 +134,8 @@ destination:jms.topic.stocks
</section> </section>
<section> <section>
<title>Sending and consuming Stomp message from JMS or HornetQ Core API</title> <title>Sending and consuming Stomp message from JMS or ActiveMQ Core API</title>
<para>Stomp is mainly a text-orientated protocol. To make it simpler to interoperate with JMS and HornetQ Core API, <para>Stomp is mainly a text-orientated protocol. To make it simpler to interoperate with JMS and ActiveMQ Core API,
our Stomp implementation checks for presence of the <literal>content-length</literal> header to decide how to map a Stomp message our Stomp implementation checks for presence of the <literal>content-length</literal> header to decide how to map a Stomp message
to a JMS Message or a Core message. to a JMS Message or a Core message.
</para> </para>
@ -151,7 +151,7 @@ destination:jms.topic.stocks
<title>Message IDs for Stomp messages</title> <title>Message IDs for Stomp messages</title>
<para>When receiving Stomp messages via a JMS consumer or a QueueBrowser, the messages have <para>When receiving Stomp messages via a JMS consumer or a QueueBrowser, the messages have
no properties like JMSMessageID by default. However this may bring some inconvenience to no properties like JMSMessageID by default. However this may bring some inconvenience to
clients who wants an ID for their purpose. HornetQ Stomp provides a parameter to enable clients who wants an ID for their purpose. ActiveMQ Stomp provides a parameter to enable
message ID on each incoming Stomp message. If you want each Stomp message to have a unique ID, message ID on each incoming Stomp message. If you want each Stomp message to have a unique ID,
just set the <literal>stomp-enable-message-id</literal> to true. For example:</para> just set the <literal>stomp-enable-message-id</literal> to true. For example:</para>
<programlisting> <programlisting>
@ -172,9 +172,9 @@ hq-message-id : STOMP12345</programlisting>
</section> </section>
<section> <section>
<title>Handling of Large Messages with Stomp</title> <title>Handling of Large Messages with Stomp</title>
<para>Stomp clients may send very large bodys of frames which can exceed the size of HornetQ <para>Stomp clients may send very large bodys of frames which can exceed the size of ActiveMQ
server's internal buffer, causing unexpected errors. To prevent this situation from happening, server's internal buffer, causing unexpected errors. To prevent this situation from happening,
HornetQ provides a stomp configuration attribute <literal>stomp-min-large-message-size</literal>. ActiveMQ provides a stomp configuration attribute <literal>stomp-min-large-message-size</literal>.
This attribute can be configured inside a stomp acceptor, as a parameter. For example: </para> This attribute can be configured inside a stomp acceptor, as a parameter. For example: </para>
<programlisting> <programlisting>
&lt;acceptor name="stomp-acceptor"> &lt;acceptor name="stomp-acceptor">
@ -183,7 +183,7 @@ hq-message-id : STOMP12345</programlisting>
&lt;param key="port" value="61613"/> &lt;param key="port" value="61613"/>
&lt;param key="stomp-min-large-message-size" value="10240"/> &lt;param key="stomp-min-large-message-size" value="10240"/>
&lt;/acceptor></programlisting> &lt;/acceptor></programlisting>
<para>The type of this attribute is integer. When this attributed is configured, HornetQ server <para>The type of this attribute is integer. When this attributed is configured, ActiveMQ server
will check the size of the body of each Stomp frame arrived from connections established with will check the size of the body of each Stomp frame arrived from connections established with
this acceptor. If the size of the body is equal or greater than the value of this acceptor. If the size of the body is equal or greater than the value of
<literal>stomp-min-large-message</literal>, the message will be persisted as a large message. <literal>stomp-min-large-message</literal>, the message will be persisted as a large message.
@ -197,8 +197,8 @@ hq-message-id : STOMP12345</programlisting>
<section id="stomp.websockets"> <section id="stomp.websockets">
<title>Stomp Over Web Sockets</title> <title>Stomp Over Web Sockets</title>
<para>HornetQ also support Stomp over <ulink url="http://dev.w3.org/html5/websockets/">Web Sockets</ulink>. Modern web browser which support Web Sockets can send and receive <para>ActiveMQ also support Stomp over <ulink url="http://dev.w3.org/html5/websockets/">Web Sockets</ulink>. Modern web browser which support Web Sockets can send and receive
Stomp messages from HornetQ.</para> Stomp messages from ActiveMQ.</para>
<para>To enable Stomp over Web Sockets, you must configure a <literal>NettyAcceptor</literal> with a <literal>protocol</literal> <para>To enable Stomp over Web Sockets, you must configure a <literal>NettyAcceptor</literal> with a <literal>protocol</literal>
parameter set to <literal>stomp_ws</literal>:</para> parameter set to <literal>stomp_ws</literal>:</para>
<programlisting> <programlisting>
@ -207,14 +207,14 @@ hq-message-id : STOMP12345</programlisting>
&lt;param key="protocols" value="STOMP_WS"/> &lt;param key="protocols" value="STOMP_WS"/>
&lt;param key="port" value="61614"/> &lt;param key="port" value="61614"/>
&lt;/acceptor></programlisting> &lt;/acceptor></programlisting>
<para>With this configuration, HornetQ will accept Stomp connections over Web Sockets on <para>With this configuration, ActiveMQ will accept Stomp connections over Web Sockets on
the port <literal>61614</literal> with the URL path <literal>/stomp</literal>. the port <literal>61614</literal> with the URL path <literal>/stomp</literal>.
Web browser can then connect to <literal>ws://&lt;server>:61614/stomp</literal> using a Web Socket to send and receive Stomp Web browser can then connect to <literal>ws://&lt;server>:61614/stomp</literal> using a Web Socket to send and receive Stomp
messages.</para> messages.</para>
<para>A companion JavaScript library to ease client-side development is available from <para>A companion JavaScript library to ease client-side development is available from
<ulink url="http://github.com/jmesnil/stomp-websocket">GitHub</ulink> (please see <ulink url="http://github.com/jmesnil/stomp-websocket">GitHub</ulink> (please see
its <ulink url="http://jmesnil.net/stomp-websocket/doc/">documentation</ulink> for a complete description).</para> its <ulink url="http://jmesnil.net/stomp-websocket/doc/">documentation</ulink> for a complete description).</para>
<para>The <literal>stomp-websockets</literal> example shows how to configure HornetQ server to have web browsers and Java <para>The <literal>stomp-websockets</literal> example shows how to configure ActiveMQ server to have web browsers and Java
applications exchanges messages on a JMS topic.</para> applications exchanges messages on a JMS topic.</para>
</section> </section>
@ -222,10 +222,10 @@ hq-message-id : STOMP12345</programlisting>
<title>StompConnect</title> <title>StompConnect</title>
<para><ulink url="http://stomp.codehaus.org/StompConnect">StompConnect</ulink> is a server that <para><ulink url="http://stomp.codehaus.org/StompConnect">StompConnect</ulink> is a server that
can act as a Stomp broker and proxy the Stomp protocol to the standard JMS API. can act as a Stomp broker and proxy the Stomp protocol to the standard JMS API.
Consequently, using StompConnect it is possible to turn HornetQ into a Stomp Broker and Consequently, using StompConnect it is possible to turn ActiveMQ into a Stomp Broker and
use any of the available stomp clients. These include clients written in C, C++, c# and use any of the available stomp clients. These include clients written in C, C++, c# and
.net etc.</para> .net etc.</para>
<para>To run StompConnect first start the HornetQ server and make sure that it is using <para>To run StompConnect first start the ActiveMQ server and make sure that it is using
JNDI.</para> JNDI.</para>
<para>Stomp requires the file <literal>jndi.properties</literal> to be available on the <para>Stomp requires the file <literal>jndi.properties</literal> to be available on the
classpath. This should look something like:</para> classpath. This should look something like:</para>
@ -234,7 +234,7 @@ java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
java.naming.provider.url=jnp://localhost:1099 java.naming.provider.url=jnp://localhost:1099
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting> java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting>
<para>Make sure this file is in the classpath along with the StompConnect jar and the <para>Make sure this file is in the classpath along with the StompConnect jar and the
HornetQ jars and simply run <literal>java org.codehaus.stomp.jms.Main</literal>.</para> ActiveMQ jars and simply run <literal>java org.codehaus.stomp.jms.Main</literal>.</para>
</section> </section>
</section> </section>
@ -244,7 +244,7 @@ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting
</section> </section>
<section> <section>
<title>AMQP</title> <title>AMQP</title>
<para>HornetQ supports the <ulink url="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp">AMQP 1.0</ulink> <para>ActiveMQ supports the <ulink url="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp">AMQP 1.0</ulink>
specification. To enable AMQP you must configure a Netty Acceptor to receive AMQP clients, like so:</para> specification. To enable AMQP you must configure a Netty Acceptor to receive AMQP clients, like so:</para>
<programlisting> <programlisting>
&lt;acceptor name="stomp-acceptor"> &lt;acceptor name="stomp-acceptor">
@ -253,20 +253,20 @@ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting
&lt;param key="port" value="5672"/> &lt;param key="port" value="5672"/>
&lt;/acceptor> &lt;/acceptor>
</programlisting> </programlisting>
<para>HornetQ will then accept AMQP 1.0 clients on port 5672 which is the default AMQP port.</para> <para>ActiveMQ will then accept AMQP 1.0 clients on port 5672 which is the default AMQP port.</para>
<para>There are 2 Stomp examples available see proton-j and proton-ruby which use the qpid Java and Ruby clients <para>There are 2 Stomp examples available see proton-j and proton-ruby which use the qpid Java and Ruby clients
respectively</para> respectively</para>
<section> <section>
<title>AMQP and security</title> <title>AMQP and security</title>
<para>The HornetQ Server accepts AMQP SASL Authentication and will use this to map onto the underlying session created <para>The ActiveMQ Server accepts AMQP SASL Authentication and will use this to map onto the underlying session created
for the connection so you can use the normal HornetQ security configuration.</para> for the connection so you can use the normal ActiveMQ security configuration.</para>
</section> </section>
<section> <section>
<title>AMQP Links</title> <title>AMQP Links</title>
<para>An AMQP Link is a uni directional transport for messages between a source and a target, i.e. a client and the <para>An AMQP Link is a uni directional transport for messages between a source and a target, i.e. a client and the
HornetQ Broker. A link will have an endpoint of which there are 2 kinds, a Sender and A Receiver. At the Broker a ActiveMQ Broker. A link will have an endpoint of which there are 2 kinds, a Sender and A Receiver. At the Broker a
Sender will have its messages converted into a HornetQ Message and forwarded to its destination or target. A Sender will have its messages converted into a ActiveMQ Message and forwarded to its destination or target. A
Receiver will map onto a HornetQ Server Consumer and convert HornetQ messages back into AMQP messages before being delivered.</para> Receiver will map onto a ActiveMQ Server Consumer and convert ActiveMQ messages back into AMQP messages before being delivered.</para>
</section> </section>
<section> <section>
<title>AMQP and destinations</title> <title>AMQP and destinations</title>
@ -282,13 +282,13 @@ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting
coordinator is used the the underlying HormetQ Server session will be transacted and will be either rolled back coordinator is used the the underlying HormetQ Server session will be transacted and will be either rolled back
or committed via the coordinator.</para> or committed via the coordinator.</para>
<note><para>AMQP allows the use of multiple transactions per session, <literal>amqp:multi-txns-per-ssn</literal>, <note><para>AMQP allows the use of multiple transactions per session, <literal>amqp:multi-txns-per-ssn</literal>,
however in this version HornetQ will only support single transactions per session</para></note> however in this version ActiveMQ will only support single transactions per session</para></note>
</section> </section>
</section> </section>
<section> <section>
<title>OpenWire</title> <title>OpenWire</title>
<para>HornetQ now supports the <ulink url="http://activemq.apache.org/openwire.html">OpenWire</ulink> <para>ActiveMQ now supports the <ulink url="http://activemq.apache.org/openwire.html">OpenWire</ulink>
protocol so that an ActiveMQ JMS client can talk directly to a HornetQ server. To enable OpenWire support protocol so that an ActiveMQ JMS client can talk directly to a ActiveMQ server. To enable OpenWire support
you must configure a Netty Acceptor, like so:</para> you must configure a Netty Acceptor, like so:</para>
<programlisting> <programlisting>
&lt;acceptor name="openwire-acceptor"> &lt;acceptor name="openwire-acceptor">
@ -297,11 +297,11 @@ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting
&lt;param key="port" value="61616"/> &lt;param key="port" value="61616"/>
&lt;/acceptor> &lt;/acceptor>
</programlisting> </programlisting>
<para>The HornetQ server will then listens on port 61616 for incoming openwire commands. Please note the "protocols" is not mandatory here. <para>The ActiveMQ server will then listens on port 61616 for incoming openwire commands. Please note the "protocols" is not mandatory here.
The openwire configuration conforms to HornetQ's "Single Port" feature. Please refer to The openwire configuration conforms to ActiveMQ's "Single Port" feature. Please refer to
<link linkend="configuring-transports.single-port">Configuring Single Port</link> for details.</para> <link linkend="configuring-transports.single-port">Configuring Single Port</link> for details.</para>
<para>Please refer to the openwire example for more coding details.</para> <para>Please refer to the openwire example for more coding details.</para>
<para>Currently we support ActiveMQ clients that using standard JMS APIs. In the future we will get more supports <para>Currently we support ActiveMQ clients that using standard JMS APIs. In the future we will get more supports
for some advanced, ActiveMQ specific features into HornetQ.</para> for some advanced, ActiveMQ specific features into ActiveMQ.</para>
</section> </section>
</chapter> </chapter>

30
docs/user-manual/en/jms-bridge.xml
View File

@ -18,24 +18,24 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="jms-bridge"> <chapter id="jms-bridge">
<title>The JMS Bridge</title> <title>The JMS Bridge</title>
<para>HornetQ includes a fully functional JMS message bridge.</para> <para>ActiveMQ includes a fully functional JMS message bridge.</para>
<para>The function of the bridge is to consume messages from a source queue or topic, and <para>The function of the bridge is to consume messages from a source queue or topic, and
send them to a target queue or topic, typically on a different server.</para> send them to a target queue or topic, typically on a different server.</para>
<para>The source and target servers do not have to be in the same cluster which makes <para>The source and target servers do not have to be in the same cluster which makes
bridging suitable for reliably sending messages from one cluster to another, for bridging suitable for reliably sending messages from one cluster to another, for
instance across a WAN, and where the connection may be unreliable.</para> instance across a WAN, and where the connection may be unreliable.</para>
<para>A bridge can be deployed as a standalone application, with HornetQ standalone server or inside a JBoss AS <para>A bridge can be deployed as a standalone application, with ActiveMQ standalone server or inside a JBoss AS
instance. The source and the target can be located in the same virtual machine or another one.</para> instance. The source and the target can be located in the same virtual machine or another one.</para>
<para>The bridge can also be used to bridge messages from other non HornetQ JMS servers, as <para>The bridge can also be used to bridge messages from other non ActiveMQ JMS servers, as
long as they are JMS 1.1 compliant.<note><para>Do not confuse a JMS bridge with a core long as they are JMS 1.1 compliant.<note><para>Do not confuse a JMS bridge with a core
bridge. A JMS bridge can be used to bridge any two JMS 1.1 compliant JMS bridge. A JMS bridge can be used to bridge any two JMS 1.1 compliant JMS
providers and uses the JMS API. A core bridge (described in <xref providers and uses the JMS API. A core bridge (described in <xref
linkend="core-bridges"/>) is used to bridge any two HornetQ instances and linkend="core-bridges"/>) is used to bridge any two ActiveMQ instances and
uses the core API. Always use a core bridge if you can in preference to a JMS uses the core API. Always use a core bridge if you can in preference to a JMS
bridge. The core bridge will typically provide better performance than a JMS bridge. The core bridge will typically provide better performance than a JMS
bridge. Also the core bridge can provide <emphasis>once and only once</emphasis> bridge. Also the core bridge can provide <emphasis>once and only once</emphasis>
@ -56,8 +56,8 @@
&lt;?xml version="1.0" encoding="UTF-8"?> &lt;?xml version="1.0" encoding="UTF-8"?>
&lt;deployment xmlns="urn:jboss:bean-deployer:2.0"> &lt;deployment xmlns="urn:jboss:bean-deployer:2.0">
&lt;bean name="JMSBridge" class="org.apache.activemq.api.jms.bridge.impl.JMSBridgeImpl"> &lt;bean name="JMSBridge" class="org.apache.activemq.api.jms.bridge.impl.JMSBridgeImpl">
&lt;!-- HornetQ must be started before the bridge --> &lt;!-- ActiveMQ must be started before the bridge -->
&lt;depends>HornetQServer&lt;/depends> &lt;depends>ActiveMQServer&lt;/depends>
&lt;constructor> &lt;constructor>
&lt;!-- Source ConnectionFactory Factory --> &lt;!-- Source ConnectionFactory Factory -->
&lt;parameter> &lt;parameter>
@ -320,7 +320,7 @@
<para>Add MessageID In Header</para> <para>Add MessageID In Header</para>
<para>If <literal>true</literal>, then the original message's message ID will be <para>If <literal>true</literal>, then the original message's message ID will be
appended in the message sent to the destination in the header <literal appended in the message sent to the destination in the header <literal
>HORNETQ_BRIDGE_MSG_ID_LIST</literal>. If the message is bridged more >ACTIVEMQ_BRIDGE_MSG_ID_LIST</literal>. If the message is bridged more
than once, each message ID will be appended. This enables a distributed than once, each message ID will be appended. This enables a distributed
request-response pattern to be used</para> request-response pattern to be used</para>
<note> <note>
@ -341,10 +341,10 @@
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>The "transactionManager" property points to a JTA transaction manager implementation. <para>The "transactionManager" property points to a JTA transaction manager implementation.
HornetQ doesn't ship with such an implementation, but one is available in the JBoss ActiveMQ doesn't ship with such an implementation, but one is available in the JBoss
Community. If you are running HornetQ in standalone mode and wish to use a JMS bridge Community. If you are running ActiveMQ in standalone mode and wish to use a JMS bridge
simply download the latest version of JBossTS from http://www.jboss.org/jbosstm/downloads simply download the latest version of JBossTS from http://www.jboss.org/jbosstm/downloads
and add it to HornetQ's classpath. If you are running HornetQ with JBoss AS then you and add it to ActiveMQ's classpath. If you are running ActiveMQ with JBoss AS then you
won't need to do this as JBoss AS ships with a JTA transaction manager already. The won't need to do this as JBoss AS ships with a JTA transaction manager already. The
bean definition for the transaction manager would look something like this: bean definition for the transaction manager would look something like this:
</para> </para>
@ -356,7 +356,7 @@
connection factory used to create the connection for the source or target connection factory used to create the connection for the source or target
server.</para> server.</para>
<para>The configuration example above uses the default implementation provided by <para>The configuration example above uses the default implementation provided by
HornetQ that looks up the connection factory using JNDI. For other Application ActiveMQ that looks up the connection factory using JNDI. For other Application
Servers or JMS providers a new implementation may have to be provided. This can Servers or JMS providers a new implementation may have to be provided. This can
easily be done by implementing the interface <literal easily be done by implementing the interface <literal
>org.apache.activemq.jms.bridge.ConnectionFactoryFactory</literal>.</para> >org.apache.activemq.jms.bridge.ConnectionFactoryFactory</literal>.</para>
@ -364,7 +364,7 @@
<section> <section>
<title>Source and Target Destination Factories</title> <title>Source and Target Destination Factories</title>
<para>Again, similarly, these are used to create or lookup up the destinations.</para> <para>Again, similarly, these are used to create or lookup up the destinations.</para>
<para>In the configuration example above, we have used the default provided by HornetQ <para>In the configuration example above, we have used the default provided by ActiveMQ
that looks up the destination using JNDI.</para> that looks up the destination using JNDI.</para>
<para>A new implementation can be provided by implementing <literal <para>A new implementation can be provided by implementing <literal
>org.apache.activemq.jms.bridge.DestinationFactory</literal> interface.</para> >org.apache.activemq.jms.bridge.DestinationFactory</literal> interface.</para>
@ -396,7 +396,7 @@
<title>ONCE_AND_ONLY_ONCE</title> <title>ONCE_AND_ONLY_ONCE</title>
<para>This QoS mode ensures messages will reach the destination from the source once <para>This QoS mode ensures messages will reach the destination from the source once
and only once. (Sometimes this mode is known as "exactly once"). If both the and only once. (Sometimes this mode is known as "exactly once"). If both the
source and the destination are on the same HornetQ server instance then this can source and the destination are on the same ActiveMQ server instance then this can
be achieved by sending and acknowledging the messages in the same local be achieved by sending and acknowledging the messages in the same local
transaction. If the source and destination are on different servers this is transaction. If the source and destination are on different servers this is
achieved by enlisting the sending and consuming sessions in a JTA transaction. achieved by enlisting the sending and consuming sessions in a JTA transaction.
@ -444,7 +444,7 @@
and use a JMS Bridge with JBoss AS to send messages to the source destination and consume them and use a JMS Bridge with JBoss AS to send messages to the source destination and consume them
from the target destination.</para> from the target destination.</para>
<para>Please see <xref linkend="examples.jms.jms-bridge"/> which shows how to configure <para>Please see <xref linkend="examples.jms.jms-bridge"/> which shows how to configure
and use a JMS Bridge between two standalone HornetQ servers.</para> and use a JMS Bridge between two standalone ActiveMQ servers.</para>
</section> </section>
</section> </section>
</chapter> </chapter>

6
docs/user-manual/en/jms-core-mapping.xml
View File

@ -18,13 +18,13 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="jms-core-mapping"> <chapter id="jms-core-mapping">
<title>Mapping JMS Concepts to the Core API</title> <title>Mapping JMS Concepts to the Core API</title>
<para>This chapter describes how JMS destinations are mapped to HornetQ addresses.</para> <para>This chapter describes how JMS destinations are mapped to ActiveMQ addresses.</para>
<para>HornetQ core is JMS-agnostic. It does not have any concept of a JMS topic. A JMS topic is <para>ActiveMQ core is JMS-agnostic. It does not have any concept of a JMS topic. A JMS topic is
implemented in core as an address (the topic name) with zero or more queues bound to it. implemented in core as an address (the topic name) with zero or more queues bound to it.
Each queue bound to that address represents a topic subscription. Likewise, a JMS queue is Each queue bound to that address represents a topic subscription. Likewise, a JMS queue is
implemented as an address (the JMS queue name) with one single queue bound to it which implemented as an address (the JMS queue name) with one single queue bound to it which

28
docs/user-manual/en/large-messages.xml
View File

@ -17,18 +17,18 @@
<!-- permitted by applicable law. --> <!-- permitted by applicable law. -->
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="large-messages"> <chapter id="large-messages">
<title>Large Messages</title> <title>Large Messages</title>
<para>HornetQ supports sending and receiving of huge messages, even when the client and server <para>ActiveMQ supports sending and receiving of huge messages, even when the client and server
are running with limited memory. The only realistic limit to the size of a message that can are running with limited memory. The only realistic limit to the size of a message that can
be sent or consumed is the amount of disk space you have available. We have tested sending be sent or consumed is the amount of disk space you have available. We have tested sending
and consuming messages up to 8 GiB in size with a client and server running in just 50MiB of and consuming messages up to 8 GiB in size with a client and server running in just 50MiB of
RAM!</para> RAM!</para>
<para>To send a large message, the user can set an <literal>InputStream</literal> on a message <para>To send a large message, the user can set an <literal>InputStream</literal> on a message
body, and when that message is sent, HornetQ will read the <literal>InputStream</literal>. A body, and when that message is sent, ActiveMQ will read the <literal>InputStream</literal>. A
<literal>FileInputStream</literal> could be used for example to send a huge message from <literal>FileInputStream</literal> could be used for example to send a huge message from
a huge file on disk.</para> a huge file on disk.</para>
<para>As the <literal>InputStream</literal> is read the data is sent to the server as a stream <para>As the <literal>InputStream</literal> is read the data is sent to the server as a stream
@ -47,7 +47,7 @@
<programlisting> <programlisting>
&lt;configuration xmlns="urn:activemq" &lt;configuration xmlns="urn:activemq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:hornetq /schema/activemq-configuration.xsd"> xsi:schemaLocation="urn:activemq /schema/activemq-configuration.xsd">
... ...
&lt;large-messages-directory>/data/large-messages&lt;/large-messages-directory> &lt;large-messages-directory>/data/large-messages&lt;/large-messages-directory>
... ...
@ -62,8 +62,8 @@
will be split up and sent in fragments. This is determined by the parameter <literal will be split up and sent in fragments. This is determined by the parameter <literal
>min-large-message-size</literal></para> >min-large-message-size</literal></para>
<note> <note>
<para>HornetQ messages are encoded using 2 bytes per character so if the message data is filled <para>ActiveMQ messages are encoded using 2 bytes per character so if the message data is filled
with ASCII characters (which are 1 byte) the size of the resulting HornetQ message would roughly with ASCII characters (which are 1 byte) the size of the resulting ActiveMQ message would roughly
double. This is important when calculating the size of a "large" message as it may appear to be double. This is important when calculating the size of a "large" message as it may appear to be
less than the <literal>min-large-message-size</literal> before it is sent, but it then turns into less than the <literal>min-large-message-size</literal> before it is sent, but it then turns into
a "large" message once it is encoded.</para> a "large" message once it is encoded.</para>
@ -71,21 +71,21 @@
<para>The default value is 100KiB.</para> <para>The default value is 100KiB.</para>
<section id="large-messages.core.config"> <section id="large-messages.core.config">
<title>Using Core API</title> <title>Using Core API</title>
<para>If the HornetQ Core API is used, the minimal large message size is specified by <para>If the ActiveMQ Core API is used, the minimal large message size is specified by
<literal>ServerLocator.setMinLargeMessageSize</literal>.</para> <literal>ServerLocator.setMinLargeMessageSize</literal>.</para>
<programlisting> <programlisting>
ServerLocator locator = HornetQClient.createServerLocatorWithoutHA(new TransportConfiguration(NettyConnectorFactory.class.getName())) ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(NettyConnectorFactory.class.getName()))
locator.setMinLargeMessageSize(25 * 1024); locator.setMinLargeMessageSize(25 * 1024);
ClientSessionFactory factory = HornetQClient.createClientSessionFactory();</programlisting> ClientSessionFactory factory = ActiveMQClient.createClientSessionFactory();</programlisting>
<para><xref linkend="configuring-transports.client.side"/> will provide more information <para><xref linkend="configuring-transports.client.side"/> will provide more information
on how to instantiate the session factory.</para> on how to instantiate the session factory.</para>
</section> </section>
<section> <section>
<title>Using JMS</title> <title>Using JMS</title>
<para>If JNDI is used to look up the connection factory, the minimum large message size <para>If JNDI is used to look up the connection factory, the minimum large message size
is specified in <literal>hornetq-jms.xml</literal></para> is specified in <literal>activemq-jms.xml</literal></para>
<programlisting>... <programlisting>...
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;connectors> &lt;connectors>
@ -101,7 +101,7 @@ ClientSessionFactory factory = HornetQClient.createClientSessionFactory();</prog
...</programlisting> ...</programlisting>
<para>If the connection factory is being instantiated directly, the minimum large <para>If the connection factory is being instantiated directly, the minimum large
message size is specified by <literal message size is specified by <literal
>HornetQConnectionFactory.setMinLargeMessageSize</literal>.</para> >ActiveMQConnectionFactory.setMinLargeMessageSize</literal>.</para>
</section> </section>
<section> <section>
<title>Compressed Large Messages</title> <title>Compressed Large Messages</title>
@ -138,7 +138,7 @@ ClientSessionFactory factory = HornetQClient.createClientSessionFactory();</prog
</section> </section>
<section> <section>
<title>Streaming large messages</title> <title>Streaming large messages</title>
<para>HornetQ supports setting the body of messages using input and output streams (<literal <para>ActiveMQ supports setting the body of messages using input and output streams (<literal
>java.lang.io</literal>)</para> >java.lang.io</literal>)</para>
<para>These streams are then used directly for sending (input streams) and receiving (output <para>These streams are then used directly for sending (input streams) and receiving (output
streams) messages.</para> streams) messages.</para>
@ -221,7 +221,7 @@ msg.setInputStream(dataInputStream);
</section> </section>
<section id="large-messages.streaming.over.jms"> <section id="large-messages.streaming.over.jms">
<title>Streaming over JMS</title> <title>Streaming over JMS</title>
<para>When using JMS, HornetQ maps the streaming methods on the core API (see <xref <para>When using JMS, ActiveMQ maps the streaming methods on the core API (see <xref
linkend="large-messages.ClientMessageAPI"/>) by setting object properties . You linkend="large-messages.ClientMessageAPI"/>) by setting object properties . You
can use the method <literal>Message.setObjectProperty</literal> to set the input and can use the method <literal>Message.setObjectProperty</literal> to set the input and
output streams.</para> output streams.</para>
@ -264,7 +264,7 @@ messageReceived.setObjectProperty("JMS_HQ_OutputStream", bufferedOutput);</progr
<section> <section>
<title>Streaming Alternative</title> <title>Streaming Alternative</title>
<para>If you choose not to use the <literal>InputStream</literal> or <literal <para>If you choose not to use the <literal>InputStream</literal> or <literal
>OutputStream</literal> capability of HornetQ You could still access the data >OutputStream</literal> capability of ActiveMQ You could still access the data
directly in an alternative fashion.</para> directly in an alternative fashion.</para>
<para>On the Core API just get the bytes of the body as you normally would.</para> <para>On the Core API just get the bytes of the body as you normally would.</para>
<programlisting> <programlisting>

2
docs/user-manual/en/last-value-queues.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="last-value-queues"> <chapter id="last-value-queues">

16
docs/user-manual/en/libaio.xml
View File

@ -18,12 +18,12 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="libaio"> <chapter id="libaio">
<title>Libaio Native Libraries</title> <title>Libaio Native Libraries</title>
<para>HornetQ distributes a native library, used as a bridge between HornetQ and Linux <para>ActiveMQ distributes a native library, used as a bridge between ActiveMQ and Linux
libaio.</para> libaio.</para>
<para><literal>libaio</literal> is a library, developed as part of the Linux kernel project. <para><literal>libaio</literal> is a library, developed as part of the Linux kernel project.
With <literal>libaio</literal> we submit writes to the operating system where they are With <literal>libaio</literal> we submit writes to the operating system where they are
@ -31,16 +31,16 @@
processed.</para> processed.</para>
<para>We use this in our high performance journal if configured to do so, please see <xref <para>We use this in our high performance journal if configured to do so, please see <xref
linkend="persistence"/>.</para> linkend="persistence"/>.</para>
<para>These are the native libraries distributed by HornetQ:</para> <para>These are the native libraries distributed by ActiveMQ:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>libHornetQAIO32.so - x86 32 bits</para> <para>libActiveMQAIO32.so - x86 32 bits</para>
</listitem> </listitem>
<listitem> <listitem>
<para>libHornetQAIO64.so - x86 64 bits</para> <para>libActiveMQAIO64.so - x86 64 bits</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>When using libaio, HornetQ will always try loading these files as long as they are on the <para>When using libaio, ActiveMQ will always try loading these files as long as they are on the
<link linkend="using-server.library.path">library path</link>.</para> <link linkend="using-server.library.path">library path</link>.</para>
<section> <section>
<title>Compiling the native libraries</title> <title>Compiling the native libraries</title>
@ -120,10 +120,10 @@ config.status: executing libtool commands
...</programlisting> ...</programlisting>
<para>The produced library will be at <literal <para>The produced library will be at <literal
>./native-src/src/.libs/libHornetQAIO.so</literal>. Simply move that file over >./native-src/src/.libs/libActiveMQAIO.so</literal>. Simply move that file over
<literal>bin</literal> on the distribution or the place you have chosen on the <literal>bin</literal> on the distribution or the place you have chosen on the
<link linkend="using-server.library.path">library path</link>.</para> <link linkend="using-server.library.path">library path</link>.</para>
<para>If you want to perform changes on the HornetQ libaio code, you could just call <para>If you want to perform changes on the ActiveMQ libaio code, you could just call
make directly at the <literal>native-src</literal> directory.</para> make directly at the <literal>native-src</literal> directory.</para>
</section> </section>
</section> </section>

14
docs/user-manual/en/logging.xml
View File

@ -18,12 +18,12 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="logging"> <chapter id="logging">
<title>Logging</title> <title>Logging</title>
<para>HornetQ uses the JBoss Logging framework to do its logging and is configurable via the <literal>logging.properties</literal> <para>ActiveMQ uses the JBoss Logging framework to do its logging and is configurable via the <literal>logging.properties</literal>
file found in the configuration directories. This is configured by Default to log to both the console and to a file.</para> file found in the configuration directories. This is configured by Default to log to both the console and to a file.</para>
<para>There are 6 loggers available which are as follows:</para> <para>There are 6 loggers available which are as follows:</para>
<table frame="topbot" border="2"> <table frame="topbot" border="2">
@ -40,7 +40,7 @@
<tbody> <tbody>
<row> <row>
<entry>org.jboss.logging</entry> <entry>org.jboss.logging</entry>
<entry>Logs any calls not handled by the HornetQ loggers</entry> <entry>Logs any calls not handled by the ActiveMQ loggers</entry>
</row> </row>
<row> <row>
<entry>org.apache.activemq.core.server</entry> <entry>org.apache.activemq.core.server</entry>
@ -92,7 +92,7 @@
&lt;/dependency> &lt;/dependency>
&lt;dependency> &lt;dependency>
&lt;groupId>org.apache.activemq&lt;/groupId> &lt;groupId>org.apache.activemq&lt;/groupId>
&lt;artifactId>hornetq-core-client&lt;/artifactId> &lt;artifactId>activemq-core-client&lt;/artifactId>
&lt;version>2.3.0.Final&lt;/version> &lt;version>2.3.0.Final&lt;/version>
&lt;/dependency></programlisting> &lt;/dependency></programlisting>
The first dependency <literal>jnp-client</literal> is not actually needed for logging, however this is needed for The first dependency <literal>jnp-client</literal> is not actually needed for logging, however this is needed for
@ -116,7 +116,7 @@ loggers=org.jboss.logging,org.apache.activemq.core.server,org.apache.activemq.ut
# Root logger level # Root logger level
logger.level=INFO logger.level=INFO
# HornetQ logger levels # ActiveMQ logger levels
logger.org.apache.activemq.core.server.level=INFO logger.org.apache.activemq.core.server.level=INFO
logger.org.apache.activemq.utils.level=INFO logger.org.apache.activemq.utils.level=INFO
logger.org.apache.activemq.jms.level=DEBUG logger.org.apache.activemq.jms.level=DEBUG
@ -136,7 +136,7 @@ handler.FILE=org.jboss.logmanager.handlers.FileHandler
handler.FILE.level=FINE handler.FILE.level=FINE
handler.FILE.properties=autoFlush,fileName handler.FILE.properties=autoFlush,fileName
handler.FILE.autoFlush=true handler.FILE.autoFlush=true
handler.FILE.fileName=hornetq.log handler.FILE.fileName=activemq.log
handler.FILE.formatter=PATTERN handler.FILE.formatter=PATTERN
# Formatter pattern configuration # Formatter pattern configuration
@ -147,7 +147,7 @@ formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n</programlisting>
</section> </section>
<section> <section>
<title>Logging With The JBoss Application Server</title> <title>Logging With The JBoss Application Server</title>
<para>When HornetQ is deployed within the JBoss Application Server version 7.x or above then <para>When ActiveMQ is deployed within the JBoss Application Server version 7.x or above then
it will still use JBoss Logging, refer to the AS7 documentation on how to configure AS7 logging.</para> it will still use JBoss Logging, refer to the AS7 documentation on how to configure AS7 logging.</para>
</section> </section>
</chapter> </chapter>

114
docs/user-manual/en/management.xml
View File

@ -18,31 +18,31 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="management"> <chapter id="management">
<title>Management</title> <title>Management</title>
<para>HornetQ has an extensive management API that allows a user to modify a server <para>ActiveMQ has an extensive management API that allows a user to modify a server
configuration, create new resources (e.g. JMS queues and topics), inspect these resources configuration, create new resources (e.g. JMS queues and topics), inspect these resources
(e.g. how many messages are currently held in a queue) and interact with it (e.g. to remove (e.g. how many messages are currently held in a queue) and interact with it (e.g. to remove
messages from a queue). All the operations allows a client to <emphasis>manage</emphasis> messages from a queue). All the operations allows a client to <emphasis>manage</emphasis>
HornetQ. It also allows clients to subscribe to management notifications.</para> ActiveMQ. It also allows clients to subscribe to management notifications.</para>
<para>There are 3 ways to manage HornetQ:</para> <para>There are 3 ways to manage ActiveMQ:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Using JMX -- JMX is the standard way to manage Java applications</para> <para>Using JMX -- JMX is the standard way to manage Java applications</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Using the core API -- management operations are sent to HornetQ server using <para>Using the core API -- management operations are sent to ActiveMQ server using
<emphasis>core messages</emphasis></para> <emphasis>core messages</emphasis></para>
</listitem> </listitem>
<listitem> <listitem>
<para>Using the JMS API -- management operations are sent to HornetQ server using <para>Using the JMS API -- management operations are sent to ActiveMQ server using
<emphasis>JMS messages</emphasis></para> <emphasis>JMS messages</emphasis></para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>Although there are 3 different ways to manage HornetQ each API supports the same <para>Although there are 3 different ways to manage ActiveMQ each API supports the same
functionality. If it is possible to manage a resource using JMX it is also possible to achieve functionality. If it is possible to manage a resource using JMX it is also possible to achieve
the same result using Core messages or JMS messages.</para> the same result using Core messages or JMS messages.</para>
<para>This choice depends on your requirements, your application settings and your environment to <para>This choice depends on your requirements, your application settings and your environment to
@ -53,7 +53,7 @@
management API is the same.</para> management API is the same.</para>
<para>For each <emphasis>managed resource</emphasis>, there exists a Java interface describing <para>For each <emphasis>managed resource</emphasis>, there exists a Java interface describing
what can be invoked for this type of resource.</para> what can be invoked for this type of resource.</para>
<para>HornetQ exposes its managed resources in 2 packages:</para> <para>ActiveMQ exposes its managed resources in 2 packages:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><emphasis>Core</emphasis> resources are located in the <literal <para><emphasis>Core</emphasis> resources are located in the <literal
@ -74,7 +74,7 @@
</note> </note>
<section> <section>
<title>Core Management API</title> <title>Core Management API</title>
<para>HornetQ defines a core management API to manage core resources. For full details of <para>ActiveMQ defines a core management API to manage core resources. For full details of
the API please consult the javadoc. In summary:</para> the API please consult the javadoc. In summary:</para>
<section id="management.core.server"> <section id="management.core.server">
<title>Core Server Management</title> <title>Core Server Management</title>
@ -86,7 +86,7 @@
<para>Core queues can be created or destroyed using the management operations <para>Core queues can be created or destroyed using the management operations
<literal>createQueue()</literal> or <literal>deployQueue()</literal> or <literal>createQueue()</literal> or <literal>deployQueue()</literal> or
<literal>destroyQueue()</literal>)on the <literal <literal>destroyQueue()</literal>)on the <literal
>HornetQServerControl</literal> (with the ObjectName <literal >ActiveMQServerControl</literal> (with the ObjectName <literal
>org.apache.activemq:module=Core,type=Server</literal> or the resource name <literal >org.apache.activemq:module=Core,type=Server</literal> or the resource name <literal
>core.server</literal>)</para> >core.server</literal>)</para>
<para><literal>createQueue</literal> will fail if the queue already exists while <para><literal>createQueue</literal> will fail if the queue already exists while
@ -132,7 +132,7 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Retrieving the server configuration and attributes</para> <para>Retrieving the server configuration and attributes</para>
<para>The <literal>HornetQServerControl</literal> exposes HornetQ server <para>The <literal>ActiveMQServerControl</literal> exposes ActiveMQ server
configuration through all its attributes (e.g. <literal>getVersion()</literal> configuration through all its attributes (e.g. <literal>getVersion()</literal>
method to retrieve the server's version, etc.)</para> method to retrieve the server's version, etc.)</para>
</listitem> </listitem>
@ -143,14 +143,14 @@
<para>Core bridges (resp. diverts) can be created or destroyed using the management operations <para>Core bridges (resp. diverts) can be created or destroyed using the management operations
<literal>createBridge()</literal> and <literal>destroyBridge()</literal> <literal>createBridge()</literal> and <literal>destroyBridge()</literal>
(resp. <literal>createDivert()</literal> and <literal>destroyDivert()</literal>) on the <literal (resp. <literal>createDivert()</literal> and <literal>destroyDivert()</literal>) on the <literal
>HornetQServerControl</literal> (with the ObjectName <literal >ActiveMQServerControl</literal> (with the ObjectName <literal
>org.apache.activemq:module=Core,type=Server</literal> or the resource name <literal >org.apache.activemq:module=Core,type=Server</literal> or the resource name <literal
>core.server</literal>).</para> >core.server</literal>).</para>
</listitem> </listitem>
<listitem> <listitem>
<para>It is possible to stop the server and force failover to occur with any currently attached clients.</para> <para>It is possible to stop the server and force failover to occur with any currently attached clients.</para>
<para>to do this use the <literal>forceFailover()</literal> on the <literal <para>to do this use the <literal>forceFailover()</literal> on the <literal
>HornetQServerControl</literal> (with the ObjectName <literal >ActiveMQServerControl</literal> (with the ObjectName <literal
>org.apache.activemq:module=Core,type=Server</literal> or the resource name <literal >org.apache.activemq:module=Core,type=Server</literal> or the resource name <literal
>core.server</literal>) </para> >core.server</literal>) </para>
<note> <note>
@ -258,7 +258,7 @@
</section> </section>
<section> <section>
<title>Other Core Resources Management</title> <title>Other Core Resources Management</title>
<para>HornetQ allows to start and stop its remote resources (acceptors, diverts, <para>ActiveMQ allows to start and stop its remote resources (acceptors, diverts,
bridges, etc.) so that a server can be taken off line for a given period of time bridges, etc.) so that a server can be taken off line for a given period of time
without stopping it completely (e.g. if other management operations must be performed without stopping it completely (e.g. if other management operations must be performed
such as resolving heuristic transactions). These resources are:</para> such as resolving heuristic transactions). These resources are:</para>
@ -335,7 +335,7 @@
</section> </section>
<section> <section>
<title>JMS Management API</title> <title>JMS Management API</title>
<para>HornetQ defines a JMS Management API to manage JMS <emphasis>administrated <para>ActiveMQ defines a JMS Management API to manage JMS <emphasis>administrated
objects</emphasis> (i.e. JMS queues, topics and connection factories).</para> objects</emphasis> (i.e. JMS queues, topics and connection factories).</para>
<section> <section>
<title>JMS Server Management</title> <title>JMS Server Management</title>
@ -520,10 +520,10 @@
</section> </section>
<section id="management.jmx"> <section id="management.jmx">
<title>Using Management Via JMX</title> <title>Using Management Via JMX</title>
<para>HornetQ can be managed using <ulink <para>ActiveMQ can be managed using <ulink
url="http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html" url="http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html"
>JMX</ulink>. </para> >JMX</ulink>. </para>
<para>The management API is exposed by HornetQ using MBeans interfaces. HornetQ registers its <para>The management API is exposed by ActiveMQ using MBeans interfaces. ActiveMQ registers its
resources with the domain <literal>org.apache.activemq</literal>.</para> resources with the domain <literal>org.apache.activemq</literal>.</para>
<para>For example, the <literal>ObjectName</literal> to manage a JMS Queue <literal <para>For example, the <literal>ObjectName</literal> to manage a JMS Queue <literal
>exampleQueue</literal> is:</para> >exampleQueue</literal> is:</para>
@ -536,17 +536,17 @@ org.apache.activemq.api.jms.management.JMSQueueControl</programlisting>
>org.apache.activemq.api.core.management.ObjectNameBuilder</literal>. You can also use <literal >org.apache.activemq.api.core.management.ObjectNameBuilder</literal>. You can also use <literal
>jconsole</literal> to find the <literal>ObjectName</literal> of the MBeans you want to >jconsole</literal> to find the <literal>ObjectName</literal> of the MBeans you want to
manage. </para> manage. </para>
<para>Managing HornetQ using JMX is identical to management of any Java Applications using <para>Managing ActiveMQ using JMX is identical to management of any Java Applications using
JMX. It can be done by reflection or by creating proxies of the MBeans.</para> JMX. It can be done by reflection or by creating proxies of the MBeans.</para>
<section id="management.jmx.configuration"> <section id="management.jmx.configuration">
<title>Configuring JMX</title> <title>Configuring JMX</title>
<para>By default, JMX is enabled to manage HornetQ. It can be disabled by setting <literal <para>By default, JMX is enabled to manage ActiveMQ. It can be disabled by setting <literal
>jmx-management-enabled</literal> to <literal>false</literal> in <literal >jmx-management-enabled</literal> to <literal>false</literal> in <literal
>hornetq-configuration.xml</literal>:</para> >activemq-configuration.xml</literal>:</para>
<programlisting> <programlisting>
&lt;!-- false to disable JMX management for HornetQ --> &lt;!-- false to disable JMX management for ActiveMQ -->
&lt;jmx-management-enabled>false&lt;/jmx-management-enabled></programlisting> &lt;jmx-management-enabled>false&lt;/jmx-management-enabled></programlisting>
<para>If JMX is enabled, HornetQ can be managed locally using <literal>jconsole</literal>.</para> <para>If JMX is enabled, ActiveMQ can be managed locally using <literal>jconsole</literal>.</para>
<note> <note>
<para>Remote connections to JMX are not enabled by default for security reasons. Please refer <para>Remote connections to JMX are not enabled by default for security reasons. Please refer
to <ulink url="http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html" to <ulink url="http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html"
@ -554,16 +554,16 @@ org.apache.activemq.api.jms.management.JMSQueueControl</programlisting>
properties must be set in <literal>run.sh</literal> or <literal>run.bat</literal> properties must be set in <literal>run.sh</literal> or <literal>run.bat</literal>
scripts).</para> scripts).</para>
</note> </note>
<para>By default, HornetQ server uses the JMX domain "org.apache.activemq". To manage several <para>By default, ActiveMQ server uses the JMX domain "org.apache.activemq". To manage several
HornetQ servers from the <emphasis>same</emphasis> MBeanServer, the JMX domain can be ActiveMQ servers from the <emphasis>same</emphasis> MBeanServer, the JMX domain can be
configured for each individual HornetQ server by setting <literal>jmx-domain</literal> configured for each individual ActiveMQ server by setting <literal>jmx-domain</literal>
in <literal>hornetq-configuration.xml</literal>: </para> in <literal>activemq-configuration.xml</literal>: </para>
<programlisting> <programlisting>
&lt;!-- use a specific JMX domain for HornetQ MBeans --> &lt;!-- use a specific JMX domain for ActiveMQ MBeans -->
&lt;jmx-domain>my.org.apache.activemq&lt;/jmx-domain></programlisting> &lt;jmx-domain>my.org.apache.activemq&lt;/jmx-domain></programlisting>
<section> <section>
<title>MBeanServer configuration</title> <title>MBeanServer configuration</title>
<para>When HornetQ is run in standalone, it uses the Java Virtual Machine's <literal <para>When ActiveMQ is run in standalone, it uses the Java Virtual Machine's <literal
>Platform MBeanServer</literal> to register its MBeans. This is configured in >Platform MBeanServer</literal> to register its MBeans. This is configured in
JBoss Microcontainer Beans file (see <xref JBoss Microcontainer Beans file (see <xref
linkend="server.microcontainer.configuration"/>):</para> linkend="server.microcontainer.configuration"/>):</para>
@ -586,12 +586,12 @@ org.apache.activemq.api.jms.management.JMSQueueControl</programlisting>
<section> <section>
<title>Example</title> <title>Example</title>
<para>See <xref linkend="examples.jmx"/> for an example which shows how to use a remote <para>See <xref linkend="examples.jmx"/> for an example which shows how to use a remote
connection to JMX and MBean proxies to manage HornetQ.</para> connection to JMX and MBean proxies to manage ActiveMQ.</para>
</section> </section>
</section> </section>
<section> <section>
<title>Using Management Via Core API</title> <title>Using Management Via Core API</title>
<para>The core management API in HornetQ is called by sending Core messages to a special <para>The core management API in ActiveMQ is called by sending Core messages to a special
address, the <emphasis>management address</emphasis>.</para> address, the <emphasis>management address</emphasis>.</para>
<para><emphasis>Management messages</emphasis> are regular Core messages with well-known <para><emphasis>Management messages</emphasis> are regular Core messages with well-known
properties that the server needs to understand to interact with the management API:</para> properties that the server needs to understand to interact with the management API:</para>
@ -606,7 +606,7 @@ org.apache.activemq.api.jms.management.JMSQueueControl</programlisting>
<para>The parameters of the management operation</para> <para>The parameters of the management operation</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>When such a management message is sent to the management address, HornetQ server will <para>When such a management message is sent to the management address, ActiveMQ server will
handle it, extract the information, invoke the operation on the managed resources and send handle it, extract the information, invoke the operation on the managed resources and send
a <emphasis>management reply</emphasis> to the management message's reply-to address a <emphasis>management reply</emphasis> to the management message's reply-to address
(specified by <literal>ClientMessageImpl.REPLYTO_HEADER_NAME</literal>). </para> (specified by <literal>ClientMessageImpl.REPLYTO_HEADER_NAME</literal>). </para>
@ -643,7 +643,7 @@ org.apache.activemq.api.jms.management.JMSQueueControl</programlisting>
>exampleQueue</literal>:</para> >exampleQueue</literal>:</para>
<programlisting> <programlisting>
ClientSession session = ... ClientSession session = ...
ClientRequestor requestor = new ClientRequestor(session, "jms.queue.hornetq.management"); ClientRequestor requestor = new ClientRequestor(session, "jms.queue.activemq.management");
ClientMessage message = session.createMessage(false); ClientMessage message = session.createMessage(false);
ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount"); ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount");
session.start(); session.start();
@ -660,31 +660,31 @@ System.out.println("There are " + count + " messages in exampleQueue");</program
<section id="management.core.configuration"> <section id="management.core.configuration">
<title>Configuring Core Management</title> <title>Configuring Core Management</title>
<para>The management address to send management messages is configured in <literal <para>The management address to send management messages is configured in <literal
>hornetq-configuration.xml</literal>:</para> >activemq-configuration.xml</literal>:</para>
<programlisting> <programlisting>
&lt;management-address>jms.queue.hornetq.management&lt;/management-address></programlisting> &lt;management-address>jms.queue.activemq.management&lt;/management-address></programlisting>
<para>By default, the address is <literal>jms.queue.hornetq.management</literal> (it is <para>By default, the address is <literal>jms.queue.activemq.management</literal> (it is
prepended by "jms.queue" so that JMS clients can also send management messages).</para> prepended by "jms.queue" so that JMS clients can also send management messages).</para>
<para>The management address requires a <emphasis>special</emphasis> user permission <para>The management address requires a <emphasis>special</emphasis> user permission
<literal>manage</literal> to be able to receive and handle management messages. This <literal>manage</literal> to be able to receive and handle management messages. This
is also configured in hornetq-configuration.xml:</para> is also configured in activemq-configuration.xml:</para>
<programlisting> <programlisting>
&lt;!-- users with the admin role will be allowed to manage --> &lt;!-- users with the admin role will be allowed to manage -->
&lt;!-- HornetQ using management messages --> &lt;!-- ActiveMQ using management messages -->
&lt;security-setting match="jms.queue.hornetq.management"> &lt;security-setting match="jms.queue.activemq.management">
&lt;permission type="manage" roles="admin" /> &lt;permission type="manage" roles="admin" />
&lt;/security-setting></programlisting> &lt;/security-setting></programlisting>
</section> </section>
</section> </section>
<section id="management.jms"> <section id="management.jms">
<title>Using Management Via JMS</title> <title>Using Management Via JMS</title>
<para>Using JMS messages to manage HornetQ is very similar to using core API.</para> <para>Using JMS messages to manage ActiveMQ is very similar to using core API.</para>
<para>An important difference is that JMS requires a JMS queue to send the messages to <para>An important difference is that JMS requires a JMS queue to send the messages to
(instead of an address for the core API).</para> (instead of an address for the core API).</para>
<para>The <emphasis>management queue</emphasis> is a special queue and needs to be <para>The <emphasis>management queue</emphasis> is a special queue and needs to be
instantiated directly by the client:</para> instantiated directly by the client:</para>
<programlisting> <programlisting>
Queue managementQueue = HornetQJMSClient.createQueue("hornetq.management");</programlisting> Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");</programlisting>
<para>All the other steps are the same than for the Core API but they use JMS API <para>All the other steps are the same than for the Core API but they use JMS API
instead:</para> instead:</para>
<orderedlist> <orderedlist>
@ -712,7 +712,7 @@ Queue managementQueue = HornetQJMSClient.createQueue("hornetq.management");</pro
<para>For example, to know the number of messages in the JMS queue <literal <para>For example, to know the number of messages in the JMS queue <literal
>exampleQueue</literal>:</para> >exampleQueue</literal>:</para>
<programlisting> <programlisting>
Queue managementQueue = HornetQJMSClient.createQueue("hornetq.management"); Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
QueueSession session = ... QueueSession session = ...
QueueRequestor requestor = new QueueRequestor(session, managementQueue); QueueRequestor requestor = new QueueRequestor(session, managementQueue);
@ -730,13 +730,13 @@ System.out.println("There are " + count + " messages in exampleQueue");</program
<section> <section>
<title>Example</title> <title>Example</title>
<para>See <xref linkend="examples.management"/> for an example which shows how to use JMS <para>See <xref linkend="examples.management"/> for an example which shows how to use JMS
messages to manage HornetQ server.</para> messages to manage ActiveMQ server.</para>
</section> </section>
</section> </section>
<section id="management.notifications"> <section id="management.notifications">
<title>Management Notifications</title> <title>Management Notifications</title>
<para>HornetQ emits <emphasis>notifications</emphasis> to inform listeners of potentially <para>ActiveMQ emits <emphasis>notifications</emphasis> to inform listeners of potentially
interesting events (creation of new resources, security violation, etc.).</para> interesting events (creation of new resources, security violation, etc.).</para>
<para>These notifications can be received by 3 different ways:</para> <para>These notifications can be received by 3 different ways:</para>
<itemizedlist> <itemizedlist>
@ -767,7 +767,7 @@ System.out.println("There are " + count + " messages in exampleQueue");</program
</section> </section>
<section> <section>
<title>Core Messages Notifications</title> <title>Core Messages Notifications</title>
<para>HornetQ defines a special <emphasis>management notification address</emphasis>. Core <para>ActiveMQ defines a special <emphasis>management notification address</emphasis>. Core
queues can be bound to this address so that clients will receive management queues can be bound to this address so that clients will receive management
notifications as Core messages</para> notifications as Core messages</para>
<para>A Core client which wants to receive management notifications must create a core <para>A Core client which wants to receive management notifications must create a core
@ -782,15 +782,15 @@ System.out.println("There are " + count + " messages in exampleQueue");</program
<section id="management.notifications.core.configuration"> <section id="management.notifications.core.configuration">
<title>Configuring The Core Management Notification Address</title> <title>Configuring The Core Management Notification Address</title>
<para>The management notification address to receive management notifications is <para>The management notification address to receive management notifications is
configured in <literal>hornetq-configuration.xml</literal>:</para> configured in <literal>activemq-configuration.xml</literal>:</para>
<programlisting> <programlisting>
&lt;management-notification-address>hornetq.notifications&lt;/management-notification-address></programlisting> &lt;management-notification-address>activemq.notifications&lt;/management-notification-address></programlisting>
<para>By default, the address is <literal>hornetq.notifications</literal>.</para> <para>By default, the address is <literal>activemq.notifications</literal>.</para>
</section> </section>
</section> </section>
<section> <section>
<title>JMS Messages Notifications</title> <title>JMS Messages Notifications</title>
<para>HornetQ's notifications can also be received using JMS messages.</para> <para>ActiveMQ's notifications can also be received using JMS messages.</para>
<para>It is similar to receiving notifications using Core API but an important difference <para>It is similar to receiving notifications using Core API but an important difference
is that JMS requires a JMS Destination to receive the messages (preferably a is that JMS requires a JMS Destination to receive the messages (preferably a
Topic).</para> Topic).</para>
@ -803,7 +803,7 @@ System.out.println("There are " + count + " messages in exampleQueue");</program
<para>Once the notification topic is created, you can receive messages from it or set a <para>Once the notification topic is created, you can receive messages from it or set a
<literal>MessageListener</literal>:</para> <literal>MessageListener</literal>:</para>
<programlisting> <programlisting>
Topic notificationsTopic = HornetQJMSClient.createTopic("notificationsTopic"); Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic");
Session session = ... Session session = ...
MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic); MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
@ -833,7 +833,7 @@ notificationConsumer.setMessageListener(new MessageListener()
<title>Example</title> <title>Example</title>
<para>See <xref linkend="examples.management-notifications"/> for an example which shows <para>See <xref linkend="examples.management-notifications"/> for an example which shows
how to use a JMS <literal>MessageListener</literal> to receive management notifications how to use a JMS <literal>MessageListener</literal> to receive management notifications
from HornetQ server.</para> from ActiveMQ server.</para>
</section> </section>
<section id="notification.types.and.headers"> <section id="notification.types.and.headers">
<title>Notification Types and Headers</title> <title>Notification Types and Headers</title>
@ -980,7 +980,7 @@ notificationConsumer.setMessageListener(new MessageListener()
<section id="management.message-counters"> <section id="management.message-counters">
<title>Message Counters</title> <title>Message Counters</title>
<para>Message counters can be used to obtain information on queues <emphasis>over <para>Message counters can be used to obtain information on queues <emphasis>over
time</emphasis> as HornetQ keeps a history on queue metrics.</para> time</emphasis> as ActiveMQ keeps a history on queue metrics.</para>
<para>They can be used to show <emphasis>trends</emphasis> on queues. For example, using the <para>They can be used to show <emphasis>trends</emphasis> on queues. For example, using the
management API, it would be possible to query the number of messages in a queue at regular management API, it would be possible to query the number of messages in a queue at regular
interval. However, this would not be enough to know if the queue is used: the number of interval. However, this would not be enough to know if the queue is used: the number of
@ -1029,13 +1029,13 @@ notificationConsumer.setMessageListener(new MessageListener()
<para>By default, message counters are disabled as it might have a small negative effect on <para>By default, message counters are disabled as it might have a small negative effect on
memory.</para> memory.</para>
<para>To enable message counters, you can set it to <literal>true</literal> in <literal <para>To enable message counters, you can set it to <literal>true</literal> in <literal
>hornetq-configuration.xml</literal>:</para> >activemq-configuration.xml</literal>:</para>
<programlisting> <programlisting>
&lt;message-counter-enabled>true&lt;/message-counter-enabled></programlisting> &lt;message-counter-enabled>true&lt;/message-counter-enabled></programlisting>
<para>Message counters keeps a history of the queue metrics (10 days by default) and <para>Message counters keeps a history of the queue metrics (10 days by default) and
samples all the queues at regular interval (10 seconds by default). If message counters samples all the queues at regular interval (10 seconds by default). If message counters
are enabled, these values should be configured to suit your messaging use case in are enabled, these values should be configured to suit your messaging use case in
<literal>hornetq-configuration.xml</literal>:</para> <literal>activemq-configuration.xml</literal>:</para>
<programlisting> <programlisting>
&lt;!-- keep history for a week --> &lt;!-- keep history for a week -->
&lt;message-counter-max-day-history>7&lt;/message-counter-max-day-history> &lt;message-counter-max-day-history>7&lt;/message-counter-max-day-history>
@ -1044,7 +1044,7 @@ notificationConsumer.setMessageListener(new MessageListener()
<para>Message counters can be retrieved using the Management API. For example, to retrieve <para>Message counters can be retrieved using the Management API. For example, to retrieve
message counters on a JMS Queue using JMX:</para> message counters on a JMS Queue using JMX:</para>
<programlisting> <programlisting>
// retrieve a connection to HornetQ's MBeanServer // retrieve a connection to ActiveMQ's MBeanServer
MBeanServerConnection mbsc = ... MBeanServerConnection mbsc = ...
JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc, JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
on, on,
@ -1065,10 +1065,10 @@ messageCounter.getMessageCountDelta());</programlisting>
</section> </section>
</section> </section>
<section> <section>
<title>Administering HornetQ Resources Using The JBoss AS Admin Console</title> <title>Administering ActiveMQ Resources Using The JBoss AS Admin Console</title>
<para>Its possible to create and configure HornetQ resources via the admin console within the JBoss Application Server.</para> <para>Its possible to create and configure ActiveMQ resources via the admin console within the JBoss Application Server.</para>
<para>The Admin Console will allow you to create destinations (JMS Topics and Queues) and JMS Connection Factories.</para> <para>The Admin Console will allow you to create destinations (JMS Topics and Queues) and JMS Connection Factories.</para>
<para>Once logged in to the admin console you will see a JMS Manager item in the left hand tree. All HornetQ resources <para>Once logged in to the admin console you will see a JMS Manager item in the left hand tree. All ActiveMQ resources
will be configured via this. This will have a child items for JMS Queues, Topics and Connection Factories, clicking will be configured via this. This will have a child items for JMS Queues, Topics and Connection Factories, clicking
on each node will reveal which resources are currently available. The following sections explain how to create on each node will reveal which resources are currently available. The following sections explain how to create
and configure each resource in turn.</para> and configure each resource in turn.</para>

10
docs/user-manual/en/message-expiry.xml
View File

@ -18,23 +18,23 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="message-expiry"> <chapter id="message-expiry">
<title>Message Expiry</title> <title>Message Expiry</title>
<para>Messages can be set with an optional <emphasis>time to live</emphasis> when sending <para>Messages can be set with an optional <emphasis>time to live</emphasis> when sending
them.</para> them.</para>
<para>HornetQ will not deliver a message to a consumer after it's time to live has been exceeded. <para>ActiveMQ will not deliver a message to a consumer after it's time to live has been exceeded.
If the message hasn't been delivered by the time that time to live is reached the server can If the message hasn't been delivered by the time that time to live is reached the server can
discard it.</para> discard it.</para>
<para>HornetQ's addresses can be assigned a expiry address so that, when messages are expired, <para>ActiveMQ's addresses can be assigned a expiry address so that, when messages are expired,
they are removed from the queue and sent to the expiry address. Many different queues can be they are removed from the queue and sent to the expiry address. Many different queues can be
bound to an expiry address. These <emphasis>expired</emphasis> messages can later be consumed bound to an expiry address. These <emphasis>expired</emphasis> messages can later be consumed
for further inspection.</para> for further inspection.</para>
<section> <section>
<title>Message Expiry</title> <title>Message Expiry</title>
<para>Using HornetQ Core API, you can set an expiration time directly on the message:</para> <para>Using ActiveMQ Core API, you can set an expiration time directly on the message:</para>
<programlisting> <programlisting>
// message will expire in 5000ms from now // message will expire in 5000ms from now
message.setExpiration(System.currentTimeMillis() + 5000);</programlisting> message.setExpiration(System.currentTimeMillis() + 5000);</programlisting>
@ -79,7 +79,7 @@ producer.setTimeToLive(5000);</programlisting>
<para>A reaper thread will periodically inspect the queues to check if messages have <para>A reaper thread will periodically inspect the queues to check if messages have
expired.</para> expired.</para>
<para>The reaper thread can be configured with the following properties in <literal <para>The reaper thread can be configured with the following properties in <literal
>hornetq-configuration.xml</literal></para> >activemq-configuration.xml</literal></para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>message-expiry-scan-period</literal></para> <para><literal>message-expiry-scan-period</literal></para>

14
docs/user-manual/en/message-grouping.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="message-grouping"> <chapter id="message-grouping">
@ -28,7 +28,7 @@
<listitem> <listitem>
<para>Messages in a message group share the same group id, i.e. they have same group <para>Messages in a message group share the same group id, i.e. they have same group
identifier property (<literal>JMSXGroupID</literal> for JMS, <literal identifier property (<literal>JMSXGroupID</literal> for JMS, <literal
>_HQ_GROUP_ID</literal> for HornetQ Core API).</para> >_HQ_GROUP_ID</literal> for ActiveMQ Core API).</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Messages in a message group are always consumed by the same consumer, even if there <para>Messages in a message group are always consumed by the same consumer, even if there
@ -79,8 +79,8 @@
message.setStringProperty("JMSXGroupID", "Group-0"); message.setStringProperty("JMSXGroupID", "Group-0");
producer.send(message);</programlisting> producer.send(message);</programlisting>
<para>Alternatively, you can set <literal>autogroup</literal> to true on the <literal <para>Alternatively, you can set <literal>autogroup</literal> to true on the <literal
>HornetQConnectonFactory</literal> which will pick a random unique id. This can also be >ActiveMQConnectonFactory</literal> which will pick a random unique id. This can also be
set in the <literal>hornetq-jms.xml</literal> file like this:</para> set in the <literal>activemq-jms.xml</literal> file like this:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;connectors> &lt;connectors>
@ -94,7 +94,7 @@
<para>Alternatively you can set the group id via the connection factory. All messages sent <para>Alternatively you can set the group id via the connection factory. All messages sent
with producers created via this connection factory will set the <literal with producers created via this connection factory will set the <literal
>JMSXGroupID</literal> to the specified value on all messages sent. To configure the >JMSXGroupID</literal> to the specified value on all messages sent. To configure the
group id set it on the connection factory in the <literal>hornetq-jms.xml</literal> config group id set it on the connection factory in the <literal>activemq-jms.xml</literal> config
file as follows file as follows
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
@ -132,7 +132,7 @@
local handler that actually makes the decision as to what route should be used, all the local handler that actually makes the decision as to what route should be used, all the
other remote handlers converse with this. Here is a sample config for both types of other remote handlers converse with this. Here is a sample config for both types of
handler, this should be configured in the <emphasis role="italic" handler, this should be configured in the <emphasis role="italic"
>hornetq-configuration.xml</emphasis> >activemq-configuration.xml</emphasis>
file.<programlisting> file.<programlisting>
&lt;grouping-handler name="my-grouping-handler"> &lt;grouping-handler name="my-grouping-handler">
&lt;type>LOCAL&lt;/type> &lt;type>LOCAL&lt;/type>
@ -201,7 +201,7 @@
<section> <section>
<title>Clustered Grouping Example</title> <title>Clustered Grouping Example</title>
<para>See <xref linkend="examples.clustered.grouping"/> for an example of how to configure <para>See <xref linkend="examples.clustered.grouping"/> for an example of how to configure
message groups with a HornetQ cluster</para> message groups with a ActiveMQ cluster</para>
</section> </section>
</section> </section>
</chapter> </chapter>

28
docs/user-manual/en/messaging-concepts.xml
View File

@ -18,12 +18,12 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="messaging-concepts"> <chapter id="messaging-concepts">
<title>Messaging Concepts</title> <title>Messaging Concepts</title>
<para>HornetQ is an asynchronous messaging system, an example of <ulink <para>ActiveMQ is an asynchronous messaging system, an example of <ulink
url="http://en.wikipedia.org/wiki/Message_oriented_middleware">Message Oriented url="http://en.wikipedia.org/wiki/Message_oriented_middleware">Message Oriented
Middleware</ulink> , we'll just call them messaging systems in the remainder of this Middleware</ulink> , we'll just call them messaging systems in the remainder of this
book.</para> book.</para>
@ -141,7 +141,7 @@
<section> <section>
<title>Transactions</title> <title>Transactions</title>
<para>Messaging systems typically support the sending and acknowledgement of multiple <para>Messaging systems typically support the sending and acknowledgement of multiple
messages in a single local transaction. HornetQ also supports the sending and messages in a single local transaction. ActiveMQ also supports the sending and
acknowledgement of message as part of a large global transaction - using the Java acknowledgement of message as part of a large global transaction - using the Java
mapping of XA: JTA.</para> mapping of XA: JTA.</para>
</section> </section>
@ -175,7 +175,7 @@
<para>JMS does not define a standard wire format - it only defines a programmatic API so <para>JMS does not define a standard wire format - it only defines a programmatic API so
JMS clients and servers from different vendors cannot directly interoperate since JMS clients and servers from different vendors cannot directly interoperate since
each will use the vendor's own internal wire protocol.</para> each will use the vendor's own internal wire protocol.</para>
<para>HornetQ provides a fully compliant JMS 1.1 and JMS 2.0 API.</para> <para>ActiveMQ provides a fully compliant JMS 1.1 and JMS 2.0 API.</para>
</section> </section>
<section> <section>
<title>System specific APIs</title> <title>System specific APIs</title>
@ -184,7 +184,7 @@
functionality to be exposed to the client application. API's like JMS are not functionality to be exposed to the client application. API's like JMS are not
normally rich enough to expose all the extra features that most messaging systems normally rich enough to expose all the extra features that most messaging systems
provide.</para> provide.</para>
<para>HornetQ provides its own core client API for clients to use if they wish to have <para>ActiveMQ provides its own core client API for clients to use if they wish to have
access to functionality over and above that accessible via the JMS API.</para> access to functionality over and above that accessible via the JMS API.</para>
</section> </section>
<section> <section>
@ -201,7 +201,7 @@
protocol.</para> protocol.</para>
<para>The advantage of a REST approach with HTTP is in its simplicity and the fact the <para>The advantage of a REST approach with HTTP is in its simplicity and the fact the
internet is already tuned to deal with HTTP optimally.</para> internet is already tuned to deal with HTTP optimally.</para>
<para>Please see <xref linkend="rest"/> for using HornetQ's RESTful interface.</para> <para>Please see <xref linkend="rest"/> for using ActiveMQ's RESTful interface.</para>
</section> </section>
<section> <section>
<title>STOMP</title> <title>STOMP</title>
@ -211,7 +211,7 @@
systems. It defines a wire format, so theoretically any Stomp client can work with systems. It defines a wire format, so theoretically any Stomp client can work with
any messaging system that supports Stomp. Stomp clients are available in many any messaging system that supports Stomp. Stomp clients are available in many
different programming languages.</para> different programming languages.</para>
<para>Please see <xref linkend="stomp"/> for using STOMP with HornetQ.</para> <para>Please see <xref linkend="stomp"/> for using STOMP with ActiveMQ.</para>
</section> </section>
<section> <section>
<title>AMQP</title> <title>AMQP</title>
@ -219,8 +219,8 @@
interoperable messaging. It also defines a wire format, so any AMQP client can work interoperable messaging. It also defines a wire format, so any AMQP client can work
with any messaging system that supports AMQP. AMQP clients are available in many with any messaging system that supports AMQP. AMQP clients are available in many
different programming languages.</para> different programming languages.</para>
<para>HornetQ implements the <ulink url="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp">AMQP 1.0</ulink> <para>ActiveMQ implements the <ulink url="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp">AMQP 1.0</ulink>
specification. Any client that supports the 1.0 specification will be able to interact with HornetQ.</para> specification. Any client that supports the 1.0 specification will be able to interact with ActiveMQ.</para>
</section> </section>
</section> </section>
<section> <section>
@ -228,7 +228,7 @@
<para>High Availability (HA) means that the system should remain operational after failure <para>High Availability (HA) means that the system should remain operational after failure
of one or more of the servers. The degree of support for HA varies between various of one or more of the servers. The degree of support for HA varies between various
messaging systems.</para> messaging systems.</para>
<para>HornetQ provides automatic failover where your sessions are automatically reconnected <para>ActiveMQ provides automatic failover where your sessions are automatically reconnected
to the backup server on event of live server failure.</para> to the backup server on event of live server failure.</para>
<para>For more information on HA, please see <xref linkend="ha"/>.</para> <para>For more information on HA, please see <xref linkend="ha"/>.</para>
</section> </section>
@ -241,10 +241,10 @@
<para>Degrees of support for clusters varies between messaging systems, with some systems <para>Degrees of support for clusters varies between messaging systems, with some systems
having fairly basic clusters with the cluster members being hardly aware of each having fairly basic clusters with the cluster members being hardly aware of each
other.</para> other.</para>
<para>HornetQ provides very configurable state-of-the-art clustering model where messages <para>ActiveMQ provides very configurable state-of-the-art clustering model where messages
can be intelligently load balanced between the servers in the cluster, according to the can be intelligently load balanced between the servers in the cluster, according to the
number of consumers on each node, and whether they are ready for messages.</para> number of consumers on each node, and whether they are ready for messages.</para>
<para>HornetQ also has the ability to automatically redistribute messages between nodes of a <para>ActiveMQ also has the ability to automatically redistribute messages between nodes of a
cluster to prevent starvation on any particular node.</para> cluster to prevent starvation on any particular node.</para>
<para>For full details on clustering, please see <xref linkend="clusters"/>.</para> <para>For full details on clustering, please see <xref linkend="clusters"/>.</para>
</section> </section>
@ -256,9 +256,9 @@
<para>A bridge normally consumes from a queue on one server and forwards messages to another <para>A bridge normally consumes from a queue on one server and forwards messages to another
queue on a different server. Bridges cope with unreliable connections, automatically queue on a different server. Bridges cope with unreliable connections, automatically
reconnecting when the connections becomes available again.</para> reconnecting when the connections becomes available again.</para>
<para>HornetQ bridges can be configured with filter expressions to only forward certain <para>ActiveMQ bridges can be configured with filter expressions to only forward certain
messages, and transformation can also be hooked in.</para> messages, and transformation can also be hooked in.</para>
<para>HornetQ also allows routing between queues to be configured in server side <para>ActiveMQ also allows routing between queues to be configured in server side
configuration. This allows complex routing networks to be set up forwarding or copying configuration. This allows complex routing networks to be set up forwarding or copying
messages from one destination to another, forming a global network of interconnected messages from one destination to another, forming a global network of interconnected
brokers.</para> brokers.</para>

2
docs/user-manual/en/notice.xml
View File

@ -17,7 +17,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>

20
docs/user-manual/en/paging.xml
View File

@ -17,19 +17,19 @@
<!-- permitted by applicable law. --> <!-- permitted by applicable law. -->
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="paging"> <chapter id="paging">
<title>Paging</title> <title>Paging</title>
<para>HornetQ transparently supports huge queues containing millions of messages while the <para>ActiveMQ transparently supports huge queues containing millions of messages while the
server is running with limited memory.</para> server is running with limited memory.</para>
<para>In such a situation it's not possible to store all of the queues in memory at any one <para>In such a situation it's not possible to store all of the queues in memory at any one
time, so HornetQ transparently <emphasis>pages</emphasis> messages into and out of memory as time, so ActiveMQ transparently <emphasis>pages</emphasis> messages into and out of memory as
they are needed, thus allowing massive queues with a low memory footprint.</para> they are needed, thus allowing massive queues with a low memory footprint.</para>
<para>HornetQ will start paging messages to disk, when the size of all messages in memory for an <para>ActiveMQ will start paging messages to disk, when the size of all messages in memory for an
address exceeds a configured maximum size.</para> address exceeds a configured maximum size.</para>
<para>By default, HornetQ does not page messages - this must be explicitly configured to <para>By default, ActiveMQ does not page messages - this must be explicitly configured to
activate it.</para> activate it.</para>
<section> <section>
<title>Page Files</title> <title>Page Files</title>
@ -46,11 +46,11 @@
<title>Configuration</title> <title>Configuration</title>
<para>You can configure the location of the paging folder</para> <para>You can configure the location of the paging folder</para>
<para>Global paging parameters are specified on the main configuration file (<literal <para>Global paging parameters are specified on the main configuration file (<literal
>hornetq-configuration.xml</literal>).</para> >activemq-configuration.xml</literal>).</para>
<programlisting> <programlisting>
&lt;configuration xmlns="urn:activemq" &lt;configuration xmlns="urn:activemq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:hornetq /schema/activemq-configuration.xsd"> xsi:schemaLocation="urn:activemq /schema/activemq-configuration.xsd">
... ...
&lt;paging-directory>/somewhere/paging-directory&lt;/paging-directory> &lt;paging-directory>/somewhere/paging-directory&lt;/paging-directory>
...</programlisting> ...</programlisting>
@ -71,7 +71,7 @@
<tbody> <tbody>
<row> <row>
<entry><literal>paging-directory</literal></entry> <entry><literal>paging-directory</literal></entry>
<entry>Where page files are stored. HornetQ will create one folder for <entry>Where page files are stored. ActiveMQ will create one folder for
each address being paged under this configured location.</entry> each address being paged under this configured location.</entry>
<entry>data/paging</entry> <entry>data/paging</entry>
</row> </row>
@ -93,7 +93,7 @@
<section> <section>
<title>Configuration</title> <title>Configuration</title>
<para>Configuration is done at the address settings, done at the main configuration file <para>Configuration is done at the address settings, done at the main configuration file
(<literal>hornetq-configuration.xml</literal>).</para> (<literal>activemq-configuration.xml</literal>).</para>
<programlisting> <programlisting>
&lt;address-settings> &lt;address-settings>
&lt;address-setting match="jms.someaddress"> &lt;address-setting match="jms.someaddress">
@ -211,6 +211,6 @@
<section> <section>
<title>Example</title> <title>Example</title>
<para>See <xref linkend="examples.paging"/> for an example which shows how to use paging <para>See <xref linkend="examples.paging"/> for an example which shows how to use paging
with HornetQ.</para> with ActiveMQ.</para>
</section> </section>
</chapter> </chapter>

30
docs/user-manual/en/perf-tuning.xml
View File

@ -18,12 +18,12 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="perf-tuning"> <chapter id="perf-tuning">
<title>Performance Tuning</title> <title>Performance Tuning</title>
<para>In this chapter we'll discuss how to tune HornetQ for optimum performance.</para> <para>In this chapter we'll discuss how to tune ActiveMQ for optimum performance.</para>
<section> <section>
<title>Tuning persistence</title> <title>Tuning persistence</title>
<itemizedlist> <itemizedlist>
@ -105,7 +105,7 @@
incur a lot more overhead in persisting them to storage.</para> incur a lot more overhead in persisting them to storage.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Batch many sends or acknowledgements in a single transaction. HornetQ will <para>Batch many sends or acknowledgements in a single transaction. ActiveMQ will
only require a network round trip on the commit, not on every send or only require a network round trip on the commit, not on every send or
acknowledgement.</para> acknowledgement.</para>
</listitem> </listitem>
@ -113,7 +113,7 @@
</section> </section>
<section> <section>
<title>Other Tunings</title> <title>Other Tunings</title>
<para>There are various other places in HornetQ where we can perform some tuning:</para> <para>There are various other places in ActiveMQ where we can perform some tuning:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Use Asynchronous Send Acknowledgements. If you need to send durable messages <para>Use Asynchronous Send Acknowledgements. If you need to send durable messages
@ -132,17 +132,17 @@
<listitem> <listitem>
<para>Disable security. You may get a small performance boost by disabling security <para>Disable security. You may get a small performance boost by disabling security
by setting the <literal>security-enabled</literal> parameter to <literal by setting the <literal>security-enabled</literal> parameter to <literal
>false</literal> in <literal>hornetq-configuration.xml</literal>.</para> >false</literal> in <literal>activemq-configuration.xml</literal>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Disable persistence. If you don't need message persistence, turn it off <para>Disable persistence. If you don't need message persistence, turn it off
altogether by setting <literal>persistence-enabled</literal> to false in altogether by setting <literal>persistence-enabled</literal> to false in
<literal>hornetq-configuration.xml</literal>.</para> <literal>activemq-configuration.xml</literal>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Sync transactions lazily. Setting <literal <para>Sync transactions lazily. Setting <literal
>journal-sync-transactional</literal> to <literal>false</literal> in >journal-sync-transactional</literal> to <literal>false</literal> in
<literal>hornetq-configuration.xml</literal> can give you better <literal>activemq-configuration.xml</literal> can give you better
transactional persistent performance at the expense of some possibility of loss transactional persistent performance at the expense of some possibility of loss
of transactions on failure. See <xref linkend="send-guarantees"/> for more of transactions on failure. See <xref linkend="send-guarantees"/> for more
information.</para> information.</para>
@ -150,7 +150,7 @@
<listitem> <listitem>
<para>Sync non transactional lazily. Setting <literal <para>Sync non transactional lazily. Setting <literal
>journal-sync-non-transactional</literal> to <literal>false</literal> in >journal-sync-non-transactional</literal> to <literal>false</literal> in
<literal>hornetq-configuration.xml</literal> can give you better <literal>activemq-configuration.xml</literal> can give you better
non-transactional persistent performance at the expense of some possibility of non-transactional persistent performance at the expense of some possibility of
loss of durable messages on failure. See <xref linkend="send-guarantees"/> for loss of durable messages on failure. See <xref linkend="send-guarantees"/> for
more information.</para> more information.</para>
@ -158,7 +158,7 @@
<listitem> <listitem>
<para>Send messages non blocking. Setting <literal>block-on-durable-send</literal> <para>Send messages non blocking. Setting <literal>block-on-durable-send</literal>
and <literal>block-on-non-durable-send</literal> to <literal>false</literal> in and <literal>block-on-non-durable-send</literal> to <literal>false</literal> in
<literal>hornetq-jms.xml</literal> (if you're using JMS and JNDI) or <literal>activemq-jms.xml</literal> (if you're using JMS and JNDI) or
directly on the ServerLocator. This means you don't have to wait a whole directly on the ServerLocator. This means you don't have to wait a whole
network round trip for every message sent. See <xref linkend="send-guarantees"/> network round trip for every message sent. See <xref linkend="send-guarantees"/>
for more information.</para> for more information.</para>
@ -168,7 +168,7 @@
effectively disables consumer flow control.</para> effectively disables consumer flow control.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Socket NIO vs Socket Old IO. By default HornetQ uses old (blocking) on the <para>Socket NIO vs Socket Old IO. By default ActiveMQ uses old (blocking) on the
server and the client side (see the chapter on configuring transports for more server and the client side (see the chapter on configuring transports for more
information <xref linkend="configuring-transports"/>). NIO is much more scalable information <xref linkend="configuring-transports"/>). NIO is much more scalable
but can give you some latency hit compared to old blocking IO. If you need to be but can give you some latency hit compared to old blocking IO. If you need to be
@ -218,11 +218,11 @@ serveruser hard nofile 20000</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>Use <literal>batch-delay</literal> and set <literal>direct-deliver</literal> <para>Use <literal>batch-delay</literal> and set <literal>direct-deliver</literal>
to false for the best throughput for very small messages. HornetQ comes with a to false for the best throughput for very small messages. ActiveMQ comes with a
preconfigured connector/acceptor pair (<literal>netty-throughput</literal>) in preconfigured connector/acceptor pair (<literal>netty-throughput</literal>) in
<literal>hornetq-configuration.xml</literal> and JMS connection factory <literal>activemq-configuration.xml</literal> and JMS connection factory
(<literal>ThroughputConnectionFactory</literal>) in <literal (<literal>ThroughputConnectionFactory</literal>) in <literal
>hornetq-jms.xml</literal>which can be used to give the very best >activemq-jms.xml</literal>which can be used to give the very best
throughput, especially for small messages. See the <xref throughput, especially for small messages. See the <xref
linkend="configuring-transports"/> for more information on this.</para> linkend="configuring-transports"/> for more information on this.</para>
</listitem> </listitem>
@ -240,7 +240,7 @@ serveruser hard nofile 20000</programlisting>
>-XX:+UseParallelOldGC</literal> on Sun JDKs.</para> >-XX:+UseParallelOldGC</literal> on Sun JDKs.</para>
</listitem> </listitem>
<listitem id="perf-tuning.memory"> <listitem id="perf-tuning.memory">
<para>Memory settings. Give as much memory as you can to the server. HornetQ can run <para>Memory settings. Give as much memory as you can to the server. ActiveMQ can run
in low memory by using paging (described in <xref linkend="paging"/>) but if it in low memory by using paging (described in <xref linkend="paging"/>) but if it
can run with all queues in RAM this will improve performance. The amount of can run with all queues in RAM this will improve performance. The amount of
memory you require will depend on the size and number of your queues and the memory you require will depend on the size and number of your queues and the
@ -272,7 +272,7 @@ serveruser hard nofile 20000</programlisting>
<note> <note>
<para>Some popular libraries such as the Spring JMS Template are known to use <para>Some popular libraries such as the Spring JMS Template are known to use
these anti-patterns. If you're using Spring JMS Template and you're getting these anti-patterns. If you're using Spring JMS Template and you're getting
poor performance you know why. Don't blame HornetQ! The Spring JMS Template poor performance you know why. Don't blame ActiveMQ! The Spring JMS Template
can only safely be used in an app server which caches JMS sessions (e.g. can only safely be used in an app server which caches JMS sessions (e.g.
using JCA), and only then for sending messages. It cannot be safely be used using JCA), and only then for sending messages. It cannot be safely be used
for synchronously consuming messages, even in an app server. </para> for synchronously consuming messages, even in an app server. </para>

64
docs/user-manual/en/persistence.xml
View File

@ -18,17 +18,17 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="persistence"> <chapter id="persistence">
<title>Persistence</title> <title>Persistence</title>
<para>In this chapter we will describe how persistence works with HornetQ and how to configure <para>In this chapter we will describe how persistence works with ActiveMQ and how to configure
it.</para> it.</para>
<para>HornetQ ships with a high performance journal. Since HornetQ handles its own persistence, <para>ActiveMQ ships with a high performance journal. Since ActiveMQ handles its own persistence,
rather than relying on a database or other 3rd party persistence engine it is very highly rather than relying on a database or other 3rd party persistence engine it is very highly
optimised for the specific messaging use cases.</para> optimised for the specific messaging use cases.</para>
<para>A HornetQ journal is an <emphasis>append only</emphasis> journal. It consists of a set of <para>A ActiveMQ journal is an <emphasis>append only</emphasis> journal. It consists of a set of
files on disk. Each file is pre-created to a fixed size and initially filled with padding. files on disk. Each file is pre-created to a fixed size and initially filled with padding.
As operations are performed on the server, e.g. add message, update message, delete message, As operations are performed on the server, e.g. add message, update message, delete message,
records are appended to the journal. When one journal file is full we move to the next records are appended to the journal. When one journal file is full we move to the next
@ -42,16 +42,16 @@
by minimising the number of disk cylinders the file is using, we can minimise the amount of by minimising the number of disk cylinders the file is using, we can minimise the amount of
disk head movement, since an entire disk cylinder is accessible simply by the disk rotating disk head movement, since an entire disk cylinder is accessible simply by the disk rotating
- the head does not have to move.</para> - the head does not have to move.</para>
<para>As delete records are added to the journal, HornetQ has a sophisticated file garbage <para>As delete records are added to the journal, ActiveMQ has a sophisticated file garbage
collection algorithm which can determine if a particular journal file is needed any more - collection algorithm which can determine if a particular journal file is needed any more -
i.e. has all its data been deleted in the same or other files. If so, the file can be i.e. has all its data been deleted in the same or other files. If so, the file can be
reclaimed and re-used. </para> reclaimed and re-used. </para>
<para>HornetQ also has a compaction algorithm which removes dead space from the journal and <para>ActiveMQ also has a compaction algorithm which removes dead space from the journal and
compresses up the data so it takes up less files on disk.</para> compresses up the data so it takes up less files on disk.</para>
<para>The journal also fully supports transactional operation if required, supporting both local <para>The journal also fully supports transactional operation if required, supporting both local
and XA transactions.</para> and XA transactions.</para>
<para>The majority of the journal is written in Java, however we abstract out the interaction <para>The majority of the journal is written in Java, however we abstract out the interaction
with the actual file system to allow different pluggable implementations. HornetQ ships with with the actual file system to allow different pluggable implementations. ActiveMQ ships with
two implementations:</para> two implementations:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -63,7 +63,7 @@
<listitem id="aio-journal"> <listitem id="aio-journal">
<para>Linux Asynchronous IO</para> <para>Linux Asynchronous IO</para>
<para>The second implementation uses a thin native code wrapper to talk to the Linux <para>The second implementation uses a thin native code wrapper to talk to the Linux
asynchronous IO library (AIO). With AIO, HornetQ will be called back when the data asynchronous IO library (AIO). With AIO, ActiveMQ will be called back when the data
has made it to disk, allowing us to avoid explicit syncs altogether and simply send has made it to disk, allowing us to avoid explicit syncs altogether and simply send
back confirmation of completion when AIO informs us that the data has been back confirmation of completion when AIO informs us that the data has been
persisted.</para> persisted.</para>
@ -80,7 +80,7 @@
<para>libaio is part of the kernel project.</para> <para>libaio is part of the kernel project.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>The standard HornetQ core server uses two instances of the journal:</para> <para>The standard ActiveMQ core server uses two instances of the journal:</para>
<itemizedlist id="persistence.journallist"> <itemizedlist id="persistence.journallist">
<listitem> <listitem>
<para>Bindings journal.</para> <para>Bindings journal.</para>
@ -89,7 +89,7 @@
such as id sequence counters. </para> such as id sequence counters. </para>
<para>The bindings journal is always a NIO journal as it is typically low throughput <para>The bindings journal is always a NIO journal as it is typically low throughput
compared to the message journal.</para> compared to the message journal.</para>
<para>The files on this journal are prefixed as <literal>hornetq-bindings</literal>. <para>The files on this journal are prefixed as <literal>activemq-bindings</literal>.
Each file has a <literal>bindings</literal> extension. File size is <literal Each file has a <literal>bindings</literal> extension. File size is <literal
>1048576</literal>, and it is located at the bindings folder.</para> >1048576</literal>, and it is located at the bindings folder.</para>
</listitem> </listitem>
@ -101,7 +101,7 @@
<para>Any JMS Resources created via the management API will be persisted to this <para>Any JMS Resources created via the management API will be persisted to this
journal. Any resources configured via configuration files will not. The JMS Journal journal. Any resources configured via configuration files will not. The JMS Journal
will only be created if JMS is being used.</para> will only be created if JMS is being used.</para>
<para>The files on this journal are prefixed as <literal>hornetq-jms</literal>. Each <para>The files on this journal are prefixed as <literal>activemq-jms</literal>. Each
file has a <literal>jms</literal> extension. File size is <literal file has a <literal>jms</literal> extension. File size is <literal
>1048576</literal>, and it is located at the bindings folder.</para> >1048576</literal>, and it is located at the bindings folder.</para>
</listitem> </listitem>
@ -109,26 +109,26 @@
<para>Message journal.</para> <para>Message journal.</para>
<para>This journal instance stores all message related data, including the message <para>This journal instance stores all message related data, including the message
themselves and also duplicate-id caches.</para> themselves and also duplicate-id caches.</para>
<para>By default HornetQ will try and use an AIO journal. If AIO is not available, e.g. <para>By default ActiveMQ will try and use an AIO journal. If AIO is not available, e.g.
the platform is not Linux with the correct kernel version or AIO has not been the platform is not Linux with the correct kernel version or AIO has not been
installed then it will automatically fall back to using Java NIO which is available installed then it will automatically fall back to using Java NIO which is available
on any Java platform.</para> on any Java platform.</para>
<para>The files on this journal are prefixed as <literal>hornetq-data</literal>. Each <para>The files on this journal are prefixed as <literal>activemq-data</literal>. Each
file has a <literal>hq</literal> extension. File size is by the default <literal file has a <literal>hq</literal> extension. File size is by the default <literal
>10485760</literal> (configurable), and it is located at the journal >10485760</literal> (configurable), and it is located at the journal
folder.</para> folder.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>For large messages, HornetQ persists them outside the message journal. This is discussed <para>For large messages, ActiveMQ persists them outside the message journal. This is discussed
in <xref linkend="large-messages"/>.</para> in <xref linkend="large-messages"/>.</para>
<para>HornetQ can also be configured to page messages to disk in low memory situations. This is <para>ActiveMQ can also be configured to page messages to disk in low memory situations. This is
discussed in <xref linkend="paging"/>.</para> discussed in <xref linkend="paging"/>.</para>
<para>If no persistence is required at all, HornetQ can also be configured not to persist any <para>If no persistence is required at all, ActiveMQ can also be configured not to persist any
data at all to storage as discussed in <xref linkend="persistence.enabled"/>.</para> data at all to storage as discussed in <xref linkend="persistence.enabled"/>.</para>
<section id="configuring.bindings.journal"> <section id="configuring.bindings.journal">
<title>Configuring the bindings journal</title> <title>Configuring the bindings journal</title>
<para>The bindings journal is configured using the following attributes in <literal <para>The bindings journal is configured using the following attributes in <literal
>hornetq-configuration.xml</literal></para> >activemq-configuration.xml</literal></para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>bindings-directory</literal></para> <para><literal>bindings-directory</literal></para>
@ -151,7 +151,7 @@
<section id="configuring.message.journal"> <section id="configuring.message.journal">
<title>Configuring the message journal</title> <title>Configuring the message journal</title>
<para>The message journal is configured using the following attributes in <literal <para>The message journal is configured using the following attributes in <literal
>hornetq-configuration.xml</literal></para> >activemq-configuration.xml</literal></para>
<itemizedlist> <itemizedlist>
<listitem id="configuring.message.journal.journal-directory"> <listitem id="configuring.message.journal.journal-directory">
<para><literal>journal-directory</literal></para> <para><literal>journal-directory</literal></para>
@ -179,18 +179,18 @@
<para>Choosing <literal>NIO</literal> chooses the Java NIO journal. Choosing <para>Choosing <literal>NIO</literal> chooses the Java NIO journal. Choosing
<literal>AIO</literal> chooses the Linux asynchronous IO journal. If you <literal>AIO</literal> chooses the Linux asynchronous IO journal. If you
choose <literal>AIO</literal> but are not running Linux or you do not have choose <literal>AIO</literal> but are not running Linux or you do not have
libaio installed then HornetQ will detect this and automatically fall back to libaio installed then ActiveMQ will detect this and automatically fall back to
using <literal>NIO</literal>.</para> using <literal>NIO</literal>.</para>
</listitem> </listitem>
<listitem id="configuring.message.journal.journal-sync-transactional"> <listitem id="configuring.message.journal.journal-sync-transactional">
<para><literal>journal-sync-transactional</literal></para> <para><literal>journal-sync-transactional</literal></para>
<para>If this is set to true then HornetQ will make sure all transaction data is <para>If this is set to true then ActiveMQ will make sure all transaction data is
flushed to disk on transaction boundaries (commit, prepare and rollback). The flushed to disk on transaction boundaries (commit, prepare and rollback). The
default value is <literal>true</literal>.</para> default value is <literal>true</literal>.</para>
</listitem> </listitem>
<listitem id="configuring.message.journal.journal-sync-non-transactional"> <listitem id="configuring.message.journal.journal-sync-non-transactional">
<para><literal>journal-sync-non-transactional</literal></para> <para><literal>journal-sync-non-transactional</literal></para>
<para>If this is set to true then HornetQ will make sure non transactional message <para>If this is set to true then ActiveMQ will make sure non transactional message
data (sends and acknowledgements) are flushed to disk each time. The default data (sends and acknowledgements) are flushed to disk each time. The default
value for this is <literal>true</literal>.</para> value for this is <literal>true</literal>.</para>
</listitem> </listitem>
@ -201,8 +201,8 @@
</listitem> </listitem>
<listitem id="configuring.message.journal.journal-min-files"> <listitem id="configuring.message.journal.journal-min-files">
<para><literal>journal-min-files</literal></para> <para><literal>journal-min-files</literal></para>
<para>The minimum number of files the journal will maintain. When HornetQ starts and <para>The minimum number of files the journal will maintain. When ActiveMQ starts and
there is no initial message data, HornetQ will pre-create <literal there is no initial message data, ActiveMQ will pre-create <literal
>journal-min-files</literal> number of files.</para> >journal-min-files</literal> number of files.</para>
<para>Creating journal files and filling them with padding is a fairly expensive <para>Creating journal files and filling them with padding is a fairly expensive
operation and we want to minimise doing this at run-time as files get filled. By operation and we want to minimise doing this at run-time as files get filled. By
@ -295,7 +295,7 @@
</section> </section>
<section id="installing-aio"> <section id="installing-aio">
<title>Installing AIO</title> <title>Installing AIO</title>
<para>The Java NIO journal gives great performance, but If you are running HornetQ using <para>The Java NIO journal gives great performance, but If you are running ActiveMQ using
Linux Kernel 2.6 or later, we highly recommend you use the <literal>AIO</literal> Linux Kernel 2.6 or later, we highly recommend you use the <literal>AIO</literal>
journal for the very best persistence performance.</para> journal for the very best persistence performance.</para>
<para>It's not possible to use the AIO journal under other operating systems or earlier <para>It's not possible to use the AIO journal under other operating systems or earlier
@ -309,11 +309,11 @@
<programlisting>apt-get install libaio</programlisting></para> <programlisting>apt-get install libaio</programlisting></para>
</section> </section>
<section id="persistence.enabled"> <section id="persistence.enabled">
<title>Configuring HornetQ for Zero Persistence</title> <title>Configuring ActiveMQ for Zero Persistence</title>
<para>In some situations, zero persistence is sometimes required for a messaging system. <para>In some situations, zero persistence is sometimes required for a messaging system.
Configuring HornetQ to perform zero persistence is straightforward. Simply set the Configuring ActiveMQ to perform zero persistence is straightforward. Simply set the
parameter <literal>persistence-enabled</literal> in <literal parameter <literal>persistence-enabled</literal> in <literal
>hornetq-configuration.xml</literal> to <literal>false</literal>. </para> >activemq-configuration.xml</literal> to <literal>false</literal>. </para>
<para>Please note that if you set this parameter to false, then <emphasis>zero</emphasis> <para>Please note that if you set this parameter to false, then <emphasis>zero</emphasis>
persistence will occur. That means no bindings data, message data, large message data, persistence will occur. That means no bindings data, message data, large message data,
duplicate id caches or paging data will be persisted.</para> duplicate id caches or paging data will be persisted.</para>
@ -321,21 +321,21 @@
<section id="persistence.importexport"> <section id="persistence.importexport">
<title>Import/Export the Journal Data</title> <title>Import/Export the Journal Data</title>
<para>You may want to inspect the existent records on each one of the journals used by <para>You may want to inspect the existent records on each one of the journals used by
HornetQ, and you can use the export/import tool for that purpose. The export/import are ActiveMQ, and you can use the export/import tool for that purpose. The export/import are
classes located at the hornetq-core.jar, you can export the journal as a text file by classes located at the activemq-core.jar, you can export the journal as a text file by
using this command:</para> using this command:</para>
<para><literal>java -cp hornetq-core.jar org.apache.activemq.core.journal.impl.ExportJournal <para><literal>java -cp activemq-core.jar org.apache.activemq.core.journal.impl.ExportJournal
&lt;JournalDirectory> &lt;JournalPrefix> &lt;FileExtension> &lt;FileSize> &lt;JournalDirectory> &lt;JournalPrefix> &lt;FileExtension> &lt;FileSize>
&lt;FileOutput></literal></para> &lt;FileOutput></literal></para>
<para>To import the file as binary data on the journal (Notice you also require <para>To import the file as binary data on the journal (Notice you also require
netty.jar):</para> netty.jar):</para>
<para><literal>java -cp hornetq-core.jar:netty.jar org.apache.activemq.core.journal.impl.ImportJournal <para><literal>java -cp activemq-core.jar:netty.jar org.apache.activemq.core.journal.impl.ImportJournal
&lt;JournalDirectory> &lt;JournalPrefix> &lt;FileExtension> &lt;FileSize> &lt;JournalDirectory> &lt;JournalPrefix> &lt;FileExtension> &lt;FileSize>
&lt;FileInput></literal></para> &lt;FileInput></literal></para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>JournalDirectory: Use the configured folder for your selected folder. Example: <para>JournalDirectory: Use the configured folder for your selected folder. Example:
./hornetq/data/journal</para> ./activemq/data/journal</para>
</listitem> </listitem>
<listitem> <listitem>
<para>JournalPrefix: Use the prefix for your selected journal, as discussed <para>JournalPrefix: Use the prefix for your selected journal, as discussed

16
docs/user-manual/en/pre-acknowledge.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="pre-acknowledge"> <chapter id="pre-acknowledge">
@ -35,11 +35,11 @@
<para><literal>DUPS_OK_ACKNOWLEDGE</literal></para> <para><literal>DUPS_OK_ACKNOWLEDGE</literal></para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>HornetQ supports two additional modes: <literal>PRE_ACKNOWLEDGE</literal> and <literal>INDIVIDUAL_ACKNOWLEDGE</literal></para> <para>ActiveMQ supports two additional modes: <literal>PRE_ACKNOWLEDGE</literal> and <literal>INDIVIDUAL_ACKNOWLEDGE</literal></para>
<para>In some cases you can afford <para>In some cases you can afford
to lose messages in event of failure, so it would make sense to acknowledge the message on the to lose messages in event of failure, so it would make sense to acknowledge the message on the
server <emphasis>before</emphasis> delivering it to the client.</para> server <emphasis>before</emphasis> delivering it to the client.</para>
<para>This extra mode is supported by HornetQ and will call it <para>This extra mode is supported by ActiveMQ and will call it
<emphasis>pre-acknowledge</emphasis> mode.</para> <emphasis>pre-acknowledge</emphasis> mode.</para>
<para>The disadvantage of acknowledging on the server before delivery is that the message will be <para>The disadvantage of acknowledging on the server before delivery is that the message will be
lost if the system crashes <emphasis>after</emphasis> acknowledging the message on the server lost if the system crashes <emphasis>after</emphasis> acknowledging the message on the server
@ -58,7 +58,7 @@
</note> </note>
<section id="pre-acknowledge.configure"> <section id="pre-acknowledge.configure">
<title>Using PRE_ACKNOWLEDGE</title> <title>Using PRE_ACKNOWLEDGE</title>
<para>This can be configured in the <literal>hornetq-jms.xml</literal> file on the <literal <para>This can be configured in the <literal>activemq-jms.xml</literal> file on the <literal
>connection factory</literal> like this:</para> >connection factory</literal> like this:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
@ -71,12 +71,12 @@
&lt;pre-acknowledge>true&lt;/pre-acknowledge> &lt;pre-acknowledge>true&lt;/pre-acknowledge>
&lt;/connection-factory></programlisting> &lt;/connection-factory></programlisting>
<para>Alternatively, to use pre-acknowledgement mode using the JMS API, create a JMS Session <para>Alternatively, to use pre-acknowledgement mode using the JMS API, create a JMS Session
with the <literal>HornetQSession.PRE_ACKNOWLEDGE</literal> constant.</para> with the <literal>ActiveMQSession.PRE_ACKNOWLEDGE</literal> constant.</para>
<programlisting> <programlisting>
// messages will be acknowledge on the server *before* being delivered to the client // messages will be acknowledge on the server *before* being delivered to the client
Session session = connection.createSession(false, HornetQJMSConstants.PRE_ACKNOWLEDGE);</programlisting> Session session = connection.createSession(false, ActiveMQJMSConstants.PRE_ACKNOWLEDGE);</programlisting>
<para>Or you can set pre-acknowledge directly on the <literal <para>Or you can set pre-acknowledge directly on the <literal
>HornetQConnectionFactory</literal> instance using the setter method.</para> >ActiveMQConnectionFactory</literal> instance using the setter method.</para>
<para>To use pre-acknowledgement mode using the core API you can set it directly on the <para>To use pre-acknowledgement mode using the core API you can set it directly on the
<literal>ClientSessionFactory</literal> instance using the setter method.</para> <literal>ClientSessionFactory</literal> instance using the setter method.</para>
</section> </section>
@ -84,7 +84,7 @@ Session session = connection.createSession(false, HornetQJMSConstants.PRE_ACKNOW
<title>Individual Acknowledge</title> <title>Individual Acknowledge</title>
<para>A valid use-case for individual acknowledgement would be when you need to have your own scheduling and you don't know when your message processing will be finished. You should prefer having one consumer per thread worker <para>A valid use-case for individual acknowledgement would be when you need to have your own scheduling and you don't know when your message processing will be finished. You should prefer having one consumer per thread worker
but this is not possible in some circumstances depending on how complex is your processing. For that you can use the individual Acknowledgement. </para> but this is not possible in some circumstances depending on how complex is your processing. For that you can use the individual Acknowledgement. </para>
<para>You basically setup Individual ACK by creating a session with the acknowledge mode with <literal>HornetQJMSConstants.INDIVIDUAL_ACKNOWLEDGE</literal>. Individual ACK inherits all the semantics from Client Acknowledge, <para>You basically setup Individual ACK by creating a session with the acknowledge mode with <literal>ActiveMQJMSConstants.INDIVIDUAL_ACKNOWLEDGE</literal>. Individual ACK inherits all the semantics from Client Acknowledge,
with the exception the message is individually acked.</para> with the exception the message is individually acked.</para>
<note> <note>
<para>Please note, that to avoid confusion on MDB processing, Individual ACKNOWLEDGE is not supported through MDBs (or the inbound resource adapter). this is because you have to finish the process of your message inside the MDB. <para>Please note, that to avoid confusion on MDB processing, Individual ACKNOWLEDGE is not supported through MDBs (or the inbound resource adapter). this is because you have to finish the process of your message inside the MDB.

22
docs/user-manual/en/preface.xml
View File

@ -18,36 +18,36 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="preface"> <chapter id="preface">
<title>Preface</title> <title>Preface</title>
<para>What is HornetQ?</para> <para>What is ActiveMQ?</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>HornetQ is an open source project to build a multi-protocol, embeddable, very high <para>ActiveMQ is an open source project to build a multi-protocol, embeddable, very high
performance, clustered, asynchronous messaging system.</para> performance, clustered, asynchronous messaging system.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>HornetQ is an example of Message Oriented Middleware (MoM). For a description of <para>ActiveMQ is an example of Message Oriented Middleware (MoM). For a description of
MoMs and other messaging concepts please see the <xref linkend="messaging-concepts" MoMs and other messaging concepts please see the <xref linkend="messaging-concepts"
/>.</para> />.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>For answers to more questions about what HornetQ is and what it isn't please visit <para>For answers to more questions about what ActiveMQ is and what it isn't please visit
the <ulink url="http://www.jboss.org/community/wiki/HornetQGeneralFAQs">FAQs wiki the <ulink url="http://www.jboss.org/community/wiki/ActiveMQGeneralFAQs">FAQs wiki
page</ulink>.</para> page</ulink>.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>Why use HornetQ? Here are just a few of the reasons:</para> <para>Why use ActiveMQ? Here are just a few of the reasons:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>100% open source software. HornetQ is licensed using the Apache Software License v <para>100% open source software. ActiveMQ is licensed using the Apache Software License v
2.0 to minimise barriers to adoption.</para> 2.0 to minimise barriers to adoption.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>HornetQ is designed with usability in mind.</para> <para>ActiveMQ is designed with usability in mind.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Written in Java. Runs on any platform with a Java 6+ runtime, that's everything <para>Written in Java. Runs on any platform with a Java 6+ runtime, that's everything
@ -63,7 +63,7 @@
and others you won't find anywhere else.</para> and others you won't find anywhere else.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Elegant, clean-cut design with minimal third party dependencies. Run HornetQ <para>Elegant, clean-cut design with minimal third party dependencies. Run ActiveMQ
stand-alone, run it in integrated in your favourite JEE application server, or run stand-alone, run it in integrated in your favourite JEE application server, or run
it embedded inside your own product. It's up to you.</para> it embedded inside your own product. It's up to you.</para>
</listitem> </listitem>
@ -80,7 +80,7 @@
</listitem> </listitem>
<listitem> <listitem>
<para>For a full list of features, please see the <ulink <para>For a full list of features, please see the <ulink
url="http://www.jboss.org/community/wiki/HornetQFeatures">features wiki url="http://www.jboss.org/community/wiki/ActiveMQFeatures">features wiki
page</ulink> .</para> page</ulink> .</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>

34
docs/user-manual/en/project-info.xml
View File

@ -18,17 +18,17 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="project-info"> <chapter id="project-info">
<title>Project Information</title> <title>Project Information</title>
<para>The official HornetQ project page is <ulink url="http://hornetq.org/" <para>The official ActiveMQ project page is <ulink url="http://activemq.org/"
>http://hornetq.org/</ulink>.</para> >http://activemq.org/</ulink>.</para>
<section id="download.software"> <section id="download.software">
<title>Software Download</title> <title>Software Download</title>
<para>The software can be download from the Download page:<ulink <para>The software can be download from the Download page:<ulink
url="http://hornetq.org/downloads.html">http://hornetq.org/downloads.html</ulink></para> url="http://activemq.org/downloads.html">http://activemq.org/downloads.html</ulink></para>
</section> </section>
<section id="download.git"> <section id="download.git">
<title>Project Information</title> <title>Project Information</title>
@ -36,41 +36,41 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Please take a look at our project <ulink <para>Please take a look at our project <ulink
url="http://www.jboss.org/community/wiki/HornetQ">wiki</ulink></para> url="http://www.jboss.org/community/wiki/ActiveMQ">wiki</ulink></para>
</listitem> </listitem>
<listitem> <listitem>
<para>If you have any user questions please use our <ulink <para>If you have any user questions please use our <ulink
url="https://community.jboss.org/en/hornetq">user url="https://community.jboss.org/en/activemq">user
forum</ulink></para> forum</ulink></para>
</listitem> </listitem>
<listitem> <listitem>
<para>If you have development related questions, please use our <ulink <para>If you have development related questions, please use our <ulink
url="https://community.jboss.org/en/hornetq/dev" url="https://community.jboss.org/en/activemq/dev"
>developer forum</ulink></para> >developer forum</ulink></para>
</listitem> </listitem>
<listitem> <listitem>
<para>Pop in and chat to us in our <ulink url="irc://irc.freenode.net:6667/hornetq" <para>Pop in and chat to us in our <ulink url="irc://irc.freenode.net:6667/activemq"
>IRC channel</ulink></para> >IRC channel</ulink></para>
</listitem> </listitem>
<listitem> <listitem>
<para>Our project <ulink url="http://hornetq.blogspot.com/">blog</ulink></para> <para>Our project <ulink url="http://activemq.blogspot.com/">blog</ulink></para>
</listitem> </listitem>
<listitem> <listitem>
<para>Follow us on <ulink url="http://twitter.com/hornetq">twitter</ulink></para> <para>Follow us on <ulink url="http://twitter.com/activemq">twitter</ulink></para>
</listitem> </listitem>
<listitem> <listitem>
<para>HornetQ Git repository is <ulink <para>ActiveMQ Git repository is <ulink
url="https://github.com/hornetq/hornetq" url="https://github.com/activemq/activemq"
>https://github.com/hornetq/hornetq</ulink></para> >https://github.com/activemq/activemq</ulink></para>
</listitem> </listitem>
<listitem> <listitem>
<para>All release tags are available from <ulink <para>All release tags are available from <ulink
url="https://github.com/hornetq/hornetq/tags" url="https://github.com/activemq/activemq/tags"
>https://github.com/hornetq/hornetq/tags</ulink></para> >https://github.com/activemq/activemq/tags</ulink></para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para>Red Hat kindly employs developers to work full time on HornetQ, they are: <itemizedlist> <para>Red Hat kindly employs developers to work full time on ActiveMQ, they are: <itemizedlist>
<listitem> <listitem>
<para>Clebert Suconic (project lead)</para> <para>Clebert Suconic (project lead)</para>
</listitem> </listitem>
@ -84,7 +84,7 @@
<para>Justin Bertram</para> <para>Justin Bertram</para>
</listitem> </listitem>
</itemizedlist></para> </itemizedlist></para>
<para> And many thanks to all our contributors, both old and new who helped create HornetQ, <para> And many thanks to all our contributors, both old and new who helped create ActiveMQ,
for a full list of the people who made it happen, take a look at our <ulink for a full list of the people who made it happen, take a look at our <ulink
url="http://jboss.org.apache.activemq/community/team.html">team page</ulink>. </para> url="http://jboss.org.apache.activemq/community/team.html">team page</ulink>. </para>
</section> </section>

8
docs/user-manual/en/queue-attributes.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="queue-attributes"> <chapter id="queue-attributes">
@ -30,7 +30,7 @@
<title>Predefined Queues</title> <title>Predefined Queues</title>
<para>Queues can be predefined via configuration at a core level or at a JMS level. Firstly <para>Queues can be predefined via configuration at a core level or at a JMS level. Firstly
let's look at a JMS level.</para> let's look at a JMS level.</para>
<para>The following shows a queue predefined in the <literal>hornetq-jms.xml</literal> <para>The following shows a queue predefined in the <literal>activemq-jms.xml</literal>
configuration file.</para> configuration file.</para>
<programlisting> <programlisting>
&lt;queue name="selectorQueue"> &lt;queue name="selectorQueue">
@ -50,7 +50,7 @@
<para>The durable element specifies whether the queue will be persisted. This again is <para>The durable element specifies whether the queue will be persisted. This again is
optional and defaults to true if omitted.</para> optional and defaults to true if omitted.</para>
<para>Secondly a queue can be predefined at a core level in the <literal <para>Secondly a queue can be predefined at a core level in the <literal
>hornetq-configuration.xml</literal> file. The following is an example.</para> >activemq-configuration.xml</literal> file. The following is an example.</para>
<programlisting> <programlisting>
&lt;queues> &lt;queues>
&lt;queue name="jms.queue.selectorQueue"> &lt;queue name="jms.queue.selectorQueue">
@ -95,7 +95,7 @@
<title>Configuring Queues Via Address Settings</title> <title>Configuring Queues Via Address Settings</title>
<para>There are some attributes that are defined against an address wildcard rather than a <para>There are some attributes that are defined against an address wildcard rather than a
specific queue. Here an example of an <literal>address-setting</literal> entry that specific queue. Here an example of an <literal>address-setting</literal> entry that
would be found in the <literal>hornetq-configuration.xml</literal> file.</para> would be found in the <literal>activemq-configuration.xml</literal> file.</para>
<programlisting> <programlisting>
&lt;address-settings> &lt;address-settings>
&lt;address-setting match="jms.queue.exampleQueue"> &lt;address-setting match="jms.queue.exampleQueue">

158
docs/user-manual/en/rest.xml
View File

@ -19,8 +19,8 @@
<chapter id="rest"> <chapter id="rest">
<title>REST Interface</title> <title>REST Interface</title>
<para>The HornetQ REST interface allows you to leverage the reliability <para>The ActiveMQ REST interface allows you to leverage the reliability
and scalability features of HornetQ over a simple REST/HTTP interface. and scalability features of ActiveMQ over a simple REST/HTTP interface.
Messages are produced and consumed by sending and receiving simple HTTP Messages are produced and consumed by sending and receiving simple HTTP
messages that contain the content you want to push around. For instance, messages that contain the content you want to push around. For instance,
here's a simple example of posting an order to an order processing queue here's a simple example of posting an order to an order processing queue
@ -40,7 +40,7 @@ Content-Type: application/xml
<para>As you can see, we're just posting some arbitrary XML <para>As you can see, we're just posting some arbitrary XML
document to a URL. When the XML is received on the server is it processed document to a URL. When the XML is received on the server is it processed
within HornetQ as a JMS message and distributed through core HornetQ. within ActiveMQ as a JMS message and distributed through core ActiveMQ.
Simple and easy. Consuming messages from a queue or topic looks very Simple and easy. Consuming messages from a queue or topic looks very
similar. We'll discuss the entire interface in detail later in this similar. We'll discuss the entire interface in detail later in this
docbook. docbook.
@ -49,7 +49,7 @@ Content-Type: application/xml
<section> <section>
<title>Goals of REST Interface</title> <title>Goals of REST Interface</title>
<para>Why would you want to use HornetQ's REST interface? What are the <para>Why would you want to use ActiveMQ's REST interface? What are the
goals of the REST interface? goals of the REST interface?
</para> </para>
@ -59,10 +59,10 @@ Content-Type: application/xml
</listitem> </listitem>
<listitem> <listitem>
<para>Zero client footprint. We want HornetQ to be usable by any <para>Zero client footprint. We want ActiveMQ to be usable by any
client/programming language that has an adequate HTTP client client/programming language that has an adequate HTTP client
library. You shouldn't have to download, install, and configure a library. You shouldn't have to download, install, and configure a
special library to interact with HornetQ. special library to interact with ActiveMQ.
</para> </para>
</listitem> </listitem>
@ -72,7 +72,7 @@ Content-Type: application/xml
RESTful the HTTP uniform interface provides all the interoperability RESTful the HTTP uniform interface provides all the interoperability
you need to communicate between different languages, platforms, and you need to communicate between different languages, platforms, and
even messaging implementations that choose to implement the same even messaging implementations that choose to implement the same
RESTful interface as HornetQ (i.e. the RESTful interface as ActiveMQ (i.e. the
<ulink url="http://rest-star.org">REST-*</ulink> effort.) <ulink url="http://rest-star.org">REST-*</ulink> effort.)
</para> </para>
</listitem> </listitem>
@ -81,13 +81,13 @@ Content-Type: application/xml
<para>No envelope (e.g. SOAP) or feed (e.g. Atom) format <para>No envelope (e.g. SOAP) or feed (e.g. Atom) format
requirements. You shouldn't have to learn, use, or parse a specific requirements. You shouldn't have to learn, use, or parse a specific
XML document format in order to send and receive messages through XML document format in order to send and receive messages through
HornetQ's REST interface. ActiveMQ's REST interface.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para>Leverage the reliability, scalability, and clustering features <para>Leverage the reliability, scalability, and clustering features
of HornetQ on the back end without sacrificing the simplicity of a of ActiveMQ on the back end without sacrificing the simplicity of a
REST interface. REST interface.
</para> </para>
</listitem> </listitem>
@ -98,22 +98,22 @@ Content-Type: application/xml
<section id="install"> <section id="install">
<title>Installation and Configuration</title> <title>Installation and Configuration</title>
<para>HornetQ's REST interface is installed as a Web archive (WAR). It <para>ActiveMQ's REST interface is installed as a Web archive (WAR). It
depends on the depends on the
<ulink url="http://jboss.org/resteasy">RESTEasy</ulink> <ulink url="http://jboss.org/resteasy">RESTEasy</ulink>
project and can currently only run within a servlet container. Installing project and can currently only run within a servlet container. Installing
the HornetQ REST interface is a little bit different depending whether the ActiveMQ REST interface is a little bit different depending whether
HornetQ is already installed and configured for your environment (e.g. ActiveMQ is already installed and configured for your environment (e.g.
you're deploying within JBoss AS 7) or you want the HornetQ REST you're deploying within JBoss AS 7) or you want the ActiveMQ REST
WAR to startup and manage the HornetQ server (e.g. you're deploying WAR to startup and manage the ActiveMQ server (e.g. you're deploying
within something like Apache Tomcat). within something like Apache Tomcat).
</para> </para>
<section> <section>
<title>Installing Within Pre-configured Environment</title> <title>Installing Within Pre-configured Environment</title>
<para>This section should be used when you want to use the HornetQ REST <para>This section should be used when you want to use the ActiveMQ REST
interface in an environment that already has HornetQ installed and interface in an environment that already has ActiveMQ installed and
running, e.g. JBoss AS 7. You must create a Web archive running, e.g. JBoss AS 7. You must create a Web archive
(.WAR) file with the following web.xml settings: (.WAR) file with the following web.xml settings:
</para> </para>
@ -146,7 +146,7 @@ Content-Type: application/xml
&lt;/web-app></programlisting> &lt;/web-app></programlisting>
<para>Within your WEB-INF/lib directory you must have the <para>Within your WEB-INF/lib directory you must have the
hornetq-rest.jar file. If RESTEasy is not installed within your activemq-rest.jar file. If RESTEasy is not installed within your
environment, you must add the RESTEasy jar files within the lib environment, you must add the RESTEasy jar files within the lib
directory as well. Here's a sample Maven pom.xml that can build your WAR directory as well. Here's a sample Maven pom.xml that can build your WAR
for this case. for this case.
@ -186,7 +186,7 @@ Content-Type: application/xml
&lt;dependencies> &lt;dependencies>
&lt;dependency> &lt;dependency>
&lt;groupId>org.apache.activemq.rest&lt;/groupId> &lt;groupId>org.apache.activemq.rest&lt;/groupId>
&lt;artifactId>hornetq-rest&lt;/artifactId> &lt;artifactId>activemq-rest&lt;/artifactId>
&lt;version>2.3.0-SNAPSHOT&lt;/version> &lt;version>2.3.0-SNAPSHOT&lt;/version>
&lt;/dependency> &lt;/dependency>
&lt;/dependencies> &lt;/dependencies>
@ -218,8 +218,8 @@ Content-Type: application/xml
It is worth noting that when deploying a WAR in a Java EE application server It is worth noting that when deploying a WAR in a Java EE application server
like AS7 the URL for the resulting application will include the name of the like AS7 the URL for the resulting application will include the name of the
WAR by default. For example, if you've constructed a WAR as described above WAR by default. For example, if you've constructed a WAR as described above
named "hornetq-rest.war" then clients will access it at, e.g. named "activemq-rest.war" then clients will access it at, e.g.
http://localhost:8080/hornetq-rest/[queues|topics]. We'll see more about http://localhost:8080/activemq-rest/[queues|topics]. We'll see more about
this later. this later.
</para> </para>
<note> <note>
@ -231,13 +231,13 @@ Content-Type: application/xml
</section> </section>
<section> <section>
<title>Bootstrapping HornetQ Along with REST</title> <title>Bootstrapping ActiveMQ Along with REST</title>
<para>You can bootstrap HornetQ within your WAR as well. To do this, you <para>You can bootstrap ActiveMQ within your WAR as well. To do this, you
must have the HornetQ core and JMS jars along with Netty, Resteasy, and must have the ActiveMQ core and JMS jars along with Netty, Resteasy, and
the HornetQ REST jar within your WEB-INF/lib. You must also have a the ActiveMQ REST jar within your WEB-INF/lib. You must also have a
hornetq-configuration.xml, hornetq-jms.xml, and hornetq-users.xml config activemq-configuration.xml, activemq-jms.xml, and activemq-users.xml config
files within WEB-INF/classes. The examples that come with the HornetQ files within WEB-INF/classes. The examples that come with the ActiveMQ
REST distribution show how to do this. You must also add an additional REST distribution show how to do this. You must also add an additional
listener to your web.xml file. Here's an example: listener to your web.xml file. Here's an example:
</para> </para>
@ -252,7 +252,7 @@ Content-Type: application/xml
&lt;listener> &lt;listener>
&lt;listener-class> &lt;listener-class>
org.apache.activemq.rest.integration.HornetqBootstrapListener org.apache.activemq.rest.integration.ActiveMQBootstrapListener
&lt;/listener-class> &lt;/listener-class>
&lt;/listener> &lt;/listener>
@ -276,7 +276,7 @@ Content-Type: application/xml
&lt;/web-app></programlisting> &lt;/web-app></programlisting>
<para>Here's a Maven pom.xml file for creating a WAR for this <para>Here's a Maven pom.xml file for creating a WAR for this
environment. Make sure your hornetq configuration files are within the environment. Make sure your activemq configuration files are within the
src/main/resources directory so that they are stuffed within the WAR's src/main/resources directory so that they are stuffed within the WAR's
WEB-INF/classes directory! WEB-INF/classes directory!
</para> </para>
@ -313,7 +313,7 @@ Content-Type: application/xml
&lt;dependencies> &lt;dependencies>
&lt;dependency> &lt;dependency>
&lt;groupId>org.apache.activemq&lt;/groupId> &lt;groupId>org.apache.activemq&lt;/groupId>
&lt;artifactId>hornetq-core&lt;/artifactId> &lt;artifactId>activemq-core&lt;/artifactId>
&lt;version>2.3.0-SNAPSHOT&lt;/version> &lt;version>2.3.0-SNAPSHOT&lt;/version>
&lt;/dependency> &lt;/dependency>
&lt;dependency> &lt;dependency>
@ -323,7 +323,7 @@ Content-Type: application/xml
&lt;/dependency> &lt;/dependency>
&lt;dependency> &lt;dependency>
&lt;groupId>org.apache.activemq&lt;/groupId> &lt;groupId>org.apache.activemq&lt;/groupId>
&lt;artifactId>hornetq-jms&lt;/artifactId> &lt;artifactId>activemq-jms&lt;/artifactId>
&lt;version>2.3.0-SNAPSHOT&lt;/version> &lt;version>2.3.0-SNAPSHOT&lt;/version>
&lt;/dependency> &lt;/dependency>
&lt;dependency> &lt;dependency>
@ -333,7 +333,7 @@ Content-Type: application/xml
&lt;/dependency> &lt;/dependency>
&lt;dependency> &lt;dependency>
&lt;groupId>org.apache.activemq.rest&lt;/groupId> &lt;groupId>org.apache.activemq.rest&lt;/groupId>
&lt;artifactId>hornetq-rest&lt;/artifactId> &lt;artifactId>activemq-rest&lt;/artifactId>
&lt;version>2.3.0-SNAPSHOT&lt;/version> &lt;version>2.3.0-SNAPSHOT&lt;/version>
&lt;/dependency> &lt;/dependency>
&lt;dependency> &lt;dependency>
@ -353,7 +353,7 @@ Content-Type: application/xml
<section id="configuration"> <section id="configuration">
<title>REST Configuration</title> <title>REST Configuration</title>
<para>The HornetQ REST implementation does have some configuration <para>The ActiveMQ REST implementation does have some configuration
options. These are configured via XML configuration file that must be in options. These are configured via XML configuration file that must be in
your WEB-INF/classes directory. You must set the web.xml context-param your WEB-INF/classes directory. You must set the web.xml context-param
<literal>rest.messaging.config.file</literal> to specify the name of the <literal>rest.messaging.config.file</literal> to specify the name of the
@ -380,15 +380,15 @@ Content-Type: application/xml
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>server-in-vm-id</literal>. The HornetQ REST <para><literal>server-in-vm-id</literal>. The ActiveMQ REST
impl uses the IN-VM transport to communicate with HornetQ. impl uses the IN-VM transport to communicate with ActiveMQ.
It uses the default server id, which is "0". It uses the default server id, which is "0".
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>use-link-headers</literal>. By default, all <para><literal>use-link-headers</literal>. By default, all
links (URLs) are published using custom headers. You can links (URLs) are published using custom headers. You can
instead have the HornetQ REST implementation publish links instead have the ActiveMQ REST implementation publish links
using the <ulink url="http://tools.ietf.org/html/draft-nottingham-http-link-header-10"> using the <ulink url="http://tools.ietf.org/html/draft-nottingham-http-link-header-10">
Link Header specification Link Header specification
</ulink> instead if you desire. </ulink> instead if you desire.
@ -421,7 +421,7 @@ Content-Type: application/xml
</listitem> </listitem>
<listitem> <listitem>
<para><literal>producer-session-pool-size</literal>. The REST <para><literal>producer-session-pool-size</literal>. The REST
implementation pools HornetQ sessions for sending messages. implementation pools ActiveMQ sessions for sending messages.
This is the size of the pool. That number of sessions will This is the size of the pool. That number of sessions will
be created at startup time. be created at startup time.
</para> </para>
@ -446,9 +446,9 @@ Content-Type: application/xml
</listitem> </listitem>
<listitem> <listitem>
<para><literal>consumer-window-size</literal>. For consumers, <para><literal>consumer-window-size</literal>. For consumers,
this config option is the same as the HornetQ one of the this config option is the same as the ActiveMQ one of the
same name. It will be used by sessions created by the same name. It will be used by sessions created by the
HornetQ REST implementation. ActiveMQ REST implementation.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -457,9 +457,9 @@ Content-Type: application/xml
<section id="basics"> <section id="basics">
<title>HornetQ REST Interface Basics</title> <title>ActiveMQ REST Interface Basics</title>
<para>The HornetQ REST interface publishes a variety of REST resources to <para>The ActiveMQ REST interface publishes a variety of REST resources to
perform various tasks on a queue or topic. Only the top-level queue and perform various tasks on a queue or topic. Only the top-level queue and
topic URI schemes are published to the outside world. You must discover topic URI schemes are published to the outside world. You must discover
all over resources to interact with by looking for and traversing links. all over resources to interact with by looking for and traversing links.
@ -479,16 +479,16 @@ Content-Type: application/xml
/topics/{name}</programlisting> /topics/{name}</programlisting>
<para>The base of the URI is the base URL of the WAR you deployed the <para>The base of the URI is the base URL of the WAR you deployed the
HornetQ REST server within as defined in the ActiveMQ REST server within as defined in the
<link linkend="install">Installation and Configuration</link> <link linkend="install">Installation and Configuration</link>
section of this document. Replace the <literal>{name}</literal> section of this document. Replace the <literal>{name}</literal>
string within the above URI pattern with the name of the queue or string within the above URI pattern with the name of the queue or
topic you are interested in interacting with. For example if you topic you are interested in interacting with. For example if you
have configured a JMS topic named "foo" within your have configured a JMS topic named "foo" within your
<literal>hornetq-jms.xml</literal> file, the URI name should be <literal>activemq-jms.xml</literal> file, the URI name should be
"jms.topic.foo". If you have configured a JMS queue name "bar" within "jms.topic.foo". If you have configured a JMS queue name "bar" within
your <literal>hornetq-jms.xml</literal> file, the URI name should be your <literal>activemq-jms.xml</literal> file, the URI name should be
"jms.queue.bar". Internally, HornetQ prepends the "jms.topic" or "jms.queue.bar". Internally, ActiveMQ prepends the "jms.topic" or
"jms.queue" strings to the name of the deployed destination. Next, "jms.queue" strings to the name of the deployed destination. Next,
perform your HEAD or GET request on this URI. Here's what a perform your HEAD or GET request on this URI. Here's what a
request/response would look like. request/response would look like.
@ -522,7 +522,7 @@ curl --head http://example.com/queues/jms.queue.bar</programlisting>
are an implementation detail. Treat them as opaque and query for them are an implementation detail. Treat them as opaque and query for them
each and every time you initially interact (at boot time) with the each and every time you initially interact (at boot time) with the
server. If you treat all URLs as opaque then you will be isolated from server. If you treat all URLs as opaque then you will be isolated from
implementation changes as the HornetQ REST interface evolves over implementation changes as the ActiveMQ REST interface evolves over
time. time.
</para> </para>
</section> </section>
@ -557,7 +557,7 @@ curl --head http://example.com/queues/jms.queue.bar</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>msg-push-consumers</literal>. This is a URL for <para><literal>msg-push-consumers</literal>. This is a URL for
registering other URLs you want the HornetQ REST server to registering other URLs you want the ActiveMQ REST server to
push messages to. The semantics of this link are described push messages to. The semantics of this link are described
in <link linkend="message-push">Pushing Messages</link>. in <link linkend="message-push">Pushing Messages</link>.
</para> </para>
@ -595,7 +595,7 @@ curl --head http://example.com/queues/jms.queue.bar</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>msg-push-subscriptions</literal>. This is a <para><literal>msg-push-subscriptions</literal>. This is a
URL for registering other URLs you want the HornetQ REST URL for registering other URLs you want the ActiveMQ REST
server to push messages to. The semantics of this link server to push messages to. The semantics of this link
are described in <link linkend="message-push">Pushing are described in <link linkend="message-push">Pushing
Messages</link>. Messages</link>.
@ -610,13 +610,13 @@ curl --head http://example.com/queues/jms.queue.bar</programlisting>
<title>Posting Messages</title> <title>Posting Messages</title>
<para>This chapter discusses the protocol for posting messages to a queue <para>This chapter discusses the protocol for posting messages to a queue
or a topic. In <link linkend="basics">HornetQ REST Interface Basics</link>, or a topic. In <link linkend="basics">ActiveMQ REST Interface Basics</link>,
you saw that a queue or topic resource publishes variable custom headers you saw that a queue or topic resource publishes variable custom headers
that are links to other RESTful resources. The <literal>msg-create</literal> that are links to other RESTful resources. The <literal>msg-create</literal>
header is a URL you can post a message to. Messages are published to a queue header is a URL you can post a message to. Messages are published to a queue
or topic by sending a simple HTTP message to the URL published by the or topic by sending a simple HTTP message to the URL published by the
<literal>msg-create</literal> header. The HTTP message contains whatever <literal>msg-create</literal> header. The HTTP message contains whatever
content you want to publish to the HornetQ destination. Here's an example content you want to publish to the ActiveMQ destination. Here's an example
scenario: scenario:
</para> </para>
@ -724,11 +724,11 @@ msg-create-next: http://example.com/queues/jms.queue.bar/create</programlisting>
messages to a queue or topic. You may do a POST and never receive a messages to a queue or topic. You may do a POST and never receive a
response. Unfortunately, you don't know whether or not the server response. Unfortunately, you don't know whether or not the server
received the message and so a re-post of the message might cause received the message and so a re-post of the message might cause
duplicates to be posted to the queue or topic. By default, the HornetQ duplicates to be posted to the queue or topic. By default, the ActiveMQ
REST interface is configured to accept and post duplicate messages. You REST interface is configured to accept and post duplicate messages. You
can change this by turning on duplicate message detection by setting the can change this by turning on duplicate message detection by setting the
<literal>dups-ok</literal> config option to <literal>false</literal> <literal>dups-ok</literal> config option to <literal>false</literal>
as described in <link linkend="basics">HornetQ REST Interface Basics</link>. as described in <link linkend="basics">ActiveMQ REST Interface Basics</link>.
When you do this, the initial POST to the <literal>msg-create</literal> When you do this, the initial POST to the <literal>msg-create</literal>
URL will redirect you, using the standard HTTP 307 redirection mechanism URL will redirect you, using the standard HTTP 307 redirection mechanism
to a unique URL to POST to. All other interactions remain the same as to a unique URL to POST to. All other interactions remain the same as
@ -832,10 +832,10 @@ msg-create-next: http://example.com/queues/jms.queue.bar/create/13582001787374</
</orderedlist> </orderedlist>
<para>How can this work? As you can see, with each successful response, <para>How can this work? As you can see, with each successful response,
the HornetQ REST server returns a uniquely generated URL within the the ActiveMQ REST server returns a uniquely generated URL within the
msg-create-next header. This URL is dedicated to the next new message msg-create-next header. This URL is dedicated to the next new message
you want to post. Behind the scenes, the code extracts an identify from you want to post. Behind the scenes, the code extracts an identify from
the URL and uses HornetQ's duplicate detection mechanism by setting the the URL and uses ActiveMQ's duplicate detection mechanism by setting the
<literal>DUPLICATE_DETECTION_ID</literal> property of the JMS message <literal>DUPLICATE_DETECTION_ID</literal> property of the JMS message
that is actually posted to the system. that is actually posted to the system.
</para> </para>
@ -844,7 +844,7 @@ msg-create-next: http://example.com/queues/jms.queue.bar/create/13582001787374</
like this on the server: like this on the server:
</para> </para>
<programlisting> <programlisting>
WARN [org.apache.activemq.core.server] (Thread-3 (HornetQ-remoting-threads-HornetQServerImpl::serverUUID=8d6be6f8-5e8b-11e2-80db-51bbde66f473-26319292-267207)) HQ112098: Duplicate message detected - message will not be routed. Message information: WARN [org.apache.activemq.core.server] (Thread-3 (ActiveMQ-remoting-threads-ActiveMQServerImpl::serverUUID=8d6be6f8-5e8b-11e2-80db-51bbde66f473-26319292-267207)) HQ112098: Duplicate message detected - message will not be routed. Message information:
ServerMessage[messageID=20,priority=4, bodySize=1500,expiration=0, durable=true, address=jms.queue.bar,properties=TypedProperties[{http_content$type=application/x-www-form-urlencoded, http_content$length=3, postedAsHttpMessage=true, _HQ_DUPL_ID=42}]]@12835058</programlisting> ServerMessage[messageID=20,priority=4, bodySize=1500,expiration=0, durable=true, address=jms.queue.bar,properties=TypedProperties[{http_content$type=application/x-www-form-urlencoded, http_content$length=3, postedAsHttpMessage=true, _HQ_DUPL_ID=42}]]@12835058</programlisting>
<para>An alternative to this approach is to use the <literal>msg-create-with-id</literal> <para>An alternative to this approach is to use the <literal>msg-create-with-id</literal>
@ -877,7 +877,7 @@ msg-create-with-id: http://example.com/queues/jms.queue.bar/create/{id}</program
<title>Persistent Messages</title> <title>Persistent Messages</title>
<para>By default, posted messages are not durable and will not be <para>By default, posted messages are not durable and will not be
persisted in HornetQ's journal. You can create durable messages by persisted in ActiveMQ's journal. You can create durable messages by
modifying the default configuration as expressed in Chapter 2 so that modifying the default configuration as expressed in Chapter 2 so that
all messages are persisted when sent. Alternatively, you can set a URL all messages are persisted when sent. Alternatively, you can set a URL
query parameter called <literal>durable</literal> to true when you post query parameter called <literal>durable</literal> to true when you post
@ -935,7 +935,7 @@ Content-Type: application/xml
important caveats. To start consuming you must create a consumer resource important caveats. To start consuming you must create a consumer resource
on the server that is dedicated to your client. Now, this pretty much on the server that is dedicated to your client. Now, this pretty much
breaks the stateless principle of REST, but after much prototyping, this breaks the stateless principle of REST, but after much prototyping, this
is the best way to work most effectively with HornetQ through a REST is the best way to work most effectively with ActiveMQ through a REST
interface. interface.
</para> </para>
@ -944,7 +944,7 @@ Content-Type: application/xml
response header if you are interacting with a queue, the response header if you are interacting with a queue, the
<literal>msg-pull-subscribers</literal> response header if you're <literal>msg-pull-subscribers</literal> response header if you're
interacting with a topic. These headers are provided by the main queue or interacting with a topic. These headers are provided by the main queue or
topic resource discussed in <link linkend="basics">HornetQ REST Interface topic resource discussed in <link linkend="basics">ActiveMQ REST Interface
Basics</link>. Doing an empty POST to one of these Basics</link>. Doing an empty POST to one of these
URLs will create a consumer resource that follows an auto-acknowledge URLs will create a consumer resource that follows an auto-acknowledge
protocol and, if you are interacting with a topic, creates a temporarily protocol and, if you are interacting with a topic, creates a temporarily
@ -979,7 +979,7 @@ Content-Type: application/xml
</listitem> </listitem>
<listitem> <listitem>
<para><literal>selector</literal>. This is an optional JMS selector <para><literal>selector</literal>. This is an optional JMS selector
string. The HornetQ REST interface adds HTTP headers to the string. The ActiveMQ REST interface adds HTTP headers to the
JMS message for REST produced messages. HTTP headers are JMS message for REST produced messages. HTTP headers are
prefixed with "http_" and every '-' character is converted prefixed with "http_" and every '-' character is converted
to a '$'. to a '$'.
@ -1223,7 +1223,7 @@ msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/con
should retry a post. Also notice, that another new should retry a post. Also notice, that another new
msg-consume-next URL is present. Although it probably is the same msg-consume-next URL is present. Although it probably is the same
URL you used last post, get in the habit of using URLs returned in URL you used last post, get in the habit of using URLs returned in
response headers as future versions of HornetQ REST might be response headers as future versions of ActiveMQ REST might be
redirecting you or adding additional data to the URL after redirecting you or adding additional data to the URL after
timeouts like this. timeouts like this.
</para> </para>
@ -1594,7 +1594,7 @@ http://example.com/queues/jms.queue.bar/pull-consumers/333/acknowledge-next-2</p
<para>Unless your queue or topic has a high rate of message flowing <para>Unless your queue or topic has a high rate of message flowing
though it, if you use the pull protocol, you're going to be receiving a though it, if you use the pull protocol, you're going to be receiving a
lot of 503 responses as you continuously pull the server for new lot of 503 responses as you continuously pull the server for new
messages. To alleviate this problem, the HornetQ REST interface provides messages. To alleviate this problem, the ActiveMQ REST interface provides
the <literal>Accept-Wait</literal> header. This is a generic HTTP the <literal>Accept-Wait</literal> header. This is a generic HTTP
request header that is a hint to the server for how long the client is request header that is a hint to the server for how long the client is
willing to wait for a response from the server. The value of this header willing to wait for a response from the server. The value of this header
@ -1643,9 +1643,9 @@ msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/con
<section id="message-push"> <section id="message-push">
<title>Pushing Messages</title> <title>Pushing Messages</title>
<para>You can configure the HornetQ REST server to push messages to a <para>You can configure the ActiveMQ REST server to push messages to a
registered URL either remotely through the REST interface, or by creating registered URL either remotely through the REST interface, or by creating
a pre-configured XML file for the HornetQ REST server to load at boot a pre-configured XML file for the ActiveMQ REST server to load at boot
time. time.
</para> </para>
@ -1702,7 +1702,7 @@ msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/con
will disable the registration if all retries have failed. It will not will disable the registration if all retries have failed. It will not
disable the connection on non-connection-failure issues (like a bad disable the connection on non-connection-failure issues (like a bad
request for instance). In these cases, the dead letter queue logic of request for instance). In these cases, the dead letter queue logic of
HornetQ will take over. ActiveMQ will take over.
</para> </para>
<para>The <literal>link</literal> element specifies the basis of the <para>The <literal>link</literal> element specifies the basis of the
@ -1720,10 +1720,10 @@ msg-consume-next: http://example.com/queues/jms.queue.bar/pull-consumers/333/con
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>destination</literal>. The href URL is assumed to be a queue or topic resource of <para><literal>destination</literal>. The href URL is assumed to be a queue or topic resource of
another HornetQ REST server. The push registration will initially another ActiveMQ REST server. The push registration will initially
do a HEAD request to this URL to obtain a msg-create-with-id do a HEAD request to this URL to obtain a msg-create-with-id
header. It will use this header to push new messages to the header. It will use this header to push new messages to the
HornetQ REST endpoint reliably. Here's an example: ActiveMQ REST endpoint reliably. Here's an example:
</para> </para>
<programlisting> <programlisting>
@ -1962,13 +1962,13 @@ Location: http://example.com/topics/jms.topic.bar/push-subscriptions/1-333-1212<
Currently you cannot create a temporary queue or topic. To create a queue Currently you cannot create a temporary queue or topic. To create a queue
you do a POST to the relative URL /queues with an XML representation of you do a POST to the relative URL /queues with an XML representation of
the queue. The XML syntax is the same queue syntax that you would specify the queue. The XML syntax is the same queue syntax that you would specify
in hornetq-jms.xml if you were creating a queue there. For example: in activemq-jms.xml if you were creating a queue there. For example:
</para> </para>
<programlisting> <programlisting>
POST /queues POST /queues
Host: example.com Host: example.com
Content-Type: application/hornetq.jms.queue+xml Content-Type: application/activemq.jms.queue+xml
&lt;queue name="testQueue"> &lt;queue name="testQueue">
&lt;durable>true&lt;/durable> &lt;durable>true&lt;/durable>
@ -1978,14 +1978,14 @@ Content-Type: application/hornetq.jms.queue+xml
HTTP/1.1 201 Created HTTP/1.1 201 Created
Location: http://example.com/queues/jms.queue.testQueue</programlisting> Location: http://example.com/queues/jms.queue.testQueue</programlisting>
<para>Notice that the Content-Type is application/hornetq.jms.queue+xml.</para> <para>Notice that the Content-Type is application/activemq.jms.queue+xml.</para>
<para>Here's what creating a topic would look like:</para> <para>Here's what creating a topic would look like:</para>
<programlisting> <programlisting>
POST /topics POST /topics
Host: example.com Host: example.com
Content-Type: application/hornetq.jms.topic+xml Content-Type: application/activemq.jms.topic+xml
&lt;topic name="testTopic"> &lt;topic name="testTopic">
&lt;/topic> &lt;/topic>
@ -1997,23 +1997,23 @@ Location: http://example.com/topics/jms.topic.testTopic</programlisting>
<section> <section>
<title>Securing the HornetQ REST Interface</title> <title>Securing the ActiveMQ REST Interface</title>
<section> <section>
<title>Within JBoss Application server</title> <title>Within JBoss Application server</title>
<para>Securing the HornetQ REST interface is very simple with the JBoss <para>Securing the ActiveMQ REST interface is very simple with the JBoss
Application Server. You turn on authentication for all URLs within your Application Server. You turn on authentication for all URLs within your
WAR's web.xml, and let the user Principal to propagate to HornetQ. This WAR's web.xml, and let the user Principal to propagate to ActiveMQ. This
only works if you are using the JBossSecurityManager with HornetQ. See only works if you are using the JBossSecurityManager with ActiveMQ. See
the HornetQ documentation for more details. the ActiveMQ documentation for more details.
</para> </para>
</section> </section>
<section> <section>
<title>Security in other environments</title> <title>Security in other environments</title>
<para>To secure the HornetQ REST interface in other environments you <para>To secure the ActiveMQ REST interface in other environments you
must role your own security by specifying security constraints with your must role your own security by specifying security constraints with your
web.xml for every path of every queue and topic you have deployed. Here web.xml for every path of every queue and topic you have deployed. Here
is a list of URI patterns: is a list of URI patterns:
@ -2091,7 +2091,7 @@ Location: http://example.com/topics/jms.topic.testTopic</programlisting>
<section> <section>
<title>Mixing JMS and REST</title> <title>Mixing JMS and REST</title>
<para>The HornetQ REST interface supports mixing JMS and REST producers <para>The ActiveMQ REST interface supports mixing JMS and REST producers
and consumers. You can send an ObjectMessage through a JMS Producer, and and consumers. You can send an ObjectMessage through a JMS Producer, and
have a REST client consume it. You can have a REST client POST a message have a REST client consume it. You can have a REST client POST a message
to a topic and have a JMS Consumer receive it. Some simple transformations to a topic and have a JMS Consumer receive it. Some simple transformations
@ -2101,11 +2101,11 @@ Location: http://example.com/topics/jms.topic.testTopic</programlisting>
<section> <section>
<title>JMS Producers - REST Consumers</title> <title>JMS Producers - REST Consumers</title>
<para>If you have a JMS producer, the HornetQ REST interface only <para>If you have a JMS producer, the ActiveMQ REST interface only
supports ObjectMessage type. If the JMS producer is aware that there may supports ObjectMessage type. If the JMS producer is aware that there may
be REST consumers, it should set a JMS property to specify what be REST consumers, it should set a JMS property to specify what
Content-Type the Java object should be translated into by REST clients. Content-Type the Java object should be translated into by REST clients.
The HornetQ REST server will use RESTEasy content handlers The ActiveMQ REST server will use RESTEasy content handlers
(MessageBodyReader/Writers) to transform the Java object to the type (MessageBodyReader/Writers) to transform the Java object to the type
desired. Here's an example of a JMS producer setting the content type of desired. Here's an example of a JMS producer setting the content type of
the message. the message.
@ -2129,7 +2129,7 @@ message.setStringProperty(org.apache.activemq.rest.HttpHeaderProperty.CONTENT_TY
<title>REST Producers - JMS Consumers</title> <title>REST Producers - JMS Consumers</title>
<para>If you have a REST client producing messages and a JMS consumer, <para>If you have a REST client producing messages and a JMS consumer,
HornetQ REST has a simple helper class for you to transform the HTTP ActiveMQ REST has a simple helper class for you to transform the HTTP
body to a Java object. Here's some example code: body to a Java object. Here's some example code:
</para> </para>

2
docs/user-manual/en/scheduled-messages.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="scheduled-messages"> <chapter id="scheduled-messages">

56
docs/user-manual/en/security.xml
View File

@ -18,26 +18,26 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="security"> <chapter id="security">
<title>Security</title> <title>Security</title>
<para>This chapter describes how security works with HornetQ and how you can configure it. To <para>This chapter describes how security works with ActiveMQ and how you can configure it. To
disable security completely simply set the <literal>security-enabled</literal> property to disable security completely simply set the <literal>security-enabled</literal> property to
false in the <literal>hornetq-configuration.xml</literal> file.</para> false in the <literal>activemq-configuration.xml</literal> file.</para>
<para>For performance reasons security is cached and invalidated every so long. To change this <para>For performance reasons security is cached and invalidated every so long. To change this
period set the property <literal>security-invalidation-interval</literal>, which is in period set the property <literal>security-invalidation-interval</literal>, which is in
milliseconds. The default is <literal>10000</literal> ms.</para> milliseconds. The default is <literal>10000</literal> ms.</para>
<section id="security.settings.roles"> <section id="security.settings.roles">
<title>Role based security for addresses</title> <title>Role based security for addresses</title>
<para>HornetQ contains a flexible role-based security model for applying security to queues, <para>ActiveMQ contains a flexible role-based security model for applying security to queues,
based on their addresses.</para> based on their addresses.</para>
<para>As explained in <xref linkend="using-core"/>, HornetQ core consists mainly of sets of <para>As explained in <xref linkend="using-core"/>, ActiveMQ core consists mainly of sets of
queues bound to addresses. A message is sent to an address and the server looks up the queues bound to addresses. A message is sent to an address and the server looks up the
set of queues that are bound to that address, the server then routes the message to set of queues that are bound to that address, the server then routes the message to
those set of queues.</para> those set of queues.</para>
<para>HornetQ allows sets of permissions to be defined against the queues based on their <para>ActiveMQ allows sets of permissions to be defined against the queues based on their
address. An exact match on the address can be used or a wildcard match can be used using address. An exact match on the address can be used or a wildcard match can be used using
the wildcard characters '<literal>#</literal>' and '<literal>*</literal>'.</para> the wildcard characters '<literal>#</literal>' and '<literal>*</literal>'.</para>
<para>Seven different permissions can be given to the set of queues which match the address. <para>Seven different permissions can be given to the set of queues which match the address.
@ -77,7 +77,7 @@
the user has any of those roles, he/she will be granted that permission for that set of the user has any of those roles, he/she will be granted that permission for that set of
addresses.</para> addresses.</para>
<para>Let's take a simple example, here's a security block from <literal <para>Let's take a simple example, here's a security block from <literal
>hornetq-configuration.xml</literal> or <literal>hornetq-queues.xml</literal> >activemq-configuration.xml</literal> or <literal>activemq-queues.xml</literal>
file:</para> file:</para>
<programlisting> <programlisting>
&lt;security-setting match="globalqueues.europe.#"> &lt;security-setting match="globalqueues.europe.#">
@ -101,7 +101,7 @@
can send messages to these addresses or consume messages from queues bound to an address can send messages to these addresses or consume messages from queues bound to an address
that starts with the string "globalqueues.europe."</para> that starts with the string "globalqueues.europe."</para>
<para>The mapping between a user and what roles they have is handled by the security <para>The mapping between a user and what roles they have is handled by the security
manager. HornetQ ships with a user manager that reads user credentials from a file on manager. ActiveMQ ships with a user manager that reads user credentials from a file on
disk, and can also plug into JAAS or JBoss Application Server security.</para> disk, and can also plug into JAAS or JBoss Application Server security.</para>
<para>For more information on configuring the security manager, please see <xref <para>For more information on configuring the security manager, please see <xref
linkend="change-security-manager"/>.</para> linkend="change-security-manager"/>.</para>
@ -135,23 +135,23 @@
<section> <section>
<title>Secure Sockets Layer (SSL) Transport</title> <title>Secure Sockets Layer (SSL) Transport</title>
<para>When messaging clients are connected to servers, or servers are connected to other <para>When messaging clients are connected to servers, or servers are connected to other
servers (e.g. via bridges) over an untrusted network then HornetQ allows that traffic to servers (e.g. via bridges) over an untrusted network then ActiveMQ allows that traffic to
be encrypted using the Secure Sockets Layer (SSL) transport.</para> be encrypted using the Secure Sockets Layer (SSL) transport.</para>
<para>For more information on configuring the SSL transport, please see <xref <para>For more information on configuring the SSL transport, please see <xref
linkend="configuring-transports"/>.</para> linkend="configuring-transports"/>.</para>
</section> </section>
<section> <section>
<title>Basic user credentials</title> <title>Basic user credentials</title>
<para>HornetQ ships with a security manager implementation that reads user credentials, i.e. <para>ActiveMQ ships with a security manager implementation that reads user credentials, i.e.
user names, passwords and role information from an xml file on the classpath called user names, passwords and role information from an xml file on the classpath called
<literal>hornetq-users.xml</literal>. This is the default security manager.</para> <literal>activemq-users.xml</literal>. This is the default security manager.</para>
<para>If you wish to use this security manager, then users, passwords and roles can easily <para>If you wish to use this security manager, then users, passwords and roles can easily
be added into this file.</para> be added into this file.</para>
<para>Let's take a look at an example file:</para> <para>Let's take a look at an example file:</para>
<programlisting> <programlisting>
&lt;configuration xmlns="urn:activemq" &lt;configuration xmlns="urn:activemq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:hornetq ../schemas/activemq-users.xsd "> xsi:schemaLocation="urn:activemq ../schemas/activemq-users.xsd ">
&lt;defaultuser name="guest" password="guest"> &lt;defaultuser name="guest" password="guest">
&lt;role name="guest"/> &lt;role name="guest"/>
@ -185,23 +185,23 @@
<section id="change-security-manager"> <section id="change-security-manager">
<title>Changing the security manager</title> <title>Changing the security manager</title>
<para>If you do not want to use the default security manager then you can specify a <para>If you do not want to use the default security manager then you can specify a
different one by editing the file <literal>hornetq-beans.xml</literal> (or <literal different one by editing the file <literal>activemq-beans.xml</literal> (or <literal
>hornetq-jboss-beans.xml</literal> if you're running JBoss Application Server) and >activemq-jboss-beans.xml</literal> if you're running JBoss Application Server) and
changing the class for the <literal>HornetQSecurityManager</literal> bean.</para> changing the class for the <literal>ActiveMQSecurityManager</literal> bean.</para>
<para>Let's take a look at a snippet from the default beans file:</para> <para>Let's take a look at a snippet from the default beans file:</para>
<programlisting> <programlisting>
&lt;bean name="HornetQSecurityManager" class="org.apache.activemq.spi.core.security.HornetQSecurityManagerImpl"> &lt;bean name="ActiveMQSecurityManager" class="org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl">
&lt;start ignored="true"/> &lt;start ignored="true"/>
&lt;stop ignored="true"/> &lt;stop ignored="true"/>
&lt;/bean></programlisting> &lt;/bean></programlisting>
<para>The class <literal>org.apache.activemq.spi.core.security.HornetQSecurityManagerImpl</literal> <para>The class <literal>org.apache.activemq.spi.core.security.ActiveMQSecurityManagerImpl</literal>
is the default security manager that is used by the standalone server.</para> is the default security manager that is used by the standalone server.</para>
<para>HornetQ ships with two other security manager implementations you can use <para>ActiveMQ ships with two other security manager implementations you can use
off-the-shelf; one a JAAS security manager and another for integrating with JBoss off-the-shelf; one a JAAS security manager and another for integrating with JBoss
Application Sever security, alternatively you could write your own implementation by Application Sever security, alternatively you could write your own implementation by
implementing the <literal>org.apache.activemq.spi.core.security.HornetQSecurityManager</literal> implementing the <literal>org.apache.activemq.spi.core.security.ActiveMQSecurityManager</literal>
interface, and specifying the classname of your implementation in the file <literal interface, and specifying the classname of your implementation in the file <literal
>hornetq-beans.xml</literal> (or <literal>hornetq-jboss-beans.xml</literal> if >activemq-beans.xml</literal> (or <literal>activemq-jboss-beans.xml</literal> if
you're running JBoss Application Server).</para> you're running JBoss Application Server).</para>
<para>These two implementations are discussed in the next two sections.</para> <para>These two implementations are discussed in the next two sections.</para>
</section> </section>
@ -214,7 +214,7 @@
you need to specify the security manager as a <literal>JAASSecurityManager</literal> in you need to specify the security manager as a <literal>JAASSecurityManager</literal> in
the beans file. Here's an example:</para> the beans file. Here's an example:</para>
<programlisting> <programlisting>
&lt;bean name="HornetQSecurityManager" class="org.apache.activemq.integration.jboss.security.JAASSecurityManager"> &lt;bean name="ActiveMQSecurityManager" class="org.apache.activemq.integration.jboss.security.JAASSecurityManager">
&lt;start ignored="true"/> &lt;start ignored="true"/>
&lt;stop ignored="true"/> &lt;stop ignored="true"/>
@ -243,27 +243,27 @@
</itemizedlist> </itemizedlist>
<section> <section>
<title>Example</title> <title>Example</title>
<para>See <xref linkend="examples.jaas"/> for an example which shows how HornetQ can be <para>See <xref linkend="examples.jaas"/> for an example which shows how ActiveMQ can be
configured to use JAAS.</para> configured to use JAAS.</para>
</section> </section>
</section> </section>
<section> <section>
<title>JBoss AS Security Manager</title> <title>JBoss AS Security Manager</title>
<para>The JBoss AS security manager is used when running HornetQ inside the JBoss <para>The JBoss AS security manager is used when running ActiveMQ inside the JBoss
Application server. This allows tight integration with the JBoss Application Server's Application server. This allows tight integration with the JBoss Application Server's
security model.</para> security model.</para>
<para>The class name of this security manager is <literal <para>The class name of this security manager is <literal
>org.apache.activemq.integration.jboss.security.JBossASSecurityManager</literal></para> >org.apache.activemq.integration.jboss.security.JBossASSecurityManager</literal></para>
<para>Take a look at one of the default <literal>hornetq-jboss-beans.xml</literal> files for <para>Take a look at one of the default <literal>activemq-jboss-beans.xml</literal> files for
JBoss Application Server that are bundled in the distribution for an example of how this JBoss Application Server that are bundled in the distribution for an example of how this
is configured.</para> is configured.</para>
<section> <section>
<title>Configuring Client Login</title> <title>Configuring Client Login</title>
<para>JBoss can be configured to allow client login, basically this is when a JEE component such as a Servlet <para>JBoss can be configured to allow client login, basically this is when a JEE component such as a Servlet
or EJB sets security credentials on the current security context and these are used throughout the call. or EJB sets security credentials on the current security context and these are used throughout the call.
If you would like these credentials to be used by HornetQ when sending or consuming messages then If you would like these credentials to be used by ActiveMQ when sending or consuming messages then
set <literal>allowClientLogin</literal> to true. This will bypass HornetQ authentication and propagate the set <literal>allowClientLogin</literal> to true. This will bypass ActiveMQ authentication and propagate the
provided Security Context. If you would like HornetQ to authenticate using the propagated security then set the provided Security Context. If you would like ActiveMQ to authenticate using the propagated security then set the
<literal>authoriseOnClientLogin</literal> to true also.</para> <literal>authoriseOnClientLogin</literal> to true also.</para>
<para>There is more info on using the JBoss client login module <ulink <para>There is more info on using the JBoss client login module <ulink
url="http://community.jboss.org/wiki/ClientLoginModule">here</ulink> </para> url="http://community.jboss.org/wiki/ClientLoginModule">here</ulink> </para>
@ -273,7 +273,7 @@
</section> </section>
<section> <section>
<title>Changing the Security Domain</title> <title>Changing the Security Domain</title>
<para>The name of the security domain used by the JBoss AS security manager defaults to <literal>java:/jaas/hornetq <para>The name of the security domain used by the JBoss AS security manager defaults to <literal>java:/jaas/activemq
</literal>. This can be changed by specifying <literal>securityDomainName</literal> (e.g. java:/jaas/myDomain). </literal>. This can be changed by specifying <literal>securityDomainName</literal> (e.g. java:/jaas/myDomain).
</para> </para>
</section> </section>

24
docs/user-manual/en/send-guarantees.xml
View File

@ -18,14 +18,14 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="send-guarantees"> <chapter id="send-guarantees">
<title>Guarantees of sends and commits</title> <title>Guarantees of sends and commits</title>
<section> <section>
<title>Guarantees of Transaction Completion</title> <title>Guarantees of Transaction Completion</title>
<para>When committing or rolling back a transaction with HornetQ, the request to commit or <para>When committing or rolling back a transaction with ActiveMQ, the request to commit or
rollback is sent to the server, and the call will block on the client side until a rollback is sent to the server, and the call will block on the client side until a
response has been received from the server that the commit or rollback was response has been received from the server that the commit or rollback was
executed.</para> executed.</para>
@ -41,11 +41,11 @@
storage by the time the call to commit or rollback returns.</para> storage by the time the call to commit or rollback returns.</para>
<para>Setting this parameter to <literal>false</literal> can improve performance at the <para>Setting this parameter to <literal>false</literal> can improve performance at the
expense of some loss of transaction durability.</para> expense of some loss of transaction durability.</para>
<para>This parameter is set in <literal>hornetq-configuration.xml</literal></para> <para>This parameter is set in <literal>activemq-configuration.xml</literal></para>
</section> </section>
<section id="non-transactional-sends"> <section id="non-transactional-sends">
<title>Guarantees of Non Transactional Message Sends</title> <title>Guarantees of Non Transactional Message Sends</title>
<para>If you are sending messages to a server using a non transacted session, HornetQ can be <para>If you are sending messages to a server using a non transacted session, ActiveMQ can be
configured to block the call to send until the message has definitely reached the configured to block the call to send until the message has definitely reached the
server, and a response has been sent back to the client. This can be configured server, and a response has been sent back to the client. This can be configured
individually for durable and non-durable messages, and is determined by the individually for durable and non-durable messages, and is determined by the
@ -72,14 +72,14 @@
your network, rather than the bandwidth of your network. For better performance we your network, rather than the bandwidth of your network. For better performance we
recommend either batching many messages sends together in a transaction since with a recommend either batching many messages sends together in a transaction since with a
transactional session, only the commit / rollback blocks not every send, or, using transactional session, only the commit / rollback blocks not every send, or, using
HornetQ's advanced <emphasis>asynchronous send acknowledgements feature</emphasis> ActiveMQ's advanced <emphasis>asynchronous send acknowledgements feature</emphasis>
described in <xref linkend="asynchronous-send-acknowledgements"/>.</para> described in <xref linkend="asynchronous-send-acknowledgements"/>.</para>
<para>If you are using JMS and you're using the JMS service on the server to load your JMS <para>If you are using JMS and you're using the JMS service on the server to load your JMS
connection factory instances into JNDI then these parameters can be configured in connection factory instances into JNDI then these parameters can be configured in
<literal>hornetq-jms.xml</literal> using the elements <literal <literal>activemq-jms.xml</literal> using the elements <literal
>block-on-durable-send</literal> and <literal >block-on-durable-send</literal> and <literal
>block-on-non-durable-send</literal>. If you're using JMS but not using JNDI then >block-on-non-durable-send</literal>. If you're using JMS but not using JNDI then
you can set these values directly on the <literal>HornetQConnectionFactory</literal> you can set these values directly on the <literal>ActiveMQConnectionFactory</literal>
instance using the appropriate setter methods.</para> instance using the appropriate setter methods.</para>
<para>If you're using core you can set these values directly on the <literal <para>If you're using core you can set these values directly on the <literal
>ClientSessionFactory</literal> instance using the appropriate setter >ClientSessionFactory</literal> instance using the appropriate setter
@ -95,7 +95,7 @@
<section id="send-guarantees.nontrans.acks"> <section id="send-guarantees.nontrans.acks">
<title>Guarantees of Non Transactional Acknowledgements</title> <title>Guarantees of Non Transactional Acknowledgements</title>
<para>If you are acknowledging the delivery of a message at the client side using a non <para>If you are acknowledging the delivery of a message at the client side using a non
transacted session, HornetQ can be configured to block the call to acknowledge until the transacted session, ActiveMQ can be configured to block the call to acknowledge until the
acknowledge has definitely reached the server, and a response has been sent back to the acknowledge has definitely reached the server, and a response has been sent back to the
client. This is configured with the parameter <literal>BlockOnAcknowledge</literal>. If client. This is configured with the parameter <literal>BlockOnAcknowledge</literal>. If
this is set to <literal>true</literal> then all calls to acknowledge on non transacted this is set to <literal>true</literal> then all calls to acknowledge on non transacted
@ -108,7 +108,7 @@
<title>Asynchronous Send Acknowledgements</title> <title>Asynchronous Send Acknowledgements</title>
<para>If you are using a non transacted session but want a guarantee that every message sent <para>If you are using a non transacted session but want a guarantee that every message sent
to the server has reached it, then, as discussed in <xref to the server has reached it, then, as discussed in <xref
linkend="non-transactional-sends"/>, you can configure HornetQ to block the call to linkend="non-transactional-sends"/>, you can configure ActiveMQ to block the call to
send until the server has received the message, persisted it and sent back a response. send until the server has received the message, persisted it and sent back a response.
This works well but has a severe performance penalty - each call to send needs to block This works well but has a severe performance penalty - each call to send needs to block
for at least the time of a network round trip (RTT) - the performance of sending is thus for at least the time of a network round trip (RTT) - the performance of sending is thus
@ -124,8 +124,8 @@
* 1024 * 1024 / 8) / 1500 = 89478 messages per second if messages are sent without * 1024 * 1024 / 8) / 1500 = 89478 messages per second if messages are sent without
blocking! These figures aren't an exact science but you can clearly see that being blocking! These figures aren't an exact science but you can clearly see that being
limited by network RTT can have serious effect on performance.</para> limited by network RTT can have serious effect on performance.</para>
<para>To remedy this, HornetQ provides an advanced new feature called <emphasis>asynchronous <para>To remedy this, ActiveMQ provides an advanced new feature called <emphasis>asynchronous
send acknowledgements</emphasis>. With this feature, HornetQ can be configured to send acknowledgements</emphasis>. With this feature, ActiveMQ can be configured to
send messages without blocking in one direction and asynchronously getting send messages without blocking in one direction and asynchronously getting
acknowledgement from the server that the messages were received in a separate stream. By acknowledgement from the server that the messages were received in a separate stream. By
de-coupling the send from the acknowledgement of the send, the system is not limited by de-coupling the send from the acknowledgement of the send, the system is not limited by
@ -142,7 +142,7 @@
<para>Then, you just send messages as normal using your <literal <para>Then, you just send messages as normal using your <literal
>ClientSession</literal>, and as messages reach the server, the server will send >ClientSession</literal>, and as messages reach the server, the server will send
back an acknowledgement of the send asynchronously, and some time later you are back an acknowledgement of the send asynchronously, and some time later you are
informed at the client side by HornetQ calling your handler's <literal informed at the client side by ActiveMQ calling your handler's <literal
>sendAcknowledged(ClientMessage message)</literal> method, passing in a >sendAcknowledged(ClientMessage message)</literal> method, passing in a
reference to the message that was sent.</para> reference to the message that was sent.</para>
<para>To enable asynchronous send acknowledgements you must make sure <literal>confirmation-window-size</literal> is set to a positive integer value, e.g. 10MiB</para> <para>To enable asynchronous send acknowledgements you must make sure <literal>confirmation-window-size</literal> is set to a positive integer value, e.g. 10MiB</para>

4
docs/user-manual/en/slow-consumers.xml
View File

@ -18,12 +18,12 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="slow-consumers"> <chapter id="slow-consumers">
<title>Detecting Slow Consumers</title> <title>Detecting Slow Consumers</title>
<para>In this section we will discuss how HornetQ can be configured to deal with slow consumers. A slow consumer with <para>In this section we will discuss how ActiveMQ can be configured to deal with slow consumers. A slow consumer with
a server-side queue (e.g. JMS topic subscriber) can pose a significant problem for broker performance. If messages a server-side queue (e.g. JMS topic subscriber) can pose a significant problem for broker performance. If messages
build up in the consumer's server-side queue then memory will begin filling up and the broker may enter paging build up in the consumer's server-side queue then memory will begin filling up and the broker may enter paging
mode which would impact performance negatively. However, criteria can be set so that consumers which don't mode which would impact performance negatively. However, criteria can be set so that consumers which don't

22
docs/user-manual/en/spring-integration.xml
View File

@ -20,27 +20,27 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="spring.integration"> <chapter id="spring.integration">
<title>Spring Integration</title> <title>Spring Integration</title>
<para>HornetQ provides a simple bootstrap class, <para>ActiveMQ provides a simple bootstrap class,
<literal>org.apache.activemq.integration.spring.SpringJmsBootstrap</literal>, for <literal>org.apache.activemq.integration.spring.SpringJmsBootstrap</literal>, for
integration with Spring. To use it, you configure HornetQ as you always integration with Spring. To use it, you configure ActiveMQ as you always
would, through its various configuration files like would, through its various configuration files like
<literal>hornetq-configuration.xml</literal>, <literal>activemq-configuration.xml</literal>,
<literal>hornetq-jms.xml</literal>, and <literal>activemq-jms.xml</literal>, and
<literal>hornetq-users.xml</literal>. The Spring helper class starts the <literal>activemq-users.xml</literal>. The Spring helper class starts the
HornetQ server and adds any factories or destinations configured within ActiveMQ server and adds any factories or destinations configured within
<literal>hornetq-jms.xml</literal> directly into the namespace of the Spring <literal>activemq-jms.xml</literal> directly into the namespace of the Spring
context. Let's take this <literal>hornetq-jms.xml</literal> file for context. Let's take this <literal>activemq-jms.xml</literal> file for
instance: </para> instance: </para>
<programlisting> <programlisting>
&lt;configuration xmlns="urn:activemq" &lt;configuration xmlns="urn:activemq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:hornetq /schema/activemq-jms.xsd"> xsi:schemaLocation="urn:activemq /schema/activemq-jms.xsd">
&lt;!--the connection factory used by the example--> &lt;!--the connection factory used by the example-->
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;connectors> &lt;connectors>
@ -82,7 +82,7 @@
&lt;/beans></programlisting> &lt;/beans></programlisting>
<para>As you can see, the <para>As you can see, the
<literal>listenerContainer</literal> bean references the components defined <literal>listenerContainer</literal> bean references the components defined
in the <literal>hornetq-jms.xml</literal> file. The in the <literal>activemq-jms.xml</literal> file. The
<literal>SpringJmsBootstrap</literal> class extends the EmbeddedJMS class <literal>SpringJmsBootstrap</literal> class extends the EmbeddedJMS class
talked about in <xref talked about in <xref
linkend="simple.embedded.jms" /> and the same defaults and linkend="simple.embedded.jms" /> and the same defaults and

30
docs/user-manual/en/thread-pooling.xml
View File

@ -18,22 +18,22 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="thread-pooling"> <chapter id="thread-pooling">
<title>Thread management</title> <title>Thread management</title>
<para>This chapter describes how HornetQ uses and pools threads and how you can manage <para>This chapter describes how ActiveMQ uses and pools threads and how you can manage
them.</para> them.</para>
<para>First we'll discuss how threads are managed and used on the server side, then we'll look <para>First we'll discuss how threads are managed and used on the server side, then we'll look
at the client side.</para> at the client side.</para>
<section> <section>
<title>Server-Side Thread Management</title> <title>Server-Side Thread Management</title>
<para>Each HornetQ Server maintains a single thread pool for general use, and a scheduled <para>Each ActiveMQ Server maintains a single thread pool for general use, and a scheduled
thread pool for scheduled use. A Java scheduled thread pool cannot be configured to use thread pool for scheduled use. A Java scheduled thread pool cannot be configured to use
a standard thread pool, otherwise we could use a single thread pool for both scheduled a standard thread pool, otherwise we could use a single thread pool for both scheduled
and non scheduled activity.</para> and non scheduled activity.</para>
<para>A separate thread pool is also used to service connections. HornetQ can use "old" <para>A separate thread pool is also used to service connections. ActiveMQ can use "old"
(blocking) IO or "new" (non-blocking) IO also called NIO. Both of these options use (blocking) IO or "new" (non-blocking) IO also called NIO. Both of these options use
a separate thread pool, but each of them behaves uniquely.</para> a separate thread pool, but each of them behaves uniquely.</para>
<para>Since old IO requires a thread per connection its thread pool is unbounded. The thread <para>Since old IO requires a thread per connection its thread pool is unbounded. The thread
@ -49,7 +49,7 @@
since it has no remaining threads to do anything else. However, even an unbounded thread since it has no remaining threads to do anything else. However, even an unbounded thread
pool can run into trouble if it becomes too large. If you require the server to handle pool can run into trouble if it becomes too large. If you require the server to handle
many concurrent connections you should use NIO, not old IO.</para> many concurrent connections you should use NIO, not old IO.</para>
<para>When using new IO (NIO), HornetQ will, by default, cap its thread pool at three times <para>When using new IO (NIO), ActiveMQ will, by default, cap its thread pool at three times
the number of cores (or hyper-threads) as reported by <literal> the number of cores (or hyper-threads) as reported by <literal>
Runtime.getRuntime().availableProcessors()</literal> for processing incoming packets. Runtime.getRuntime().availableProcessors()</literal> for processing incoming packets.
To override this value, you can set the number of threads by specifying the parameter To override this value, you can set the number of threads by specifying the parameter
@ -63,7 +63,7 @@
that require running periodically or with delays. It maps internally to a <literal that require running periodically or with delays. It maps internally to a <literal
>java.util.concurrent.ScheduledThreadPoolExecutor</literal> instance.</para> >java.util.concurrent.ScheduledThreadPoolExecutor</literal> instance.</para>
<para>The maximum number of thread used by this pool is configure in <literal <para>The maximum number of thread used by this pool is configure in <literal
>hornetq-configuration.xml</literal> with the <literal >activemq-configuration.xml</literal> with the <literal
>scheduled-thread-pool-max-size</literal> parameter. The default value is >scheduled-thread-pool-max-size</literal> parameter. The default value is
<literal>5</literal> threads. A small number of threads is usually sufficient <literal>5</literal> threads. A small number of threads is usually sufficient
for this pool.</para> for this pool.</para>
@ -74,7 +74,7 @@
server side. It maps internally to a <literal server side. It maps internally to a <literal
>java.util.concurrent.ThreadPoolExecutor</literal> instance.</para> >java.util.concurrent.ThreadPoolExecutor</literal> instance.</para>
<para>The maximum number of thread used by this pool is configure in <literal <para>The maximum number of thread used by this pool is configure in <literal
>hornetq-configuration.xml</literal> with the <literal >activemq-configuration.xml</literal> with the <literal
>thread-pool-max-size</literal> parameter.</para> >thread-pool-max-size</literal> parameter.</para>
<para>If a value of <literal>-1</literal> is used this signifies that the thread pool <para>If a value of <literal>-1</literal> is used this signifies that the thread pool
has no upper bound and new threads will be created on demand if there are not enough has no upper bound and new threads will be created on demand if there are not enough
@ -105,21 +105,21 @@
<title>Asynchronous IO</title> <title>Asynchronous IO</title>
<para>Asynchronous IO has a thread pool for receiving and dispatching events out of the <para>Asynchronous IO has a thread pool for receiving and dispatching events out of the
native layer. You will find it on a thread dump with the prefix native layer. You will find it on a thread dump with the prefix
HornetQ-AIO-poller-pool. HornetQ uses one thread per opened file on the journal ActiveMQ-AIO-poller-pool. ActiveMQ uses one thread per opened file on the journal
(there is usually one).</para> (there is usually one).</para>
<para>There is also a single thread used to invoke writes on libaio. We do that to avoid <para>There is also a single thread used to invoke writes on libaio. We do that to avoid
context switching on libaio that would cause performance issues. You will find this context switching on libaio that would cause performance issues. You will find this
thread on a thread dump with the prefix HornetQ-AIO-writer-pool.</para> thread on a thread dump with the prefix ActiveMQ-AIO-writer-pool.</para>
</section> </section>
</section> </section>
<section id="thread-pooling.client.side"> <section id="thread-pooling.client.side">
<title>Client-Side Thread Management</title> <title>Client-Side Thread Management</title>
<para>On the client side, HornetQ maintains a single static scheduled thread pool and a <para>On the client side, ActiveMQ maintains a single static scheduled thread pool and a
single static general thread pool for use by all clients using the same classloader in single static general thread pool for use by all clients using the same classloader in
that JVM instance.</para> that JVM instance.</para>
<para>The static scheduled thread pool has a maximum size of <literal>5</literal> threads, <para>The static scheduled thread pool has a maximum size of <literal>5</literal> threads,
and the general purpose thread pool has an unbounded maximum size.</para> and the general purpose thread pool has an unbounded maximum size.</para>
<para>If required HornetQ can also be configured so that each <literal <para>If required ActiveMQ can also be configured so that each <literal
>ClientSessionFactory</literal> instance does not use these static pools but instead >ClientSessionFactory</literal> instance does not use these static pools but instead
maintains its own scheduled and general purpose pool. Any sessions created from that maintains its own scheduled and general purpose pool. Any sessions created from that
<literal>ClientSessionFactory</literal> will use those pools instead.</para> <literal>ClientSessionFactory</literal> will use those pools instead.</para>
@ -127,7 +127,7 @@
simply use the appropriate setter methods immediately after creation, for simply use the appropriate setter methods immediately after creation, for
example:</para> example:</para>
<programlisting> <programlisting>
ServerLocator locator = HornetQClient.createServerLocatorWithoutHA(...) ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(...)
ClientSessionFactory myFactory = locator.createClientSessionFactory(); ClientSessionFactory myFactory = locator.createClientSessionFactory();
myFactory.setUseGlobalPools(false); myFactory.setUseGlobalPools(false);
myFactory.setScheduledThreadPoolMaxSize(10); myFactory.setScheduledThreadPoolMaxSize(10);
@ -136,9 +136,9 @@ myFactory.setThreadPoolMaxSize(-1); </programlisting>
ClientSessionFactory and use it to create the <literal>ConnectionFactory</literal> ClientSessionFactory and use it to create the <literal>ConnectionFactory</literal>
instance, for example:</para> instance, for example:</para>
<programlisting> <programlisting>
ConnectionFactory myConnectionFactory = HornetQJMSClient.createConnectionFactory(myFactory);</programlisting> ConnectionFactory myConnectionFactory = ActiveMQJMSClient.createConnectionFactory(myFactory);</programlisting>
<para>If you're using JNDI to instantiate <literal>HornetQConnectionFactory</literal> <para>If you're using JNDI to instantiate <literal>ActiveMQConnectionFactory</literal>
instances, you can also set these parameters in the <literal>hornetq-jms.xml</literal> instances, you can also set these parameters in the <literal>activemq-jms.xml</literal>
file where you describe your connection factory, for example:</para> file where you describe your connection factory, for example:</para>
<programlisting> <programlisting>
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">

18
docs/user-manual/en/tools.xml
View File

@ -18,14 +18,14 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="tools"> <chapter id="tools">
<title>Tools</title> <title>Tools</title>
<para>HornetQ ships with several helpful command line tools. All tools are available from the hornetq-tools-&lt;version&gt;-jar-with-dependencies.jar. <para>ActiveMQ ships with several helpful command line tools. All tools are available from the activemq-tools-&lt;version&gt;-jar-with-dependencies.jar.
As the name suggests, this Java archive contains HornetQ along with all of its dependencies. This is done to As the name suggests, this Java archive contains ActiveMQ along with all of its dependencies. This is done to
simplify the execution of the tools by eliminating the need so specify a classpath. These tools are:</para> simplify the execution of the tools by eliminating the need so specify a classpath. These tools are:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -34,7 +34,7 @@
are the paths to the directories where the bindings and message journals are stored, respectively. For are the paths to the directories where the bindings and message journals are stored, respectively. For
example: example:
</para> </para>
<programlisting>java -jar hornetq-tools-&lt;version&gt;-jar-with-dependencies.jar print-data /home/user/hornetq/data/bindings /home/user/hornetq/data/journal</programlisting> <programlisting>java -jar activemq-tools-&lt;version&gt;-jar-with-dependencies.jar print-data /home/user/activemq/data/bindings /home/user/activemq/data/journal</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold"><literal>print-pages</literal></emphasis>. Used for low-level inspection of paged message data. It takes two <para><emphasis role="bold"><literal>print-pages</literal></emphasis>. Used for low-level inspection of paged message data. It takes two
@ -42,7 +42,7 @@
paths to the directories where paged messages and the message journals are stored, respectively. For paths to the directories where paged messages and the message journals are stored, respectively. For
example: example:
</para> </para>
<programlisting>java -jar hornetq-tools-&lt;version&gt;-jar-with-dependencies.jar print-pages /home/user/hornetq/data/paging-directory /home/user/hornetq/data/journal</programlisting> <programlisting>java -jar activemq-tools-&lt;version&gt;-jar-with-dependencies.jar print-pages /home/user/activemq/data/paging-directory /home/user/activemq/data/journal</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold"><literal>export</literal></emphasis>. Used for exporting all binding and message data (including paged and large <para><emphasis role="bold"><literal>export</literal></emphasis>. Used for exporting all binding and message data (including paged and large
@ -65,7 +65,7 @@
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>Here's an example:</para> <para>Here's an example:</para>
<programlisting>java -jar hornetq-tools-&lt;version&gt;-jar-with-dependencies.jar export /home/user/hornetq/data/bindings-directory /home/user/hornetq/data/journal-directory /home/user/hornetq/data/paging-directory /home/user/hornetq/data/large-messages</programlisting> <programlisting>java -jar activemq-tools-&lt;version&gt;-jar-with-dependencies.jar export /home/user/activemq/data/bindings-directory /home/user/activemq/data/journal-directory /home/user/activemq/data/paging-directory /home/user/activemq/data/large-messages</programlisting>
<para>This tool will export directly to standard out so if the data needs to be stored in a file please <para>This tool will export directly to standard out so if the data needs to be stored in a file please
redirect as appropriate for the operation system in use. Also, please note that the <literal>export</literal> redirect as appropriate for the operation system in use. Also, please note that the <literal>export</literal>
tool is single threaded so depending on the size of the journal it could take awhile to complete. tool is single threaded so depending on the size of the journal it could take awhile to complete.
@ -74,7 +74,7 @@
<listitem> <listitem>
<para><emphasis role="bold"><literal>import</literal></emphasis>. Used for importing data from an XML document generated by the <para><emphasis role="bold"><literal>import</literal></emphasis>. Used for importing data from an XML document generated by the
<literal>export</literal> tool. The <literal>import</literal> tool reads the XML document and connects <literal>export</literal> tool. The <literal>import</literal> tool reads the XML document and connects
to a HornetQ server via Netty to import all the data. It takes 5 parameters: to a ActiveMQ server via Netty to import all the data. It takes 5 parameters:
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -88,7 +88,7 @@
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>port</literal> - the port where HornetQ is listening.</para> <para><literal>port</literal> - the port where ActiveMQ is listening.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>transactional</literal> - a <literal>boolean</literal> flag to indicate whether or not to <para><literal>transactional</literal> - a <literal>boolean</literal> flag to indicate whether or not to
@ -108,7 +108,7 @@
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>Here's an example:</para> <para>Here's an example:</para>
<programlisting>java -jar hornetq-tools-&lt;version&gt;-jar-with-dependencies.jar import /home/user/exportData.xml 127.0.0.1 5445 false false</programlisting> <programlisting>java -jar activemq-tools-&lt;version&gt;-jar-with-dependencies.jar import /home/user/exportData.xml 127.0.0.1 5445 false false</programlisting>
<para>Like the <literal>export</literal> tool the <literal>import</literal> tool is single threaded so <para>Like the <literal>export</literal> tool the <literal>import</literal> tool is single threaded so
depending on the size of the XML file it may take awhile for the process to complete. depending on the size of the XML file it may take awhile for the process to complete.
</para> </para>

10
docs/user-manual/en/transaction-config.xml
View File

@ -18,22 +18,22 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="transaction-config"> <chapter id="transaction-config">
<title>Resource Manager Configuration</title> <title>Resource Manager Configuration</title>
<para>HornetQ has its own Resource Manager for handling the lifespan of JTA transactions. When a <para>ActiveMQ has its own Resource Manager for handling the lifespan of JTA transactions. When a
transaction is started the resource manager is notified and keeps a record of the transaction is started the resource manager is notified and keeps a record of the
transaction and its current state. It is possible in some cases for a transaction to be transaction and its current state. It is possible in some cases for a transaction to be
started but then forgotten about. Maybe the client died and never came back. If this happens started but then forgotten about. Maybe the client died and never came back. If this happens
then the transaction will just sit there indefinitely.</para> then the transaction will just sit there indefinitely.</para>
<para>To cope with this HornetQ can, if configured, scan for old transactions and rollback any <para>To cope with this ActiveMQ can, if configured, scan for old transactions and rollback any
it finds. The default for this is 3000000 milliseconds (5 minutes), i.e. any transactions older it finds. The default for this is 3000000 milliseconds (5 minutes), i.e. any transactions older
than 5 minutes are removed. This timeout can be changed by editing the <literal than 5 minutes are removed. This timeout can be changed by editing the <literal
>transaction-timeout</literal> property in <literal>hornetq-configuration.xml</literal> (value must be in milliseconds). >transaction-timeout</literal> property in <literal>activemq-configuration.xml</literal> (value must be in milliseconds).
The property <literal>transaction-timeout-scan-period</literal> configures how often, in The property <literal>transaction-timeout-scan-period</literal> configures how often, in
milliseconds, to scan for old transactions.</para> milliseconds, to scan for old transactions.</para>
<para>Please note that HornetQ will not unilaterally rollback any XA transactions in a prepared state - this must be heuristically rolled <para>Please note that ActiveMQ will not unilaterally rollback any XA transactions in a prepared state - this must be heuristically rolled
back via the management API if you are sure they will never be resolved by the transaction manager.</para> back via the management API if you are sure they will never be resolved by the transaction manager.</para>
</chapter> </chapter>

12
docs/user-manual/en/undelivered-messages.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="undelivered-messages"> <chapter id="undelivered-messages">
@ -62,7 +62,7 @@
&lt;max-redelivery-delay>50000&lt;/max-redelivery-delay> &lt;max-redelivery-delay>50000&lt;/max-redelivery-delay>
&lt;/address-setting></programlisting> &lt;/address-setting></programlisting>
<para>If a <literal>redelivery-delay</literal> is specified, HornetQ will wait this delay <para>If a <literal>redelivery-delay</literal> is specified, ActiveMQ will wait this delay
before redelivering the messages.</para> before redelivering the messages.</para>
<para>By default, there is no redelivery delay (<literal>redelivery-delay</literal>is set <para>By default, there is no redelivery delay (<literal>redelivery-delay</literal>is set
to 0).</para> to 0).</para>
@ -89,7 +89,7 @@
attempts, the message is removed from the queue and send instead to a dead letter address. </para> attempts, the message is removed from the queue and send instead to a dead letter address. </para>
<para>Any such messages can then be diverted to queue(s) where they can later be perused by <para>Any such messages can then be diverted to queue(s) where they can later be perused by
the system administrator for action to be taken.</para> the system administrator for action to be taken.</para>
<para>HornetQ's addresses can be assigned a dead letter address. Once the messages have been <para>ActiveMQ's addresses can be assigned a dead letter address. Once the messages have been
unsuccessfully delivered for a given number of attempts, they are removed from the queue unsuccessfully delivered for a given number of attempts, they are removed from the queue
and sent to the dead letter address. These <emphasis>dead letter</emphasis> messages can and sent to the dead letter address. These <emphasis>dead letter</emphasis> messages can
later be consumed for further inspection.</para> later be consumed for further inspection.</para>
@ -138,7 +138,7 @@
</section> </section>
<section id="configuring.delivery.count.persistence"> <section id="configuring.delivery.count.persistence">
<title>Delivery Count Persistence</title> <title>Delivery Count Persistence</title>
<para>In normal use, HornetQ does not update delivery count <emphasis>persistently</emphasis> <para>In normal use, ActiveMQ does not update delivery count <emphasis>persistently</emphasis>
until a message is rolled back (i.e. the delivery count is not updated until a message is rolled back (i.e. the delivery count is not updated
<emphasis>before</emphasis> the message is delivered to the consumer). In most messaging <emphasis>before</emphasis> the message is delivered to the consumer). In most messaging
use cases, the messages are consumed, acknowledged and forgotten as soon as they are use cases, the messages are consumed, acknowledged and forgotten as soon as they are
@ -150,10 +150,10 @@
not have been reflected in the delivery count. During the recovery phase, the server will not have been reflected in the delivery count. During the recovery phase, the server will
not have knowledge of that and will deliver the message with <literal>redelivered</literal> not have knowledge of that and will deliver the message with <literal>redelivered</literal>
set to <literal>false</literal> while it should be <literal>true</literal>. </para> set to <literal>false</literal> while it should be <literal>true</literal>. </para>
<para>As this behavior breaks strict JMS semantics, HornetQ allows to persist delivery count <para>As this behavior breaks strict JMS semantics, ActiveMQ allows to persist delivery count
before message delivery but disabled it by default for performance implications.</para> before message delivery but disabled it by default for performance implications.</para>
<para>To enable it, set <literal>persist-delivery-count-before-delivery</literal> to <literal <para>To enable it, set <literal>persist-delivery-count-before-delivery</literal> to <literal
>true</literal> in <literal>hornetq-configuration.xml</literal>:</para> >true</literal> in <literal>activemq-configuration.xml</literal>:</para>
<programlisting> <programlisting>
&lt;persist-delivery-count-before-delivery>true&lt;/persist-delivery-count-before-delivery></programlisting> &lt;persist-delivery-count-before-delivery>true&lt;/persist-delivery-count-before-delivery></programlisting>
</section> </section>

14
docs/user-manual/en/using-core.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<chapter id="using-core"> <chapter id="using-core">
<title>Using Core</title> <title>Using Core</title>
<para>HornetQ core is a completely JMS-agnostic messaging system with its own non-JMS API. We <para>ActiveMQ core is a completely JMS-agnostic messaging system with its own non-JMS API. We
call this the <emphasis>core API</emphasis>.</para> call this the <emphasis>core API</emphasis>.</para>
<para>If you don't want to use JMS you can use the core API directly. The core API provides all <para>If you don't want to use JMS you can use the core API directly. The core API provides all
the functionality of JMS but without much of the complexity. It also provides features that the functionality of JMS but without much of the complexity. It also provides features that
@ -62,12 +62,12 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Messages can be specified with a priority value between 0 and 9. 0 <para>Messages can be specified with a priority value between 0 and 9. 0
represents the lowest priority and 9 represents the highest. HornetQ will represents the lowest priority and 9 represents the highest. ActiveMQ will
attempt to deliver higher priority messages before lower priority attempt to deliver higher priority messages before lower priority
ones.</para> ones.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Messages can be specified with an optional expiry time. HornetQ will not <para>Messages can be specified with an optional expiry time. ActiveMQ will not
deliver messages after its expiry time has been exceeded.</para> deliver messages after its expiry time has been exceeded.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -75,7 +75,7 @@
message was sent.</para> message was sent.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>HornetQ also supports the sending/consuming of very large messages - much <para>ActiveMQ also supports the sending/consuming of very large messages - much
larger than can fit in available RAM at any one time.</para> larger than can fit in available RAM at any one time.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -122,7 +122,7 @@
<para>In JMS terms think of a <literal>ServerLocator</literal> in the same way you would <para>In JMS terms think of a <literal>ServerLocator</literal> in the same way you would
a JMS Connection Factory.</para> a JMS Connection Factory.</para>
<para><literal>ServerLocator</literal> instances are created using the <literal <para><literal>ServerLocator</literal> instances are created using the <literal
>HornetQClient</literal> factory class.</para> >ActiveMQClient</literal> factory class.</para>
</section> </section>
<section> <section>
<title>ClientSessionFactory</title> <title>ClientSessionFactory</title>
@ -145,7 +145,7 @@
<para>ClientSession instances can be registered with an optional <literal <para>ClientSession instances can be registered with an optional <literal
>SendAcknowledgementHandler</literal>. This allows your client code to be >SendAcknowledgementHandler</literal>. This allows your client code to be
notified asynchronously when sent messages have successfully reached the server. notified asynchronously when sent messages have successfully reached the server.
This unique HornetQ feature, allows you to have full guarantees that sent messages This unique ActiveMQ feature, allows you to have full guarantees that sent messages
have reached the server without having to block on each message sent until a have reached the server without having to block on each message sent until a
response is received. Blocking on each messages sent is costly since it requires a response is received. Blocking on each messages sent is costly since it requires a
network round trip for each message sent. By not blocking and receiving send network round trip for each message sent. By not blocking and receiving send
@ -186,7 +186,7 @@
<emphasis>queue</emphasis> for the consumer, creating the consumer and <emphasis>queue</emphasis> for the consumer, creating the consumer and
<emphasis>starting</emphasis> it.</para> <emphasis>starting</emphasis> it.</para>
<programlisting> <programlisting>
ServerLocator locator = HornetQClient.createServerLocatorWithoutHA(new TransportConfiguration( ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(
InVMConnectorFactory.class.getName())); InVMConnectorFactory.class.getName()));
// In this simple example, we just use one session for both producing and receiving // In this simple example, we just use one session for both producing and receiving

38
docs/user-manual/en/using-jms.xml
View File

@ -18,24 +18,24 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="using-jms"> <chapter id="using-jms">
<title>Using JMS</title> <title>Using JMS</title>
<para>Although HornetQ provides a JMS agnostic messaging API, many users will be more <para>Although ActiveMQ provides a JMS agnostic messaging API, many users will be more
comfortable using JMS.</para> comfortable using JMS.</para>
<para>JMS is a very popular API standard for messaging, and most messaging systems provide a JMS <para>JMS is a very popular API standard for messaging, and most messaging systems provide a JMS
API. If you are completely new to JMS we suggest you follow the<ulink API. If you are completely new to JMS we suggest you follow the<ulink
url="http://docs.oracle.com/javaee/1.3/jms/tutorial"> Sun url="http://docs.oracle.com/javaee/1.3/jms/tutorial"> Sun
JMS tutorial</ulink> - a full JMS tutorial is out of scope for this guide.</para> JMS tutorial</ulink> - a full JMS tutorial is out of scope for this guide.</para>
<para>HornetQ also ships with a wide range of examples, many of which demonstrate JMS API usage. <para>ActiveMQ also ships with a wide range of examples, many of which demonstrate JMS API usage.
A good place to start would be to play around with the simple JMS Queue and Topic example, A good place to start would be to play around with the simple JMS Queue and Topic example,
but we also provide examples for many other parts of the JMS API. A full description of the but we also provide examples for many other parts of the JMS API. A full description of the
examples is available in <xref linkend="examples"/>.</para> examples is available in <xref linkend="examples"/>.</para>
<para>In this section we'll go through the main steps in configuring the server for JMS and <para>In this section we'll go through the main steps in configuring the server for JMS and
creating a simple JMS program. We'll also show how to configure and use JNDI, and also how creating a simple JMS program. We'll also show how to configure and use JNDI, and also how
to use JMS with HornetQ without using any JNDI.</para> to use JMS with ActiveMQ without using any JNDI.</para>
<section> <section>
<title>A simple ordering system</title> <title>A simple ordering system</title>
<para>For this chapter we're going to use a very simple ordering system as our example. It is <para>For this chapter we're going to use a very simple ordering system as our example. It is
@ -52,7 +52,7 @@
</section> </section>
<section id="using-jms.server.configuration"> <section id="using-jms.server.configuration">
<title>JMS Server Configuration</title> <title>JMS Server Configuration</title>
<para>The file <literal>hornetq-jms.xml</literal> on the server classpath contains any JMS <para>The file <literal>activemq-jms.xml</literal> on the server classpath contains any JMS
Queue, Topic and ConnectionFactory instances that we wish to create and make available Queue, Topic and ConnectionFactory instances that we wish to create and make available
to lookup via the JNDI.</para> to lookup via the JNDI.</para>
<para>A JMS ConnectionFactory object is used by the client to make connections to the <para>A JMS ConnectionFactory object is used by the client to make connections to the
@ -65,7 +65,7 @@
<programlisting> <programlisting>
&lt;configuration xmlns="urn:activemq" &lt;configuration xmlns="urn:activemq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:hornetq ../schemas/activemq-jms.xsd "> xsi:schemaLocation="urn:activemq ../schemas/activemq-jms.xsd ">
&lt;connection-factory name="ConnectionFactory"> &lt;connection-factory name="ConnectionFactory">
&lt;connectors> &lt;connectors>
@ -86,13 +86,13 @@
<note> <note>
<para>The JMS connection factory references a <literal>connector</literal> called <para>The JMS connection factory references a <literal>connector</literal> called
<literal>netty</literal>. This is a reference to a connector object deployed in <literal>netty</literal>. This is a reference to a connector object deployed in
the main core configuration file <literal>hornetq-configuration.xml</literal> which the main core configuration file <literal>activemq-configuration.xml</literal> which
defines the transport and parameters used to actually connect to the server.</para> defines the transport and parameters used to actually connect to the server.</para>
</note> </note>
</section> </section>
<section id="using-jms.configure.factory.types"> <section id="using-jms.configure.factory.types">
<title>Connection Factory Types</title> <title>Connection Factory Types</title>
<para>The JMS API doc provides several connection factories for applications. HornetQ JMS users <para>The JMS API doc provides several connection factories for applications. ActiveMQ JMS users
can choose to configure the types for their connection factories. Each connection factory can choose to configure the types for their connection factories. Each connection factory
has a <literal>signature</literal> attribute and a <literal>xa</literal> parameter, the has a <literal>signature</literal> attribute and a <literal>xa</literal> parameter, the
combination of which determines the type of the factory. Attribute <literal>signature</literal> combination of which determines the type of the factory. Attribute <literal>signature</literal>
@ -151,7 +151,11 @@
<programlisting> <programlisting>
&lt;configuration xmlns="urn:activemq" &lt;configuration xmlns="urn:activemq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<<<<<<< HEAD
xsi:schemaLocation="urn:hornetq ../schemas/activemq-jms.xsd "> xsi:schemaLocation="urn:hornetq ../schemas/activemq-jms.xsd ">
=======
xsi:schemaLocation="urn:activemq ../schemas/activemq-jms.xsd ">
>>>>>>> 198a239... ACTIVEMQ6-9 Clean up docs
&lt;connection-factory name="ConnectionFactory" signature="queue"> &lt;connection-factory name="ConnectionFactory" signature="queue">
&lt;xa>true&lt;/xa> &lt;xa>true&lt;/xa>
@ -184,13 +188,13 @@ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting
is the port used by the JNDI server and may vary depending on how you have configured is the port used by the JNDI server and may vary depending on how you have configured
your JNDI server.</para> your JNDI server.</para>
<para>In the default standalone configuration, JNDI server ports are configured in the file <para>In the default standalone configuration, JNDI server ports are configured in the file
<literal>hornetq-beans.xml</literal> by setting properties on the <literal <literal>activemq-beans.xml</literal> by setting properties on the <literal
>JNDIServer</literal> bean:</para> >JNDIServer</literal> bean:</para>
<programlisting> <programlisting>
&lt;bean name="StandaloneServer" class="org.apache.activemq.jms.server.impl.StandaloneNamingServer"> &lt;bean name="StandaloneServer" class="org.apache.activemq.jms.server.impl.StandaloneNamingServer">
&lt;constructor> &lt;constructor>
&lt;parameter> &lt;parameter>
&lt;inject bean="HornetQServer"/> &lt;inject bean="ActiveMQServer"/>
&lt;/parameter> &lt;/parameter>
&lt;/constructor> &lt;/constructor>
&lt;property name="port">${jnp.port:1099}&lt;/property> &lt;property name="port">${jnp.port:1099}&lt;/property>
@ -204,8 +208,8 @@ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting
>localhost</literal>!</para> >localhost</literal>!</para>
</note> </note>
<note> <note>
<para>The JNDIServer bean must be defined <emphasis>only when HornetQ is running in <para>The JNDIServer bean must be defined <emphasis>only when ActiveMQ is running in
stand-alone mode</emphasis>. When HornetQ is integrated to JBoss Application stand-alone mode</emphasis>. When ActiveMQ is integrated to JBoss Application
Server, JBoss AS will provide a ready-to-use JNDI server without any additional Server, JBoss AS will provide a ready-to-use JNDI server without any additional
configuration.</para> configuration.</para>
</note> </note>
@ -254,21 +258,21 @@ System.out.println("Got order: " + receivedMessage.getText());</programlisting>
JNDI, in some cases a JNDI server is not available and you still want to use JMS, or you JNDI, in some cases a JNDI server is not available and you still want to use JMS, or you
just think "Why do I need JNDI? Why can't I just instantiate these objects just think "Why do I need JNDI? Why can't I just instantiate these objects
directly?"</para> directly?"</para>
<para>With HornetQ you can do exactly that. HornetQ supports the direct instantiation of JMS <para>With ActiveMQ you can do exactly that. ActiveMQ supports the direct instantiation of JMS
Queue, Topic and ConnectionFactory instances, so you don't have to use JNDI at Queue, Topic and ConnectionFactory instances, so you don't have to use JNDI at
all.</para> all.</para>
<para>For a full working example of direct instantiation please see the JMS examples in <para>For a full working example of direct instantiation please see the JMS examples in
<xref linkend="examples"/>.</para> <xref linkend="examples"/>.</para>
<para>Here's our simple example, rewritten to not use JNDI at all:</para> <para>Here's our simple example, rewritten to not use JNDI at all:</para>
<para>We create the JMS ConnectionFactory object via the HornetQJMSClient Utility class, <para>We create the JMS ConnectionFactory object via the ActiveMQJMSClient Utility class,
note we need to provide connection parameters and specify which transport we are using, note we need to provide connection parameters and specify which transport we are using,
for more information on connectors please see <xref linkend="configuring-transports" for more information on connectors please see <xref linkend="configuring-transports"
/>.</para> />.</para>
<programlisting> <programlisting>
TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName()); TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName());
ConnectionFactory cf = HornetQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);</programlisting> ConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);</programlisting>
<para>We also create the JMS Queue object via the HornetQJMSClient Utility class:</para> <para>We also create the JMS Queue object via the ActiveMQJMSClient Utility class:</para>
<programlisting>Queue orderQueue = HornetQJMSClient.createQueue("OrderQueue");</programlisting> <programlisting>Queue orderQueue = ActiveMQJMSClient.createQueue("OrderQueue");</programlisting>
<para>Next we create a JMS connection using the connection factory:</para> <para>Next we create a JMS connection using the connection factory:</para>
<programlisting>Connection connection = cf.createConnection();</programlisting> <programlisting>Connection connection = cf.createConnection();</programlisting>
<para>And we create a non transacted JMS Session, with AUTO_ACKNOWLEDGE acknowledge <para>And we create a non transacted JMS Session, with AUTO_ACKNOWLEDGE acknowledge

70
docs/user-manual/en/using-server.xml
View File

@ -18,16 +18,16 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="using-server"> <chapter id="using-server">
<title>Using the Server</title> <title>Using the Server</title>
<para>This chapter will familiarise you with how to use the HornetQ server.</para> <para>This chapter will familiarise you with how to use the ActiveMQ server.</para>
<para>We'll show where it is, how to start and stop it, and we'll describe the directory layout <para>We'll show where it is, how to start and stop it, and we'll describe the directory layout
and what all the files are and what they do.</para> and what all the files are and what they do.</para>
<para>For the remainder of this chapter when we talk about the HornetQ server we mean the <para>For the remainder of this chapter when we talk about the ActiveMQ server we mean the
HornetQ standalone server, in its default configuration with a JMS Service and JNDI service ActiveMQ standalone server, in its default configuration with a JMS Service and JNDI service
enabled.</para> enabled.</para>
<para>When running embedded in JBoss Application Server the layout may be slightly different but <para>When running embedded in JBoss Application Server the layout may be slightly different but
by-and-large will be the same.</para> by-and-large will be the same.</para>
@ -35,19 +35,19 @@
<title>Starting and Stopping the standalone server</title> <title>Starting and Stopping the standalone server</title>
<para>In the distribution you will find a directory called <literal>bin</literal>.</para> <para>In the distribution you will find a directory called <literal>bin</literal>.</para>
<para><literal>cd</literal> into that directory and you will find a Unix/Linux script called <para><literal>cd</literal> into that directory and you will find a Unix/Linux script called
<literal>hornetq</literal> and a Windows script called <literal>hornetq.cmd</literal>.</para> <literal>activemq</literal> and a Windows script called <literal>activemq.cmd</literal>.</para>
<para>To start the HornetQ instance on Unix/Linux type <literal>./hornetq run</literal></para> <para>To start the ActiveMQ instance on Unix/Linux type <literal>./activemq run</literal></para>
<para>To start the HornetQ instance on Windows type <literal>hornetq.cmd run</literal></para> <para>To start the ActiveMQ instance on Windows type <literal>activemq.cmd run</literal></para>
<para>These scripts are very simple and basically just set-up the classpath and some JVM <para>These scripts are very simple and basically just set-up the classpath and some JVM
parameters and bootstrap the server using <ulink parameters and bootstrap the server using <ulink
url="https://github.com/airlift/airline">Airline</ulink>.</para> url="https://github.com/airlift/airline">Airline</ulink>.</para>
<para>To stop the HornetQ instance you will use the same <literal>hornetq</literal> script.</para> <para>To stop the ActiveMQ instance you will use the same <literal>activemq</literal> script.</para>
<para>To run on Unix/Linux type <literal>./hornetq stop</literal></para> <para>To run on Unix/Linux type <literal>./activemq stop</literal></para>
<para>To run on Windows type <literal>hornetq.cmd stop</literal></para> <para>To run on Windows type <literal>activemq.cmd stop</literal></para>
<para>Please note that HornetQ requires a Java 6 or later runtime to run.</para> <para>Please note that ActiveMQ requires a Java 6 or later runtime to run.</para>
<para>By default the <literal>config/non-clustered/bootstrap.xml</literal> configuration is used. The <para>By default the <literal>config/non-clustered/bootstrap.xml</literal> configuration is used. The
configuration can be changed e.g. by running configuration can be changed e.g. by running
<literal>./hornetq run -- xml:../config/clustered/bootstrap.xml</literal> or another config of <literal>./activemq run -- xml:../config/clustered/bootstrap.xml</literal> or another config of
your choosing.</para> your choosing.</para>
</section> </section>
<section> <section>
@ -55,7 +55,7 @@
<para>The run scripts set some JVM settings for tuning the garbage collection policy <para>The run scripts set some JVM settings for tuning the garbage collection policy
and heap size. We recommend using a parallel garbage collection algorithm to smooth and heap size. We recommend using a parallel garbage collection algorithm to smooth
out latency and minimise large GC pauses.</para> out latency and minimise large GC pauses.</para>
<para>By default HornetQ runs in a maximum of 1GiB of RAM. To increase the memory settings <para>By default ActiveMQ runs in a maximum of 1GiB of RAM. To increase the memory settings
change the <literal>-Xms</literal> and <literal>-Xmx</literal> memory settings as you change the <literal>-Xms</literal> and <literal>-Xmx</literal> memory settings as you
would for any Java program.</para> would for any Java program.</para>
<para>If you wish to add any more JVM arguments or tune the existing ones, the run scripts <para>If you wish to add any more JVM arguments or tune the existing ones, the run scripts
@ -91,7 +91,7 @@
</section> </section>
<section> <section>
<title>System properties</title> <title>System properties</title>
<para>HornetQ can take a system property on the command line for configuring logging.</para> <para>ActiveMQ can take a system property on the command line for configuring logging.</para>
<para>For more information on configuring logging, please see <xref linkend="logging" <para>For more information on configuring logging, please see <xref linkend="logging"
/>.</para> />.</para>
</section> </section>
@ -101,31 +101,31 @@
by default) references the specific broker configuration files.</para> by default) references the specific broker configuration files.</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>hornetq-configuration.xml</literal>. This is the main HornetQ <para><literal>activemq-configuration.xml</literal>. This is the main ActiveMQ
configuration file. All the parameters in this file are described in <xref configuration file. All the parameters in this file are described in <xref
linkend="configuration-index"/>. Please see <xref linkend="configuration-index"/>. Please see <xref
linkend="usingserver.mainconfig"/> for more information on this file.</para> linkend="usingserver.mainconfig"/> for more information on this file.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>hornetq-queues.xml</literal>. This file contains predefined queues, <para><literal>activemq-queues.xml</literal>. This file contains predefined queues,
queue settings and security settings. The file is optional - all this queue settings and security settings. The file is optional - all this
configuration can also live in <literal>hornetq-configuration.xml</literal>. In configuration can also live in <literal>activemq-configuration.xml</literal>. In
fact, the default configuration sets do not have a <literal fact, the default configuration sets do not have a <literal
>hornetq-queues.xml</literal> file. The purpose of allowing queues to be >activemq-queues.xml</literal> file. The purpose of allowing queues to be
configured in these files is to allow you to manage your queue configuration configured in these files is to allow you to manage your queue configuration
over many files instead of being forced to maintain it in a single file. There over many files instead of being forced to maintain it in a single file. There
can be many <literal>hornetq-queues.xml</literal> files on the classpath. All can be many <literal>activemq-queues.xml</literal> files on the classpath. All
will be loaded if found.</para> will be loaded if found.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>hornetq-users.xml</literal> HornetQ ships with a basic security <para><literal>activemq-users.xml</literal> ActiveMQ ships with a basic security
manager implementation which obtains user credentials from the <literal manager implementation which obtains user credentials from the <literal
>hornetq-users.xml</literal> file. This file contains user, password and >activemq-users.xml</literal> file. This file contains user, password and
role information. For more information on security, please see <xref role information. For more information on security, please see <xref
linkend="security"/>.</para> linkend="security"/>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>hornetq-jms.xml</literal> The distro configuration by default <para><literal>activemq-jms.xml</literal> The distro configuration by default
includes a server side JMS service which mainly deploys JMS Queues, Topics and includes a server side JMS service which mainly deploys JMS Queues, Topics and
ConnectionFactorys from this file into JNDI. If you're not using JMS, or you ConnectionFactorys from this file into JNDI. If you're not using JMS, or you
don't need to deploy JMS objects on the server side, then you don't need this don't need to deploy JMS objects on the server side, then you don't need this
@ -135,7 +135,7 @@
</itemizedlist> </itemizedlist>
<note> <note>
<para>The property <literal>file-deployment-enabled</literal> in the <literal <para>The property <literal>file-deployment-enabled</literal> in the <literal
>hornetq-configuration.xml</literal> configuration when set to false means that >activemq-configuration.xml</literal> configuration when set to false means that
the other configuration files are not loaded. This is true by default.</para> the other configuration files are not loaded. This is true by default.</para>
</note> </note>
<para>It is also possible to use system property substitution in all the configuration <para>It is also possible to use system property substitution in all the configuration
@ -144,15 +144,15 @@
<programlisting> <programlisting>
&lt;connector name="netty"> &lt;connector name="netty">
&lt;factory-class>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory&lt;/factory-class> &lt;factory-class>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory&lt;/factory-class>
&lt;param key="host" value="${hornetq.remoting.netty.host:localhost}"/> &lt;param key="host" value="${activemq.remoting.netty.host:localhost}"/>
&lt;param key="port" value="${hornetq.remoting.netty.port:5445}"/> &lt;param key="port" value="${activemq.remoting.netty.port:5445}"/>
&lt;/connector></programlisting> &lt;/connector></programlisting>
<para>Here you can see we have replaced 2 values with system properties <literal <para>Here you can see we have replaced 2 values with system properties <literal
>hornetq.remoting.netty.host</literal> and <literal >activemq.remoting.netty.host</literal> and <literal
>hornetq.remoting.netty.port</literal>. These values will be replaced by the value >activemq.remoting.netty.port</literal>. These values will be replaced by the value
found in the system property if there is one, if not they default back to localhost or found in the system property if there is one, if not they default back to localhost or
5445 respectively. It is also possible to not supply a default. i.e. <literal 5445 respectively. It is also possible to not supply a default. i.e. <literal
>${hornetq.remoting.netty.host}</literal>, however the system property >${activemq.remoting.netty.host}</literal>, however the system property
<emphasis>must</emphasis> be supplied in that case.</para> <emphasis>must</emphasis> be supplied in that case.</para>
</section> </section>
<section id="server.bootstrap.configuration"> <section id="server.bootstrap.configuration">
@ -161,10 +161,10 @@
<para>The bootstrap file is very simple. Let's take a look at an example:</para> <para>The bootstrap file is very simple. Let's take a look at an example:</para>
<para> <para>
<programlisting> <programlisting>
&lt;broker xmlns="http://hornetq.org/schema"> &lt;broker xmlns="http://activemq.org/schema">
&lt;file:core configuration="${hornetq.home}/config/stand-alone/non-clustered/hornetq-configuration.xml">&lt;/core> &lt;file:core configuration="${activemq.home}/config/stand-alone/non-clustered/activemq-configuration.xml">&lt;/core>
&lt;file:jms configuration="${hornetq.home}/config/stand-alone/non-clustered/hornetq-jms.xml">&lt;/jms> &lt;file:jms configuration="${activemq.home}/config/stand-alone/non-clustered/activemq-jms.xml">&lt;/jms>
&lt;basic-security/> &lt;basic-security/>
@ -182,7 +182,7 @@
<listitem id="jms"> <listitem id="jms">
<para>jms</para> <para>jms</para>
<para>This deploys any JMS Objects such as JMS Queues, Topics and ConnectionFactory <para>This deploys any JMS Objects such as JMS Queues, Topics and ConnectionFactory
instances from the <literal>hornetq-jms.xml</literal> file specified. It also instances from the <literal>activemq-jms.xml</literal> file specified. It also
provides a simple management API for manipulating JMS Objects. On the whole it provides a simple management API for manipulating JMS Objects. On the whole it
just translates and delegates its work to the core server. If you don't need to just translates and delegates its work to the core server. If you don't need to
deploy JMS Queues, Topics and ConnectionFactories from server side configuration deploy JMS Queues, Topics and ConnectionFactories from server side configuration
@ -197,10 +197,10 @@
</section> </section>
<section id="usingserver.mainconfig"> <section id="usingserver.mainconfig">
<title>The main configuration file.</title> <title>The main configuration file.</title>
<para>The configuration for the HornetQ core server is contained in <literal <para>The configuration for the ActiveMQ core server is contained in <literal
>hornetq-configuration.xml</literal>. This is what the FileConfiguration bean uses >activemq-configuration.xml</literal>. This is what the FileConfiguration bean uses
to configure the messaging server.</para> to configure the messaging server.</para>
<para>There are many attributes which you can configure HornetQ. In most cases the defaults <para>There are many attributes which you can configure ActiveMQ. In most cases the defaults
will do fine, in fact every attribute can be defaulted which means a file with a single will do fine, in fact every attribute can be defaulted which means a file with a single
empty <literal>configuration</literal> element is a valid configuration file. The empty <literal>configuration</literal> element is a valid configuration file. The
different configuration will be explained throughout the manual or you can refer to the different configuration will be explained throughout the manual or you can refer to the

16
docs/user-manual/en/vertx-integration.xml
View File

@ -18,7 +18,7 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="vertx-integration"> <chapter id="vertx-integration">
@ -26,13 +26,13 @@
<para><ulink url="http://vertx.io/">Vert.x</ulink> is a lightweight, high performance application platform for the <para><ulink url="http://vertx.io/">Vert.x</ulink> is a lightweight, high performance application platform for the
JVM that's designed for modern mobile, web, and enterprise applications. Vert.x provides a distributed event bus that JVM that's designed for modern mobile, web, and enterprise applications. Vert.x provides a distributed event bus that
allows messages to be sent across vert.x instances and clients. You can now redirect and persist any vert.x messages allows messages to be sent across vert.x instances and clients. You can now redirect and persist any vert.x messages
to HornetQ and route those messages to a specified vertx address by configuring HornetQ vertx incoming and outgoing to ActiveMQ and route those messages to a specified vertx address by configuring ActiveMQ vertx incoming and outgoing
vertx connector services. vertx connector services.
</para> </para>
<section> <section>
<title>Configuring a Vertx Incoming Connector Service</title> <title>Configuring a Vertx Incoming Connector Service</title>
<para>Vertx Incoming Connector services receive messages from vertx event bus and route them to a HornetQ queue. <para>Vertx Incoming Connector services receive messages from vertx event bus and route them to a ActiveMQ queue.
Such a service can be configured as follows:</para> Such a service can be configured as follows:</para>
<programlisting> <programlisting>
&lt;connector-service name="vertx-incoming-connector"> &lt;connector-service name="vertx-incoming-connector">
@ -46,7 +46,7 @@
<para>Shown are the required params for the connector service:</para> <para>Shown are the required params for the connector service:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>queue</literal>. The name of the HornetQ queue to send message to.</para> <para><literal>queue</literal>. The name of the ActiveMQ queue to send message to.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>As well as these required paramaters there are the following optional parameters</para> <para>As well as these required paramaters there are the following optional parameters</para>
@ -61,7 +61,7 @@
<para><literal>quorum-size</literal>. The quorum size of the target vertx instance.</para> <para><literal>quorum-size</literal>. The quorum size of the target vertx instance.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>ha-group</literal>. The name of the ha-group of target vertx instance. Default is <literal>hornetq</literal>.</para> <para><literal>ha-group</literal>. The name of the ha-group of target vertx instance. Default is <literal>activemq</literal>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>vertx-address</literal>. The vertx address to listen to. default is org.apache.activemq.</para> <para><literal>vertx-address</literal>. The vertx address to listen to. default is org.apache.activemq.</para>
@ -71,7 +71,7 @@
<section> <section>
<title>Configuring a Vertx Outgoing Connector Service</title> <title>Configuring a Vertx Outgoing Connector Service</title>
<para>Vertx Outgoing Connector services fetch vertx messages from a HornetQ queue and put them to vertx event bus. <para>Vertx Outgoing Connector services fetch vertx messages from a ActiveMQ queue and put them to vertx event bus.
Such a service can be configured as follows:</para> Such a service can be configured as follows:</para>
<programlisting> <programlisting>
&lt;connector-service name="vertx-outgoing-connector"> &lt;connector-service name="vertx-outgoing-connector">
@ -86,7 +86,7 @@
<para>Shown are the required params for the connector service:</para> <para>Shown are the required params for the connector service:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>queue</literal>. The name of the HornetQ queue to fetch message from.</para> <para><literal>queue</literal>. The name of the ActiveMQ queue to fetch message from.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>As well as these required paramaters there are the following optional parameters</para> <para>As well as these required paramaters there are the following optional parameters</para>
@ -101,7 +101,7 @@
<para><literal>quorum-size</literal>. The quorum size of the target vertx instance.</para> <para><literal>quorum-size</literal>. The quorum size of the target vertx instance.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>ha-group</literal>. The name of the ha-group of target vertx instance. Default is <literal>hornetq</literal>.</para> <para><literal>ha-group</literal>. The name of the ha-group of target vertx instance. Default is <literal>activemq</literal>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>vertx-address</literal>. The vertx address to put messages to. default is org.apache.activemq.</para> <para><literal>vertx-address</literal>. The vertx address to put messages to. default is org.apache.activemq.</para>

6
docs/user-manual/en/wildcard-routing.xml
View File

@ -19,13 +19,13 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="wildcard-routing"> <chapter id="wildcard-routing">
<title>Routing Messages With Wild Cards</title> <title>Routing Messages With Wild Cards</title>
<para>HornetQ allows the routing of messages via wildcard addresses.</para> <para>ActiveMQ allows the routing of messages via wildcard addresses.</para>
<para>If a queue is created with an address of say <literal>queue.news.#</literal> then it <para>If a queue is created with an address of say <literal>queue.news.#</literal> then it
will receive any messages sent to addresses that match this, for instance <literal will receive any messages sent to addresses that match this, for instance <literal
>queue.news.europe</literal> or <literal>queue.news.usa</literal> or <literal >queue.news.europe</literal> or <literal>queue.news.usa</literal> or <literal
@ -35,7 +35,7 @@
<para>In JMS terminology this allows "topic hierarchies" to be created.</para> <para>In JMS terminology this allows "topic hierarchies" to be created.</para>
</note> </note>
<para>To enable this functionality set the property <literal>wild-card-routing-enabled</literal> <para>To enable this functionality set the property <literal>wild-card-routing-enabled</literal>
in the <literal>hornetq-configuration.xml</literal> file to <literal>true</literal>. This is in the <literal>activemq-configuration.xml</literal> file to <literal>true</literal>. This is
<literal>true</literal> by default.</para> <literal>true</literal> by default.</para>
<para>For more information on the wild card syntax take a look at <xref <para>For more information on the wild card syntax take a look at <xref
linkend="wildcard-syntax" /> chapter, also see <xref linkend="wildcard-syntax" /> chapter, also see <xref

8
docs/user-manual/en/wildcard-syntax.xml
View File

@ -19,16 +19,16 @@
<!-- ============================================================================= --> <!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!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 "HornetQ_User_Manual.ent"> <!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES; %BOOK_ENTITIES;
]> ]>
<chapter id="wildcard-syntax"> <chapter id="wildcard-syntax">
<title>Understanding the HornetQ Wildcard Syntax</title> <title>Understanding the ActiveMQ Wildcard Syntax</title>
<para>HornetQ uses a specific syntax for representing wildcards in security settings, <para>ActiveMQ uses a specific syntax for representing wildcards in security settings,
address settings and when creating consumers.</para> address settings and when creating consumers.</para>
<para>The syntax is similar to that used by <ulink url="http://www.amqp.org">AMQP</ulink>.</para> <para>The syntax is similar to that used by <ulink url="http://www.amqp.org">AMQP</ulink>.</para>
<para>A HornetQ wildcard expression contains words delimited by the character '<literal <para>A ActiveMQ wildcard expression contains words delimited by the character '<literal
>.</literal>' (full stop).</para> >.</literal>' (full stop).</para>
<para>The special characters '<literal>#</literal>' and '<literal>*</literal>' also have special <para>The special characters '<literal>#</literal>' and '<literal>*</literal>' also have special
meaning and can take the place of a word.</para> meaning and can take the place of a word.</para>

4
docs/user-manual/pom.xml
View File

@ -32,8 +32,8 @@
<properties> <properties>
<translation>en</translation> <translation>en</translation>
<docname>HornetQ_User_Manual</docname> <docname>ActiveMQ_User_Manual</docname>
<bookname>HornetQ User Manual</bookname> <bookname>ActiveMQ User Manual</bookname>
</properties> </properties>
<repositories> <repositories>

1
examples/jms/activemq-jms-examples-common/common.css
View File

@ -1,5 +1,4 @@
body { body {
background: url(images/hornetQ-banner_final.png) top left no-repeat;
} }
h1 { h1 {

BIN
examples/jms/activemq-jms-examples-common/images/hornetQ-banner_final.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 107 KiB

1
tests/integration-tests/src/test/java/org/apache/activemq/tests/integration/management/SecurityManagementWithConfiguredAdminUserTest.java
View File

@ -16,7 +16,6 @@ import org.apache.activemq.api.config.ActiveMQDefaultConfiguration;
import org.junit.Test; import org.junit.Test;
import java.util.Set; import java.util.Set;
import org.apache.activemq.api.core.TransportConfiguration; import org.apache.activemq.api.core.TransportConfiguration;
import org.apache.activemq.core.config.Configuration; import org.apache.activemq.core.config.Configuration;
import org.apache.activemq.core.remoting.impl.invm.InVMAcceptorFactory; import org.apache.activemq.core.remoting.impl.invm.InVMAcceptorFactory;