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

documentation review fixes

This commit is contained in:
Andy Taylor 2014-12-11 12:17:29 +00:00
parent 1491f4a123
commit b4144013d9
53 changed files with 1287 additions and 1647 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/user-manual/en/SUMMARY.md
View File

@ -1,7 +1,7 @@
* [Legal Notice](notice.md) * [Legal Notice](notice.md)
* [Preface](preface.md) * [Preface](preface.md)
* [Project Info](project-info.md) * [Project Info](project-info/project-info.md)
* [Messaging Concepts](messaging-concepts.md) * [Messaging Concepts](messaging-concepts/messaging-concepts.md)
* [Architecture](architecture.md) * [Architecture](architecture.md)
* [Using the Server](using-server.md) * [Using the Server](using-server.md)
* [Using JMS](using-jms.md) * [Using JMS](using-jms.md)

29
docs/user-manual/en/aerogear-integration.md
View File

@ -1,5 +1,4 @@
AeroGear Integration # AeroGear Integration
====================
AeroGears push technology provides support for different push AeroGears push technology provides support for different push
notification technologies like Google Cloud Messaging, Apple's APNs or notification technologies like Google Cloud Messaging, Apple's APNs or
@ -8,8 +7,7 @@ Service that will consume messages from a queue and forward them to an
AeroGear push server and subsequently sent as notifications to mobile AeroGear push server and subsequently sent as notifications to mobile
devices. devices.
Configuring an AeroGear Connector Service ## Configuring an AeroGear Connector Service
=========================================
AeroGear Connector services are configured in the connector-services AeroGear Connector services are configured in the connector-services
configuration: configuration:
@ -64,20 +62,21 @@ parameters
More in depth explanations of the AeroGear related parameters can be More in depth explanations of the AeroGear related parameters can be
found in the [AeroGear Push docs](http://aerogear.org/push/) found in the [AeroGear Push docs](http://aerogear.org/push/)
How to send a message for AeroGear ## How to send a message for AeroGear
==================================
To send a message intended for AeroGear simply send a JMS Message and To send a message intended for AeroGear simply send a JMS Message and
set the appropriate headers, like so set the appropriate headers, like so
Message message = session.createMessage(); ``` java
Message message = session.createMessage();
message.setStringProperty("AEROGEAR_ALERT", "Hello this is a notification from ActiveMQ"); message.setStringProperty("AEROGEAR_ALERT", "Hello this is a notification from ActiveMQ");
producer.send(message); producer.send(message);
```
The 'AEROGEAR\_ALERT' property will be the alert sent to the mobile The 'AEROGEAR_ALERT' property will be the alert sent to the mobile
device. device.
> **Note** > **Note**
@ -89,13 +88,17 @@ Its also possible to override any of the other AeroGear parameters by
simply setting them on the message, for instance if you wanted to set simply setting them on the message, for instance if you wanted to set
ttl of a message you would: ttl of a message you would:
message.setIntProperty("AEROGEAR_TTL", 1234); ``` java
message.setIntProperty("AEROGEAR_TTL", 1234);
```
or if you wanted to set the list of variants you would use: or if you wanted to set the list of variants you would use:
message.setStringProperty("AEROGEAR_VARIANTS", "variant1,variant2,variant3"); ``` java
message.setStringProperty("AEROGEAR_VARIANTS", "variant1,variant2,variant3");
```
```
Again refer to the AeroGear documentation for a more in depth view on Again refer to the AeroGear documentation for a more in depth view on
how to use these settings how to use these settings

409
docs/user-manual/en/appserver-integration.md
View File

@ -1,5 +1,4 @@
Application Server Integration and Java EE # Application Server Integration and Java EE
==========================================
ActiveMQ can be easily installed in JBoss Application Server 4 or later. ActiveMQ can be easily installed in JBoss Application Server 4 or later.
For details on installing ActiveMQ in the JBoss Application Server For details on installing ActiveMQ in the JBoss Application Server
@ -18,8 +17,7 @@ JEE components, e.g. EJBs and Servlets.
This section explains the basics behind configuring the different JEE This section explains the basics behind configuring the different JEE
components in the AS. components in the AS.
Configuring Message-Driven Beans ## Configuring Message-Driven Beans
================================
The delivery of messages to an MDB using ActiveMQ is configured on the The delivery of messages to an MDB using ActiveMQ is configured on the
JCA Adapter via a configuration file `ra.xml` which can be found under JCA Adapter via a configuration file `ra.xml` which can be found under
@ -32,16 +30,18 @@ All MDBs however need to have the destination type and the destination
configured. The following example shows how this can be done using configured. The following example shows how this can be done using
annotations: annotations:
@MessageDriven(name = "MDBExample", activationConfig = ``` java
{ @MessageDriven(name = "MDBExample", activationConfig =
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"), {
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue") @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
}) @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
@ResourceAdapter("activemq-ra.rar") })
public class MDBExample implements MessageListener @ResourceAdapter("activemq-ra.rar")
{ public class MDBExample implements MessageListener
public void onMessage(Message message)... {
} public void onMessage(Message message)...
}
```
In this example you can see that the MDB will consume messages from a In this example you can see that the MDB will consume messages from a
queue that is mapped into JNDI with the binding `queue/testQueue`. This queue that is mapped into JNDI with the binding `queue/testQueue`. This
@ -77,8 +77,7 @@ file and change `rar-name` element.
All the examples shipped with the ActiveMQ distribution use the All the examples shipped with the ActiveMQ distribution use the
annotation. annotation.
Using Container-Managed Transactions ### Using Container-Managed Transactions
------------------------------------
When an MDB is using Container-Managed Transactions (CMT), the delivery When an MDB is using Container-Managed Transactions (CMT), the delivery
of the message is done within the scope of a JTA transaction. The commit of the message is done within the scope of a JTA transaction. The commit
@ -88,18 +87,20 @@ will kick in (by default, it will try to redeliver the message up to 10
times before sending to a DLQ). Using annotations this would be times before sending to a DLQ). Using annotations this would be
configured as follows: configured as follows:
@MessageDriven(name = "MDB_CMP_TxRequiredExample", activationConfig = ``` java
{ @MessageDriven(name = "MDB_CMP_TxRequiredExample", activationConfig =
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"), {
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue") @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
}) @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
@TransactionManagement(value= TransactionManagementType.CONTAINER) })
@TransactionAttribute(value= TransactionAttributeType.REQUIRED) @TransactionManagement(value= TransactionManagementType.CONTAINER)
@ResourceAdapter("activemq-ra.rar") @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
public class MDB_CMP_TxRequiredExample implements MessageListener @ResourceAdapter("activemq-ra.rar")
{ public class MDB_CMP_TxRequiredExample implements MessageListener
public void onMessage(Message message)... {
} public void onMessage(Message message)...
}
```
The `TransactionManagement` annotation tells the container to manage the The `TransactionManagement` annotation tells the container to manage the
transaction. The `TransactionAttribute` annotation tells the container transaction. The `TransactionAttribute` annotation tells the container
@ -112,59 +113,64 @@ It is also possible to inform the container that it must rollback the
transaction by calling `setRollbackOnly` on the `MessageDrivenContext`. transaction by calling `setRollbackOnly` on the `MessageDrivenContext`.
The code for this would look something like: The code for this would look something like:
@Resource ``` java
MessageDrivenContextContext ctx; @Resource
MessageDrivenContextContext ctx;
public void onMessage(Message message) public void onMessage(Message message)
{ {
try try
{ {
//something here fails //something here fails
} }
catch (Exception e) catch (Exception e)
{ {
ctx.setRollbackOnly(); ctx.setRollbackOnly();
} }
} }
```
If you do not want the overhead of an XA transaction being created every If you do not want the overhead of an XA transaction being created every
time but you would still like the message delivered within a transaction time but you would still like the message delivered within a transaction
(i.e. you are only using a JMS resource) then you can configure the MDB (i.e. you are only using a JMS resource) then you can configure the MDB
to use a local transaction. This would be configured as such: to use a local transaction. This would be configured as such:
@MessageDriven(name = "MDB_CMP_TxLocalExample", activationConfig = ``` java
{ @MessageDriven(name = "MDB_CMP_TxLocalExample", activationConfig =
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"), {
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"), @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "useLocalTx", propertyValue = "true") @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
}) @ActivationConfigProperty(propertyName = "useLocalTx", propertyValue = "true")
@TransactionManagement(value = TransactionManagementType.CONTAINER) })
@TransactionAttribute(value = TransactionAttributeType.NOT_SUPPORTED) @TransactionManagement(value = TransactionManagementType.CONTAINER)
@ResourceAdapter("activemq-ra.rar") @TransactionAttribute(value = TransactionAttributeType.NOT_SUPPORTED)
public class MDB_CMP_TxLocalExample implements MessageListener @ResourceAdapter("activemq-ra.rar")
{ public class MDB_CMP_TxLocalExample implements MessageListener
public void onMessage(Message message)... {
} public void onMessage(Message message)...
}
```
Using Bean-Managed Transactions ### Using Bean-Managed Transactions
-------------------------------
Message-driven beans can also be configured to use Bean-Managed Message-driven beans can also be configured to use Bean-Managed
Transactions (BMT). In this case a User Transaction is created. This Transactions (BMT). In this case a User Transaction is created. This
would be configured as follows: would be configured as follows:
@MessageDriven(name = "MDB_BMPExample", activationConfig = ``` java
{ @MessageDriven(name = "MDB_BMPExample", activationConfig =
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"), {
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"), @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Dups-ok-acknowledge") @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
}) @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Dups-ok-acknowledge")
@TransactionManagement(value= TransactionManagementType.BEAN) })
@ResourceAdapter("activemq-ra.rar") @TransactionManagement(value= TransactionManagementType.BEAN)
public class MDB_BMPExample implements MessageListener @ResourceAdapter("activemq-ra.rar")
{ public class MDB_BMPExample implements MessageListener
public void onMessage(Message message) {
} public void onMessage(Message message)
}
```
When using Bean-Managed Transactions the message delivery to the MDB When using Bean-Managed Transactions the message delivery to the MDB
will occur outside the scope of the user transaction and use the will occur outside the scope of the user transaction and use the
@ -177,55 +183,57 @@ not cause the message to be redelivered.
A user would control the life-cycle of the transaction something like A user would control the life-cycle of the transaction something like
the following: the following:
@Resource ``` java
MessageDrivenContext ctx; @Resource
MessageDrivenContext ctx;
public void onMessage(Message message) public void onMessage(Message message)
{ {
UserTransaction tx; UserTransaction tx;
try try
{ {
TextMessage textMessage = (TextMessage)message; TextMessage textMessage = (TextMessage)message;
String text = textMessage.getText(); String text = textMessage.getText();
UserTransaction tx = ctx.getUserTransaction(); UserTransaction tx = ctx.getUserTransaction();
tx.begin(); tx.begin();
//do some stuff within the transaction //do some stuff within the transaction
tx.commit(); tx.commit();
} }
catch (Exception e) catch (Exception e)
{ {
tx.rollback(); tx.rollback();
} }
} }
```
Using Message Selectors with Message-Driven Beans ### Using Message Selectors with Message-Driven Beans
-------------------------------------------------
It is also possible to use MDBs with message selectors. To do this It is also possible to use MDBs with message selectors. To do this
simple define your message selector as follows: simple define your message selector as follows:
@MessageDriven(name = "MDBMessageSelectorExample", activationConfig = ``` java
{ @MessageDriven(name = "MDBMessageSelectorExample", activationConfig =
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"), {
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"), @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "messageSelector", propertyValue = "color = 'RED'") @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
}) @ActivationConfigProperty(propertyName = "messageSelector", propertyValue = "color = 'RED'")
@TransactionManagement(value= TransactionManagementType.CONTAINER) })
@TransactionAttribute(value= TransactionAttributeType.REQUIRED) @TransactionManagement(value= TransactionManagementType.CONTAINER)
@ResourceAdapter("activemq-ra.rar") @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
public class MDBMessageSelectorExample implements MessageListener @ResourceAdapter("activemq-ra.rar")
{ public class MDBMessageSelectorExample implements MessageListener
public void onMessage(Message message).... {
} public void onMessage(Message message)....
}
```
Sending Messages from within JEE components ## Sending Messages from within JEE components
===========================================
The JCA adapter can also be used for sending messages. The Connection The JCA adapter can also be used for sending messages. The Connection
Factory to use is configured by default in the `jms-ds.xml` file and is Factory to use is configured by default in the `jms-ds.xml` file and is
@ -237,70 +245,71 @@ This means that if the sending of the message fails the overall
transaction would rollback and the message be re-sent. Heres an example transaction would rollback and the message be re-sent. Heres an example
of this from within an MDB: of this from within an MDB:
@MessageDriven(name = "MDBMessageSendTxExample", activationConfig = ``` java
{ @MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"), {
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue") @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
}) @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
@TransactionManagement(value= TransactionManagementType.CONTAINER) })
@TransactionAttribute(value= TransactionAttributeType.REQUIRED) @TransactionManagement(value= TransactionManagementType.CONTAINER)
@ResourceAdapter("activemq-ra.rar") @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
public class MDBMessageSendTxExample implements MessageListener @ResourceAdapter("activemq-ra.rar")
{ public class MDBMessageSendTxExample implements MessageListener
@Resource(mappedName = "java:/JmsXA") {
ConnectionFactory connectionFactory; @Resource(mappedName = "java:/JmsXA")
ConnectionFactory connectionFactory;
@Resource(mappedName = "queue/replyQueue") @Resource(mappedName = "queue/replyQueue")
Queue replyQueue; Queue replyQueue;
public void onMessage(Message message) public void onMessage(Message message)
{ {
Connection conn = null; Connection conn = null;
try try
{ {
//Step 9. We know the client is sending a text message so we cast //Step 9. We know the client is sending a text message so we cast
TextMessage textMessage = (TextMessage)message; TextMessage textMessage = (TextMessage)message;
//Step 10. get the text from the message. //Step 10. get the text from the message.
String text = textMessage.getText(); String text = textMessage.getText();
System.out.println("message " + text); System.out.println("message " + text);
conn = connectionFactory.createConnection(); conn = connectionFactory.createConnection();
Session sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE); Session sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
MessageProducer producer = sess.createProducer(replyQueue); MessageProducer producer = sess.createProducer(replyQueue);
producer.send(sess.createTextMessage("this is a reply")); producer.send(sess.createTextMessage("this is a reply"));
} }
catch (Exception e) catch (Exception e)
{ {
e.printStackTrace(); e.printStackTrace();
} }
finally finally
{ {
if(conn != null) if(conn != null)
{ {
try try
{ {
conn.close(); conn.close();
} }
catch (JMSException e) catch (JMSException e)
{ {
} }
} }
} }
} }
} }
```
In JBoss Application Server you can use the JMS JCA adapter for sending In JBoss Application Server you can use the JMS JCA adapter for sending
messages from EJBs (including Session, Entity and Message-Driven Beans), messages from EJBs (including Session, Entity and Message-Driven Beans),
Servlets (including jsps) and custom MBeans. Servlets (including jsps) and custom MBeans.
MDB and Consumer pool size ## MDB and Consumer pool size
==========================
Most application servers, including JBoss, allow you to configure how Most application servers, including JBoss, allow you to configure how
many MDB's there are in a pool. In JBoss this is configured via the many MDB's there are in a pool. In JBoss this is configured via the
@ -314,21 +323,22 @@ limit how many sessions/consumers are created then you need to set the
`maxSession` parameter either on the resource adapter itself or via an `maxSession` parameter either on the resource adapter itself or via an
an Activation Config Property on the MDB itself an Activation Config Property on the MDB itself
@MessageDriven(name = "MDBMessageSendTxExample", activationConfig = ``` java
{ @MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"), {
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"), @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "maxSession", propertyValue = "1") @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
}) @ActivationConfigProperty(propertyName = "maxSession", propertyValue = "1")
@TransactionManagement(value= TransactionManagementType.CONTAINER) })
@TransactionAttribute(value= TransactionAttributeType.REQUIRED) @TransactionManagement(value= TransactionManagementType.CONTAINER)
@ResourceAdapter("activemq-ra.rar") @TransactionAttribute(value= TransactionAttributeType.REQUIRED)
public class MyMDB implements MessageListener @ResourceAdapter("activemq-ra.rar")
{ ....} public class MyMDB implements MessageListener
{ ....}
```
Configuring the JCA Adaptor ## Configuring the JCA Adaptor
===========================
The Java Connector Architecture (JCA) Adapter is what allows ActiveMQ to The Java Connector Architecture (JCA) Adapter is what allows ActiveMQ to
be integrated with JEE components such as MDBs and EJBs. It configures be integrated with JEE components such as MDBs and EJBs. It configures
@ -422,8 +432,7 @@ There are three main parts to this configuration.
3. The configuration of the inbound part of the adapter. This is used 3. The configuration of the inbound part of the adapter. This is used
for controlling the consumption of messages via MDBs. for controlling the consumption of messages via MDBs.
Global Properties ### Global Properties
-----------------
The first element you see is `resourceadapter-class` which should be The first element you see is `resourceadapter-class` which should be
left unchanged. This is the ActiveMQ resource adapter class. left unchanged. This is the ActiveMQ resource adapter class.
@ -446,7 +455,7 @@ The following table explains what each property is for.
Property Name Property Type Property Description Property Name Property Type Property Description
--------------------------------------------------------------------------- --------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --------------------------------------------------------------------------- --------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
ConnectorClassName String The Connector class name (see ? for more information). If multiple connectors are needed this should be provided as a comma separated list. ConnectorClassName String The Connector class name (see [Configuring the Transport](configuring-transports.md) for more information). If multiple connectors are needed this should be provided as a comma separated list.
ConnectionParameters String The transport configuration. These parameters must be in the form of `key1=val1;key2=val2;` and will be specific to the connector used. If multiple connectors are configured then parameters should be supplied for each connector separated by a comma. ConnectionParameters String The transport configuration. These parameters must be in the form of `key1=val1;key2=val2;` and will be specific to the connector used. If multiple connectors are configured then parameters should be supplied for each connector separated by a comma.
ha boolean True if high availability is needed. ha boolean True if high availability is needed.
useLocalTx boolean True will enable local transaction optimisation. useLocalTx boolean True will enable local transaction optimisation.
@ -485,8 +494,7 @@ The following table explains what each property is for.
: Global Configuration Properties : Global Configuration Properties
Adapter Outbound Configuration ### Adapter Outbound Configuration
------------------------------
The outbound configuration should remain unchanged as they define The outbound configuration should remain unchanged as they define
connection factories that are used by Java EE components. These connection factories that are used by Java EE components. These
@ -545,8 +553,7 @@ addition to the global configuration properties.
: Outbound Configuration Properties : Outbound Configuration Properties
Adapter Inbound Configuration ### Adapter Inbound Configuration
-----------------------------
The inbound configuration should again remain unchanged. This controls The inbound configuration should again remain unchanged. This controls
what forwards messages onto MDBs. It is possible to override properties what forwards messages onto MDBs. It is possible to override properties
@ -572,16 +579,13 @@ to the global configuration properties.
: Inbound Configuration Properties : Inbound Configuration Properties
Configuring the adapter to use a standalone ActiveMQ Server ### Configuring the adapter to use a standalone ActiveMQ Server
-----------------------------------------------------------
Sometime you may want your messaging server on a different machine or 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 separate from the application server. If this is the case you will only
need the activemq client libs installed. This section explains what need the activemq client libs installed. This section explains what
config to create and what jar dependencies are needed. config to create and what jar dependencies are needed.
###
There are two configuration files needed to do this, one for the There are two configuration files needed to do this, one for the
incoming adapter used for MDB's and one for outgoing connections managed incoming adapter used for MDB's and one for outgoing connections managed
by the JCA managed connection pool used by outgoing JEE components by the JCA managed connection pool used by outgoing JEE components
@ -700,15 +704,13 @@ This is a list of the ActiveMQ and third party jars needed
: Jar Dependencies : Jar Dependencies
Configuring the JBoss Application Server to connect to Remote ActiveMQ Server ## Configuring the JBoss Application Server to connect to Remote ActiveMQ Server
=============================================================================
This is a step by step guide on how to configure a JBoss application 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 server that doesn't have ActiveMQ installed to use a remote instance of
ActiveMQ ActiveMQ
Configuring JBoss 5 ### Configuring JBoss 5
-------------------
Firstly download and install JBoss AS 5 as per the JBoss installation Firstly download and install JBoss AS 5 as per the JBoss installation
guide and ActiveMQ as per the ActiveMQ installation guide. After that guide and ActiveMQ as per the ActiveMQ installation guide. After that
@ -836,7 +838,7 @@ the following steps are required
At this point you should be able to now deploy MDB's that consume from 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 the remote server. You will however, have to make sure that your MDB's
have the annotation `@ResourceAdapter("activemq-ra.rar")` added, this is have the annotation `@ResourceAdapter("activemq-ra.rar")` added, this is
illustrated in the ? section. If you don't want to add this annotation illustrated in the Configuring Message-Driven Beans section. If you don't want to add this annotation
then you can delete the generic resource adapter `jms-ra.rar` and rename then you can delete the generic resource adapter `jms-ra.rar` and rename
the `activemq-ra.rar` to this. the `activemq-ra.rar` to this.
@ -879,8 +881,7 @@ connections, i.e. sending messages, then do the following:
Now you should be able to send messages using the JCA JMS connection Now you should be able to send messages using the JCA JMS connection
pooling within an XA transaction. pooling within an XA transaction.
Configuring JBoss 5 ### Configuring JBoss 5
-------------------
The steps to do this are exactly the same as for JBoss 4, you will have The steps to do this are exactly the same as for JBoss 4, you will have
to create a jboss.xml definition file for your MDB with the following to create a jboss.xml definition file for your MDB with the following
@ -896,33 +897,7 @@ section with the following 'Uncomment to use JMS message inflow from
jmsra.rar' and then comment out the invoker-proxy-binding called jmsra.rar' and then comment out the invoker-proxy-binding called
'message-driven-bean' 'message-driven-bean'
High Availability JNDI (HA-JNDI) ## XA Recovery
================================
If you are using JNDI to look-up JMS queues, topics and connection
factories from a cluster of servers, it is likely you will want to use
HA-JNDI so that your JNDI look-ups will continue to work if one or more
of the servers in the cluster fail.
HA-JNDI is a JBoss Application Server service which allows you to use
JNDI from clients without them having to know the exact JNDI connection
details of every server in the cluster. This service is only available
if using a cluster of JBoss Application Server instances.
To use it use the following properties when connecting to JNDI.
Hashtable<String, String> jndiParameters = new Hashtable<String, String>();
jndiParameters.put("java.naming.factory.initial", "org.jnp.interfaces.NamingContextFactory");
jndiParameters.put("java.naming.factory.url.pkgs=", "org.jboss.naming:org.jnp.interfaces");
initialContext = new InitialContext(jndiParameters);
For more information on using HA-JNDI see the [JBoss Application Server
clustering
documentation](http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Clustering_Guide/5/html/clustering-jndi.html)
XA Recovery
===========
*XA recovery* deals with system or application failures to ensure that *XA recovery* deals with system or application failures to ensure that
of a transaction are applied consistently to all resources affected by of a transaction are applied consistently to all resources affected by
@ -938,8 +913,7 @@ crash, the recovery manager will ensure that the transactions are
recovered and the messages will either be committed or rolled back recovered and the messages will either be committed or rolled back
(depending on the transaction outcome) when the server is restarted. (depending on the transaction outcome) when the server is restarted.
XA Recovery Configuration ### XA Recovery Configuration
-------------------------
To enable ActiveMQ's XA Recovery, the Recovery Manager must be To enable ActiveMQ's XA Recovery, the Recovery Manager must be
configured to connect to ActiveMQ to recover its resources. The configured to connect to ActiveMQ to recover its resources. The
@ -971,7 +945,7 @@ to connect to ActiveMQ node under the form `[connector factory class
mandatory only if the user name is specified mandatory only if the user name is specified
- `[connector parameters]` is a list of comma-separated key=value pair - `[connector parameters]` is a list of comma-separated key=value pair
which are passed to the connector factory (see ? for a list of the which are passed to the connector factory (see [Configuring the transport](configuring-transports.md) for a list of the
transport parameters). transport parameters).
Also note the `com.arjuna.ats.jta.xaRecoveryNode` parameter. If you want Also note the `com.arjuna.ats.jta.xaRecoveryNode` parameter. If you want
@ -984,7 +958,7 @@ id is set to, this is configured in the same file by the
> ActiveMQ must have a valid acceptor which corresponds to the connector > ActiveMQ must have a valid acceptor which corresponds to the connector
> specified in `conf/jbossts-properties.xml`. > specified in `conf/jbossts-properties.xml`.
### Configuration Settings #### Configuration Settings
If ActiveMQ is configured with a default in-vm acceptor: If ActiveMQ is configured with a default in-vm acceptor:
@ -1024,8 +998,7 @@ Configuring ActiveMQ with an invm acceptor and configuring the Recovery
Manager with an invm connector is the recommended way to enable XA Manager with an invm connector is the recommended way to enable XA
Recovery. Recovery.
Example ## Example
-------
See ? which shows how to configure XA Recovery and recover messages See ? which shows how to configure XA Recovery and recover messages
after a server crash. after a server crash.

43
docs/user-manual/en/architecture.md
View File

@ -1,11 +1,9 @@
Architecture # Architecture
============
In this section we will give an overview of the ActiveMQ high level In this section we will give an overview of the ActiveMQ high level
architecture. architecture.
Core Architecture ## Core Architecture
=================
ActiveMQ core is designed simply as set of Plain Old Java Objects ActiveMQ core is designed simply as set of Plain Old Java Objects
(POJOs) - we hope you like its clean-cut design. (POJOs) - we hope you like its clean-cut design.
@ -16,8 +14,8 @@ other than the standard JDK classes! This is because we use some of the
netty buffer classes internally. netty buffer classes internally.
This allows ActiveMQ to be easily embedded in your own project, or This allows ActiveMQ to be easily embedded in your own project, or
instantiated in any dependency injection framework such as JBoss instantiated in any dependency injection framework such as Spring or
Microcontainer, Spring or Google Guice. Google Guice.
Each ActiveMQ server has its own ultra high performance persistent Each ActiveMQ server has its own ultra high performance persistent
journal, which it uses for message and other persistence. journal, which it uses for message and other persistence.
@ -61,18 +59,16 @@ server. User Application 1 is using the JMS API, while User Application
You can see from the diagram that the JMS API is implemented by a thin You can see from the diagram that the JMS API is implemented by a thin
facade layer on the client side. facade layer on the client side.
ActiveMQ embedded in your own application ## ActiveMQ embedded in your own application
=========================================
ActiveMQ core is designed as a set of simple POJOs so if you have an ActiveMQ core is designed as a set of simple POJOs so if you have an
application that requires messaging functionality internally but you application that requires messaging functionality internally but you
don't want to expose that as a ActiveMQ server you can directly don't want to expose that as a ActiveMQ server you can directly
instantiate and embed ActiveMQ servers in your own application. instantiate and embed ActiveMQ servers in your own application.
For more information on embedding ActiveMQ, see ?. For more information on embedding ActiveMQ, see [Embedding HornetQ](embedding-hornetq.md).
ActiveMQ integrated with a JEE application server ## ActiveMQ integrated with a JEE application server
=================================================
ActiveMQ provides its own fully functional Java Connector Architecture ActiveMQ provides its own fully functional Java Connector Architecture
(JCA) adaptor which enables it to be integrated easily into any JEE (JCA) adaptor which enables it to be integrated easily into any JEE
@ -118,35 +114,26 @@ time you want to interact from the EJB, which is an anti-pattern.
![ActiveMQ architecture2](images/architecture2.jpg) ![ActiveMQ architecture2](images/architecture2.jpg)
For more information on using the JCA adaptor, please see ?. For more information on using the JCA adaptor, please see [Application Server Integration and Java EE](appserver-integration.md).
ActiveMQ stand-alone server ## ActiveMQ stand-alone server
===========================
ActiveMQ can also be deployed as a stand-alone server. This means a ActiveMQ can also be deployed as a stand-alone server. This means a
fully independent messaging server not dependent on a JEE application fully independent messaging server not dependent on a JEE application
server. server.
The standard stand-alone messaging server configuration comprises a core The standard stand-alone messaging server configuration comprises a core
messaging server, a JMS service and a JNDI service. messaging server and a JMS service.
The role of the JMS Service is to deploy any JMS Queue, Topic and The role of the JMS Service is to deploy any JMS Queue, Topic and
ConnectionFactory instances from any server side `activemq-jms.xml` ConnectionFactory instances from any server side `activemq-jms.xml`
configuration files. It also provides a simple management API for configuration files. It also provides a simple management API for
creating and destroying Queues, Topics and ConnectionFactory instances creating and destroying Queues and Topics
which can be accessed via JMX or the connection. It is a separate which can be accessed via JMX or the connection. It is a separate
service to the ActiveMQ core server, since the core server is JMS 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 agnostic. If you don't want to deploy any JMS Queue or Topic via
ConnectionFactory instances via server side XML configuration and don't server side XML configuration and don't require a JMS management
require a JMS management API on the server side then you can disable API on the server side then you can disable this service.
this service.
We also include a JNDI server since JNDI is a common requirement when
using JMS to lookup Queues, Topics and ConnectionFactory instances. If
you do not require JNDI then this service can also be disabled. ActiveMQ
allows you to programmatically create JMS and core objects directly on
the client side as opposed to looking them up from JNDI, so a JNDI
server is not always a requirement.
The stand-alone server configuration uses JBoss Microcontainer to The stand-alone server configuration uses JBoss Microcontainer to
instantiate and enforce dependencies between the components. JBoss instantiate and enforce dependencies between the components. JBoss
@ -156,4 +143,4 @@ The stand-alone server architecture is shown in figure 3.3 below:
![ActiveMQ architecture3](images/architecture3.jpg) ![ActiveMQ architecture3](images/architecture3.jpg)
For more information on server configuration files see ?. \$ For more information on server configuration files see [Server Configuration](server-configuration.md)

9
docs/user-manual/en/client-classpath.md
View File

@ -1,5 +1,4 @@
The Client Classpath # The Client Classpath
====================
ActiveMQ requires several jars on the *Client Classpath* depending on ActiveMQ requires several jars on the *Client Classpath* depending on
whether the client uses ActiveMQ Core API, JMS, and JNDI. whether the client uses ActiveMQ Core API, JMS, and JNDI.
@ -12,15 +11,13 @@ whether the client uses ActiveMQ Core API, JMS, and JNDI.
> from different ActiveMQ versions. Mixing and matching different jar > from different ActiveMQ versions. Mixing and matching different jar
> versions may cause subtle errors and failures to occur. > versions may cause subtle errors and failures to occur.
ActiveMQ Core Client ## ActiveMQ Core Client
====================
If you are using just a pure ActiveMQ Core client (i.e. no JMS) then you If you are using just a pure ActiveMQ Core client (i.e. no JMS) then you
need `activemq-core-client.jar`, `activemq-commons.jar`, and `netty.jar` need `activemq-core-client.jar`, `activemq-commons.jar`, and `netty.jar`
on your client classpath. on your client classpath.
JMS Client ## JMS Client
==========
If you are using JMS on the client side, then you will also need to If you are using JMS on the client side, then you will also need to
include `activemq-jms-client.jar` and `jboss-jms-api.jar`. include `activemq-jms-client.jar` and `jboss-jms-api.jar`.

16
docs/user-manual/en/client-reconnection.md
View File

@ -1,17 +1,15 @@
Client Reconnection and Session Reattachment # Client Reconnection and Session Reattachment
============================================
ActiveMQ clients can be configured to automatically reconnect or ActiveMQ clients can be configured to automatically reconnect or
re-attach to the server in the event that a failure is detected in the re-attach to the server in the event that a failure is detected in the
connection between the client and the server. connection between the client and the server.
100% Transparent session re-attachment ## 100% Transparent session re-attachment
======================================
If the failure was due to some transient failure such as a temporary If the failure was due to some transient failure such as a temporary
network failure, and the target server was not restarted, then the network failure, and the target server was not restarted, then the
sessions will still be existent on the server, assuming the client sessions will still be existent on the server, assuming the client
hasn't been disconnected for more than connection-ttl ?. hasn't been disconnected for more than connection-ttl [Detecting Dead Connections](connection-ttl.md)
In this scenario, ActiveMQ will automatically re-attach the client In this scenario, ActiveMQ will automatically re-attach the client
sessions to the server sessions when the connection reconnects. This is sessions to the server sessions when the connection reconnects. This is
@ -54,8 +52,7 @@ re-attachment from occurring, forcing reconnect instead. The default
value for this parameter is `-1`. (Which means by default no auto value for this parameter is `-1`. (Which means by default no auto
re-attachment will occur) re-attachment will occur)
Session reconnection ## Session reconnection
====================
Alternatively, the server might have actually been restarted after Alternatively, the server might have actually been restarted after
crashing or being stopped. In this case any sessions will no longer be crashing or being stopped. In this case any sessions will no longer be
@ -70,13 +67,12 @@ as what happens during failover onto a backup server.
Client reconnection is also used internally by components such as core Client reconnection is also used internally by components such as core
bridges to allow them to reconnect to their target servers. bridges to allow them to reconnect to their target servers.
Please see the section on failover ? to get a full understanding of how Please see the section on failover [Automatic Client Failover](ha.md) to get a full understanding of how
transacted and non-transacted sessions are reconnected during transacted and non-transacted sessions are reconnected during
failover/reconnect and what you need to do to maintain *once and only failover/reconnect and what you need to do to maintain *once and only
once*delivery guarantees. once*delivery guarantees.
Configuring reconnection/reattachment attributes ## Configuring reconnection/reattachment attributes
================================================
Client reconnection is configured using the following parameters: Client reconnection is configured using the following parameters:

171
docs/user-manual/en/clusters.md
View File

@ -1,8 +1,6 @@
Clusters # Clusters
========
Clusters Overview ## Clusters Overview
=================
ActiveMQ clusters allow groups of ActiveMQ servers to be grouped ActiveMQ clusters allow groups of ActiveMQ servers to be grouped
together in order to share message processing load. Each active node in together in order to share message processing load. Each active node in
@ -18,7 +16,7 @@ and handles its own connections.
The cluster is formed by each node declaring *cluster connections* to The cluster is formed by each node declaring *cluster connections* to
other nodes in the core configuration file `activemq-configuration.xml`. other nodes in the core configuration file `activemq-configuration.xml`.
When a node forms a cluster connection to another node, internally it When a node forms a cluster connection to another node, internally it
creates a *core bridge* (as described in ?) connection between it and creates a *core bridge* (as described in [Core Bridges](core-bridges.md)) connection between it and
the other node, this is done transparently behind the scenes - you don't the other node, this is done transparently behind the scenes - you don't
have to declare an explicit bridge for each node. These cluster have to declare an explicit bridge for each node. These cluster
connections allow messages to flow between the nodes of the cluster to connections allow messages to flow between the nodes of the cluster to
@ -49,8 +47,7 @@ connect to them with the minimum of configuration.
> *must* be unique among nodes in the cluster or the cluster will not > *must* be unique among nodes in the cluster or the cluster will not
> form properly. > form properly.
Server discovery ## Server discovery
================
Server discovery is a mechanism by which servers can propagate their Server discovery is a mechanism by which servers can propagate their
connection details to: connection details to:
@ -72,20 +69,19 @@ techniques like
[JGroups](http://www.jgroups.org/), or by providing a list of initial [JGroups](http://www.jgroups.org/), or by providing a list of initial
connectors. connectors.
Dynamic Discovery ### Dynamic Discovery
-----------------
Server discovery uses Server discovery uses
[UDP](http://en.wikipedia.org/wiki/User_Datagram_Protocol) multicast or [UDP](http://en.wikipedia.org/wiki/User_Datagram_Protocol) multicast or
[JGroups](http://www.jgroups.org/) to broadcast server connection [JGroups](http://www.jgroups.org/) to broadcast server connection
settings. settings.
### Broadcast Groups #### Broadcast Groups
A broadcast group is the means by which a server broadcasts connectors A broadcast group is the means by which a server broadcasts connectors
over the network. A connector defines a way in which a client (or other over the network. A connector defines a way in which a client (or other
server) can make connections to the server. For more information on what server) can make connections to the server. For more information on what
a connector is, please see ?. a connector is, please see [Configuring the Transport](configuring-transports.md).
The broadcast group takes a set of connector pairs, each connector pair The broadcast group takes a set of connector pairs, each connector pair
contains connection settings for a live and backup server (if one contains connection settings for a live and backup server (if one
@ -147,7 +143,7 @@ clarity. Let's discuss each one in turn:
value is `2000` milliseconds. value is `2000` milliseconds.
- `connector-ref`. This specifies the connector and optional backup - `connector-ref`. This specifies the connector and optional backup
connector that will be broadcasted (see ? for more information on connector that will be broadcasted (see [Configuring the Transport](configuring-transports.md) for more information on
connectors). The connector to be broadcasted is specified by the connectors). The connector to be broadcasted is specified by the
`connector-name` attribute. `connector-name` attribute.
@ -244,7 +240,7 @@ example if the above stacks configuration is stored in a file named
<jgroups-file>jgroups-stacks.xml</jgroups-file> <jgroups-file>jgroups-stacks.xml</jgroups-file>
### Discovery Groups #### Discovery Groups
While the broadcast group defines how connector information is While the broadcast group defines how connector information is
broadcasted from a server, a discovery group defines how connector broadcasted from a server, a discovery group defines how connector
@ -279,7 +275,7 @@ normal ActiveMQ connections.
> if broadcast is configured using UDP, the discovery group must also > if broadcast is configured using UDP, the discovery group must also
> use UDP, and the same multicast address. > use UDP, and the same multicast address.
### Defining Discovery Groups on the Server #### Defining Discovery Groups on the Server
For cluster connections, discovery groups are defined in the server side For cluster connections, discovery groups are defined in the server side
configuration file `activemq-configuration.xml`. All discovery groups configuration file `activemq-configuration.xml`. All discovery groups
@ -353,13 +349,13 @@ details as following:
> one set can be specified in a discovery group configuration. Don't mix > one set can be specified in a discovery group configuration. Don't mix
> them! > them!
### Discovery Groups on the Client Side #### Discovery Groups on the Client Side
Let's discuss how to configure a ActiveMQ client to use discovery to 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 discover a 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. differs depending on whether you're using JMS or the core API.
#### Configuring client discovery using JMS ##### Configuring client discovery using JMS
If you're using JMS and you're using JNDI on the client to look up your If you're using JMS and you're using JNDI on the client to look up your
JMS connection factory instances then you can specify these parameters JMS connection factory instances then you can specify these parameters
@ -385,17 +381,19 @@ factory - you're instantiating the JMS connection factory directly then
you can specify the discovery group parameters directly when creating you can specify the discovery group parameters directly when creating
the JMS connection factory. Here's an example: the JMS connection factory. Here's an example:
final String groupAddress = "231.7.7.7"; ``` java
final String groupAddress = "231.7.7.7";
final int groupPort = 9876; final int groupPort = 9876;
ConnectionFactory jmsConnectionFactory = ConnectionFactory jmsConnectionFactory =
ActiveMQJMSClient.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();
Connection jmsConnection2 = jmsConnectionFactory.createConnection(); Connection jmsConnection2 = jmsConnectionFactory.createConnection();
```
The `refresh-timeout` can be set directly on the The `refresh-timeout` can be set directly on the
DiscoveryGroupConfiguration by using the setter method DiscoveryGroupConfiguration by using the setter method
@ -410,20 +408,22 @@ the connection factory will make sure it waits this long since creation
before creating the first connection. The default value for this before creating the first connection. The default value for this
parameter is `10000` milliseconds. parameter is `10000` milliseconds.
#### Configuring client discovery using Core ##### Configuring client discovery using Core
If you're using the core API to directly instantiate If you're using the core API to directly instantiate
`ClientSessionFactory` instances, then you can specify the discovery `ClientSessionFactory` instances, then you can specify the discovery
group parameters directly when creating the session factory. Here's an group parameters directly when creating the session factory. Here's an
example: example:
final String groupAddress = "231.7.7.7"; ``` java
final int groupPort = 9876; final String groupAddress = "231.7.7.7";
ServerLocator factory = ActiveMQClient.createServerLocatorWithHA(new DiscoveryGroupConfiguration(groupAddress, groupPort, final int groupPort = 9876;
new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1)))); ServerLocator factory = ActiveMQClient.createServerLocatorWithHA(new DiscoveryGroupConfiguration(groupAddress, groupPort,
ClientSessionFactory factory = locator.createSessionFactory(); new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1))));
ClientSession session1 = factory.createSession(); ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session2 = factory.createSession(); ClientSession session1 = factory.createSession();
ClientSession session2 = factory.createSession();
```
The `refresh-timeout` can be set directly on the The `refresh-timeout` can be set directly on the
DiscoveryGroupConfiguration by using the setter method DiscoveryGroupConfiguration by using the setter method
@ -438,8 +438,7 @@ the session factory will make sure it waits this long since creation
before creating the first session. The default value for this parameter before creating the first session. The default value for this parameter
is `10000` milliseconds. is `10000` milliseconds.
Discovery using static Connectors ### Discovery using static Connectors
---------------------------------
Sometimes it may be impossible to use UDP on the network you are using. Sometimes it may be impossible to use UDP on the network you are using.
In this case its possible to configure a connection with an initial list In this case its possible to configure a connection with an initial list
@ -452,18 +451,18 @@ to be hosted, you can configure these servers to use the reliable
servers to connect to. Once they are connected there connection details servers to connect to. Once they are connected there connection details
will be propagated via the server it connects to will be propagated via the server it connects to
### Configuring a Cluster Connection #### Configuring a Cluster Connection
For cluster connections there is no extra configuration needed, you just For cluster connections there is no extra configuration needed, you just
need to make sure that any connectors are defined in the usual manner, need to make sure that any connectors are defined in the usual manner,
(see ? for more information on connectors). These are then referenced by (see [Configuring the Transport](configuring-transports.md) for more information on connectors). These are then referenced by
the cluster connection configuration. the cluster connection configuration.
### Configuring a Client Connection #### Configuring a Client Connection
A static list of possible servers can also be used by a normal client. A static list of possible servers can also be used by a normal client.
#### Configuring client discovery using JMS ##### Configuring client discovery using JMS
If you're using JMS and you're using JNDI on the client to look up your If you're using JMS and you're using JNDI on the client to look up your
JMS connection factory instances then you can specify these parameters JMS connection factory instances then you can specify these parameters
@ -483,43 +482,46 @@ factory - you're instantiating the JMS connection factory directly then
you can specify the connector list directly when creating the JMS you can specify the connector list directly when creating the JMS
connection factory. Here's an example: connection factory. Here's an example:
HashMap<String, Object> map = new HashMap<String, Object>(); ``` java
map.put("host", "myhost"); HashMap<String, Object> map = new HashMap<String, Object>();
map.put("port", "5445"); map.put("host", "myhost");
TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map); map.put("port", "5445");
HashMap<String, Object> map2 = new HashMap<String, Object>(); TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
map2.put("host", "myhost2"); HashMap<String, Object> map2 = new HashMap<String, Object>();
map2.put("port", "5446"); map2.put("host", "myhost2");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2); map2.put("port", "5446");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
ActiveMQConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithHA(JMSFactoryType.CF, server1, server2); ActiveMQConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithHA(JMSFactoryType.CF, server1, server2);
```
#### Configuring client discovery using Core ##### Configuring client discovery using Core
If you are using the core API then the same can be done as follows: If you are using the core API then the same can be done as follows:
HashMap<String, Object> map = new HashMap<String, Object>(); ``` java
map.put("host", "myhost"); HashMap<String, Object> map = new HashMap<String, Object>();
map.put("port", "5445"); map.put("host", "myhost");
TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map); map.put("port", "5445");
HashMap<String, Object> map2 = new HashMap<String, Object>(); TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
map2.put("host", "myhost2"); HashMap<String, Object> map2 = new HashMap<String, Object>();
map2.put("port", "5446"); map2.put("host", "myhost2");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2); map2.put("port", "5446");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2); ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
ClientSessionFactory factory = locator.createSessionFactory(); ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session = factory.createSession(); ClientSession session = factory.createSession();
```
Server-Side Message Load Balancing ## Server-Side Message Load Balancing
==================================
If cluster connections are defined between nodes of a cluster, then If cluster connections are defined between nodes of a cluster, then
ActiveMQ will load balance messages arriving at a particular node from a ActiveMQ will load balance messages arriving at a particular node from a
client. client.
Let's take a simple example of a cluster of four nodes A, B, C, and D Let's take a simple example of a cluster of four nodes A, B, C, and D
arranged in a *symmetric cluster* (described in ?). We have a queue arranged in a *symmetric cluster* (described in Symmetrical Clusters section). We have a queue
called `OrderQueue` deployed on each node of the cluster. called `OrderQueue` deployed on each node of the cluster.
We have client Ca connected to node A, sending orders to the server. We We have client Ca connected to node A, sending orders to the server. We
@ -549,8 +551,7 @@ nodes if they have matching consumers. We'll look at both these cases in
turn with some examples, but first we'll discuss configuring cluster turn with some examples, but first we'll discuss configuring cluster
connections in general. connections in general.
Configuring Cluster Connections ### Configuring Cluster Connections
-------------------------------
Cluster connections group servers into clusters so that messages can be 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 load balanced between the nodes of the cluster. Let's take a look at a
@ -665,7 +666,7 @@ specified. The following shows all the available configuration options
This parameter determines the interval in milliseconds between retry This parameter determines the interval in milliseconds between retry
attempts. It has the same meaning as the `retry-interval` on a attempts. It has the same meaning as the `retry-interval` on a
bridge (as described in ?). bridge (as described in [Core Bridges](core-bridges.md)).
This parameter is optional and its default value is `500` This parameter is optional and its default value is `500`
milliseconds. milliseconds.
@ -697,7 +698,7 @@ specified. The following shows all the available configuration options
the target node. the target node.
This parameter has the same meaning as `use-duplicate-detection` on This parameter has the same meaning as `use-duplicate-detection` on
a bridge. For more information on duplicate detection, please see ?. a bridge. For more information on duplicate detection, please see [Duplicate Detection](duplicate-detection.md).
Default is true. Default is true.
- `forward-when-no-consumers`. This parameter determines whether - `forward-when-no-consumers`. This parameter determines whether
@ -772,8 +773,7 @@ one will be available. There may be many more servers in the cluster but
these will; be discovered via one of these connectors once an initial these will; be discovered via one of these connectors once an initial
connection has been made. connection has been made.
Cluster User Credentials ### Cluster User Credentials
------------------------
When creating connections between nodes of a cluster to form a cluster When creating connections between nodes of a cluster to form a cluster
connection, ActiveMQ uses a cluster user and cluster password which is connection, ActiveMQ uses a cluster user and cluster password which is
@ -789,8 +789,7 @@ defined in `activemq-configuration.xml`:
> the default values. If they are not changed from the default, ActiveMQ > the default values. If they are not changed from the default, ActiveMQ
> will detect this and pester you with a warning on every start-up. > will detect this and pester you with a warning on every start-up.
Client-Side Load balancing ## Client-Side Load balancing
==========================
With ActiveMQ client-side load balancing, subsequent sessions created With ActiveMQ client-side load balancing, subsequent sessions created
using a single session factory can be connected to different nodes of using a single session factory can be connected to different nodes of
@ -857,14 +856,18 @@ 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 directly on the client side then you can set the load balancing policy
using the setter on the `ActiveMQConnectionFactory` before using it: using the setter on the `ActiveMQConnectionFactory` before using it:
ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactory(...); ``` java
jmsConnectionFactory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy"); ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactory(...);
jmsConnectionFactory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
```
If you're using the core API, you can set the load balancing policy If you're using the core API, you can set the load balancing policy
directly on the `ServerLocator` instance you are using: directly on the `ServerLocator` instance you are using:
ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2); ``` java
locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy"); ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
```
The set of servers over which the factory load balances can be The set of servers over which the factory load balances can be
determined in one of two ways: determined in one of two ways:
@ -873,8 +876,7 @@ determined in one of two ways:
- Using discovery. - Using discovery.
Specifying Members of a Cluster Explicitly ## Specifying Members of a Cluster Explicitly
==========================================
Sometimes you want to explicitly define a cluster more explicitly, that Sometimes you want to explicitly define a cluster more explicitly, that
is control which server connect to each other in the cluster. This is is control which server connect to each other in the cluster. This is
@ -899,8 +901,7 @@ In this example we have set the attribute
this server can create a cluster connection to is server1-connector. this server can create a cluster connection to is server1-connector.
This means you can explicitly create any cluster topology you want. This means you can explicitly create any cluster topology you want.
Message Redistribution ## Message Redistribution
======================
Another important part of clustering is message redistribution. Earlier Another important part of clustering is message redistribution. Earlier
we learned how server side message load balancing round robins messages we learned how server side message load balancing round robins messages
@ -925,7 +926,7 @@ default message redistribution is disabled.
Message redistribution can be configured on a per address basis, by Message redistribution can be configured on a per address basis, by
specifying the redistribution delay in the address settings, for more specifying the redistribution delay in the address settings, for more
information on configuring address settings, please see ?. information on configuring address settings, please see [Queue Attributes](queue-attributes.md).
Here's an address settings snippet from `activemq-configuration.xml` Here's an address settings snippet from `activemq-configuration.xml`
showing how message redistribution is enabled for a set of queues: showing how message redistribution is enabled for a set of queues:
@ -943,7 +944,7 @@ with "jms.", so the above would enable instant (no delay) redistribution
for all JMS queues and topic subscriptions. for all JMS queues and topic subscriptions.
The attribute `match` can be an exact match or it can be a string that The attribute `match` can be an exact match or it can be a string that
conforms to the ActiveMQ wildcard syntax (described in ?). conforms to the ActiveMQ wildcard syntax (described in [Wildcard Syntax](wildcard-syntax.md)).
The element `redistribution-delay` defines the delay in milliseconds The element `redistribution-delay` defines the delay in milliseconds
after the last consumer is closed on a queue before redistributing after the last consumer is closed on a queue before redistributing
@ -957,14 +958,12 @@ a common case that a consumer closes but another one quickly is created
on the same queue, in such a case you probably don't want to on the same queue, in such a case you probably don't want to
redistribute immediately since the new consumer will arrive shortly. redistribute immediately since the new consumer will arrive shortly.
Cluster topologies ## Cluster topologies
==================
ActiveMQ clusters can be connected together in many different ActiveMQ clusters can be connected together in many different
topologies, let's consider the two most common ones here topologies, let's consider the two most common ones here
Symmetric cluster ### Symmetric cluster
-----------------
A symmetric cluster is probably the most common cluster topology, and A symmetric cluster is probably the most common cluster topology, and
you'll be familiar with if you've had experience of JBoss Application you'll be familiar with if you've had experience of JBoss Application
@ -989,8 +988,7 @@ the nodes.
Don't forget [this warning](#copy-warning) when creating a symmetric Don't forget [this warning](#copy-warning) when creating a symmetric
cluster. cluster.
Chain cluster ### Chain cluster
-------------
With a chain cluster, each node in the cluster is not connected to every With a chain cluster, each node in the cluster is not connected to every
node in the cluster directly, instead the nodes form a chain with a node node in the cluster directly, instead the nodes form a chain with a node
@ -1021,8 +1019,7 @@ distribute messages to node B when they arrive, even though node B has
no consumers itself, it would know that a further hop away is node C no consumers itself, it would know that a further hop away is node C
which does have consumers. which does have consumers.
Scaling Down ### Scaling Down
============
ActiveMQ supports scaling down a cluster with no message loss (even for ActiveMQ supports scaling down a cluster with no message loss (even for
non-durable messages). This is especially useful in certain environments non-durable messages). This is especially useful in certain environments

77
docs/user-manual/en/configuring-transports.md
View File

@ -1,5 +1,4 @@
Configuring the Transport # Configuring the Transport
=========================
ActiveMQ has a fully pluggable and highly flexible transport layer and ActiveMQ has a fully pluggable and highly flexible transport layer and
defines its own Service Provider Interface (SPI) to make plugging in a defines its own Service Provider Interface (SPI) to make plugging in a
@ -8,8 +7,7 @@ new transport provider relatively straightforward.
In this chapter we'll describe the concepts required for understanding In this chapter we'll describe the concepts required for understanding
ActiveMQ transports and where and how they're configured. ActiveMQ transports and where and how they're configured.
Understanding Acceptors ## Understanding Acceptors
=======================
One of the most important concepts in ActiveMQ transports is the One of the most important concepts in ActiveMQ transports is the
*acceptor*. Let's dive straight in and take a look at an acceptor *acceptor*. Let's dive straight in and take a look at an acceptor
@ -56,8 +54,7 @@ multiple protocols. By default this will be all available protocols but
can be limited by either the now deprecated `protocol` param or by can be limited by either the now deprecated `protocol` param or by
setting a comma seperated list to the newly added `protocols` parameter. setting a comma seperated list to the newly added `protocols` parameter.
Understanding Connectors ## Understanding Connectors
========================
Whereas acceptors are used on the server to define how we accept Whereas acceptors are used on the server to define how we accept
connections, connectors are used by a client to define how it connects connections, connectors are used by a client to define how it connects
@ -103,8 +100,7 @@ couple of reasons for this:
java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
java.naming.provider.url=tcp://myhost:5445 java.naming.provider.url=tcp://myhost:5445
Configuring the transport directly from the client side. ## Configuring the transport directly from the client side.
========================================================
How do we configure a core `ClientSessionFactory` with the information How do we configure a core `ClientSessionFactory` with the information
that it needs to connect with a server? that it needs to connect with a server?
@ -120,45 +116,48 @@ connect directly to the acceptor we defined earlier in this chapter, it
uses the standard Netty TCP transport and will try and connect on port uses the standard Netty TCP transport and will try and connect on port
5446 to localhost (default): 5446 to localhost (default):
Map<String, Object> connectionParams = new HashMap<String, Object>(); ``` java
Map<String, Object> connectionParams = new HashMap<String, Object>();
connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME, connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME,
5446); 5446);
TransportConfiguration transportConfiguration = TransportConfiguration transportConfiguration =
new TransportConfiguration( new TransportConfiguration(
"org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory", "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
connectionParams); connectionParams);
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(transportConfiguration); ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(transportConfiguration);
ClientSessionFactory sessionFactory = locator.createClientSessionFactory(); ClientSessionFactory sessionFactory = locator.createClientSessionFactory();
ClientSession session = sessionFactory.createSession(...); ClientSession session = sessionFactory.createSession(...);
etc etc
```
Similarly, if you're using JMS, you can configure the JMS connection Similarly, if you're using JMS, you can configure the JMS connection
factory directly on the client side without having to define a connector factory directly on the client side without having to define a connector
on the server side or define a connection factory in `activemq-jms.xml`: on the server side or define a connection factory in `activemq-jms.xml`:
Map<String, Object> connectionParams = new HashMap<String, Object>(); ``` java
Map<String, Object> connectionParams = new HashMap<String, Object>();
connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME, 5446); connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME, 5446);
TransportConfiguration transportConfiguration = TransportConfiguration transportConfiguration =
new TransportConfiguration( new TransportConfiguration(
"org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory", "org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
connectionParams); connectionParams);
ConnectionFactory connectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF, transportConfiguration); ConnectionFactory connectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF, transportConfiguration);
Connection jmsConnection = connectionFactory.createConnection(); Connection jmsConnection = connectionFactory.createConnection();
etc etc
```
Configuring the Netty transport ## Configuring the Netty transport
===============================
Out of the box, ActiveMQ currently uses Out of the box, ActiveMQ currently uses
[Netty](http://www.jboss.org/netty/), a high performance low level [Netty](http://www.jboss.org/netty/), a high performance low level
@ -170,8 +169,7 @@ straightforward TCP sockets, SSL, or to tunnel over HTTP or HTTPS..
We believe this caters for the vast majority of transport requirements. We believe this caters for the vast majority of transport requirements.
Single Port Support ## Single Port Support
-------------------
As of version 2.4 ActiveMQ now supports using a single port for all As of version 2.4 ActiveMQ now supports using a single port for all
protocols, ActiveMQ will automatically detect which protocol is being protocols, ActiveMQ will automatically detect which protocol is being
@ -189,8 +187,7 @@ It is possible to limit which protocols are supported by using the
> >
> The `protocol` parameter is now deprecated > The `protocol` parameter is now deprecated
Configuring Netty TCP ## Configuring Netty TCP
---------------------
Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP
can be configured to use old blocking Java IO or non blocking Java NIO. can be configured to use old blocking Java IO or non blocking Java NIO.
@ -320,8 +317,7 @@ Netty for simple TCP:
connector will let the system pick up an ephemeral port. valid ports connector will let the system pick up an ephemeral port. valid ports
are 0 to 65535 are 0 to 65535
Configuring Netty SSL ## Configuring Netty SSL
---------------------
Netty SSL is similar to the Netty TCP transport but it provides Netty SSL is similar to the Netty TCP transport but it provides
additional security by encrypting TCP connections using the Secure additional security by encrypting TCP connections using the Secure
@ -424,8 +420,7 @@ following additional properties:
connecting to this acceptor that 2-way SSL is required. Valid values connecting to this acceptor that 2-way SSL is required. Valid values
are `true` or `false`. Default is `false`. are `true` or `false`. Default is `false`.
Configuring Netty HTTP ## Configuring Netty HTTP
----------------------
Netty HTTP tunnels packets over the HTTP protocol. It can be useful in Netty HTTP tunnels packets over the HTTP protocol. It can be useful in
scenarios where firewalls only allow HTTP traffic to pass. scenarios where firewalls only allow HTTP traffic to pass.
@ -454,9 +449,3 @@ additional properties:
- `http-requires-session-id`. If true the client will wait after the - `http-requires-session-id`. If true the client will wait after the
first call to receive a session id. Used the http connector is first call to receive a session id. Used the http connector is
connecting to servlet acceptor (not recommended) connecting to servlet acceptor (not recommended)
Configuring Netty Servlet
-------------------------
As of 2.4 ActiveMQ Servlet support will be provided via Undertow in
Wildfly

101
docs/user-manual/en/connection-ttl.md
View File

@ -1,12 +1,10 @@
Detecting Dead Connections # Detecting Dead Connections
==========================
In this section we will discuss connection time-to-live (TTL) and In this section we will discuss connection time-to-live (TTL) and
explain how ActiveMQ deals with crashed clients and clients which have explain how ActiveMQ deals with crashed clients and clients which have
exited without cleanly closing their resources. exited without cleanly closing their resources.
Cleaning up Dead Connection Resources on the Server ## Cleaning up Dead Connection Resources on the Server
===================================================
Before a ActiveMQ client application exits it is considered good Before a ActiveMQ client application exits it is considered good
practice that it should close its resources in a controlled manner, practice that it should close its resources in a controlled manner,
@ -15,57 +13,61 @@ using a `finally` block.
Here's an example of a well behaved core client application closing its Here's an example of a well behaved core client application closing its
session and session factory in a finally block: session and session factory in a finally block:
ServerLocator locator = null; ``` java
ClientSessionFactory sf = null; ServerLocator locator = null;
ClientSession session = null; ClientSessionFactory sf = null;
ClientSession session = null;
try try
{ {
locator = ActiveMQClient.createServerLocatorWithoutHA(..); locator = ActiveMQClient.createServerLocatorWithoutHA(..);
sf = locator.createClientSessionFactory();; sf = locator.createClientSessionFactory();;
session = sf.createSession(...); session = sf.createSession(...);
... do some stuff with the session... ... do some stuff with the session...
} }
finally finally
{ {
if (session != null) if (session != null)
{ {
session.close(); session.close();
} }
if (sf != null) if (sf != null)
{ {
sf.close(); sf.close();
} }
if(locator != null) if(locator != null)
{ {
locator.close(); locator.close();
} }
} }
```
And here's an example of a well behaved JMS client application: And here's an example of a well behaved JMS client application:
Connection jmsConnection = null; ``` java
Connection jmsConnection = null;
try try
{ {
ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(...); ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(...);
jmsConnection = jmsConnectionFactory.createConnection(); jmsConnection = jmsConnectionFactory.createConnection();
... do some stuff with the connection... ... do some stuff with the connection...
} }
finally finally
{ {
if (connection != null) if (connection != null)
{ {
connection.close(); connection.close();
} }
} }
```
Unfortunately users don't always write well behaved applications, and Unfortunately users don't always write well behaved applications, and
sometimes clients just crash so they don't have a chance to clean up sometimes clients just crash so they don't have a chance to clean up
@ -112,8 +114,7 @@ server side. This can be done by specifying the
The default value for `connection-ttl-override` is `-1` which means "do The default value for `connection-ttl-override` is `-1` which means "do
not override" (i.e. let clients use their own values). not override" (i.e. let clients use their own values).
Closing core sessions or JMS connections that you have failed to close ## Closing core sessions or JMS connections that you have failed to close
----------------------------------------------------------------------
As previously discussed, it's important that all core client sessions As previously discussed, it's important that all core client sessions
and JMS connections are always closed explicitly in a `finally` block and JMS connections are always closed explicitly in a `finally` block
@ -138,8 +139,7 @@ where you created the JMS connection / client session that you later did
not close. This will enable you to pinpoint the error in your code and not close. This will enable you to pinpoint the error in your code and
correct it appropriately. correct it appropriately.
Detecting failure from the client side. ## Detecting failure from the client side.
=======================================
In the previous section we discussed how the client sends pings to the In the previous section we discussed how the client sends pings to the
server and how "dead" connection resources are cleaned up by the server. server and how "dead" connection resources are cleaned up by the server.
@ -169,8 +169,7 @@ will never fail the connection on the client side if no data is received
from the server. Typically this is much lower than connection TTL to from the server. Typically this is much lower than connection TTL to
allow clients to reconnect in case of transitory failure. allow clients to reconnect in case of transitory failure.
Configuring Asynchronous Connection Execution ## Configuring Asynchronous Connection Execution
=============================================
Most packets received on the server side are executed on the remoting Most packets received on the server side are executed on the remoting
thread. These packets represent short-running operations and are always thread. These packets represent short-running operations and are always

18
docs/user-manual/en/core-bridges.md
View File

@ -1,5 +1,4 @@
Core Bridges # Core Bridges
============
The function of a bridge is to consume messages from a source queue, and The function of a bridge is to consume messages from a source queue, and
forward them to a target address, typically on a different ActiveMQ forward them to a target address, typically on a different ActiveMQ
@ -21,7 +20,7 @@ be ActiveMQ servers.
Bridges can be configured to provide *once and only once* delivery Bridges can be configured to provide *once and only once* delivery
guarantees even in the event of the failure of the source or the target guarantees even in the event of the failure of the source or the target
server. They do this by using duplicate detection (described in ?). server. They do this by using duplicate detection (described in [Duplicate Detection](duplicate-detection.md)).
> **Note** > **Note**
> >
@ -37,8 +36,7 @@ server. They do this by using duplicate detection (described in ?).
> provide the same guarantee using a JMS bridge you would have to use XA > provide the same guarantee using a JMS bridge you would have to use XA
> which has a higher overhead and is more complex to configure. > which has a higher overhead and is more complex to configure.
Configuring Bridges ## Configuring Bridges
===================
Bridges are configured in `activemq-configuration.xml`. Let's kick off Bridges are configured in `activemq-configuration.xml`. Let's kick off
with an example (this is actually from the bridge example): with an example (this is actually from the bridge example):
@ -100,7 +98,7 @@ Let's take a look at all the parameters in turn:
- `filter-string`. An optional filter string can be supplied. If - `filter-string`. An optional filter string can be supplied. If
specified then only messages which match the filter expression specified then only messages which match the filter expression
specified in the filter string will be forwarded. The filter string specified in the filter string will be forwarded. The filter string
follows the ActiveMQ filter expression syntax described in ?. follows the ActiveMQ filter expression syntax described in [Filter Expressions](filter-expressions.md).
- `transformer-class-name`. An optional transformer-class-name can be - `transformer-class-name`. An optional transformer-class-name can be
specified. This is the name of a user-defined class which implements specified. This is the name of a user-defined class which implements
@ -179,7 +177,7 @@ Let's take a look at all the parameters in turn:
allows these duplicates to be screened out and ignored. allows these duplicates to be screened out and ignored.
This allows the bridge to provide a *once and only once* delivery This allows the bridge to provide a *once and only once* delivery
guarantee without using heavyweight methods such as XA (see ? for guarantee without using heavyweight methods such as XA (see [Duplicate Detection](duplicate-detection.md) for
more information). more information).
The default value for this parameter is `true`. The default value for this parameter is `true`.
@ -187,7 +185,7 @@ Let's take a look at all the parameters in turn:
- `confirmation-window-size`. This optional parameter determines the - `confirmation-window-size`. This optional parameter determines the
`confirmation-window-size` to use for the connection used to forward `confirmation-window-size` to use for the connection used to forward
messages to the target node. This attribute is described in section messages to the target node. This attribute is described in section
? [Reconnection and Session Reattachment](client-reconnection.md)
> **Warning** > **Warning**
> >
@ -215,11 +213,11 @@ Let's take a look at all the parameters in turn:
encapsulates knowledge of what transport to use (TCP, SSL, HTTP etc) encapsulates knowledge of what transport to use (TCP, SSL, HTTP etc)
as well as the server connection parameters (host, port etc). For as well as the server connection parameters (host, port etc). For
more information about what connectors are and how to configure more information about what connectors are and how to configure
them, please see ?. them, please see [Configuring the Transport](configuring-transports.md).
The `discovery-group-ref` element has one attribute - The `discovery-group-ref` element has one attribute -
`discovery-group-name`. This attribute points to a `discovery-group` `discovery-group-name`. This attribute points to a `discovery-group`
defined elsewhere. For more information about what discovery-groups defined elsewhere. For more information about what discovery-groups
are and how to configure them, please see ?. are and how to configure them, please see [Discovery Groups](clusters.md).

9
docs/user-manual/en/diverts.md
View File

@ -1,5 +1,4 @@
Diverting and Splitting Message Flows # Diverting and Splitting Message Flows
=====================================
ActiveMQ allows you to configure objects called *diverts* with some ActiveMQ allows you to configure objects called *diverts* with some
simple server configuration. simple server configuration.
@ -43,8 +42,7 @@ use diverts.
Let's take a look at some divert examples: Let's take a look at some divert examples:
Exclusive Divert ## Exclusive Divert
================
Let's take a look at an exclusive divert. An exclusive divert diverts Let's take a look at an exclusive divert. An exclusive divert diverts
all matching messages that are routed to the old address to the new all matching messages that are routed to the old address to the new
@ -86,8 +84,7 @@ queue, which is configured with a bridge which forwards the message to
an address on another ActiveMQ server. Please see the example for more an address on another ActiveMQ server. Please see the example for more
details. details.
Non-exclusive Divert ## Non-exclusive Divert
====================
Now we'll take a look at a non-exclusive divert. Non exclusive diverts Now we'll take a look at a non-exclusive divert. Non exclusive diverts
are the same as exclusive diverts, but they only forward a *copy* of the are the same as exclusive diverts, but they only forward a *copy* of the

42
docs/user-manual/en/duplicate-detection.md
View File

@ -1,5 +1,4 @@
Duplicate Message Detection # Duplicate Message Detection
===========================
ActiveMQ includes powerful automatic duplicate message detection, ActiveMQ includes powerful automatic duplicate message detection,
filtering out duplicate messages without you having to code your own filtering out duplicate messages without you having to code your own
@ -38,8 +37,7 @@ successfully committed or not!
To solve these issues ActiveMQ provides automatic duplicate messages To solve these issues ActiveMQ provides automatic duplicate messages
detection for messages sent to addresses. detection for messages sent to addresses.
Using Duplicate Detection for Message Sending ## Using Duplicate Detection for Message Sending
=============================================
Enabling duplicate message detection for sent messages is simple: you Enabling duplicate message detection for sent messages is simple: you
just need to set a special property on the message to a unique value. just need to set a special property on the message to a unique value.
@ -75,30 +73,32 @@ by generating a UUID.
Here's an example of setting the property using the core API: Here's an example of setting the property using the core API:
... ``` java
...
ClientMessage message = session.createMessage(true); ClientMessage message = session.createMessage(true);
SimpleString myUniqueID = "This is my unique id"; // Could use a UUID for this SimpleString myUniqueID = "This is my unique id"; // Could use a UUID for this
message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID); message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID);
... ```
And here's an example using the JMS API: And here's an example using the JMS API:
... ``` java
...
Message jmsMessage = session.createMessage(); Message jmsMessage = session.createMessage();
String myUniqueID = "This is my unique id"; // Could use a UUID for this String myUniqueID = "This is my unique id"; // Could use a UUID for this
message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID); message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);
... ...
```
Configuring the Duplicate ID Cache ## Configuring the Duplicate ID Cache
==================================
The server maintains caches of received values of the The server maintains caches of received values of the
`org.apache.activemq.core.message.impl.HDR_DUPLICATE_DETECTION_ID` `org.apache.activemq.core.message.impl.HDR_DUPLICATE_DETECTION_ID`
@ -124,8 +124,7 @@ value for this parameter is `true`.
> larger enough size so if you resend messages all the previously sent > larger enough size so if you resend messages all the previously sent
> ones are in the cache not having been overwritten. > ones are in the cache not having been overwritten.
Duplicate Detection and Bridges ## Duplicate Detection and Bridges
===============================
Core bridges can be configured to automatically add a unique duplicate Core bridges can be configured to automatically add a unique duplicate
id value (if there isn't already one in the message) before forwarding id value (if there isn't already one in the message) before forwarding
@ -141,10 +140,9 @@ the `use-duplicate-detection` to `true` when configuring a bridge in
The default value for this parameter is `true`. The default value for this parameter is `true`.
For more information on core bridges and how to configure them, please For more information on core bridges and how to configure them, please
see ?. see [Core Bridges](core-bridges.md).
Duplicate Detection and Cluster Connections ## Duplicate Detection and Cluster Connections
===========================================
Cluster connections internally use core bridges to move messages Cluster connections internally use core bridges to move messages
reliable between nodes of the cluster. Consequently they can also be reliable between nodes of the cluster. Consequently they can also be
@ -158,4 +156,4 @@ connection in `activemq-configuration.xml`.
The default value for this parameter is `true`. The default value for this parameter is `true`.
For more information on cluster connections and how to configure them, For more information on cluster connections and how to configure them,
please see ?. please see [Clusters](clusters.md).

162
docs/user-manual/en/embedding-activemq.md
View File

@ -1,5 +1,4 @@
Embedding ActiveMQ # Embedding ActiveMQ
==================
ActiveMQ is designed as set of simple Plain Old Java Objects (POJOs). ActiveMQ is designed as set of simple Plain Old Java Objects (POJOs).
This means ActiveMQ can be instantiated and run in any dependency This means ActiveMQ can be instantiated and run in any dependency
@ -18,60 +17,59 @@ configuration object, instantiate the server, start it, and you have a
ActiveMQ 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. that.
Simple Config File Embedding ## Simple Config File Embedding
============================
The simplest way to embed ActiveMQ is to use the embedded wrapper The simplest way to embed ActiveMQ is to use the embedded wrapper
classes and configure ActiveMQ through its configuration files. There classes and configure ActiveMQ through its configuration files. There
are two different helper classes for this depending on whether your are two different helper classes for this depending on whether your
using the ActiveMQ Core API or JMS. using the ActiveMQ Core API or JMS.
Core API Only ## Core API Only
-------------
For instantiating a core ActiveMQ Server only, the steps are pretty 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
`activemq-configuration.xml` in your classpath: `activemq-configuration.xml` in your classpath:
import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ; ``` java
import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
... ...
EmbeddedActiveMQ embedded = new EmbeddedActiveMQ(); EmbeddedActiveMQ embedded = new EmbeddedActiveMQ();
embedded.start(); embedded.start();
ClientSessionFactory nettyFactory = ActiveMQClient.createClientSessionFactory( ClientSessionFactory nettyFactory = ActiveMQClient.createClientSessionFactory(
new TransportConfiguration( new TransportConfiguration(
InVMConnectorFactory.class.getName())); InVMConnectorFactory.class.getName()));
ClientSession session = factory.createSession(); ClientSession session = factory.createSession();
session.createQueue("example", "example", true); session.createQueue("example", "example", true);
ClientProducer producer = session.createProducer("example"); ClientProducer producer = session.createProducer("example");
ClientMessage message = session.createMessage(true); ClientMessage message = session.createMessage(true);
message.getBody().writeString("Hello"); message.getBody().writeString("Hello");
producer.send(message); producer.send(message);
session.start(); session.start();
ClientConsumer consumer = session.createConsumer("example"); ClientConsumer consumer = session.createConsumer("example");
ClientMessage msgReceived = consumer.receive(); ClientMessage msgReceived = consumer.receive();
System.out.println("message = " + msgReceived.getBody().readString()); System.out.println("message = " + msgReceived.getBody().readString());
session.close(); session.close();
```
The `EmbeddedActiveMQ` class has a few additional setter methods that The `EmbeddedActiveMQ` class has a few additional setter methods that
allow you to specify a different config file name as well as other allow you to specify a different config file name as well as other
properties. See the javadocs for this class for more details. properties. See the javadocs for this class for more details.
JMS API ## JMS API
-------
JMS embedding is simple as well. This example requires that you have JMS embedding is simple as well. This example requires that you have
defined the config files `activemq-configuration.xml`, defined the config files `activemq-configuration.xml`,
@ -79,18 +77,20 @@ defined the config files `activemq-configuration.xml`,
enabled. Let's also assume that a queue and connection factory has been enabled. Let's also assume that a queue and connection factory has been
defined in the `activemq-jms.xml` config file. defined in the `activemq-jms.xml` config file.
import org.apache.activemq.jms.server.embedded.EmbeddedJMS; ``` java
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 activemq-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 ... ... regular JMS code ...
```
By default, the `EmbeddedJMS` class will store component entries defined By default, the `EmbeddedJMS` class will store component entries defined
within your `activemq-jms.xml` file in an internal concurrent hash map. within your `activemq-jms.xml` file in an internal concurrent hash map.
@ -99,8 +99,7 @@ If you want to use JNDI, call the `EmbeddedJMS.setContext()` method with
the root JNDI context you want your components bound into. See the the root JNDI context you want your components bound into. See the
javadocs for this class for more details on other config options. javadocs for this class for more details on other config options.
POJO instantiation - Embedding Programmatically ## POJO instantiation - Embedding Programmatically
===============================================
You can follow this step-by-step guide to programmatically embed the You can follow this step-by-step guide to programmatically embed the
core, non-JMS ActiveMQ Server instance: core, non-JMS ActiveMQ Server instance:
@ -108,43 +107,49 @@ core, non-JMS ActiveMQ Server instance:
Create the configuration object - this contains configuration Create the configuration object - this contains configuration
information for a ActiveMQ instance. The setter methods of this class information for a ActiveMQ instance. The setter methods of this class
allow you to programmatically set configuration options as describe in allow you to programmatically set configuration options as describe in
the ? section. the [Server Configuration](configuration-index.md) section.
The acceptors are configured through `ConfigurationImpl`. Just add the The acceptors are configured through `ConfigurationImpl`. Just add the
`NettyAcceptorFactory` on the transports the same way you would through `NettyAcceptorFactory` on the transports the same way you would through
the main configuration file. the main configuration file.
import org.apache.activemq.core.config.Configuration; ``` java
import org.apache.activemq.core.config.impl.ConfigurationImpl; import org.apache.activemq.core.config.Configuration;
import org.apache.activemq.core.config.impl.ConfigurationImpl;
... ...
Configuration config = new ConfigurationImpl(); Configuration config = new ConfigurationImpl();
HashSet<TransportConfiguration> transports = new HashSet<TransportConfiguration>(); HashSet<TransportConfiguration> transports = new HashSet<TransportConfiguration>();
transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName())); transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName())); transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));
config.setAcceptorConfigurations(transports); config.setAcceptorConfigurations(transports);
```
You need to instantiate an instance of You need to instantiate an instance of
`org.apache.activemq.api.core.server.embedded.EmbeddedActiveMQ` and add `org.apache.activemq.api.core.server.embedded.EmbeddedActiveMQ` and add
the configuration object to it. the configuration object to it.
import org.apache.activemq.api.core.server.ActiveMQ; ``` java
import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ; import org.apache.activemq.api.core.server.ActiveMQ;
import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
... ...
EmbeddedActiveMQ server = new EmbeddedActiveMQ(); EmbeddedActiveMQ server = new EmbeddedActiveMQ();
server.setConfiguration(config); server.setConfiguration(config);
server.start(); server.start();
```
You also have the option of instantiating `ActiveMQServerImpl` directly: You also have the option of instantiating `ActiveMQServerImpl` directly:
ActiveMQServer server = new ActiveMQServerImpl(config); ``` java
server.start(); ActiveMQServer server = new ActiveMQServerImpl(config);
server.start();
```
For JMS POJO instantiation, you work with the EmbeddedJMS class instead For JMS POJO instantiation, you work with the EmbeddedJMS class instead
as described earlier. First you define the configuration as described earlier. First you define the configuration
@ -152,35 +157,36 @@ programmatically for your ConnectionFactory and Destination objects,
then set the JmsConfiguration property of the EmbeddedJMS class. Here is then set the JmsConfiguration property of the EmbeddedJMS class. Here is
an example of this: an example of this:
// Step 1. Create ActiveMQ core configuration, and set the properties accordingly ``` java
Configuration configuration = new ConfigurationImpl(); // Step 1. Create ActiveMQ core configuration, and set the properties accordingly
configuration.setPersistenceEnabled(false); Configuration configuration = new ConfigurationImpl();
configuration.setSecurityEnabled(false); configuration.setPersistenceEnabled(false);
configuration.getAcceptorConfigurations().add(new TransportConfiguration(NettyAcceptorFactory.class.getName())); configuration.setSecurityEnabled(false);
configuration.getAcceptorConfigurations().add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
// Step 2. Create the JMS configuration // Step 2. Create the JMS configuration
JMSConfiguration jmsConfig = new JMSConfigurationImpl(); JMSConfiguration jmsConfig = new JMSConfigurationImpl();
// Step 3. Configure the JMS ConnectionFactory // Step 3. Configure the JMS ConnectionFactory
TransportConfiguration connectorConfig = new TransportConfiguration(NettyConnectorFactory.class.getName()); TransportConfiguration connectorConfig = new TransportConfiguration(NettyConnectorFactory.class.getName());
ConnectionFactoryConfiguration cfConfig = new ConnectionFactoryConfigurationImpl("cf", connectorConfig, "/cf"); ConnectionFactoryConfiguration cfConfig = new ConnectionFactoryConfigurationImpl("cf", connectorConfig, "/cf");
jmsConfig.getConnectionFactoryConfigurations().add(cfConfig); jmsConfig.getConnectionFactoryConfigurations().add(cfConfig);
// Step 4. Configure the JMS Queue // Step 4. Configure the JMS Queue
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 ActiveMQ 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(); jmsServer.start();
```
Please see ? for an example which shows how to setup and run ActiveMQ Please see ? for an example which shows how to setup and run ActiveMQ
embedded with JMS. embedded with JMS.
Dependency Frameworks ## Dependency Frameworks
=====================
You may also choose to use a dependency injection framework such as You may also choose to use a dependency injection framework such as
JBoss Micro Container or Spring Framework. See ? for more details on JBoss Micro Container or Spring Framework. See ? for more details on
@ -221,5 +227,7 @@ be:
`ActiveMQBootstrapServer` provides an easy encapsulation of JBoss Micro `ActiveMQBootstrapServer` provides an easy encapsulation of JBoss Micro
Container. Container.
ActiveMQBootstrapServer bootStrap = new ActiveMQBootstrapServer(new String[] {"activemq-beans.xml"}); ``` java
bootStrap.run(); ActiveMQBootstrapServer bootStrap = new ActiveMQBootstrapServer(new String[] {"activemq-beans.xml"});
bootStrap.run();
```

9
docs/user-manual/en/filter-expressions.md
View File

@ -1,5 +1,4 @@
Filter Expressions # Filter Expressions
==================
ActiveMQ provides a powerful filter language based on a subset of the ActiveMQ provides a powerful filter language based on a subset of the
SQL 92 expression syntax. SQL 92 expression syntax.
@ -17,13 +16,13 @@ Filter expressions are used in several places in ActiveMQ
filter expression will enter the queue. filter expression will enter the queue.
- Core bridges can be defined with an optional filter expression, only - Core bridges can be defined with an optional filter expression, only
matching messages will be bridged (see ?). matching messages will be bridged (see [Core Bridges]9core-bridges.md)).
- Diverts can be defined with an optional filter expression, only - Diverts can be defined with an optional filter expression, only
matching messages will be diverted (see ?). matching messages will be diverted (see [Diverts](diverts.md)).
- Filter are also used programmatically when creating consumers, - Filter are also used programmatically when creating consumers,
queues and in several places as described in ?. queues and in several places as described in [management](management.md).
There are some differences between JMS selector expressions and ActiveMQ There are some differences between JMS selector expressions and ActiveMQ
core filter expressions. Whereas JMS selector expressions operate on a core filter expressions. Whereas JMS selector expressions operate on a

85
docs/user-manual/en/flow-control.md
View File

@ -1,12 +1,10 @@
Flow Control # Flow Control
============
Flow control is used to limit the flow of data between a client and Flow control is used to limit the flow of data between a client and
server, or a server and another server in order to prevent the client or server, or a server and another server in order to prevent the client or
server being overwhelmed with data. server being overwhelmed with data.
Consumer Flow Control ## Consumer Flow Control
=====================
This controls the flow of data between the server and the client as the This controls the flow of data between the server and the client as the
client consumes messages. For performance reasons clients normally client consumes messages. For performance reasons clients normally
@ -17,8 +15,7 @@ internal buffer, then you could end up with a situation where messages
would keep building up possibly causing out of memory on the client if would keep building up possibly causing out of memory on the client if
they cannot be processed in time. they cannot be processed in time.
Window-Based Flow Control ## Window-Based Flow Control
-------------------------
By default, ActiveMQ consumers buffer messages from the server in a By default, ActiveMQ consumers buffer messages from the server in a
client side buffer before the client consumes them. This improves client side buffer before the client consumes them. This improves
@ -51,38 +48,38 @@ Setting the consumer window size can considerably improve performance
depending on the messaging use case. As an example, let's consider the depending on the messaging use case. As an example, let's consider the
two extremes: two extremes:
Fast consumers ### Fast consumers
: Fast consumers can process messages as fast as they consume them (or Fast consumers can process messages as fast as they consume them (or
even faster) even faster)
To allow fast consumers, set the `consumer-window-size` to -1. This To allow fast consumers, set the `consumer-window-size` to -1. This
will allow *unbounded* message buffering on the client side. will allow *unbounded* message buffering on the client side.
Use this setting with caution: it can overflow the client memory if Use this setting with caution: it can overflow the client memory if
the consumer is not able to process messages as fast as it receives the consumer is not able to process messages as fast as it receives
them. them.
Slow consumers ### Slow consumers
: Slow consumers takes significant time to process each message and it Slow consumers takes significant time to process each message and it
is desirable to prevent buffering messages on the client side so is desirable to prevent buffering messages on the client side so
that they can be delivered to another consumer instead. that they can be delivered to another consumer instead.
Consider a situation where a queue has 2 consumers; 1 of which is Consider a situation where a queue has 2 consumers; 1 of which is
very slow. Messages are delivered in a round robin fashion to both very slow. Messages are delivered in a round robin fashion to both
consumers, the fast consumer processes all of its messages very consumers, the fast consumer processes all of its messages very
quickly until its buffer is empty. At this point there are still quickly until its buffer is empty. At this point there are still
messages awaiting to be processed in the buffer of the slow consumer messages awaiting to be processed in the buffer of the slow consumer
thus preventing them being processed by the fast consumer. The fast thus preventing them being processed by the fast consumer. The fast
consumer is therefore sitting idle when it could be processing the consumer is therefore sitting idle when it could be processing the
other messages. other messages.
To allow slow consumers, set the `consumer-window-size` to 0 (for no To allow slow consumers, set the `consumer-window-size` to 0 (for no
buffer at all). This will prevent the slow consumer from buffering buffer at all). This will prevent the slow consumer from buffering
any messages on the client side. Messages will remain on the server any messages on the client side. Messages will remain on the server
side ready to be consumed by other consumers. side ready to be consumed by other consumers.
Setting this to 0 can give deterministic distribution between Setting this to 0 can give deterministic distribution between
multiple consumers on a queue. multiple consumers on a queue.
Most of the consumers cannot be clearly identified as fast or slow Most of the consumers cannot be clearly identified as fast or slow
consumers but are in-between. In that case, setting the value of consumers but are in-between. In that case, setting the value of
@ -115,8 +112,7 @@ method.
Please see ? for an example which shows how to configure ActiveMQ to Please see ? for an example which shows how to configure ActiveMQ to
prevent consumer buffering when dealing with slow consumers. prevent consumer buffering when dealing with slow consumers.
Rate limited flow control ## Rate limited flow control
-------------------------
It is also possible to control the *rate* at which a consumer can It is also possible to control the *rate* at which a consumer can
consume messages. This is a form of throttling and can be used to make consume messages. This is a form of throttling and can be used to make
@ -162,14 +158,12 @@ can be set via the `ActiveMQConnectionFactory.setConsumerMaxRate(int
Please see ? for an example which shows how to configure ActiveMQ to Please see ? for an example which shows how to configure ActiveMQ to
prevent consumer buffering when dealing with slow consumers. prevent consumer buffering when dealing with slow consumers.
Producer flow control ## Producer flow control
=====================
ActiveMQ also can limit the amount of data sent from a client to a ActiveMQ also can limit the amount of data sent from a client to a
server to prevent the server being overwhelmed. server to prevent the server being overwhelmed.
Window based flow control ### Window based flow control
-------------------------
In a similar way to consumer window based flow control, ActiveMQ In a similar way to consumer window based flow control, ActiveMQ
producers, by default, can only send messages to an address as long as producers, by default, can only send messages to an address as long as
@ -186,12 +180,12 @@ The window size therefore determines the amount of bytes that can be
in-flight at any one time before more need to be requested - this in-flight at any one time before more need to be requested - this
prevents the remoting connection from getting overloaded. prevents the remoting connection from getting overloaded.
### Using Core API #### Using Core API
If the ActiveMQ core API is being used, window size can be set via the If the ActiveMQ core API is being used, window size can be set via the
`ServerLocator.setProducerWindowSize(int producerWindowSize)` method. `ServerLocator.setProducerWindowSize(int producerWindowSize)` method.
### Using JMS #### Using JMS
If JNDI is used to instantiate and look up the connection factory, the If JNDI is used to instantiate and look up the connection factory, the
producer window size can be configured in the JNDI context environment, producer window size can be configured in the JNDI context environment,
@ -208,7 +202,7 @@ size can be set via the
`ActiveMQConnectionFactory.setProducerWindowSize(int `ActiveMQConnectionFactory.setProducerWindowSize(int
producerWindowSize)` method. producerWindowSize)` method.
### Blocking producer window based flow control #### Blocking producer window based flow control
Normally the server will always give the same number of credits as have Normally the server will always give the same number of credits as have
been requested. However, it is also possible to set a maximum size on been requested. However, it is also possible to set a maximum size on
@ -234,7 +228,7 @@ but instead pages messages to storage.
To configure an address with a maximum size and tell the server that you To configure an address with a maximum size and tell the server that you
want to block producers for this address if it becomes full, you need to want to block producers for this address if it becomes full, you need to
define an AddressSettings (?) block for the address and specify define an AddressSettings ([Configuring Queues Via Address Settings](queue-attributes.md)) block for the address and specify
`max-size-bytes` and `address-full-policy` `max-size-bytes` and `address-full-policy`
The address block applies to all queues registered to that address. I.e. The address block applies to all queues registered to that address. I.e.
@ -267,8 +261,7 @@ control.
> want this behaviour increase the `max-size-bytes` parameter or change > want this behaviour increase the `max-size-bytes` parameter or change
> the address full message policy. > the address full message policy.
Rate limited flow control ### Rate limited flow control
-------------------------
ActiveMQ also allows the rate a producer can emit message to be limited, ActiveMQ also allows the rate a producer can emit message to be limited,
in units of messages per second. By specifying such a rate, ActiveMQ in units of messages per second. By specifying such a rate, ActiveMQ
@ -282,13 +275,13 @@ control. The default value is `-1`.
Please see the ? for a working example of limiting producer rate. Please see the ? for a working example of limiting producer rate.
### Using Core API #### Using Core API
If the ActiveMQ core API is being used the rate can be set via the If the ActiveMQ core API is being used the rate can be set via the
`ServerLocator.setProducerMaxRate(int producerMaxRate)` method or `ServerLocator.setProducerMaxRate(int producerMaxRate)` method or
alternatively via some of the `ClientSession.createProducer()` methods. alternatively via some of the `ClientSession.createProducer()` methods.
### Using JMS #### Using JMS
If JNDI is used to instantiate and look up the connection factory, the If JNDI is used to instantiate and look up the connection factory, the
max rate size can be configured in the JNDI context environment, e.g. max rate size can be configured in the JNDI context environment, e.g.

95
docs/user-manual/en/ha.md
View File

@ -1,5 +1,4 @@
High Availability and Failover # High Availability and Failover
==============================
We define high availability as the *ability for the system to continue We define high availability as the *ability for the system to continue
functioning after failure of one or more of the servers*. functioning after failure of one or more of the servers*.
@ -8,8 +7,7 @@ A part of high availability is *failover* which we define as the
*ability for client connections to migrate from one server to another in *ability for client connections to migrate from one server to another in
event of server failure so client applications can continue to operate*. event of server failure so client applications can continue to operate*.
Live - Backup Groups ## Live - Backup Groups
====================
ActiveMQ allows servers to be linked together as *live - backup* groups ActiveMQ allows servers to be linked together as *live - backup* groups
where each live server can have 1 or more backup servers. A backup where each live server can have 1 or more backup servers. A backup
@ -28,8 +26,7 @@ become live when the current live server goes down, if the current live
server is configured to allow automatic failback then it will detect the server is configured to allow automatic failback then it will detect the
live server coming back up and automatically stop. live server coming back up and automatically stop.
HA Policies ### HA Policies
-----------
ActiveMQ supports two different strategies for backing up a server ActiveMQ supports two different strategies for backing up a server
*shared store* and *replication*. Which is configured via the *shared store* and *replication*. Which is configured via the
@ -95,8 +92,7 @@ or
</ha-policy> </ha-policy>
Data Replication ### Data Replication
----------------
Support for network-based data replication was added in version 2.3. Support for network-based data replication was added in version 2.3.
@ -124,13 +120,13 @@ the connection speed.
Replication will create a copy of the data at the backup. One issue to Replication will create a copy of the data at the backup. One issue to
be aware of is: in case of a successful fail-over, the backup's data be aware of is: in case of a successful fail-over, the backup's data
will be newer than the one at the live's storage. If you configure your will be newer than the one at the live's storage. If you configure your
live server to perform a ? when restarted, it will synchronize its data live server to perform a failback to live server when restarted, it will synchronize its data
with the backup's. If both servers are shutdown, the administrator will with the backup's. If both servers are shutdown, the administrator will
have to determine which one has the latest data. have to determine which one has the latest data.
The replicating live and backup pair must be part of a cluster. The The replicating live and backup pair must be part of a cluster. The
Cluster Connection also defines how backup servers will find the remote Cluster Connection also defines how backup servers will find the remote
live servers to pair with. Refer to ? for details on how this is done, live servers to pair with. Refer to [Clusters](clusters.md) for details on how this is done,
and how to configure a cluster connection. Notice that: and how to configure a cluster connection. Notice that:
- Both live and backup servers must be part of the same cluster. - Both live and backup servers must be part of the same cluster.
@ -202,7 +198,7 @@ than half the servers, it will become active, if more than half the
servers also disappeared with the live, the backup will wait and try servers also disappeared with the live, the backup will wait and try
reconnecting with the live. This avoids a split brain situation. reconnecting with the live. This avoids a split brain situation.
### Configuration #### Configuration
To configure the live and backup servers to be a replicating pair, To configure the live and backup servers to be a replicating pair,
configure the live server in ' `activemq-configuration.xml` to have: configure the live server in ' `activemq-configuration.xml` to have:
@ -228,7 +224,7 @@ The backup server must be similarly configured but as a `slave`
</replication> </replication>
</ha-policy> </ha-policy>
### All Replication Configuration #### All Replication Configuration
The following table lists all the `ha-policy` configuration elements for The following table lists all the `ha-policy` configuration elements for
HA strategy Replication for `master`: HA strategy Replication for `master`:
@ -250,8 +246,7 @@ HA strategy Replication for `slave`:
`allow-failback` Whether a server will automatically stop when a another places a request to take over its place. The use case is when the backup has failed over `allow-failback` Whether a server will automatically stop when a another places a request to take over its place. The use case is when the backup has failed over
`failback-delay` delay to wait before fail-back occurs on (failed over live's) restart `failback-delay` delay to wait before fail-back occurs on (failed over live's) restart
Shared Store ### Shared Store
------------
When using a shared store, both live and backup servers share the *same* When using a shared store, both live and backup servers share the *same*
entire data directory using a shared file system. This means the paging entire data directory using a shared file system. This means the paging
@ -284,7 +279,7 @@ on amount of data).
![ActiveMQ ha-shared-store.png](images/ha-shared-store.png) ![ActiveMQ ha-shared-store.png](images/ha-shared-store.png)
### Configuration #### Configuration
To configure the live and backup servers to share their store, configure To configure the live and backup servers to share their store, configure
id via the `ha-policy` configuration in `activemq-configuration.xml`: id via the `ha-policy` configuration in `activemq-configuration.xml`:
@ -313,7 +308,7 @@ The backup server must also be configured as a backup.
In order for live - backup groups to operate properly with a shared In order for live - backup groups to operate properly with a shared
store, both servers must have configured the location of journal store, both servers must have configured the location of journal
directory to point to the *same shared location* (as explained in ?) directory to point to the *same shared location* (as explained in [Configuring the message journal](persistence.md))
> **Note** > **Note**
> >
@ -322,11 +317,10 @@ directory to point to the *same shared location* (as explained in ?)
Also each node, live and backups, will need to have a cluster connection Also each node, live and backups, will need to have a cluster connection
defined even if not part of a cluster. The Cluster Connection info defined even if not part of a cluster. The Cluster Connection info
defines how backup servers announce there presence to its live server or defines how backup servers announce there presence to its live server or
any other nodes in the cluster. Refer to ? for details on how this is any other nodes in the cluster. Refer to [Clusters](clusters.md) for details on how this is
done. done.
Failing Back to live Server ### Failing Back to live Server
---------------------------
After a live server has failed and a backup taken has taken over its After a live server has failed and a backup taken has taken over its
duties, you may want to restart the live server and have clients fail duties, you may want to restart the live server and have clients fail
@ -396,7 +390,7 @@ or `slave` like so:
By default this is set to false, if by some chance you have set this to By default this is set to false, if by some chance you have set this to
false but still want to stop the server normally and cause failover then false but still want to stop the server normally and cause failover then
you can do this by using the management API as explained at ? you can do this by using the management API as explained at [Management](management.md)
You can also force the running live server to shutdown when the old live 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 server comes back up allowing the original live server to take over
@ -411,7 +405,7 @@ automatically by setting the following property in the
</shared-store> </shared-store>
</ha-policy> </ha-policy>
### All Shared Store Configuration #### All Shared Store Configuration
The following table lists all the `ha-policy` configuration elements for The following table lists all the `ha-policy` configuration elements for
HA strategy shared store for `master`: HA strategy shared store for `master`:
@ -419,19 +413,18 @@ HA strategy shared store for `master`:
name Description name Description
------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------------------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`failback-delay` If a backup server is detected as being live, via the lock file, then the live server will wait announce itself as a backup and wait this amount of time (in ms) before starting as a live `failback-delay` If a backup server is detected as being live, via the lock file, then the live server will wait announce itself as a backup and wait this amount of time (in ms) before starting as a live
`failover-on-server-shutdown` If set to true then when this server is stopped normally the backup will become live assuming failover. If false then the backup server will remain passive. Note that if false you want failover to occur the you can use the the management API as explained at ? `failover-on-server-shutdown` If set to true then when this server is stopped normally the backup will become live assuming failover. If false then the backup server will remain passive. Note that if false you want failover to occur the you can use the the management API as explained at [Management](management.md)
The following table lists all the `ha-policy` configuration elements for The following table lists all the `ha-policy` configuration elements for
HA strategy Shared Store for `slave`: HA strategy Shared Store for `slave`:
name Description name Description
------------------------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------------------------- ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`failover-on-server-shutdown` In the case of a backup that has become live. then when set to true then when this server is stopped normally the backup will become liveassuming failover. If false then the backup server will remain passive. Note that if false you want failover to occur the you can use the the management API as explained at ? `failover-on-server-shutdown` In the case of a backup that has become live. then when set to true then when this server is stopped normally the backup will become liveassuming failover. If false then the backup server will remain passive. Note that if false you want failover to occur the you can use the the management API as explained at [Management](management.md)
`allow-failback` Whether a server will automatically stop when a another places a request to take over its place. The use case is when the backup has failed over. `allow-failback` Whether a server will automatically stop when a another places a request to take over its place. The use case is when the backup has failed over.
`failback-delay` After failover and the slave has become live, this is set on the new live server. When starting If a backup server is detected as being live, via the lock file, then the live server will wait announce itself as a backup and wait this amount of time (in ms) before starting as a live, however this is unlikely since this backup has just stopped anyway. It is also used as the delay after failback before this backup will restart (if `allow-failback` is set to true. `failback-delay` After failover and the slave has become live, this is set on the new live server. When starting If a backup server is detected as being live, via the lock file, then the live server will wait announce itself as a backup and wait this amount of time (in ms) before starting as a live, however this is unlikely since this backup has just stopped anyway. It is also used as the delay after failback before this backup will restart (if `allow-failback` is set to true.
Colocated Backup Servers #### Colocated Backup Servers
------------------------
It is also possible when running standalone to colocate backup servers It is also possible when running standalone to colocate backup servers
in the same JVM as another live server. Live Servers can be configured in the same JVM as another live server. Live Servers can be configured
@ -467,7 +460,7 @@ replication as in the previous chapter. `shared-store` is also supported
![ActiveMQ ha-colocated.png](images/ha-colocated.png) ![ActiveMQ ha-colocated.png](images/ha-colocated.png)
### Configuring Connectors and Acceptors #### Configuring Connectors and Acceptors
If the HA Policy is colocated then connectors and acceptors will be If the HA Policy is colocated then connectors and acceptors will be
inherited from the live server creating it and offset depending on the inherited from the live server creating it and offset depending on the
@ -499,7 +492,7 @@ adding them to the `ha-policy` configuration like so:
</ha-policy> </ha-policy>
### Configuring Directories #### Configuring Directories
Directories for the Journal, Large messages and Paging will be set Directories for the Journal, Large messages and Paging will be set
according to what the HA strategy is. If shared store the the requesting according to what the HA strategy is. If shared store the the requesting
@ -517,8 +510,7 @@ The following table lists all the `ha-policy` configuration elements:
`max-backups` Whether or not this live server will accept backup requests from other live servers. `max-backups` Whether or not this live server will accept backup requests from other live servers.
`backup-port-offset` The offset to use for the Connectors and Acceptors when creating a new backup server. `backup-port-offset` The offset to use for the Connectors and Acceptors when creating a new backup server.
Scaling Down ### Scaling Down
============
An alternative to using Live/Backup groups is to configure scaledown. An alternative to using Live/Backup groups is to configure scaledown.
when configured for scale down a server can copy all its messages and when configured for scale down a server can copy all its messages and
@ -568,8 +560,7 @@ this would look like:
</ha-policy> </ha-policy>
Scale Down with groups #### Scale Down with groups
----------------------
It is also possible to configure servers to only scale down to servers It is also possible to configure servers to only scale down to servers
that belong in the same group. This is done by configuring the group that belong in the same group. This is done by configuring the group
@ -588,8 +579,7 @@ like so:
In this scenario only servers that belong to the group `my-group` will In this scenario only servers that belong to the group `my-group` will
be scaled down to be scaled down to
Scale Down and Backups #### Scale Down and Backups
----------------------
It is also possible to mix scale down with HA via backup servers. If a It is also possible to mix scale down with HA via backup servers. If a
slave is configured to scale down then after failover has occurred, slave is configured to scale down then after failover has occurred,
@ -630,8 +620,7 @@ typical configuration would look like:
</ha-policy> </ha-policy>
Scale Down and Clients #### Scale Down and Clients
----------------------
When a server is stopping and preparing to scale down it will send a When a server is stopping and preparing to scale down it will send a
message to all its clients informing them which server it is scaling message to all its clients informing them which server it is scaling
@ -642,8 +631,7 @@ transactions are there for the client when it reconnects. The normal
reconnect settings apply when the client is reconnecting so these should reconnect settings apply when the client is reconnecting so these should
be high enough to deal with the time needed to scale down. be high enough to deal with the time needed to scale down.
Failover Modes ## Failover Modes
==============
ActiveMQ defines two types of client failover: ActiveMQ defines two types of client failover:
@ -654,15 +642,14 @@ ActiveMQ defines two types of client failover:
ActiveMQ also provides 100% transparent automatic reattachment of ActiveMQ also provides 100% transparent automatic reattachment of
connections to the same server (e.g. in case of transient network connections to the same server (e.g. in case of transient network
problems). This is similar to failover, except it is reconnecting to the problems). This is similar to failover, except it is reconnecting to the
same server and is discussed in ? same server and is discussed in [Client Reconnection and Session Reattachment](client-reconnection.md)
During failover, if the client has consumers on any non persistent or During failover, if the client has consumers on any non persistent or
temporary queues, those queues will be automatically recreated during temporary queues, those queues will be automatically recreated during
failover on the backup node, since the backup node will not have any failover on the backup node, since the backup node will not have any
knowledge of non persistent queues. knowledge of non persistent queues.
Automatic Client Failover ### Automatic Client Failover
-------------------------
ActiveMQ clients can be configured to receive knowledge of all live and ActiveMQ clients can be configured to receive knowledge of all live and
backup servers, so that in event of connection failure at the client - backup servers, so that in event of connection failure at the client -
@ -673,7 +660,7 @@ thus saving the user from having to hand-code manual reconnection logic.
ActiveMQ clients detect connection failure when it has not received ActiveMQ clients detect connection failure when it has not received
packets from the server within the time given by packets from the server within the time given by
`client-failure-check-period` as explained in section ?. If the client `client-failure-check-period` as explained in section [Detecting Dead Connections](connection-ttl.md). If the client
does not receive data in good time, it will assume the connection has does not receive data in good time, it will assume the connection has
failed and attempt failover. Also if the socket is closed by the OS, failed and attempt failover. Also if the socket is closed by the OS,
usually if the server process is killed rather than the machine itself usually if the server process is killed rather than the machine itself
@ -683,12 +670,12 @@ ActiveMQ clients can be configured to discover the list of live-backup
server groups in a number of different ways. They can be configured server groups in a number of different ways. They can be configured
explicitly or probably the most common way of doing this is to use explicitly or probably the most common way of doing this is to use
*server discovery* for the client to automatically discover the list. *server discovery* for the client to automatically discover the list.
For full details on how to configure server discovery, please see ?. For full details on how to configure server discovery, please see [Clusters](clusters.md).
Alternatively, the clients can explicitly connect to a specific server Alternatively, the clients can explicitly connect to a specific server
and download the current servers and backups see ?. and download the current servers and backups see [Clusters](clusters.md).
To enable automatic client failover, the client must be configured to To enable automatic client failover, the client must be configured to
allow non-zero reconnection attempts (as explained in ?). allow non-zero reconnection attempts (as explained in [Client Reconnection and Session Reattachment](client-reconnection.md)).
By default failover will only occur after at least one connection has By default failover will only occur after at least one connection has
been made to the live server. In other words, by default, failover will been made to the live server. In other words, by default, failover will
@ -697,7 +684,7 @@ server - in this case it will simply retry connecting to the live server
according to the reconnect-attempts property and fail after this number according to the reconnect-attempts property and fail after this number
of attempts. of attempts.
### Failing over on the Initial Connection #### Failing over on the Initial Connection
Since the client does not learn about the full topology until after the Since the client does not learn about the full topology until after the
first connection is made there is a window where it does not know about first connection is made there is a window where it does not know about
@ -712,7 +699,7 @@ will be thrown.
For examples of automatic failover with transacted and non-transacted For examples of automatic failover with transacted and non-transacted
JMS sessions, please see ? and ?. JMS sessions, please see ? and ?.
### A Note on Server Replication #### A Note on Server Replication
ActiveMQ does not replicate full server state between live and backup ActiveMQ does not replicate full server state between live and backup
servers. When the new session is automatically recreated on the backup servers. When the new session is automatically recreated on the backup
@ -747,7 +734,7 @@ and only once* delivery, even in the case of failure, by using a
combination of duplicate detection and retrying of transactions. However combination of duplicate detection and retrying of transactions. However
this is not 100% transparent to the client code. this is not 100% transparent to the client code.
### Handling Blocking Calls During Failover #### Handling Blocking Calls During Failover
If the client code is in a blocking call to the server, waiting for a If the client code is in a blocking call to the server, waiting for a
response to continue its execution, when failover occurs, the new response to continue its execution, when failover occurs, the new
@ -767,7 +754,7 @@ throw a `javax.jms.TransactionRolledBackException` (if using JMS), or a
`ActiveMQException` with error code `ActiveMQException` with error code
`ActiveMQException.TRANSACTION_ROLLED_BACK` if using the core API. `ActiveMQException.TRANSACTION_ROLLED_BACK` if using the core API.
### Handling Failover With Transactions #### Handling Failover With Transactions
If the session is transactional and messages have already been sent or If the session is transactional and messages have already been sent or
acknowledged in the current transaction, then the server cannot be sure acknowledged in the current transaction, then the server cannot be sure
@ -816,7 +803,7 @@ live server before failure occurred.
> it does not exist then it is assumed to have been committed although > it does not exist then it is assumed to have been committed although
> the transaction manager may log a warning. > the transaction manager may log a warning.
To remedy this, the client can simply enable duplicate detection (?) in To remedy this, the client can simply enable duplicate detection ([Duplicate Message Detection](duplicate-detection.md)) in
the transaction, and retry the transaction operations again after the the transaction, and retry the transaction operations again after the
call is unblocked. If the transaction had indeed been committed on the call is unblocked. If the transaction had indeed been committed on the
live server successfully before failover, then when the transaction is live server successfully before failover, then when the transaction is
@ -831,17 +818,16 @@ getting sent more than once.
> guarantees for messages can be provided in the case of failure, > guarantees for messages can be provided in the case of failure,
> guaranteeing 100% no loss or duplication of messages. > guaranteeing 100% no loss or duplication of messages.
### Handling Failover With Non Transactional Sessions #### Handling Failover With Non Transactional Sessions
If the session is non transactional, messages or acknowledgements can be If the session is non transactional, messages or acknowledgements can be
lost in the event of failover. lost in the event of failover.
If you wish to provide *once and only once* delivery guarantees for non If you wish to provide *once and only once* delivery guarantees for non
transacted sessions too, enabled duplicate detection, and catch unblock transacted sessions too, enabled duplicate detection, and catch unblock
exceptions as described in ? exceptions as described in [Handling Blocking Calls During Failover](ha.md)
Getting Notified of Connection Failure ### Getting Notified of Connection Failure
--------------------------------------
JMS provides a standard mechanism for getting notified asynchronously of JMS provides a standard mechanism for getting notified asynchronously of
connection failure: `java.jms.ExceptionListener`. Please consult the JMS connection failure: `java.jms.ExceptionListener`. Please consult the JMS
@ -867,8 +853,7 @@ following:
: JMSException error codes : JMSException error codes
Application-Level Failover ### Application-Level Failover
--------------------------
In some cases you may not want automatic client failover, and prefer to In some cases you may not want automatic client failover, and prefer to
handle any connection failure yourself, and code your own manually handle any connection failure yourself, and code your own manually

27
docs/user-manual/en/intercepting-operations.md
View File

@ -1,5 +1,4 @@
Intercepting Operations # Intercepting Operations
=======================
ActiveMQ supports *interceptors* to intercept packets entering and ActiveMQ supports *interceptors* to intercept packets entering and
exiting the server. Incoming and outgoing interceptors are be called for exiting the server. Incoming and outgoing interceptors are be called for
@ -8,17 +7,18 @@ custom code to be executed, e.g. for auditing packets, filtering or
other reasons. Interceptors can change the packets they intercept. This other reasons. Interceptors can change the packets they intercept. This
makes interceptors powerful, but also potentially dangerous. makes interceptors powerful, but also potentially dangerous.
Implementing The Interceptors ## Implementing The Interceptors
=============================
An interceptor must implement the `Interceptor interface`: An interceptor must implement the `Interceptor interface`:
package org.apache.activemq.api.core.interceptor; ``` java
package org.apache.activemq.api.core.interceptor;
public interface Interceptor public interface Interceptor
{ {
boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException; boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException;
} }
```
The returned boolean value is important: The returned boolean value is important:
@ -28,8 +28,7 @@ The returned boolean value is important:
interceptors will be called and the packet will not be processed interceptors will be called and the packet will not be processed
further by the server. further by the server.
Configuring The Interceptors ## Configuring The Interceptors
============================
Both incoming and outgoing interceptors are configured in Both incoming and outgoing interceptors are configured in
`activemq-configuration.xml`: `activemq-configuration.xml`:
@ -47,8 +46,7 @@ Both incoming and outgoing interceptors are configured in
The interceptors classes (and their dependencies) must be added to the The interceptors classes (and their dependencies) must be added to the
server classpath to be properly instantiated and called. server classpath to be properly instantiated and called.
Interceptors on the Client Side ## Interceptors on the Client Side
===============================
The interceptors can also be run on the client side to intercept packets The interceptors can also be run on the client side to intercept packets
either sent by the client to the server or by the server to the client. either sent by the client to the server or by the server to the client.
@ -77,8 +75,7 @@ As on the server, the client interceptor classes (and their
dependencies) must be added to the classpath to be properly instantiated dependencies) must be added to the classpath to be properly instantiated
and invoked. and invoked.
Example ## Example
=======
See ? for an example which shows how to use interceptors to add See ? for an example which shows how to use interceptors to add
properties to a message on the server. properties to a message on the server.

58
docs/user-manual/en/interoperability.md
View File

@ -1,8 +1,6 @@
Interoperability # Interoperability
================
Stomp ## Stomp
=====
[Stomp](http://stomp.github.com/) is a text-orientated wire protocol [Stomp](http://stomp.github.com/) is a text-orientated wire protocol
that allows Stomp clients to communicate with Stomp Brokers. ActiveMQ that allows Stomp clients to communicate with Stomp Brokers. ActiveMQ
@ -11,8 +9,7 @@ now supports Stomp 1.0, 1.1 and 1.2.
Stomp clients are available for several languages and platforms making Stomp clients are available for several languages and platforms making
it a good choice for interoperability. it a good choice for interoperability.
Native Stomp support ## Native Stomp support
--------------------
ActiveMQ provides native support for Stomp. To be able to send and ActiveMQ provides native support for Stomp. To be able to send and
receive Stomp messages, you must configure a `NettyAcceptor` with a receive Stomp messages, you must configure a `NettyAcceptor` with a
@ -52,8 +49,7 @@ heartbeat values lower than 500, the server will defaults the value to
500 milliseconds regardless the values of the 'heart-beat' header in the 500 milliseconds regardless the values of the 'heart-beat' header in the
frame. frame.
Mapping Stomp destinations to ActiveMQ addresses and queues ### Mapping Stomp destinations to ActiveMQ addresses and queues
-----------------------------------------------------------
Stomp clients deals with *destinations* when sending messages and Stomp clients deals with *destinations* when sending messages and
subscribing. Destination names are simply strings which are mapped to subscribing. Destination names are simply strings which are mapped to
@ -66,8 +62,7 @@ specified destination is mapped to an address. When a Stomp client
subscribes (or unsubscribes) for a destination (using a `SUBSCRIBE` or subscribes (or unsubscribes) for a destination (using a `SUBSCRIBE` or
`UNSUBSCRIBE` frame), the destination is mapped to a ActiveMQ queue. `UNSUBSCRIBE` frame), the destination is mapped to a ActiveMQ queue.
STOMP and connection-ttl ### STOMP and connection-ttl
------------------------
Well behaved STOMP clients will always send a DISCONNECT frame before Well behaved STOMP clients will always send a DISCONNECT frame before
closing their connections. In this case the server will clear up any closing their connections. In this case the server will clear up any
@ -105,12 +100,12 @@ seconds.
> users can use heart-beats to maintain the life cycle of stomp > users can use heart-beats to maintain the life cycle of stomp
> connections. > connections.
Stomp and JMS interoperability ### Stomp and JMS interoperability
------------------------------
### Using JMS destinations #### Using JMS destinations
As explained in ?, JMS destinations are also mapped to ActiveMQ As explained in [Mapping JMS Concepts to the Core API](jms-core-mapping.md),
JMS destinations are also mapped to ActiveMQ
addresses and queues. If you want to use Stomp to send messages to JMS addresses and queues. If you want to use Stomp to send messages to JMS
destinations, the Stomp destinations must follow the same convention: destinations, the Stomp destinations must follow the same convention:
@ -137,7 +132,7 @@ destinations, the Stomp destinations must follow the same convention:
^@ ^@
### Sending and consuming Stomp message from JMS or ActiveMQ Core API #### Sending and consuming Stomp message from JMS or ActiveMQ Core API
Stomp is mainly a text-orientated protocol. To make it simpler to Stomp is mainly a text-orientated protocol. To make it simpler to
interoperate with JMS and ActiveMQ Core API, our Stomp implementation interoperate with JMS and ActiveMQ Core API, our Stomp implementation
@ -156,7 +151,7 @@ The same logic applies when mapping a JMS message or a Core message to
Stomp. A Stomp client can check the presence of the `content-length` Stomp. A Stomp client can check the presence of the `content-length`
header to determine the type of the message body (String or bytes). header to determine the type of the message body (String or bytes).
### Message IDs for Stomp messages #### Message IDs for Stomp messages
When receiving Stomp messages via a JMS consumer or a QueueBrowser, the When receiving Stomp messages via a JMS consumer or a QueueBrowser, the
messages have no properties like JMSMessageID by default. However this messages have no properties like JMSMessageID by default. However this
@ -183,7 +178,7 @@ long type internal message id prefixed with "`STOMP`", like:
If `stomp-enable-message-id` is not specified in the configuration, If `stomp-enable-message-id` is not specified in the configuration,
default is `false`. default is `false`.
### Handling of Large Messages with Stomp #### Handling of Large Messages with Stomp
Stomp clients may send very large bodys of frames which can exceed the Stomp clients may send very large bodys of frames which can exceed the
size of ActiveMQ server's internal buffer, causing unexpected errors. To size of ActiveMQ server's internal buffer, causing unexpected errors. To
@ -212,8 +207,7 @@ sending it to stomp clients. The default value of
`stomp-min-large-message-size` is the same as the default value of `stomp-min-large-message-size` is the same as the default value of
[min-large-message-size](#large-messages.core.config). [min-large-message-size](#large-messages.core.config).
Stomp Over Web Sockets ### Stomp Over Web Sockets
----------------------
ActiveMQ also support Stomp over [Web ActiveMQ also support Stomp over [Web
Sockets](http://dev.w3.org/html5/websockets/). Modern web browser which Sockets](http://dev.w3.org/html5/websockets/). Modern web browser which
@ -242,8 +236,7 @@ The `stomp-websockets` example shows how to configure ActiveMQ server to
have web browsers and Java applications exchanges messages on a JMS have web browsers and Java applications exchanges messages on a JMS
topic. topic.
StompConnect ### StompConnect
------------
[StompConnect](http://stomp.codehaus.org/StompConnect) is a server that [StompConnect](http://stomp.codehaus.org/StompConnect) is a server that
can act as a Stomp broker and proxy the Stomp protocol to the standard can act as a Stomp broker and proxy the Stomp protocol to the standard
@ -265,13 +258,11 @@ documentation.
Make sure this file is in the classpath along with the StompConnect jar Make sure this file is in the classpath along with the StompConnect jar
and the ActiveMQ jars and simply run `java org.codehaus.stomp.jms.Main`. and the ActiveMQ jars and simply run `java org.codehaus.stomp.jms.Main`.
REST ## REST
====
Please see ? Please see [Rest Interface](rest.md)
AMQP ## AMQP
====
ActiveMQ supports the [AMQP ActiveMQ supports the [AMQP
1.0](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp) 1.0](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp)
@ -291,15 +282,13 @@ default AMQP port.
There are 2 Stomp examples available see proton-j and proton-ruby which There are 2 Stomp examples available see proton-j and proton-ruby which
use the qpid Java and Ruby clients respectively use the qpid Java and Ruby clients respectively
AMQP and security ### AMQP and security
-----------------
The ActiveMQ Server accepts AMQP SASL Authentication and will use this The ActiveMQ Server accepts AMQP SASL Authentication and will use this
to map onto the underlying session created for the connection so you can to map onto the underlying session created for the connection so you can
use the normal ActiveMQ security configuration. use the normal ActiveMQ security configuration.
AMQP Links ### AMQP Links
----------
An AMQP Link is a uni directional transport for messages between a An AMQP Link is a uni directional transport for messages between a
source and a target, i.e. a client and the ActiveMQ Broker. A link will source and a target, i.e. a client and the ActiveMQ Broker. A link will
@ -309,8 +298,7 @@ Message and forwarded to its destination or target. A Receiver will map
onto a ActiveMQ Server Consumer and convert ActiveMQ messages back into onto a ActiveMQ Server Consumer and convert ActiveMQ messages back into
AMQP messages before being delivered. AMQP messages before being delivered.
AMQP and destinations ### AMQP and destinations
---------------------
If an AMQP Link is dynamic then a temporary queue will be created and If an AMQP Link is dynamic then a temporary queue will be created and
either the remote source or remote target address will be set to the either the remote source or remote target address will be set to the
@ -323,8 +311,7 @@ does not exist then an exception will be sent
> For the next version we will add a flag to aut create durable queue > For the next version we will add a flag to aut create durable queue
> but for now you will have to add them via the configuration > but for now you will have to add them via the configuration
AMQP and Coordinations - Handling Transactions ### AMQP and Coordinations - Handling Transactions
----------------------------------------------
An AMQP links target can also be a Coordinator, the Coordinator is used An AMQP links target can also be a Coordinator, the Coordinator is used
to handle transactions. If a coordinator is used the the underlying to handle transactions. If a coordinator is used the the underlying
@ -337,8 +324,7 @@ or committed via the coordinator.
> `amqp:multi-txns-per-ssn`, however in this version ActiveMQ will only > `amqp:multi-txns-per-ssn`, however in this version ActiveMQ will only
> support single transactions per session > support single transactions per session
OpenWire ## OpenWire
========
ActiveMQ now supports the ActiveMQ now supports the
[OpenWire](http://activemq.apache.org/openwire.html) protocol so that an [OpenWire](http://activemq.apache.org/openwire.html) protocol so that an

34
docs/user-manual/en/jms-bridge.md
View File

@ -1,5 +1,4 @@
The JMS Bridge # The JMS Bridge
==============
ActiveMQ includes a fully functional JMS message bridge. ActiveMQ includes a fully functional JMS message bridge.
@ -23,7 +22,7 @@ JMS servers, as long as they are JMS 1.1 compliant.
> >
> Do not confuse a JMS bridge with a core bridge. A JMS bridge can be > 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 providers and uses the > used to bridge any two JMS 1.1 compliant JMS providers and uses the
> JMS API. A core bridge (described in ?) is used to bridge any two > JMS API. A core bridge (described in [Core Bidges](core-bridges.md)) is used to bridge any two
> ActiveMQ instances and uses the core API. Always use a core bridge if > ActiveMQ instances and uses the core API. Always use a core bridge if
> you can in preference to a JMS bridge. The core bridge will typically > you can in preference to a JMS bridge. The core bridge will typically
> provide better performance than a JMS bridge. Also the core bridge can > provide better performance than a JMS bridge. Also the core bridge can
@ -183,8 +182,7 @@ server.
</bean> </bean>
</deployment> </deployment>
JMS Bridge Parameters ## JMS Bridge Parameters
=====================
The main bean deployed is the `JMSBridge` bean. The bean is configurable The main bean deployed is the `JMSBridge` bean. The bean is configurable
by the parameters passed to its constructor. by the parameters passed to its constructor.
@ -268,7 +266,7 @@ by the parameters passed to its constructor.
- `ONCE_AND_ONLY_ONCE` - `ONCE_AND_ONLY_ONCE`
See ? for a explanation of these modes. See Quality Of Service section for a explanation of these modes.
- Max Batch Size - Max Batch Size
@ -333,8 +331,7 @@ look something like this:
<bean name="RealTransactionManager" class="com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple"/> <bean name="RealTransactionManager" class="com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple"/>
Source and Target Connection Factories ## Source and Target Connection Factories
======================================
The source and target connection factory factories are used to create The source and target connection factory factories are used to create
the connection factory used to create the connection for the source or the connection factory used to create the connection for the source or
@ -346,8 +343,7 @@ Application Servers or JMS providers a new implementation may have to be
provided. This can easily be done by implementing the interface provided. This can easily be done by implementing the interface
`org.apache.activemq.jms.bridge.ConnectionFactoryFactory`. `org.apache.activemq.jms.bridge.ConnectionFactoryFactory`.
Source and Target Destination Factories ## Source and Target Destination Factories
=======================================
Again, similarly, these are used to create or lookup up the Again, similarly, these are used to create or lookup up the
destinations. destinations.
@ -358,14 +354,12 @@ ActiveMQ that looks up the destination using JNDI.
A new implementation can be provided by implementing A new implementation can be provided by implementing
`org.apache.activemq.jms.bridge.DestinationFactory` interface. `org.apache.activemq.jms.bridge.DestinationFactory` interface.
Quality Of Service ## Quality Of Service
==================
The quality of service modes used by the bridge are described here in The quality of service modes used by the bridge are described here in
more detail. more detail.
AT\_MOST\_ONCE ### AT_MOST_ONCE
--------------
With this QoS mode messages will reach the destination from the source With this QoS mode messages will reach the destination from the source
at most once. The messages are consumed from the source and acknowledged at most once. The messages are consumed from the source and acknowledged
@ -376,8 +370,7 @@ occur at most once.
This mode is available for both durable and non-durable messages. This mode is available for both durable and non-durable messages.
DUPLICATES\_OK ### DUPLICATES_OK
--------------
With this QoS mode, the messages are consumed from the source and then With this QoS mode, the messages are consumed from the source and then
acknowledged after they have been successfully sent to the destination. acknowledged after they have been successfully sent to the destination.
@ -388,8 +381,7 @@ after a failure.
This mode is available for both durable and non-durable messages. This mode is available for both durable and non-durable messages.
ONCE\_AND\_ONLY\_ONCE ### ONCE_AND_ONLY_ONCE
---------------------
This QoS mode ensures messages will reach the destination from the This QoS mode ensures messages will reach the destination from the
source once and only once. (Sometimes this mode is known as "exactly source once and only once. (Sometimes this mode is known as "exactly
@ -420,8 +412,7 @@ This mode is only available for durable messages.
> this approach is not as watertight as using ONCE\_AND\_ONLY\_ONCE but > this approach is not as watertight as using ONCE\_AND\_ONLY\_ONCE but
> may be a good choice depending on your specific application. > may be a good choice depending on your specific application.
Time outs and the JMS bridge ### Time outs and the JMS bridge
----------------------------
There is a possibility that the target or source server will not be There is a possibility that the target or source server will not be
available at some point in time. If this occurs then the bridge will try available at some point in time. If this occurs then the bridge will try
@ -449,8 +440,7 @@ connection and the second the read timeout for the socket.
If you implement your own factories for looking up JMS resources then If you implement your own factories for looking up JMS resources then
you will have to bear in mind timeout issues. you will have to bear in mind timeout issues.
Examples ### Examples
--------
Please see ? which shows how to configure and use a JMS Bridge with Please see ? which shows how to configure and use a JMS Bridge with
JBoss AS to send messages to the source destination and consume them JBoss AS to send messages to the source destination and consume them

3
docs/user-manual/en/jms-core-mapping.md
View File

@ -1,5 +1,4 @@
Mapping JMS Concepts to the Core API # Mapping JMS Concepts to the Core API
====================================
This chapter describes how JMS destinations are mapped to ActiveMQ This chapter describes how JMS destinations are mapped to ActiveMQ
addresses. addresses.

154
docs/user-manual/en/large-messages.md
View File

@ -1,5 +1,4 @@
Large Messages # Large Messages
==============
ActiveMQ supports sending and receiving of huge messages, even when the ActiveMQ supports sending and receiving of huge messages, even when the
client and server are running with limited memory. The only realistic client and server are running with limited memory. The only realistic
@ -23,8 +22,7 @@ stream the huge message body to a file on disk or elsewhere. At no time
is the entire message body stored fully in memory, either on the client is the entire message body stored fully in memory, either on the client
or the server. or the server.
Configuring the server ## Configuring the server
======================
Large messages are stored on a disk directory on the server side, as Large messages are stored on a disk directory on the server side, as
configured on the main configuration file. configured on the main configuration file.
@ -46,8 +44,7 @@ For the best performance we recommend large messages directory is stored
on a different physical volume to the message journal or paging on a different physical volume to the message journal or paging
directory. directory.
Configuring Parameters ## Configuring Parameters
======================
Any message larger than a certain size is considered a large message. Any message larger than a certain size is considered a large message.
Large messages will be split up and sent in fragments. This is Large messages will be split up and sent in fragments. This is
@ -64,23 +61,23 @@ determined by the parameter `min-large-message-size`
The default value is 100KiB. The default value is 100KiB.
Using Core API ### Using Core API
--------------
If the ActiveMQ Core API is used, the minimal large message size is If the ActiveMQ Core API is used, the minimal large message size is
specified by `ServerLocator.setMinLargeMessageSize`. specified by `ServerLocator.setMinLargeMessageSize`.
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(NettyConnectorFactory.class.getName())) ``` java
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(NettyConnectorFactory.class.getName()))
locator.setMinLargeMessageSize(25 * 1024); locator.setMinLargeMessageSize(25 * 1024);
ClientSessionFactory factory = ActiveMQClient.createClientSessionFactory(); ClientSessionFactory factory = ActiveMQClient.createClientSessionFactory();
```
? will provide more information on how to instantiate the session [Configuring the transport directly from the client side](configuring-transports.md) will provide more information on how to instantiate the session
factory. factory.
Using JMS ### Using JMS
---------
If JNDI is used to instantiate and look up the connection factory, the If JNDI is used to instantiate and look up the connection factory, the
minimum large message size is configured in the JNDI context minimum large message size is configured in the JNDI context
@ -97,13 +94,12 @@ If the connection factory is being instantiated directly, the minimum
large message size is specified by large message size is specified by
`ActiveMQConnectionFactory.setMinLargeMessageSize`. `ActiveMQConnectionFactory.setMinLargeMessageSize`.
Compressed Large Messages ### Compressed Large Messages
-------------------------
You can choose to send large messages in compressed form using ` You can choose to send large messages in compressed form using `
compress-large-messages` attributes. compress-large-messages` attributes.
### `compress-large-messages` #### `compress-large-messages`
If you specify the boolean property `compress-large-messages` on the If you specify the boolean property `compress-large-messages` on the
`server locator` or `ConnectionFactory` as true, The system will use the `server locator` or `ConnectionFactory` as true, The system will use the
@ -129,8 +125,7 @@ by default:
java.naming.provider.url=tcp://localhost:5445 java.naming.provider.url=tcp://localhost:5445
connection.ConnectionFactory.compressLargeMessages=true connection.ConnectionFactory.compressLargeMessages=true
Streaming large messages ## Streaming large messages
========================
ActiveMQ supports setting the body of messages using input and output ActiveMQ supports setting the body of messages using input and output
streams (`java.lang.io`) streams (`java.lang.io`)
@ -151,8 +146,7 @@ Blobs, `SocketInputStream`, things you recovered from `HTTPRequests`
etc. Anything as long as it implements `java.io.InputStream` for sending etc. Anything as long as it implements `java.io.InputStream` for sending
messages or `java.io.OutputStream` for receiving them. messages or `java.io.OutputStream` for receiving them.
Streaming over Core API ### Streaming over Core API
-----------------------
The following table shows a list of methods available at `ClientMessage` The following table shows a list of methods available at `ClientMessage`
which are also available through JMS by the use of object properties. which are also available through JMS by the use of object properties.
@ -167,78 +161,82 @@ which are also available through JMS by the use of object properties.
To set the output stream when receiving a core message: To set the output stream when receiving a core message:
... ``` java
ClientMessage msg = consumer.receive(...); ClientMessage msg = consumer.receive(...);
// This will block here until the stream was transferred // This will block here until the stream was transferred
msg.saveOutputStream(someOutputStream); msg.saveOutputStream(someOutputStream);
ClientMessage msg2 = consumer.receive(...); ClientMessage msg2 = consumer.receive(...);
// This will not wait the transfer to finish // This will not wait the transfer to finish
msg.setOutputStream(someOtherOutputStream); msg.setOutputStream(someOtherOutputStream);
... ```
Set the input stream when sending a core message: Set the input stream when sending a core message:
... ``` java
ClientMessage msg = session.createMessage(); ClientMessage msg = session.createMessage();
msg.setInputStream(dataInputStream); msg.setInputStream(dataInputStream);
... ```
Notice also that for messages with more than 2GiB the getBodySize() will Notice also that for messages with more than 2GiB the getBodySize() will
return invalid values since this is an integer (which is also exposed to return invalid values since this is an integer (which is also exposed to
the JMS API). On those cases you can use the message property the JMS API). On those cases you can use the message property
\_HQ\_LARGE\_SIZE. _HQ_LARGE_SIZE.
Streaming over JMS ### Streaming over JMS
------------------
When using JMS, ActiveMQ maps the streaming methods on the core API (see When using JMS, ActiveMQ maps the streaming methods on the core API (see
?) by setting object properties . You can use the method ClientMessage API table above) by setting object properties . You can use the method
`Message.setObjectProperty` to set the input and output streams. `Message.setObjectProperty` to set the input and output streams.
The `InputStream` can be defined through the JMS Object Property The `InputStream` can be defined through the JMS Object Property
JMS\_HQ\_InputStream on messages being sent: JMS_HQ_InputStream on messages being sent:
BytesMessage message = session.createBytesMessage(); ``` java
BytesMessage message = session.createBytesMessage();
FileInputStream fileInputStream = new FileInputStream(fileInput); FileInputStream fileInputStream = new FileInputStream(fileInput);
BufferedInputStream bufferedInput = new BufferedInputStream(fileInputStream); BufferedInputStream bufferedInput = new BufferedInputStream(fileInputStream);
message.setObjectProperty("JMS_HQ_InputStream", bufferedInput); message.setObjectProperty("JMS_HQ_InputStream", bufferedInput);
someProducer.send(message); someProducer.send(message);
```
The `OutputStream` can be set through the JMS Object Property The `OutputStream` can be set through the JMS Object Property
JMS\_HQ\_SaveStream on messages being received in a blocking way. JMS_HQ_SaveStream on messages being received in a blocking way.
BytesMessage messageReceived = (BytesMessage)messageConsumer.receive(120000); ``` java
BytesMessage messageReceived = (BytesMessage)messageConsumer.receive(120000);
File outputFile = new File("huge_message_received.dat");
File outputFile = new File("huge_message_received.dat");
FileOutputStream fileOutputStream = new FileOutputStream(outputFile);
FileOutputStream fileOutputStream = new FileOutputStream(outputFile);
BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream);
BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream);
// This will block until the entire content is saved on disk
messageReceived.setObjectProperty("JMS_HQ_SaveStream", bufferedOutput); // This will block until the entire content is saved on disk
messageReceived.setObjectProperty("JMS_HQ_SaveStream", bufferedOutput);
```
Setting the `OutputStream` could also be done in a non blocking way Setting the `OutputStream` could also be done in a non blocking way
using the property JMS\_HQ\_OutputStream. using the property JMS_HQ_OutputStream.
// This won't wait the stream to finish. You need to keep the consumer active. ``` java
messageReceived.setObjectProperty("JMS_HQ_OutputStream", bufferedOutput); // This won't wait the stream to finish. You need to keep the consumer active.
messageReceived.setObjectProperty("JMS_HQ_OutputStream", bufferedOutput);
```
> **Note** > **Note**
> >
> When using JMS, Streaming large messages are only supported on > When using JMS, Streaming large messages are only supported on
> `StreamMessage` and `BytesMessage`. > `StreamMessage` and `BytesMessage`.
Streaming Alternative ## Streaming Alternative
=====================
If you choose not to use the `InputStream` or `OutputStream` capability If you choose not to use the `InputStream` or `OutputStream` capability
of ActiveMQ You could still access the data directly in an alternative of ActiveMQ You could still access the data directly in an alternative
@ -246,30 +244,32 @@ fashion.
On the Core API just get the bytes of the body as you normally would. On the Core API just get the bytes of the body as you normally would.
ClientMessage msg = consumer.receive(); ``` java
ClientMessage msg = consumer.receive();
byte[] bytes = new byte[1024];
for (int i = 0 ; i < msg.getBodySize(); i += bytes.length) byte[] bytes = new byte[1024];
{ for (int i = 0 ; i < msg.getBodySize(); i += bytes.length)
msg.getBody().readBytes(bytes); {
// Whatever you want to do with the bytes msg.getBody().readBytes(bytes);
} // Whatever you want to do with the bytes
}
```
If using JMS API, `BytesMessage` and `StreamMessage` also supports it If using JMS API, `BytesMessage` and `StreamMessage` also supports it
transparently. transparently.
``` java
BytesMessage rm = (BytesMessage)cons.receive(10000);
BytesMessage rm = (BytesMessage)cons.receive(10000); byte data[] = new byte[1024];
byte data[] = new byte[1024]; for (int i = 0; i < rm.getBodyLength(); i += 1024)
{
int numberOfBytes = rm.readBytes(data);
// Do whatever you want with the data
}
```
for (int i = 0; i < rm.getBodyLength(); i += 1024) ## Large message example
{
int numberOfBytes = rm.readBytes(data);
// Do whatever you want with the data
}
Large message example
=====================
Please see ? for an example which shows how large message is configured Please see ? for an example which shows how large message is configured
and used with JMS. and used with JMS.

44
docs/user-manual/en/last-value-queues.md
View File

@ -1,5 +1,4 @@
Last-Value Queues # Last-Value Queues
=================
Last-Value queues are special queues which discard any messages when a Last-Value queues are special queues which discard any messages when a
newer message with the same value for a well-defined Last-Value property newer message with the same value for a well-defined Last-Value property
@ -9,8 +8,7 @@ last value.
A typical example for Last-Value queue is for stock prices, where you A typical example for Last-Value queue is for stock prices, where you
are only interested by the latest value for a particular stock. are only interested by the latest value for a particular stock.
Configuring Last-Value Queues ## Configuring Last-Value Queues
=============================
Last-value queues are defined in the address-setting configuration: Last-value queues are defined in the address-setting configuration:
@ -21,8 +19,7 @@ Last-value queues are defined in the address-setting configuration:
By default, `last-value-queue` is false. Address wildcards can be used By default, `last-value-queue` is false. Address wildcards can be used
to configure Last-Value queues for a set of addresses (see ?). to configure Last-Value queues for a set of addresses (see ?).
Using Last-Value Property ## Using Last-Value Property
=========================
The property name used to identify the last value is `"_HQ_LVQ_NAME"` The property name used to identify the last value is `"_HQ_LVQ_NAME"`
(or the constant `Message.HDR_LAST_VALUE_NAME` from the Core API). (or the constant `Message.HDR_LAST_VALUE_NAME` from the Core API).
@ -31,25 +28,26 @@ For example, if two messages with the same value for the Last-Value
property are sent to a Last-Value queue, only the latest message will be property are sent to a Last-Value queue, only the latest message will be
kept in the queue: kept in the queue:
// send 1st message with Last-Value property set to STOCK_NAME ``` java
TextMessage message = session.createTextMessage("1st message with Last-Value property set"); // send 1st message with Last-Value property set to STOCK_NAME
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME"); TextMessage message = session.createTextMessage("1st message with Last-Value property set");
producer.send(message); message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
producer.send(message);
// send 2nd message with Last-Value property set to STOCK_NAME // send 2nd message with Last-Value property set to STOCK_NAME
message = session.createTextMessage("2nd message with Last-Value property set"); message = session.createTextMessage("2nd message with Last-Value property set");
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME"); message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
producer.send(message); producer.send(message);
... ...
// only the 2nd message will be received: it is the latest with // only the 2nd message will be received: it is the latest with
// the Last-Value property set // the Last-Value property set
TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000); TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
System.out.format("Received message: %s\n", messageReceived.getText()); System.out.format("Received message: %s\n", messageReceived.getText());
```
Example ## Example
=======
See ? for an example which shows how last value queues are configured See ? for an example which shows how last value queues are configured
and used with JMS. and used with JMS.

14
docs/user-manual/en/libaio.md
View File

@ -1,5 +1,4 @@
Libaio Native Libraries # Libaio Native Libraries
=======================
ActiveMQ distributes a native library, used as a bridge between ActiveMQ ActiveMQ distributes a native library, used as a bridge between ActiveMQ
and Linux libaio. and Linux libaio.
@ -10,7 +9,7 @@ processed asynchronously. Some time later the OS will call our code back
when they have been processed. when they have been processed.
We use this in our high performance journal if configured to do so, We use this in our high performance journal if configured to do so,
please see ?. please see [Persistence](persistence.md).
These are the native libraries distributed by ActiveMQ: These are the native libraries distributed by ActiveMQ:
@ -21,16 +20,14 @@ These are the native libraries distributed by ActiveMQ:
When using libaio, ActiveMQ will always try loading these files as long When using libaio, ActiveMQ will always try loading these files as long
as they are on the [library path](#using-server.library.path). as they are on the [library path](#using-server.library.path).
Compiling the native libraries ## Compiling the native libraries
==============================
In the case that you are using Linux on a platform other than x86\_32 or In the case that you are using Linux on a platform other than x86\_32 or
x86\_64 (for example Itanium 64 bits or IBM Power) you may need to x86\_64 (for example Itanium 64 bits or IBM Power) you may need to
compile the native library, since we do not distribute binaries for compile the native library, since we do not distribute binaries for
those platforms with the release. those platforms with the release.
Install requirements ## Install requirements
--------------------
> **Note** > **Note**
> >
@ -76,8 +73,7 @@ Or on Debian systems:
> the version and Linux distribution. (for example gcc-c++ on Fedora > the version and Linux distribution. (for example gcc-c++ on Fedora
> versus g++ on Debian systems) > versus g++ on Debian systems)
Invoking the compilation ## Invoking the compilation
------------------------
In the distribution, in the `native-src` directory, execute the shell In the distribution, in the `native-src` directory, execute the shell
script `bootstrap`. This script will invoke `automake` and `make` what script `bootstrap`. This script will invoke `automake` and `make` what

9
docs/user-manual/en/logging.md
View File

@ -1,5 +1,4 @@
Logging # Logging
=======
ActiveMQ uses the JBoss Logging framework to do its logging and is ActiveMQ uses the JBoss Logging framework to do its logging and is
configurable via the `logging.properties` file found in the configurable via the `logging.properties` file found in the
@ -19,8 +18,7 @@ There are 6 loggers available which are as follows:
: Global Configuration Properties : Global Configuration Properties
Logging in a client or with an Embedded server ## Logging in a client or with an Embedded server
==============================================
Firstly, if you want to enable logging on the client side you need to Firstly, if you want to enable logging on the client side you need to
include the JBoss logging jars in your library. If you are using maven include the JBoss logging jars in your library. If you are using maven
@ -85,8 +83,7 @@ The following is a typical `logging.properties for a client`
formatter.PATTERN.properties=pattern formatter.PATTERN.properties=pattern
formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n
Logging With The JBoss Application Server ## Logging With The JBoss Application Server
=========================================
When ActiveMQ is deployed within the JBoss Application Server version 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 7.x or above then it will still use JBoss Logging, refer to the AS7

243
docs/user-manual/en/management.md
View File

@ -1,5 +1,4 @@
Management # Management
==========
ActiveMQ has an extensive management API that allows a user to modify a ActiveMQ has an extensive management API that allows a user to modify a
server configuration, create new resources (e.g. JMS queues and topics), server configuration, create new resources (e.g. JMS queues and topics),
@ -26,8 +25,7 @@ JMS messages.
This choice depends on your requirements, your application settings and This choice depends on your requirements, your application settings and
your environment to decide which way suits you best. your environment to decide which way suits you best.
The Management API ## The Management API
==================
Regardless of the way you *invoke* management operations, the management Regardless of the way you *invoke* management operations, the management
API is the same. API is the same.
@ -53,13 +51,12 @@ messages, or JMS messages are used.
> empty string means that the management operation will be performed on > empty string means that the management operation will be performed on
> *all messages*. > *all messages*.
Core Management API ### Core Management API
-------------------
ActiveMQ defines a core management API to manage core resources. For ActiveMQ defines a core management API to manage core resources. For
full details of the API please consult the javadoc. In summary: full details of the API please consult the javadoc. In summary:
### Core Server Management #### Core Server Management
- Listing, creating, deploying and destroying queues - Listing, creating, deploying and destroying queues
@ -145,7 +142,7 @@ full details of the API please consult the javadoc. In summary:
> receive some sort of error depending on which management service > receive some sort of error depending on which management service
> you use to call it. > you use to call it.
### Core Address Management #### Core Address Management
Core addresses can be managed using the `AddressControl` class (with the Core addresses can be managed using the `AddressControl` class (with the
ObjectName `org.apache.activemq:module=Core,type=Address,name="<the ObjectName `org.apache.activemq:module=Core,type=Address,name="<the
@ -159,7 +156,7 @@ ObjectName `org.apache.activemq:module=Core,type=Address,name="<the
`addRole()` or `removeRole()` methods. You can list all the roles `addRole()` or `removeRole()` methods. You can list all the roles
associated to the queue with the `getRoles()` method associated to the queue with the `getRoles()` method
### Core Queue Management #### Core Queue Management
The bulk of the core management API deals with core queues. The The bulk of the core management API deals with core queues. The
`QueueControl` class defines the Core queue management operations (with `QueueControl` class defines the Core queue management operations (with
@ -219,8 +216,8 @@ messages with a given property.)
Message counters can be listed for a queue with the Message counters can be listed for a queue with the
`listMessageCounter()` and `listMessageCounterHistory()` methods `listMessageCounter()` and `listMessageCounterHistory()` methods
(see ?). The message counters can also be reset for a single queue (see Message Counters section). The message counters can also be
using the `resetMessageCounter()` method. reset for a single queue using the `resetMessageCounter()` method.
- Retrieving the queue attributes - Retrieving the queue attributes
@ -236,7 +233,7 @@ messages with a given property.)
When it's resume, it'll begin delivering the queued messages, if When it's resume, it'll begin delivering the queued messages, if
any. any.
### Other Core Resources Management #### Other Core Resources Management
ActiveMQ allows to start and stop its remote resources (acceptors, ActiveMQ allows to start and stop its remote resources (acceptors,
diverts, bridges, etc.) so that a server can be taken off line for a diverts, bridges, etc.) so that a server can be taken off line for a
@ -252,7 +249,7 @@ transactions). These resources are:
name>"` or the resource name name>"` or the resource name
`core.acceptor.<the `core.acceptor.<the
address name>`). The acceptors parameters address name>`). The acceptors parameters
can be retrieved using the `AcceptorControl` attributes (see ?) can be retrieved using the `AcceptorControl` attributes (see [Understanding Acceptors](configuring-transports.md))
- Diverts - Diverts
@ -261,7 +258,7 @@ transactions). These resources are:
`org.apache.activemq:module=Core,type=Divert,name=<the divert name>` `org.apache.activemq:module=Core,type=Divert,name=<the divert name>`
or the resource name `core.divert.<the divert name>`). Diverts or the resource name `core.divert.<the divert name>`). Diverts
parameters can be retrieved using the `DivertControl` attributes parameters can be retrieved using the `DivertControl` attributes
(see ?) (see [Diverting and Splitting Message Flows)](diverts.md))
- Bridges - Bridges
@ -271,7 +268,7 @@ transactions). These resources are:
name>"` or the resource name name>"` or the resource name
`core.bridge.<the bridge `core.bridge.<the bridge
name>`). Bridges parameters can be retrieved name>`). Bridges parameters can be retrieved
using the `BridgeControl` attributes (see ?) using the `BridgeControl` attributes (see [Core bridges](core-bridges.md))
- Broadcast groups - Broadcast groups
@ -281,7 +278,7 @@ transactions). These resources are:
name>"` or the resource name name>"` or the resource name
`core.broadcastgroup.<the broadcast group name>`). Broadcast groups `core.broadcastgroup.<the broadcast group name>`). Broadcast groups
parameters can be retrieved using the `BroadcastGroupControl` parameters can be retrieved using the `BroadcastGroupControl`
attributes (see ?) attributes (see [Clusters](clusters.md))
- Discovery groups - Discovery groups
@ -292,7 +289,7 @@ transactions). These resources are:
`core.discovery.<the `core.discovery.<the
discovery group name>`). Discovery groups discovery group name>`). Discovery groups
parameters can be retrieved using the `DiscoveryGroupControl` parameters can be retrieved using the `DiscoveryGroupControl`
attributes (see ?) attributes (see [Clusters](clusters.md))
- Cluster connections - Cluster connections
@ -302,15 +299,14 @@ transactions). These resources are:
connection name>"` or the resource name connection name>"` or the resource name
`core.clusterconnection.<the cluster connection name>`). Cluster `core.clusterconnection.<the cluster connection name>`). Cluster
connections parameters can be retrieved using the connections parameters can be retrieved using the
`ClusterConnectionControl` attributes (see ?) `ClusterConnectionControl` attributes (see [Clusters](clusters.md))
JMS Management API ### JMS Management API
------------------
ActiveMQ defines a JMS Management API to manage JMS *administrated ActiveMQ defines a JMS Management API to manage JMS *administrated
objects* (i.e. JMS queues, topics and connection factories). objects* (i.e. JMS queues, topics and connection factories).
### JMS Server Management #### JMS Server Management
JMS Resources (connection factories and destinations) can be created JMS Resources (connection factories and destinations) can be created
using the `JMSServerControl` class (with the ObjectName using the `JMSServerControl` class (with the ObjectName
@ -333,7 +329,8 @@ using the `JMSServerControl` class (with the ObjectName
curly braces. For example `{key=10}, {key=20}`. In that case, the curly braces. For example `{key=10}, {key=20}`. In that case, the
first `key` will be associated to the first transport configuration first `key` will be associated to the first transport configuration
and the second `key` will be associated to the second transport and the second `key` will be associated to the second transport
configuration (see ? for a list of the transport parameters) configuration (see [Configuring Transports](configuring-transports.md)
for a list of the transport parameters)
- Listing, creating, destroying queues - Listing, creating, destroying queues
@ -364,7 +361,7 @@ using the `JMSServerControl` class (with the ObjectName
`listConnectionIDs()` and all the sessions for a given connection ID `listConnectionIDs()` and all the sessions for a given connection ID
can be listed using `listSessions()`. can be listed using `listSessions()`.
### JMS ConnectionFactory Management #### JMS ConnectionFactory Management
JMS Connection Factories can be managed using the JMS Connection Factories can be managed using the
`ConnectionFactoryControl` class (with the ObjectName `ConnectionFactoryControl` class (with the ObjectName
@ -382,7 +379,7 @@ JMS Connection Factories can be managed using the
from the connection factory will block or not when sending from the connection factory will block or not when sending
non-durable messages, etc.) non-durable messages, etc.)
### JMS Queue Management #### JMS Queue Management
JMS queues can be managed using the `JMSQueueControl` class (with the JMS queues can be managed using the `JMSQueueControl` class (with the
ObjectName `org.apache.activemq:module=JMS,type=Queue,name="<the queue ObjectName `org.apache.activemq:module=JMS,type=Queue,name="<the queue
@ -439,7 +436,7 @@ operations on a core queue.*
Message counters can be listed for a queue with the Message counters can be listed for a queue with the
`listMessageCounter()` and `listMessageCounterHistory()` methods `listMessageCounter()` and `listMessageCounterHistory()` methods
(see ?) (see Message Counters section)
- Retrieving the queue attributes - Retrieving the queue attributes
@ -455,7 +452,7 @@ operations on a core queue.*
will not deliver them. When resumed again it will deliver the will not deliver them. When resumed again it will deliver the
enqueued messages, if any. enqueued messages, if any.
### JMS Topic Management #### JMS Topic Management
JMS Topics can be managed using the `TopicControl` class (with the JMS Topics can be managed using the `TopicControl` class (with the
ObjectName `org.apache.activemq:module=JMS,type=Topic,name="<the topic ObjectName `org.apache.activemq:module=JMS,type=Topic,name="<the topic
@ -484,8 +481,7 @@ ObjectName `org.apache.activemq:module=JMS,type=Topic,name="<the topic
message selector to know the number of messages matching the message selector to know the number of messages matching the
selector) selector)
Using Management Via JMX ## Using Management Via JMX
========================
ActiveMQ can be managed using ActiveMQ can be managed using
[JMX](http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html). [JMX](http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html).
@ -510,8 +506,7 @@ Managing ActiveMQ using JMX is identical to management of any Java
Applications using JMX. It can be done by reflection or by creating Applications using JMX. It can be done by reflection or by creating
proxies of the MBeans. proxies of the MBeans.
Configuring JMX ### Configuring JMX
---------------
By default, JMX is enabled to manage ActiveMQ. It can be disabled by By default, JMX is enabled to manage ActiveMQ. It can be disabled by
setting `jmx-management-enabled` to `false` in setting `jmx-management-enabled` to `false` in
@ -538,7 +533,7 @@ domain can be configured for each individual ActiveMQ server by setting
<!-- use a specific JMX domain for ActiveMQ MBeans --> <!-- use a specific JMX domain for ActiveMQ MBeans -->
<jmx-domain>my.org.apache.activemq</jmx-domain> <jmx-domain>my.org.apache.activemq</jmx-domain>
### MBeanServer configuration #### MBeanServer configuration
When ActiveMQ is run in standalone, it uses the Java Virtual Machine's When ActiveMQ is run in standalone, it uses the Java Virtual Machine's
`Platform MBeanServer` to register its MBeans. This is configured in `Platform MBeanServer` to register its MBeans. This is configured in
@ -559,14 +554,12 @@ own MBean Server so that it can be managed using AS 5's jmx-console:
factoryMethod="locateJBoss" /> factoryMethod="locateJBoss" />
</bean> </bean>
Example ### Example
-------
See ? for an example which shows how to use a remote connection to JMX See ? for an example which shows how to use a remote connection to JMX
and MBean proxies to manage ActiveMQ. and MBean proxies to manage ActiveMQ.
Using Management Via Core API ## Using Management Via Core API
=============================
The core management API in ActiveMQ is called by sending Core messages The core management API in ActiveMQ is called by sending Core messages
to a special address, the *management address*. to a special address, the *management address*.
@ -615,14 +608,16 @@ operations using Core messages:
For example, to find out the number of messages in the core queue For example, to find out the number of messages in the core queue
`exampleQueue`: `exampleQueue`:
ClientSession session = ... ``` java
ClientRequestor requestor = new ClientRequestor(session, "jms.queue.activemq.management"); ClientSession session = ...
ClientMessage message = session.createMessage(false); ClientRequestor requestor = new ClientRequestor(session, "jms.queue.activemq.management");
ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount"); ClientMessage message = session.createMessage(false);
session.start(); ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount");
ClientMessage reply = requestor.request(m); session.start();
int count = (Integer) ManagementHelper.getResult(reply); ClientMessage reply = requestor.request(m);
System.out.println("There are " + count + " messages in exampleQueue"); int count = (Integer) ManagementHelper.getResult(reply);
System.out.println("There are " + count + " messages in exampleQueue");
```
Management operation name and parameters must conform to the Java Management operation name and parameters must conform to the Java
interfaces defined in the `management` packages. interfaces defined in the `management` packages.
@ -633,8 +628,7 @@ straightforward (`core.queue.exampleQueue` for the Core Queue
`exampleQueue`, `jms.topic.exampleTopic` for the JMS Topic `exampleQueue`, `jms.topic.exampleTopic` for the JMS Topic
`exampleTopic`, etc.). `exampleTopic`, etc.).
Configuring Core Management ### Configuring Core Management
---------------------------
The management address to send management messages is configured in The management address to send management messages is configured in
`activemq-configuration.xml`: `activemq-configuration.xml`:
@ -655,8 +649,7 @@ configured in activemq-configuration.xml:
<permission type="manage" roles="admin" /> <permission type="manage" roles="admin" />
</security-setting> </security-setting>
Using Management Via JMS ## Using Management Via JMS
========================
Using JMS messages to manage ActiveMQ is very similar to using core API. Using JMS messages to manage ActiveMQ is very similar to using core API.
@ -688,32 +681,29 @@ API instead:
For example, to know the number of messages in the JMS queue For example, to know the number of messages in the JMS queue
`exampleQueue`: `exampleQueue`:
``` java
Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management"); QueueSession session = ...
QueueRequestor requestor = new QueueRequestor(session, managementQueue);
QueueSession session = ... connection.start();
QueueRequestor requestor = new QueueRequestor(session, managementQueue); Message message = session.createMessage();
connection.start(); JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "messageCount");
Message message = session.createMessage(); Message reply = requestor.request(message);
JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "messageCount"); int count = (Integer)JMSManagementHelper.getResult(reply);
Message reply = requestor.request(message); System.out.println("There are " + count + " messages in exampleQueue");
int count = (Integer)JMSManagementHelper.getResult(reply); ```
System.out.println("There are " + count + " messages in exampleQueue"); ### Configuring JMS Management
Configuring JMS Management
--------------------------
Whether JMS or the core API is used for management, the configuration Whether JMS or the core API is used for management, the configuration
steps are the same (see ?). steps are the same (see Configuring Core Management section).
Example ### Example
-------
See ? for an example which shows how to use JMS messages to manage See ? for an example which shows how to use JMS messages to manage
ActiveMQ server. ActiveMQ server.
Management Notifications ## Management Notifications
========================
ActiveMQ emits *notifications* to inform listeners of potentially ActiveMQ emits *notifications* to inform listeners of potentially
interesting events (creation of new resources, security violation, interesting events (creation of new resources, security violation,
@ -727,10 +717,9 @@ These notifications can be received by 3 different ways:
- JMS messages - JMS messages
JMX Notifications ### JMX Notifications
-----------------
If JMX is enabled (see ?), JMX notifications can be received by If JMX is enabled (see Configuring JMX section), JMX notifications can be received by
subscribing to 2 MBeans: subscribing to 2 MBeans:
- `org.apache.activemq:module=Core,type=Server` for notifications on - `org.apache.activemq:module=Core,type=Server` for notifications on
@ -739,8 +728,7 @@ subscribing to 2 MBeans:
- `org.apache.activemq:module=JMS,type=Server` for notifications on - `org.apache.activemq:module=JMS,type=Server` for notifications on
*JMS* resources *JMS* resources
Core Messages Notifications ### Core Messages Notifications
---------------------------
ActiveMQ defines a special *management notification address*. Core ActiveMQ defines a special *management notification address*. Core
queues can be bound to this address so that clients will receive queues can be bound to this address so that clients will receive
@ -758,7 +746,7 @@ Since notifications are regular core messages, it is possible to use
message selectors to filter out notifications and receives only a subset message selectors to filter out notifications and receives only a subset
of all the notifications emitted by the server. of all the notifications emitted by the server.
### Configuring The Core Management Notification Address #### Configuring The Core Management Notification Address
The management notification address to receive management notifications The management notification address to receive management notifications
is configured in `activemq-configuration.xml`: is configured in `activemq-configuration.xml`:
@ -767,8 +755,7 @@ is configured in `activemq-configuration.xml`:
By default, the address is `activemq.notifications`. By default, the address is `activemq.notifications`.
JMS Messages Notifications ### JMS Messages Notifications
--------------------------
ActiveMQ's notifications can also be received using JMS messages. ActiveMQ's notifications can also be received using JMS messages.
@ -786,40 +773,39 @@ change the server's management notification address to start with
Once the notification topic is created, you can receive messages from it Once the notification topic is created, you can receive messages from it
or set a `MessageListener`: or set a `MessageListener`:
Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic"); ``` java
Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic");
Session session = ... Session session = ...
MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic); MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
notificationConsumer.setMessageListener(new MessageListener() notificationConsumer.setMessageListener(new MessageListener()
{ {
public void onMessage(Message notif) public void onMessage(Message notif)
{ {
System.out.println("------------------------"); System.out.println("------------------------");
System.out.println("Received notification:"); System.out.println("Received notification:");
try try
{ {
Enumeration propertyNames = notif.getPropertyNames(); Enumeration propertyNames = notif.getPropertyNames();
while (propertyNames.hasMoreElements()) while (propertyNames.hasMoreElements())
{ {
String propertyName = (String)propertyNames.nextElement(); String propertyName = (String)propertyNames.nextElement();
System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName)); System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName));
} }
} }
catch (JMSException e) catch (JMSException e)
{ {
} }
System.out.println("------------------------"); System.out.println("------------------------");
} }
}); });
```
Example ### Example
-------
See ? for an example which shows how to use a JMS `MessageListener` to See ? for an example which shows how to use a JMS `MessageListener` to
receive management notifications from ActiveMQ server. receive management notifications from ActiveMQ server.
Notification Types and Headers ### Notification Types and Headers
------------------------------
Below is a list of all the different kinds of notifications as well as Below is a list of all the different kinds of notifications as well as
which headers are on the messages. Every notification has a which headers are on the messages. Every notification has a
@ -914,8 +900,7 @@ header. The timestamp is the un-formatted result of a call to
`_HQ_Address`, `_HQ_ConsumerCount`, `_HQ_RemoteAddress`, `_HQ_Address`, `_HQ_ConsumerCount`, `_HQ_RemoteAddress`,
`_HQ_ConnectionName`, `_HQ_ConsumerName`, `_HQ_SessionName` `_HQ_ConnectionName`, `_HQ_ConsumerName`, `_HQ_SessionName`
Message Counters ## Message Counters
================
Message counters can be used to obtain information on queues *over time* Message counters can be used to obtain information on queues *over time*
as ActiveMQ keeps a history on queue metrics. as ActiveMQ keeps a history on queue metrics.
@ -966,8 +951,7 @@ For example, to know specifically how many messages were *consumed* from
the queue since the last update simply subtract the `messageCountDelta` the queue since the last update simply subtract the `messageCountDelta`
from `countDelta`. from `countDelta`.
Configuring Message Counters ### Configuring Message Counters
----------------------------
By default, message counters are disabled as it might have a small By default, message counters are disabled as it might have a small
negative effect on memory. negative effect on memory.
@ -991,28 +975,28 @@ configured to suit your messaging use case in
Message counters can be retrieved using the Management API. For example, Message counters can be retrieved using the Management API. For example,
to retrieve message counters on a JMS Queue using JMX: to retrieve message counters on a JMS Queue using JMX:
// retrieve a connection to ActiveMQ's MBeanServer ``` java
MBeanServerConnection mbsc = ... // retrieve a connection to ActiveMQ's MBeanServer
JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc, MBeanServerConnection mbsc = ...
on, JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
JMSQueueControl.class, on,
false); JMSQueueControl.class,
// message counters are retrieved as a JSON String false);
String counters = queueControl.listMessageCounter(); // message counters are retrieved as a JSON String
// use the MessageCounterInfo helper class to manipulate message counters more easily String counters = queueControl.listMessageCounter();
MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters); // use the MessageCounterInfo helper class to manipulate message counters more easily
System.out.format("%s message(s) in the queue (since last sample: %s)\n", MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);
messageCounter.getMessageCount(), System.out.format("%s message(s) in the queue (since last sample: %s)\n",
messageCounter.getMessageCountDelta()); messageCounter.getMessageCount(),
messageCounter.getMessageCountDelta());
```
Example ### Example
-------
See ? for an example which shows how to use message counters to retrieve See ? for an example which shows how to use message counters to retrieve
information on a JMS `Queue`. information on a JMS `Queue`.
Administering ActiveMQ Resources Using The JBoss AS Admin Console ## Administering ActiveMQ Resources Using The JBoss AS Admin Console
=================================================================
Its possible to create and configure ActiveMQ resources via the admin Its possible to create and configure ActiveMQ resources via the admin
console within the JBoss Application Server. console within the JBoss Application Server.
@ -1027,8 +1011,7 @@ Factories, clicking on each node will reveal which resources are
currently available. The following sections explain how to create and currently available. The following sections explain how to create and
configure each resource in turn. configure each resource in turn.
JMS Queues ### JMS Queues
----------
To create a new JMS Queue click on the JMS Queues item to reveal the To create a new JMS Queue click on the JMS Queues item to reveal the
available queues. On the right hand panel you will see an add a new available queues. On the right hand panel you will see an add a new
@ -1055,7 +1038,7 @@ configuration options, apart from security roles, relate to address
settings for a particular address. The default address settings are settings for a particular address. The default address settings are
picked up from the servers configuration, if you change any of these picked up from the servers configuration, if you change any of these
settings or create a queue via the console a new Address Settings entry settings or create a queue via the console a new Address Settings entry
will be added. For a full explanation on Address Settings see ? will be added. For a full explanation on Address Settings see [Configuring Queues Via Address Settings](queue-attributes.md)
To delete a queue simply click on the delete button beside the queue To delete a queue simply click on the delete button beside the queue
name in the main JMS Queues screen. This will also delete any address name in the main JMS Queues screen. This will also delete any address
@ -1065,7 +1048,7 @@ The last part of the configuration options are security roles. If non
are provided on creation then the servers default security settings will are provided on creation then the servers default security settings will
be shown. If these are changed or updated then new security settings are be shown. If these are changed or updated then new security settings are
created for the address of this queue. For more information on security created for the address of this queue. For more information on security
setting see ? setting see [Security](security.md)
It is also possible via the metrics tab to view statistics for this It is also possible via the metrics tab to view statistics for this
queue. This will show statistics such as message count, consumer count queue. This will show statistics such as message count, consumer count
@ -1079,15 +1062,13 @@ you to a screen where you can parameters for the operation can be set.
Once set clicking the ok button will invoke the operation, results Once set clicking the ok button will invoke the operation, results
appear at the bottom of the screen. appear at the bottom of the screen.
JMS Topics ### JMS Topics
----------
Creating and configuring JMS Topics is almost identical to creating Creating and configuring JMS Topics is almost identical to creating
queues. The only difference is that the configuration will be applied to queues. The only difference is that the configuration will be applied to
the queue representing a subscription. the queue representing a subscription.
JMS Connection Factories ### JMS Connection Factories
------------------------
The format for creating connection factories is the same as for JMS The format for creating connection factories is the same as for JMS
Queues and topics apart from the configuration being different. For as Queues and topics apart from the configuration being different. For as

17
docs/user-manual/en/message-expiry.md
View File

@ -1,5 +1,4 @@
Message Expiry # Message Expiry
==============
Messages can be set with an optional *time to live* when sending them. Messages can be set with an optional *time to live* when sending them.
@ -12,8 +11,7 @@ messages are expired, they are removed from the queue and sent to the
expiry address. Many different queues can be bound to an expiry address. expiry address. Many different queues can be bound to an expiry address.
These *expired* messages can later be consumed for further inspection. These *expired* messages can later be consumed for further inspection.
Message Expiry ## Message Expiry
==============
Using ActiveMQ Core API, you can set an expiration time directly on the Using ActiveMQ Core API, you can set an expiration time directly on the
message: message:
@ -44,8 +42,7 @@ following properties:
a Long property containing the *actual expiration time* of the a Long property containing the *actual expiration time* of the
expired message expired message
Configuring Expiry Addresses ## Configuring Expiry Addresses
============================
Expiry address are defined in the address-setting configuration: Expiry address are defined in the address-setting configuration:
@ -56,10 +53,9 @@ Expiry address are defined in the address-setting configuration:
If messages are expired and no expiry address is specified, messages are If messages are expired and no expiry address is specified, messages are
simply removed from the queue and dropped. Address wildcards can be used simply removed from the queue and dropped. Address wildcards can be used
to configure expiry address for a set of addresses (see ?). to configure expiry address for a set of addresses (see [Understanding the HornetQ Wildcard Syntax](wildcard-syntax.md)).
Configuring The Expiry Reaper Thread ## Configuring The Expiry Reaper Thread
====================================
A reaper thread will periodically inspect the queues to check if A reaper thread will periodically inspect the queues to check if
messages have expired. messages have expired.
@ -78,8 +74,7 @@ The reaper thread can be configured with the following properties in
The reaper thread priority (it must be between 0 and 9, 9 being the The reaper thread priority (it must be between 0 and 9, 9 being the
highest priority, default is 3) highest priority, default is 3)
Example ## Example
=======
See ? for an example which shows how message expiry is configured and See ? for an example which shows how message expiry is configured and
used with JMS. used with JMS.

26
docs/user-manual/en/message-grouping.md
View File

@ -1,5 +1,4 @@
Message Grouping # Message Grouping
================
Message groups are sets of messages that have the following Message groups are sets of messages that have the following
characteristics: characteristics:
@ -21,7 +20,7 @@ An example might be orders for a certain stock. You may want orders for
any particular stock to be processed serially by the same consumer. To any particular stock to be processed serially by the same consumer. To
do this you can create a pool of consumers (perhaps one for each stock, do this you can create a pool of consumers (perhaps one for each stock,
but less will work too), then set the stock name as the value of the but less will work too), then set the stock name as the value of the
\_HQ\_GROUP\_ID property. _HQ_GROUP_ID property.
This will ensure that all messages for a particular stock will always be This will ensure that all messages for a particular stock will always be
processed by the same consumer. processed by the same consumer.
@ -41,16 +40,14 @@ processed by the same consumer.
> and consider whether or not you should isolate your grouped messages > and consider whether or not you should isolate your grouped messages
> from your non-grouped messages. > from your non-grouped messages.
Using Core API ## Using Core API
==============
The property name used to identify the message group is `"_HQ_GROUP_ID"` The property name used to identify the message group is `"_HQ_GROUP_ID"`
(or the constant `MessageImpl.HDR_GROUP_ID`). Alternatively, you can set (or the constant `MessageImpl.HDR_GROUP_ID`). Alternatively, you can set
`autogroup` to true on the `SessionFactory` which will pick a random `autogroup` to true on the `SessionFactory` which will pick a random
unique id. unique id.
Using JMS ## Using JMS
=========
The property name used to identify the message group is `JMSXGroupID`. The property name used to identify the message group is `JMSXGroupID`.
@ -85,20 +82,17 @@ which is available in the context by default:
java.naming.provider.url=tcp://localhost:5445 java.naming.provider.url=tcp://localhost:5445
connection.ConnectionFactory.groupID=Group-0 connection.ConnectionFactory.groupID=Group-0
Example ## Example
=======
See ? for an example which shows how message groups are configured and See ? for an example which shows how message groups are configured and
used with JMS. used with JMS.
Example ## Example
=======
See ? for an example which shows how message groups are configured via a See ? for an example which shows how message groups are configured via a
connection factory. connection factory.
Clustered Grouping ## Clustered Grouping
==================
Using message groups in a cluster is a bit more complex. This is because Using message groups in a cluster is a bit more complex. This is because
messages with a particular group id can arrive on any node so each node messages with a particular group id can arrive on any node so each node
@ -158,8 +152,7 @@ exception thrown. To avoid this happening Local Handlers can be
replicated on another backup node. Simple create your back up node and replicated on another backup node. Simple create your back up node and
configure it with the same Local handler. configure it with the same Local handler.
Clustered Grouping Best Practices ## Clustered Grouping Best Practices
---------------------------------
Some best practices should be followed when using clustered grouping: Some best practices should be followed when using clustered grouping:
@ -191,8 +184,7 @@ Some best practices should be followed when using clustered grouping:
last-time-use value should be updated with a round trip for a last-time-use value should be updated with a round trip for a
request to the group between the nodes. request to the group between the nodes.
Clustered Grouping Example ## Clustered Grouping Example
--------------------------
See ? for an example of how to configure message groups with a ActiveMQ See ? for an example of how to configure message groups with a ActiveMQ
cluster cluster

61
docs/user-manual/en/messaging-concepts.md
View File

@ -1,5 +1,4 @@
Messaging Concepts # Messaging Concepts
==================
ActiveMQ is an asynchronous messaging system, an example of [Message ActiveMQ is an asynchronous messaging system, an example of [Message
Oriented Oriented
@ -13,8 +12,7 @@ about in the messaging world.
If you're already familiar with what a messaging system is and what it's If you're already familiar with what a messaging system is and what it's
capable of, then you can skip this chapter. capable of, then you can skip this chapter.
Messaging Concepts ## Messaging Concepts
==================
Messaging systems allow you to loosely couple heterogeneous systems Messaging systems allow you to loosely couple heterogeneous systems
together, whilst typically providing reliability, transactions and many together, whilst typically providing reliability, transactions and many
@ -51,8 +49,7 @@ grow and adapt more easily. It also allows more flexibility to add new
systems or retire old ones since they don't have brittle dependencies on systems or retire old ones since they don't have brittle dependencies on
each other. each other.
Messaging styles ## Messaging styles
================
Messaging systems normally support two main styles of asynchronous Messaging systems normally support two main styles of asynchronous
messaging: [message queue](http://en.wikipedia.org/wiki/Message_queue) messaging: [message queue](http://en.wikipedia.org/wiki/Message_queue)
@ -60,8 +57,7 @@ messaging (also known as *point-to-point messaging*) and [publish
subscribe](http://en.wikipedia.org/wiki/Publish_subscribe) messaging. subscribe](http://en.wikipedia.org/wiki/Publish_subscribe) messaging.
We'll summarise them briefly here: We'll summarise them briefly here:
The Message Queue Pattern ### The Message Queue Pattern
-------------------------
With this type of messaging you send a message to a queue. The message With this type of messaging you send a message to a queue. The message
is then typically persisted to provide a guarantee of delivery, then is then typically persisted to provide a guarantee of delivery, then
@ -101,8 +97,7 @@ forgotten about. Often the send to the warehouse system, update in
database and acknowledgement will be completed in a single transaction database and acknowledgement will be completed in a single transaction
to ensure [ACID](http://en.wikipedia.org/wiki/ACID) properties. to ensure [ACID](http://en.wikipedia.org/wiki/ACID) properties.
The Publish-Subscribe Pattern ### The Publish-Subscribe Pattern
-----------------------------
With publish-subscribe messaging many senders can send messages to an With publish-subscribe messaging many senders can send messages to an
entity on the server, often called a *topic* (e.g. in the JMS world). entity on the server, often called a *topic* (e.g. in the JMS world).
@ -126,8 +121,7 @@ are interested in receiving news items - each one creates a subscription
and the messaging system ensures that a copy of each news message is and the messaging system ensures that a copy of each news message is
delivered to each subscription. delivered to each subscription.
Delivery guarantees ## Delivery guarantees
===================
A key feature of most messaging systems is *reliable messaging*. With A key feature of most messaging systems is *reliable messaging*. With
reliable messaging the server gives a guarantee that the message will be reliable messaging the server gives a guarantee that the message will be
@ -143,16 +137,14 @@ which are quickly superseded by the next update on the same stock. The
messaging system allows you to configure which delivery guarantees you messaging system allows you to configure which delivery guarantees you
require. require.
Transactions ## Transactions
============
Messaging systems typically support the sending and acknowledgement of Messaging systems typically support the sending and acknowledgement of
multiple messages in a single local transaction. ActiveMQ also supports multiple messages in a single local transaction. ActiveMQ also supports
the sending and acknowledgement of message as part of a large global the sending and acknowledgement of message as part of a large global
transaction - using the Java mapping of XA: JTA. transaction - using the Java mapping of XA: JTA.
Durability ## Durability
==========
Messages are either durable or non durable. Durable messages will be Messages are either durable or non durable. Durable messages will be
persisted in permanent storage and will survive server failure or persisted in permanent storage and will survive server failure or
@ -162,8 +154,7 @@ they cannot be lost. An example of a non durable message might be a
stock price update which is transitory and doesn't need to survive a stock price update which is transitory and doesn't need to survive a
restart. restart.
Messaging APIs and protocols ## Messaging APIs and protocols
============================
How do client applications interact with messaging systems in order to How do client applications interact with messaging systems in order to
send and consume messages? send and consume messages?
@ -176,8 +167,7 @@ and some emerging standards in this space.
Let's take a brief look at these: Let's take a brief look at these:
Java Message Service (JMS) ### Java Message Service (JMS)
--------------------------
[JMS](http://en.wikipedia.org/wiki/Java_Message_Service) is part of [JMS](http://en.wikipedia.org/wiki/Java_Message_Service) is part of
Sun's JEE specification. It's a Java API that encapsulates both message Sun's JEE specification. It's a Java API that encapsulates both message
@ -196,8 +186,7 @@ internal wire protocol.
ActiveMQ provides a fully compliant JMS 1.1 and JMS 2.0 API. ActiveMQ provides a fully compliant JMS 1.1 and JMS 2.0 API.
System specific APIs ### System specific APIs
--------------------
Many systems provide their own programmatic API for which to interact Many systems provide their own programmatic API for which to interact
with the messaging system. The advantage of this it allows the full set with the messaging system. The advantage of this it allows the full set
@ -209,8 +198,7 @@ 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 wish to have access to functionality over and above that accessible via
the JMS API. the JMS API.
RESTful API ### RESTful API
-----------
[REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer)
approaches to messaging are showing a lot interest recently. approaches to messaging are showing a lot interest recently.
@ -228,10 +216,9 @@ use HTTP as their underlying protocol.
The advantage of a REST approach with HTTP is in its simplicity and the 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. fact the internet is already tuned to deal with HTTP optimally.
Please see ? for using ActiveMQ's RESTful interface. Please see [Rest Interface](rest.md) for using ActiveMQ's RESTful interface.
STOMP ### STOMP
-----
[Stomp](http://stomp.github.io/) is a very simple text protocol for [Stomp](http://stomp.github.io/) is a very simple text protocol for
interoperating with messaging systems. It defines a wire format, so interoperating with messaging systems. It defines a wire format, so
@ -239,10 +226,9 @@ theoretically any Stomp client can work with any messaging system that
supports Stomp. Stomp clients are available in many different supports Stomp. Stomp clients are available in many different
programming languages. programming languages.
Please see ? for using STOMP with ActiveMQ. Please see [Stomp](interoperability.md) for using STOMP with ActiveMQ.
AMQP ### AMQP
----
[AMQP](http://en.wikipedia.org/wiki/AMQP) is a specification for [AMQP](http://en.wikipedia.org/wiki/AMQP) is a specification for
interoperable messaging. It also defines a wire format, so any AMQP interoperable messaging. It also defines a wire format, so any AMQP
@ -254,8 +240,7 @@ ActiveMQ implements the [AMQP
specification. Any client that supports the 1.0 specification will be specification. Any client that supports the 1.0 specification will be
able to interact with ActiveMQ. able to interact with ActiveMQ.
High Availability ## High Availability
=================
High Availability (HA) means that the system should remain operational High Availability (HA) means that the system should remain operational
after failure of one or more of the servers. The degree of support for after failure of one or more of the servers. The degree of support for
@ -265,10 +250,9 @@ ActiveMQ provides automatic failover where your sessions are
automatically reconnected to the backup server on event of live server automatically reconnected to the backup server on event of live server
failure. failure.
For more information on HA, please see ?. For more information on HA, please see [High Availability and Failover](ha.md).
Clusters ## Clusters
========
Many messaging systems allow you to create groups of messaging servers Many messaging systems allow you to create groups of messaging servers
called *clusters*. Clusters allow the load of sending and consuming called *clusters*. Clusters allow the load of sending and consuming
@ -287,10 +271,9 @@ whether they are ready for messages.
ActiveMQ also has the ability to automatically redistribute messages ActiveMQ also has the ability to automatically redistribute messages
between nodes of a cluster to prevent starvation on any particular node. between nodes of a cluster to prevent starvation on any particular node.
For full details on clustering, please see ?. For full details on clustering, please see [Clusters](clusters.md).
Bridges and routing ## Bridges and routing
===================
Some messaging systems allow isolated clusters or single nodes to be Some messaging systems allow isolated clusters or single nodes to be
bridged together, typically over unreliable connections like a wide area bridged together, typically over unreliable connections like a wide area
@ -309,4 +292,4 @@ side configuration. This allows complex routing networks to be set up
forwarding or copying messages from one destination to another, forming forwarding or copying messages from one destination to another, forming
a global network of interconnected brokers. a global network of interconnected brokers.
For more information please see ? and ?. For more information please see [Core Bridges](core-bridges.md) and [Diverting and Splitting Message Flows](diverts.md).

30
docs/user-manual/en/paging.md
View File

@ -1,5 +1,4 @@
Paging # Paging
======
ActiveMQ transparently supports huge queues containing millions of ActiveMQ transparently supports huge queues containing millions of
messages while the server is running with limited memory. messages while the server is running with limited memory.
@ -15,8 +14,7 @@ messages in memory for an address exceeds a configured maximum size.
By default, ActiveMQ does not page messages - this must be explicitly By default, ActiveMQ does not page messages - this must be explicitly
configured to activate it. configured to activate it.
Page Files ## Page Files
==========
Messages are stored per address on the file system. Each address has an Messages are stored per address on the file system. Each address has an
individual folder where messages are stored in multiple files (page individual folder where messages are stored in multiple files (page
@ -30,8 +28,7 @@ Browsers will read through the page-cursor system.
Consumers with selectors will also navigate through the page-files and Consumers with selectors will also navigate through the page-files and
it will ignore messages that don't match the criteria. it will ignore messages that don't match the criteria.
Configuration ## Configuration
=============
You can configure the location of the paging folder You can configure the location of the paging folder
@ -51,8 +48,7 @@ Global paging parameters are specified on the main configuration file
: Paging Configuration Parameters : Paging Configuration Parameters
Paging Mode ## Paging Mode
===========
As soon as messages delivered to an address exceed the configured size, As soon as messages delivered to an address exceed the configured size,
that address alone goes into page mode. that address alone goes into page mode.
@ -65,8 +61,7 @@ that address alone goes into page mode.
> total overall size of all matching addresses is limited to > total overall size of all matching addresses is limited to
> max-size-bytes. > max-size-bytes.
Configuration ## Configuration
-------------
Configuration is done at the address settings, done at the main Configuration is done at the address settings, done at the main
configuration file (`activemq-configuration.xml`). configuration file (`activemq-configuration.xml`).
@ -90,8 +85,7 @@ This is the list of available parameters on the address settings.
: Paging Address Settings : Paging Address Settings
Dropping messages ## Dropping messages
=================
Instead of paging messages when the max size is reached, an address can Instead of paging messages when the max size is reached, an address can
also be configured to just drop messages when the address is full. also be configured to just drop messages when the address is full.
@ -99,8 +93,7 @@ also be configured to just drop messages when the address is full.
To do this just set the `address-full-policy` to `DROP` in the address To do this just set the `address-full-policy` to `DROP` in the address
settings settings
Dropping messages and throwing an exception to producers ## Dropping messages and throwing an exception to producers
========================================================
Instead of paging messages when the max size is reached, an address can Instead of paging messages when the max size is reached, an address can
also be configured to drop messages and also throw an exception on the also be configured to drop messages and also throw an exception on the
@ -109,8 +102,7 @@ client-side when the address is full.
To do this just set the `address-full-policy` to `FAIL` in the address To do this just set the `address-full-policy` to `FAIL` in the address
settings settings
Blocking producers ## Blocking producers
==================
Instead of paging messages when the max size is reached, an address can Instead of paging messages when the max size is reached, an address can
also be configured to block producers from sending further messages when also be configured to block producers from sending further messages when
@ -126,8 +118,7 @@ settings
In the default configuration, all addresses are configured to block In the default configuration, all addresses are configured to block
producers after 10 MiB of data are in the address. producers after 10 MiB of data are in the address.
Caution with Addresses with Multiple Queues ## Caution with Addresses with Multiple Queues
===========================================
When a message is routed to an address that has multiple queues bound to When a message is routed to an address that has multiple queues bound to
it, e.g. a JMS subscription in a Topic, there is only 1 copy of the it, e.g. a JMS subscription in a Topic, there is only 1 copy of the
@ -154,7 +145,6 @@ In this example all the other 9 queues will be consuming messages from
the page system. This may cause performance issues if this is an the page system. This may cause performance issues if this is an
undesirable state. undesirable state.
Example ## Example
=======
See ? for an example which shows how to use paging with ActiveMQ. See ? for an example which shows how to use paging with ActiveMQ.

46
docs/user-manual/en/perf-tuning.md
View File

@ -1,11 +1,9 @@
Performance Tuning # Performance Tuning
==================
In this chapter we'll discuss how to tune ActiveMQ for optimum In this chapter we'll discuss how to tune ActiveMQ for optimum
performance. performance.
Tuning persistence ## Tuning persistence
==================
- Put the message journal on its own physical volume. If the disk is - Put the message journal on its own physical volume. If the disk is
shared with other processes e.g. transaction co-ordinator, database shared with other processes e.g. transaction co-ordinator, database
@ -38,8 +36,7 @@ Tuning persistence
performance by increasing `journal-max-io`. DO NOT change this performance by increasing `journal-max-io`. DO NOT change this
parameter if you are running NIO. parameter if you are running NIO.
Tuning JMS ## Tuning JMS
==========
There are a few areas where some tweaks can be done if you are using the There are a few areas where some tweaks can be done if you are using the
JMS API JMS API
@ -78,8 +75,7 @@ JMS API
ActiveMQ will only require a network round trip on the commit, not ActiveMQ will only require a network round trip on the commit, not
on every send or acknowledgement. on every send or acknowledgement.
Other Tunings ## Other Tunings
=============
There are various other places in ActiveMQ where we can perform some There are various other places in ActiveMQ where we can perform some
tuning: tuning:
@ -89,12 +85,13 @@ tuning:
reached the server by the time the call to send() returns, don't set reached the server by the time the call to send() returns, don't set
durable messages to be sent blocking, instead use asynchronous send durable messages to be sent blocking, instead use asynchronous send
acknowledgements to get your acknowledgements of send back in a acknowledgements to get your acknowledgements of send back in a
separate stream, see ? for more information on this. separate stream, see [Guarantees of sends and commits](send-guarantees.md)
for more information on this.
- Use pre-acknowledge mode. With pre-acknowledge mode, messages are - Use pre-acknowledge mode. With pre-acknowledge mode, messages are
acknowledged `before` they are sent to the client. This reduces the acknowledged `before` they are sent to the client. This reduces the
amount of acknowledgement traffic on the wire. For more information amount of acknowledgement traffic on the wire. For more information
on this, see ?. on this, see [Extra Acknowledge Modes](pre-acknowledge.md).
- Disable security. You may get a small performance boost by disabling - Disable security. You may get a small performance boost by disabling
security by setting the `security-enabled` parameter to `false` in security by setting the `security-enabled` parameter to `false` in
@ -107,20 +104,22 @@ tuning:
- Sync transactions lazily. Setting `journal-sync-transactional` to - Sync transactions lazily. Setting `journal-sync-transactional` to
`false` in `activemq-configuration.xml` can give you better `false` in `activemq-configuration.xml` can give you better
transactional persistent performance at the expense of some transactional persistent performance at the expense of some
possibility of loss of transactions on failure. See ? for more possibility of loss of transactions on failure. See [Guarantees of sends and commits](send-guarantees.md)
information. for more information.
- Sync non transactional lazily. Setting - Sync non transactional lazily. Setting
`journal-sync-non-transactional` to `false` in `journal-sync-non-transactional` to `false` in
`activemq-configuration.xml` can give you better non-transactional `activemq-configuration.xml` can give you better non-transactional
persistent performance at the expense of some possibility of loss of persistent performance at the expense of some possibility of loss of
durable messages on failure. See ? for more information. durable messages on failure. See [Guarantees of sends and commits](send-guarantees.md)
for more information.
- Send messages non blocking. Setting `block-on-durable-send` and - Send messages non blocking. Setting `block-on-durable-send` and
`block-on-non-durable-send` to `false` in `activemq-jms.xml` (if `block-on-non-durable-send` to `false` in `activemq-jms.xml` (if
you're using JMS and JNDI) or directly on the ServerLocator. This you're using JMS and JNDI) or directly on the ServerLocator. This
means you don't have to wait a whole network round trip for every means you don't have to wait a whole network round trip for every
message sent. See ? for more information. message sent. See [Guarantees of sends and commits](send-guarantees.md)
for more information.
- If you have very fast consumers, you can increase - If you have very fast consumers, you can increase
consumer-window-size. This effectively disables consumer flow consumer-window-size. This effectively disables consumer flow
@ -128,7 +127,7 @@ tuning:
- Socket NIO vs Socket Old IO. By default ActiveMQ uses old (blocking) - Socket NIO vs Socket Old IO. By default ActiveMQ uses old (blocking)
on the server and the client side (see the chapter on configuring on the server and the client side (see the chapter on configuring
transports for more information ?). NIO is much more scalable but transports for more information [Configuring the Transport](configuring-transports.md). NIO is much more scalable but
can give you some latency hit compared to old blocking IO. If you can give you some latency hit compared to old blocking IO. If you
need to be able to service many thousands of connections on the need to be able to service many thousands of connections on the
server, then you should make sure you're using NIO on the server. server, then you should make sure you're using NIO on the server.
@ -145,12 +144,12 @@ tuning:
the wire, so if you re-use `SimpleString` instances between calls the wire, so if you re-use `SimpleString` instances between calls
then you can avoid some unnecessary copying. then you can avoid some unnecessary copying.
Tuning Transport Settings ## Tuning Transport Settings
=========================
- TCP buffer sizes. If you have a fast network and fast machines you - TCP buffer sizes. If you have a fast network and fast machines you
may get a performance boost by increasing the TCP send and receive may get a performance boost by increasing the TCP send and receive
buffer sizes. See the ? for more information on this. buffer sizes. See the [Configuring the Transport](configuring-transports.md)
for more information on this.
> **Note** > **Note**
> >
@ -180,10 +179,10 @@ Tuning Transport Settings
`activemq-configuration.xml` and JMS connection factory `activemq-configuration.xml` and JMS connection factory
(`ThroughputConnectionFactory`) in `activemq-jms.xml`which can be (`ThroughputConnectionFactory`) in `activemq-jms.xml`which can be
used to give the very best throughput, especially for small used to give the very best throughput, especially for small
messages. See the ? for more information on this. messages. See the [Configuring the Transport](configuring-transports.md)
for more information on this.
Tuning the VM ## Tuning the VM
=============
We highly recommend you use the latest Java JVM for the best We highly recommend you use the latest Java JVM for the best
performance. We test internally using the Sun JVM, so some of these performance. We test internally using the Sun JVM, so some of these
@ -194,7 +193,7 @@ tunings won't apply to JDKs from other providers (e.g. IBM or JRockit)
`-XX:+UseParallelOldGC` on Sun JDKs. `-XX:+UseParallelOldGC` on Sun JDKs.
- Memory settings. Give as much memory as you can to the server. - Memory settings. Give as much memory as you can to the server.
ActiveMQ can run in low memory by using paging (described in ?) but ActiveMQ can run in low memory by using paging (described in [Paging](paging.md)) but
if it can run with all queues in RAM this will improve performance. if it can run with all queues in RAM this will improve performance.
The amount of memory you require will depend on the size and number The amount of memory you require will depend on the size and number
of your queues and the size and number of your messages. Use the JVM of your queues and the size and number of your messages. Use the JVM
@ -210,8 +209,7 @@ tunings won't apply to JDKs from other providers (e.g. IBM or JRockit)
some mileage with the other tuning parameters depending on your OS some mileage with the other tuning parameters depending on your OS
platform and application usage patterns. platform and application usage patterns.
Avoiding Anti-Patterns ## Avoiding Anti-Patterns
======================
- Re-use connections / sessions / consumers / producers. Probably the - Re-use connections / sessions / consumers / producers. Probably the
most common messaging anti-pattern we see is users who create a new most common messaging anti-pattern we see is users who create a new

42
docs/user-manual/en/persistence.md
View File

@ -1,5 +1,4 @@
Persistence # Persistence
===========
In this chapter we will describe how persistence works with ActiveMQ and In this chapter we will describe how persistence works with ActiveMQ and
how to configure it. how to configure it.
@ -63,14 +62,14 @@ implementations. ActiveMQ ships with two implementations:
The AIO journal is only available when running Linux kernel 2.6 or The AIO journal is only available when running Linux kernel 2.6 or
later and after having installed libaio (if it's not already later and after having installed libaio (if it's not already
installed). For instructions on how to install libaio please see ?. installed). For instructions on how to install libaio please see Installing AIO section.
Also, please note that AIO will only work with the following file Also, please note that AIO will only work with the following file
systems: ext2, ext3, ext4, jfs, xfs. With other file systems, e.g. systems: ext2, ext3, ext4, jfs, xfs. With other file systems, e.g.
NFS it may appear to work, but it will fall back to a slower NFS it may appear to work, but it will fall back to a slower
synchronous behaviour. Don't put the journal on a NFS share! synchronous behaviour. Don't put the journal on a NFS share!
For more information on libaio please see ?. For more information on libaio please see [lib AIO](libaio.md).
libaio is part of the kernel project. libaio is part of the kernel project.
@ -118,16 +117,16 @@ The standard ActiveMQ core server uses two instances of the journal:
(configurable), and it is located at the journal folder. (configurable), and it is located at the journal folder.
For large messages, ActiveMQ persists them outside the message journal. For large messages, ActiveMQ persists them outside the message journal.
This is discussed in ?. This is discussed in [Large Messages](large-messages.md).
ActiveMQ can also be configured to page messages to disk in low memory ActiveMQ can also be configured to page messages to disk in low memory
situations. This is discussed in ?. situations. This is discussed in [Paging](paging.md).
If no persistence is required at all, ActiveMQ can also be configured If no persistence is required at all, ActiveMQ can also be configured
not to persist any data at all to storage as discussed in ?. not to persist any data at all to storage as discussed in the Configuring
HornetQ for Zero Persistence section.
Configuring the bindings journal ## Configuring the bindings journal
================================
The bindings journal is configured using the following attributes in The bindings journal is configured using the following attributes in
`activemq-configuration.xml` `activemq-configuration.xml`
@ -144,13 +143,11 @@ The bindings journal is configured using the following attributes in
`bindings-directory` if it does not already exist. The default value `bindings-directory` if it does not already exist. The default value
is `true` is `true`
Configuring the jms journal ## Configuring the jms journal
===========================
The jms config shares its configuration with the bindings journal. The jms config shares its configuration with the bindings journal.
Configuring the message journal ## Configuring the message journal
===============================
The message journal is configured using the following attributes in The message journal is configured using the following attributes in
`activemq-configuration.xml` `activemq-configuration.xml`
@ -283,8 +280,7 @@ The message journal is configured using the following attributes in
The default for this parameter is `30` The default for this parameter is `30`
An important note on disabling disk write cache. ## An important note on disabling disk write cache.
================================================
> **Warning** > **Warning**
> >
@ -323,8 +319,7 @@ An important note on disabling disk write cache.
> On Windows you can check / change the setting by right clicking on the > On Windows you can check / change the setting by right clicking on the
> disk and clicking properties. > disk and clicking properties.
Installing AIO ## Installing AIO
==============
The Java NIO journal gives great performance, but If you are running 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 ActiveMQ using Linux Kernel 2.6 or later, we highly recommend you use
@ -344,8 +339,7 @@ Using aptitude, (e.g. on Ubuntu or Debian system):
apt-get install libaio apt-get install libaio
Configuring ActiveMQ for Zero Persistence ## Configuring ActiveMQ for Zero Persistence
=========================================
In some situations, zero persistence is sometimes required for a In some situations, zero persistence is sometimes required for a
messaging system. Configuring ActiveMQ to perform zero persistence is messaging system. Configuring ActiveMQ to perform zero persistence is
@ -356,8 +350,7 @@ Please note that if you set this parameter to false, then *zero*
persistence will occur. That means no bindings data, message data, large persistence will occur. That means no bindings data, message data, large
message data, duplicate id caches or paging data will be persisted. message data, duplicate id caches or paging data will be persisted.
Import/Export the Journal Data ## Import/Export the Journal Data
==============================
You may want to inspect the existent records on each one of the journals You may want to inspect the existent records on each one of the journals
used by ActiveMQ, and you can use the export/import tool for that used by ActiveMQ, and you can use the export/import tool for that
@ -379,13 +372,12 @@ require netty.jar):
folder. Example: ./activemq/data/journal folder. Example: ./activemq/data/journal
- JournalPrefix: Use the prefix for your selected journal, as - JournalPrefix: Use the prefix for your selected journal, as
discussed [here](#persistence.journallist) discussed above
- FileExtension: Use the extension for your selected journal, as - FileExtension: Use the extension for your selected journal, as
discussed [here](#persistence.journallist) discussed above
- FileSize: Use the size for your selected journal, as discussed - FileSize: Use the size for your selected journal, as discussed above
[here](#persistence.journallist)
- FileOutput: text file that will contain the exported data - FileOutput: text file that will contain the exported data

12
docs/user-manual/en/pre-acknowledge.md
View File

@ -1,5 +1,4 @@
Extra Acknowledge Modes # Extra Acknowledge Modes
=======================
JMS specifies 3 acknowledgement modes: JMS specifies 3 acknowledgement modes:
@ -41,8 +40,7 @@ arrive soon, overriding the previous price.
> the transaction. This may be stating the obvious but we like to be > the transaction. This may be stating the obvious but we like to be
> clear on these things to avoid confusion! > clear on these things to avoid confusion!
Using PRE\_ACKNOWLEDGE ## Using PRE_ACKNOWLEDGE
======================
This can be configured in a client's JNDI context environment, e.g. This can be configured in a client's JNDI context environment, e.g.
`jndi.properties`, like this: `jndi.properties`, like this:
@ -63,8 +61,7 @@ Or you can set pre-acknowledge directly on the
To use pre-acknowledgement mode using the core API you can set it To use pre-acknowledgement mode using the core API you can set it
directly on the `ClientSessionFactory` instance using the setter method. directly on the `ClientSessionFactory` instance using the setter method.
Individual Acknowledge ## Individual Acknowledge
======================
A valid use-case for individual acknowledgement would be when you need 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 to have your own scheduling and you don't know when your message
@ -85,8 +82,7 @@ the exception the message is individually acked.
> adapter). this is because you have to finish the process of your > adapter). this is because you have to finish the process of your
> message inside the MDB. > message inside the MDB.
Example ## Example
=======
See ? for an example which shows how to use pre-acknowledgement mode See ? for an example which shows how to use pre-acknowledgement mode
with JMS. with JMS.

9
docs/user-manual/en/preface.md
View File

@ -1,5 +1,4 @@
Preface # Preface
=======
What is ActiveMQ? What is ActiveMQ?
@ -8,11 +7,11 @@ What is ActiveMQ?
system. system.
- ActiveMQ is an example of Message Oriented Middleware (MoM). For a - ActiveMQ is an example of Message Oriented Middleware (MoM). For a
description of MoMs and other messaging concepts please see the ?. description of MoMs and other messaging concepts please see the [Messaging Concepts](messaging-concepts.md).
- For answers to more questions about what ActiveMQ is and what it - For answers to more questions about what ActiveMQ is and what it
isn't please visit the [FAQs wiki isn't please visit the [FAQs wiki
page](http://www.jboss.org/community/wiki/ActiveMQGeneralFAQs). page](todo).
Why use ActiveMQ? Here are just a few of the reasons: Why use ActiveMQ? Here are just a few of the reasons:
@ -47,6 +46,6 @@ Why use ActiveMQ? Here are just a few of the reasons:
routing of messages in a highly flexible way. routing of messages in a highly flexible way.
- For a full list of features, please see the [features wiki - For a full list of features, please see the [features wiki
page](http://www.jboss.org/community/wiki/ActiveMQFeatures) . page](todo) .

42
docs/user-manual/en/project-info.md
View File

@ -1,50 +1,30 @@
Project Information # Project Information
===================
The official ActiveMQ project page is <http://activemq.org/>. The official ActiveMQ project page is <http://activemq.apache.org//>.
Software Download ## Software Download
=================
The software can be download from the Download The software can be download from the Download
page:<http://activemq.org/downloads.html> page:<http://activemq.apache.org/download.html>
Project Information ## Project Information
===================
- Please take a look at our project
[wiki](http://www.jboss.org/community/wiki/ActiveMQ)
- If you have any user questions please use our [user - If you have any user questions please use our [user
forum](https://community.jboss.org/en/activemq) forum](http://activemq.2283324.n4.nabble.com/ActiveMQ-User-f2341805.html)
- If you have development related questions, please use our [developer - If you have development related questions, please use our [developer
forum](https://community.jboss.org/en/activemq/dev) forum](http://activemq.2283324.n4.nabble.com/ActiveMQ-Dev-f2368404.html)
- Pop in and chat to us in our [IRC - Pop in and chat to us in our [IRC
channel](irc://irc.freenode.net:6667/activemq) channel](irc://irc.freenode.net:6667/activemq)
- Our project [blog](http://activemq.blogspot.com/) - Follow us on [twitter](https://twitter.com/activemq)
- Follow us on [twitter](http://twitter.com/activemq) - ActiveMQ Git repository is <https://github.com/apache/activemq-6>
- ActiveMQ Git repository is <https://github.com/activemq/activemq>
- All release tags are available from - All release tags are available from
<https://github.com/activemq/activemq/tags> <https://github.com/apache/activemq-6/releases>
Red Hat kindly employs developers to work full time on ActiveMQ, they
are:
- Clebert Suconic (project lead)
- Andy Taylor
- Howard Gao
- Justin Bertram
And many thanks to all our contributors, both old and new who helped 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 create ActiveMQ.
a look at our [team
page](http://jboss.org.apache.activemq/community/team.html).

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

@ -1,90 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- ============================================================================= -->
<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
<!-- contributor license agreements. See the NOTICE file distributed with -->
<!-- this work for additional information regarding copyright ownership. -->
<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
<!-- (the "License"); you may not use this file except in compliance with -->
<!-- the License. You may obtain a copy of the License at -->
<!-- -->
<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
<!-- -->
<!-- Unless required by applicable law or agreed to in writing, software -->
<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
<!-- See the License for the specific language governing permissions and -->
<!-- limitations under the License. -->
<!-- ============================================================================= -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
%BOOK_ENTITIES;
]>
<chapter id="project-info">
<title>Project Information</title>
<para>The official ActiveMQ project page is <ulink url="http://activemq.org/"
>http://activemq.org/</ulink>.</para>
<section id="download.software">
<title>Software Download</title>
<para>The software can be download from the Download page:<ulink
url="http://activemq.org/downloads.html">http://activemq.org/downloads.html</ulink></para>
</section>
<section id="download.git">
<title>Project Information</title>
<para>
<itemizedlist>
<listitem>
<para>Please take a look at our project <ulink
url="http://www.jboss.org/community/wiki/ActiveMQ">wiki</ulink></para>
</listitem>
<listitem>
<para>If you have any user questions please use our <ulink
url="https://community.jboss.org/en/activemq">user
forum</ulink></para>
</listitem>
<listitem>
<para>If you have development related questions, please use our <ulink
url="https://community.jboss.org/en/activemq/dev"
>developer forum</ulink></para>
</listitem>
<listitem>
<para>Pop in and chat to us in our <ulink url="irc://irc.freenode.net:6667/activemq"
>IRC channel</ulink></para>
</listitem>
<listitem>
<para>Our project <ulink url="http://activemq.blogspot.com/">blog</ulink></para>
</listitem>
<listitem>
<para>Follow us on <ulink url="http://twitter.com/activemq">twitter</ulink></para>
</listitem>
<listitem>
<para>ActiveMQ Git repository is <ulink
url="https://github.com/activemq/activemq"
>https://github.com/activemq/activemq</ulink></para>
</listitem>
<listitem>
<para>All release tags are available from <ulink
url="https://github.com/activemq/activemq/tags"
>https://github.com/activemq/activemq/tags</ulink></para>
</listitem>
</itemizedlist>
</para>
<para>Red Hat kindly employs developers to work full time on ActiveMQ, they are: <itemizedlist>
<listitem>
<para>Clebert Suconic (project lead)</para>
</listitem>
<listitem>
<para>Andy Taylor</para>
</listitem>
<listitem>
<para>Howard Gao</para>
</listitem>
<listitem>
<para>Justin Bertram</para>
</listitem>
</itemizedlist></para>
<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
url="http://jboss.org.apache.activemq/community/team.html">team page</ulink>. </para>
</section>
</chapter>

18
docs/user-manual/en/queue-attributes.md
View File

@ -1,13 +1,11 @@
Queue Attributes # Queue Attributes
================
Queue attributes can be set in one of two ways. Either by configuring Queue attributes can be set in one of two ways. Either by configuring
them using the configuration file or by using the core API. This chapter them using the configuration file or by using the core API. This chapter
will explain how to configure each attribute and what effect the will explain how to configure each attribute and what effect the
attribute has. attribute has.
Predefined Queues ## Predefined Queues
=================
Queues can be predefined via configuration at a core level or at a JMS Queues can be predefined via configuration at a core level or at a JMS
level. Firstly let's look at a JMS level. level. Firstly let's look at a JMS level.
@ -59,11 +57,10 @@ which are.
3. There is no entry element. 3. There is no entry element.
4. The filter uses the *Core filter syntax* (described in ?), *not* the 4. The filter uses the *Core filter syntax* (described in [filter Expressions](filter-expressions.md)), *not* the
JMS selector syntax. JMS selector syntax.
Using the API ## Using the API
=============
Queues can also be created using the core API or the management API. Queues can also be created using the core API or the management API.
@ -74,11 +71,10 @@ previously mentioned attributes. There is one extra attribute that can
be set via this API which is `temporary`. setting this to true means be set via this API which is `temporary`. setting this to true means
that the queue will be deleted once the session is disconnected. that the queue will be deleted once the session is disconnected.
Take a look at ? for a description of the management API for creating Take a look at [Management](management.md) for a description of the management API for creating
queues. queues.
Configuring Queues Via Address Settings ## Configuring Queues Via Address Settings
=======================================
There are some attributes that are defined against an address wildcard There are some attributes that are defined against an address wildcard
rather than a specific queue. Here an example of an `address-setting` rather than a specific queue. Here an example of an `address-setting`
@ -163,7 +159,7 @@ to disk. If the value is DROP then further messages will be silently
dropped. If the value is FAIL then further messages will be dropped and dropped. If the value is FAIL then further messages will be dropped and
an exception will be thrown on the client-side. If the value is BLOCK an exception will be thrown on the client-side. If the value is BLOCK
then client message producers will block when they try and send further then client message producers will block when they try and send further
messages. See the following chapters for more info ?, ?. messages. See the following chapters for more info [Flow Control](flow-control.md), [Paging](paging.md).
`slow-consumer-threshold`. The minimum rate of message consumption `slow-consumer-threshold`. The minimum rate of message consumption
allowed before a consumer is considered "slow." Measured in allowed before a consumer is considered "slow." Measured in

112
docs/user-manual/en/rest.md
View File

@ -1,5 +1,4 @@
REST Interface # REST Interface
==============
The ActiveMQ REST interface allows you to leverage the reliability and The ActiveMQ REST interface allows you to leverage the reliability and
scalability features of ActiveMQ over a simple REST/HTTP interface. scalability features of ActiveMQ over a simple REST/HTTP interface.
@ -24,8 +23,7 @@ as a JMS message and distributed through core ActiveMQ. Simple and easy.
Consuming messages from a queue or topic looks very similar. We'll Consuming messages from a queue or topic looks very similar. We'll
discuss the entire interface in detail later in this docbook. discuss the entire interface in detail later in this docbook.
Goals of REST Interface ## Goals of REST Interface
=======================
Why would you want to use ActiveMQ's REST interface? What are the goals Why would you want to use ActiveMQ's REST interface? What are the goals
of the REST interface? of the REST interface?
@ -54,8 +52,7 @@ of the REST interface?
ActiveMQ on the back end without sacrificing the simplicity of a ActiveMQ on the back end without sacrificing the simplicity of a
REST interface. REST interface.
Installation and Configuration ## Installation and Configuration
==============================
ActiveMQ's REST interface is installed as a Web archive (WAR). It ActiveMQ's REST interface is installed as a Web archive (WAR). It
depends on the [RESTEasy](http://jboss.org/resteasy) project and can depends on the [RESTEasy](http://jboss.org/resteasy) project and can
@ -66,8 +63,7 @@ deploying within JBoss AS 7) or you want the ActiveMQ REST WAR to
startup and manage the ActiveMQ server (e.g. you're deploying within startup and manage the ActiveMQ server (e.g. you're deploying within
something like Apache Tomcat). something like Apache Tomcat).
Installing Within Pre-configured Environment ### Installing Within Pre-configured Environment
--------------------------------------------
This section should be used when you want to use the ActiveMQ REST This section should be used when you want to use the ActiveMQ REST
interface in an environment that already has ActiveMQ installed and interface in an environment that already has ActiveMQ installed and
@ -178,8 +174,7 @@ more about this later.
> It is possible to put the WAR file at the "root context" of AS7, but > It is possible to put the WAR file at the "root context" of AS7, but
> that is beyond the scope of this documentation. > that is beyond the scope of this documentation.
Bootstrapping ActiveMQ Along with REST ### Bootstrapping ActiveMQ Along with REST
--------------------------------------
You can bootstrap ActiveMQ within your WAR as well. To do this, you must You can bootstrap ActiveMQ within your WAR as well. To do this, you must
have the ActiveMQ core and JMS jars along with Netty, Resteasy, and the have the ActiveMQ core and JMS jars along with Netty, Resteasy, and the
@ -293,8 +288,7 @@ WEB-INF/classes directory!
</dependencies> </dependencies>
</project> </project>
REST Configuration ### REST Configuration
------------------
The ActiveMQ REST implementation does have some configuration options. The ActiveMQ REST implementation does have some configuration options.
These are configured via XML configuration file that must be in your These are configured via XML configuration file that must be in your
@ -362,8 +356,7 @@ Let's give an explanation of each config option.
same as the ActiveMQ one of the same name. It will be used by same as the ActiveMQ one of the same name. It will be used by
sessions created by the ActiveMQ REST implementation. sessions created by the ActiveMQ REST implementation.
ActiveMQ REST Interface Basics ## ActiveMQ REST Interface Basics
==============================
The ActiveMQ REST interface publishes a variety of REST resources to 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
@ -372,8 +365,7 @@ all over resources to interact with by looking for and traversing links.
You'll find published links within custom response headers and embedded You'll find published links within custom response headers and embedded
in published XML representations. Let's look at how this works. in published XML representations. Let's look at how this works.
Queue and Topic Resources ### Queue and Topic Resources
-------------------------
To interact with a queue or topic you do a HEAD or GET request on the To interact with a queue or topic you do a HEAD or GET request on the
following relative URI pattern: following relative URI pattern:
@ -420,8 +412,7 @@ every time you initially interact (at boot time) with the server. If you
treat all URLs as opaque then you will be isolated from implementation treat all URLs as opaque then you will be isolated from implementation
changes as the ActiveMQ REST interface evolves over time. changes as the ActiveMQ REST interface evolves over time.
Queue Resource Response Headers ### Queue Resource Response Headers
-------------------------------
Below is a list of response headers you should expect when interacting Below is a list of response headers you should expect when interacting
with a Queue resource. with a Queue resource.
@ -441,8 +432,7 @@ with a Queue resource.
want the ActiveMQ REST server to push messages to. The semantics of want the ActiveMQ REST server to push messages to. The semantics of
this link are described in [Pushing Messages](#message-push). this link are described in [Pushing Messages](#message-push).
Topic Resource Response Headers ### Topic Resource Response Headers
-------------------------------
Below is a list of response headers you should expect when interacting Below is a list of response headers you should expect when interacting
with a Topic resource. with a Topic resource.
@ -462,8 +452,7 @@ with a Topic resource.
you want the ActiveMQ REST server to push messages to. The semantics you want the ActiveMQ REST server to push messages to. The semantics
of this link are described in [Pushing Messages](#message-push). of this link are described in [Pushing Messages](#message-push).
Posting Messages ## Posting Messages
================
This chapter discusses the protocol for posting messages to a queue or a This chapter discusses the protocol for posting messages to a queue or a
topic. In [ActiveMQ REST Interface Basics](#basics), you saw that a topic. In [ActiveMQ REST Interface Basics](#basics), you saw that a
@ -548,8 +537,7 @@ ActiveMQ destination. Here's an example scenario:
> then just go back to the queue or topic resource to get the > then just go back to the queue or topic resource to get the
> `msg-create` URL again. > `msg-create` URL again.
Duplicate Detection ### Duplicate Detection
-------------------
Sometimes you might have network problems when posting new messages to a Sometimes you might have network problems when posting new messages to a
queue or topic. You may do a POST and never receive a response. queue or topic. You may do a POST and never receive a response.
@ -670,8 +658,7 @@ The advantage of this approach is that the client does not have to
repost the message. It also only has to come up with a unique repost the message. It also only has to come up with a unique
`DUPLICATE_DETECTION_ID` once. `DUPLICATE_DETECTION_ID` once.
Persistent Messages ### Persistent Messages
-------------------
By default, posted messages are not durable and will not be persisted in By default, posted messages are not durable and will not be persisted in
ActiveMQ's journal. You can create durable messages by modifying the ActiveMQ's journal. You can create durable messages by modifying the
@ -691,8 +678,7 @@ headers. here's an example of that.
<cost>$199.99</cost> <cost>$199.99</cost>
</order> </order>
TTL, Expiration and Priority ### TTL, Expiration and Priority
----------------------------
You can set the time to live, expiration, and/or the priority of the You can set the time to live, expiration, and/or the priority of the
message in the queue or topic by setting an additional query parameter. message in the queue or topic by setting an additional query parameter.
@ -712,8 +698,7 @@ the priority of the message. i.e.:
<cost>$199.99</cost> <cost>$199.99</cost>
</order> </order>
Consuming Messages via Pull ## Consuming Messages via Pull
===========================
There are two different ways to consume messages from a topic or queue. There are two different ways to consume messages from a topic or queue.
You can wait and have the messaging server push them to you, or you can You can wait and have the messaging server push them to you, or you can
@ -769,8 +754,7 @@ parameters (`application/x-www-form-urlencoded`) described below.
> then one consumer might buffer messages while the other consumer gets > then one consumer might buffer messages while the other consumer gets
> none. > none.
Auto-Acknowledge ### Auto-Acknowledge
----------------
This section focuses on the auto-acknowledge protocol for consuming This section focuses on the auto-acknowledge protocol for consuming
messages via a pull. Here's a list of the response headers and URLs messages via a pull. Here's a list of the response headers and URLs
@ -790,7 +774,7 @@ you'll be interested in.
- `msg-consumer`. This is a URL pointing back to the consumer or - `msg-consumer`. This is a URL pointing back to the consumer or
subscription resource created for the client. subscription resource created for the client.
### Creating an Auto-Ack Consumer or Subscription #### Creating an Auto-Ack Consumer or Subscription
Here is an example of creating an auto-acknowledged queue pull consumer. Here is an example of creating an auto-acknowledged queue pull consumer.
@ -858,7 +842,7 @@ pull subscription.
although, as you'll see later, it is transmitted with each response although, as you'll see later, it is transmitted with each response
just to remind you. just to remind you.
### Consuming Messages #### Consuming Messages
After you have created a consumer resource, you are ready to start After you have created a consumer resource, you are ready to start
pulling messages from the server. Notice that when you created the pulling messages from the server. Notice that when you created the
@ -935,7 +919,7 @@ resource.
<order>...</order> <order>...</order>
### Recovering From Network Failures #### Recovering From Network Failures
If you experience a network failure and do not know if your post to a If you experience a network failure and do not know if your post to a
msg-consume-next URL was successful or not, just re-do your POST. A POST msg-consume-next URL was successful or not, just re-do your POST. A POST
@ -948,7 +932,7 @@ URL). This is the reason why the protocol always requires you to use the
next new msg-consume-next URL returned with each response. Information next new msg-consume-next URL returned with each response. Information
about what state the client is in is embedded within the actual URL. about what state the client is in is embedded within the actual URL.
### Recovering From Client or Server Crashes #### Recovering From Client or Server Crashes
If the server crashes and you do a POST to the msg-consume-next URL, the If the server crashes and you do a POST to the msg-consume-next URL, the
server will return a 412 (Preconditions Failed) response code. This is server will return a 412 (Preconditions Failed) response code. This is
@ -970,8 +954,7 @@ would happen if the server crashes after auto-acknowledging a message
and before the client receives the message. If you want more reliable and before the client receives the message. If you want more reliable
messaging, then you must use the acknowledgement protocol. messaging, then you must use the acknowledgement protocol.
Manual Acknowledgement ### Manual Acknowledgement
----------------------
The manual acknowledgement protocol is similar to the auto-ack protocol The manual acknowledgement protocol is similar to the auto-ack protocol
except there is an additional round trip to the server to tell it that except there is an additional round trip to the server to tell it that
@ -995,7 +978,7 @@ in.
- `msg-consumer`. This is a URL pointing back to the consumer or - `msg-consumer`. This is a URL pointing back to the consumer or
subscription resource created for the client. subscription resource created for the client.
### Creating manually-acknowledged consumers or subscriptions #### Creating manually-acknowledged consumers or subscriptions
Here is an example of creating an auto-acknowledged queue pull consumer. Here is an example of creating an auto-acknowledged queue pull consumer.
@ -1067,7 +1050,7 @@ topic pull subscription.
although, as you'll see later, it is transmitted with each response although, as you'll see later, it is transmitted with each response
just to remind you. just to remind you.
### Consuming and Acknowledging a Message #### Consuming and Acknowledging a Message
After you have created a consumer resource, you are ready to start After you have created a consumer resource, you are ready to start
pulling messages from the server. Notice that when you created the pulling messages from the server. Notice that when you created the
@ -1127,7 +1110,7 @@ resource.
will contain a new msg-acknowledge-next header that you must use to will contain a new msg-acknowledge-next header that you must use to
obtain the next message. obtain the next message.
### Recovering From Network Failures #### Recovering From Network Failures
If you experience a network failure and do not know if your post to a If you experience a network failure and do not know if your post to a
`msg-acknowledge-next` or `msg-acknowledgement` URL was successful or `msg-acknowledge-next` or `msg-acknowledgement` URL was successful or
@ -1142,7 +1125,7 @@ at the URLs you'll see that they contain information about the expected
current state of the server. This is how the server knows what the current state of the server. This is how the server knows what the
client is expecting. client is expecting.
### Recovering From Client or Server Crashes #### Recovering From Client or Server Crashes
If the server crashes and while you are doing a POST to the If the server crashes and while you are doing a POST to the
`msg-acknowledge-next` URL, just re-post. Everything should reconnect `msg-acknowledge-next` URL, just re-post. Everything should reconnect
@ -1168,8 +1151,7 @@ can re-create the consumer resource with the same exact name. The
response will contain the same information as if you did a GET or HEAD response will contain the same information as if you did a GET or HEAD
request on the consumer resource. request on the consumer resource.
Blocking Pulls with Accept-Wait #### Blocking Pulls with Accept-Wait
-------------------------------
Unless your queue or topic has a high rate of message flowing though it, 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 lot of 503 if you use the pull protocol, you're going to be receiving a lot of 503
@ -1195,8 +1177,7 @@ header with your pull requests. Here's an example:
In this example, we're posting to a msg-consume-next URL and telling the In this example, we're posting to a msg-consume-next URL and telling the
server that we would be willing to block for 30 seconds. server that we would be willing to block for 30 seconds.
Clean Up Your Consumers! ### Clean Up Your Consumers!
------------------------
When the client is done with its consumer or topic subscription it When the client is done with its consumer or topic subscription it
should do an HTTP DELETE call on the consumer URL passed back from the should do an HTTP DELETE call on the consumer URL passed back from the
@ -1208,16 +1189,14 @@ clean up your messes. A consumer timeout for durable subscriptions will
not delete the underlying durable JMS subscription though, only the not delete the underlying durable JMS subscription though, only the
server-side consumer resource (and underlying JMS session). server-side consumer resource (and underlying JMS session).
Pushing Messages ## Pushing Messages
================
You can configure the ActiveMQ REST server to push messages to a You can configure the ActiveMQ REST server to push messages to a
registered URL either remotely through the REST interface, or by registered URL either remotely through the REST interface, or by
creating a pre-configured XML file for the ActiveMQ REST server to load creating a pre-configured XML file for the ActiveMQ REST server to load
at boot time. at boot time.
The Queue Push Subscription XML ### The Queue Push Subscription XML
-------------------------------
Creating a push consumer for a queue first involves creating a very Creating a push consumer for a queue first involves creating a very
simple XML document. This document tells the server if the push simple XML document. This document tells the server if the push
@ -1302,8 +1281,7 @@ values a rel attribute can have:
<link href="http://somewhere.com" type="application/json" method="PUT"/> <link href="http://somewhere.com" type="application/json" method="PUT"/>
</push-registration> </push-registration>
The Topic Push Subscription XML ### The Topic Push Subscription XML
-------------------------------
The push XML for a topic is the same except the root element is The push XML for a topic is the same except the root element is
push-topic-registration. (Also remember the `selector` element is push-topic-registration. (Also remember the `selector` element is
@ -1319,8 +1297,7 @@ template registration:
<link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/> <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
</push-topic registration> </push-topic registration>
Creating a Push Subscription at Runtime ### Creating a Push Subscription at Runtime
---------------------------------------
Creating a push subscription at runtime involves getting the factory Creating a push subscription at runtime involves getting the factory
resource URL from the msg-push-consumers header, if the destination is a resource URL from the msg-push-consumers header, if the destination is a
@ -1387,8 +1364,7 @@ Here's an example of creating a push registration for a topic:
The Location header contains the URL for the created resource. If The Location header contains the URL for the created resource. If
you want to unregister this, then do a HTTP DELETE on this URL. you want to unregister this, then do a HTTP DELETE on this URL.
Creating a Push Subscription by Hand ### Creating a Push Subscription by Hand
------------------------------------
You can create a push XML file yourself if you do not want to go through You can create a push XML file yourself if you do not want to go through
the REST interface to create a push subscription. There is some the REST interface to create a push subscription. There is some
@ -1420,8 +1396,7 @@ variable defined in Chapter 2:
<topic>jms.topic.foo</topic> <topic>jms.topic.foo</topic>
</push-topic-registration> </push-topic-registration>
Pushing to Authenticated Servers ### Pushing to Authenticated Servers
--------------------------------
Push subscriptions only support BASIC and DIGEST authentication out of Push subscriptions only support BASIC and DIGEST authentication out of
the box. Here is an example of adding BASIC authentication: the box. Here is an example of adding BASIC authentication:
@ -1450,8 +1425,7 @@ headers might look like:
<header name="secret-header">jfdiwe3321</header> <header name="secret-header">jfdiwe3321</header>
</push-topic registration> </push-topic registration>
Creating Destinations ## Creating Destinations
=====================
You can create a durable queue or topic through the REST interface. You can create a durable queue or topic through the REST interface.
Currently you cannot create a temporary queue or topic. To create a Currently you cannot create a temporary queue or topic. To create a
@ -1487,11 +1461,9 @@ Here's what creating a topic would look like:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Location: http://example.com/topics/jms.topic.testTopic Location: http://example.com/topics/jms.topic.testTopic
Securing the ActiveMQ REST Interface ## Securing the ActiveMQ REST Interface
====================================
Within JBoss Application server ### Within JBoss Application server
-------------------------------
Securing the ActiveMQ REST interface is very simple with the JBoss 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
@ -1499,8 +1471,7 @@ WAR's web.xml, and let the user Principal to propagate to ActiveMQ. This
only works if you are using the JBossSecurityManager with ActiveMQ. See only works if you are using the JBossSecurityManager with ActiveMQ. See
the ActiveMQ documentation for more details. the ActiveMQ documentation for more details.
Security in other environments ### Security in other environments
------------------------------
To secure the ActiveMQ REST interface in other environments you must To secure the ActiveMQ REST interface in other environments you must
role your own security by specifying security constraints with your role your own security by specifying security constraints with your
@ -1520,8 +1491,7 @@ is a list of URI patterns:
/topics/{topic-name}/push-subscriptions/\* secure this URL pattern for pushing messages. /topics/{topic-name}/push-subscriptions/\* secure this URL pattern for pushing messages.
-------------------------------------------- ----------------------------------------------------------------------- -------------------------------------------- -----------------------------------------------------------------------
Mixing JMS and REST ## Mixing JMS and REST
===================
The ActiveMQ REST interface supports mixing JMS and REST producers and The ActiveMQ REST interface supports mixing JMS and REST producers and
consumers. You can send an ObjectMessage through a JMS Producer, and consumers. You can send an ObjectMessage through a JMS Producer, and
@ -1530,8 +1500,7 @@ to a topic and have a JMS Consumer receive it. Some simple
transformations are supported if you have the correct RESTEasy providers transformations are supported if you have the correct RESTEasy providers
installed. installed.
JMS Producers - REST Consumers ### JMS Producers - REST Consumers
------------------------------
If you have a JMS producer, the ActiveMQ REST interface only supports If you have a JMS producer, the ActiveMQ REST interface only supports
ObjectMessage type. If the JMS producer is aware that there may be REST ObjectMessage type. If the JMS producer is aware that there may be REST
@ -1551,8 +1520,7 @@ types it wants to convert the Java object into. If the REST client is a
push registration, then the type attribute of the link element of the push registration, then the type attribute of the link element of the
push registration should be set to the desired type. push registration should be set to the desired type.
REST Producers - JMS Consumers ### REST Producers - JMS Consumers
------------------------------
If you have a REST client producing messages and a JMS consumer, If you have a REST client producing messages and a JMS consumer,
ActiveMQ 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

24
docs/user-manual/en/scheduled-messages.md
View File

@ -1,13 +1,11 @@
Scheduled Messages # Scheduled Messages
==================
Scheduled messages differ from normal messages in that they won't be Scheduled messages differ from normal messages in that they won't be
delivered until a specified time in the future, at the earliest. delivered until a specified time in the future, at the earliest.
To do this, a special property is set on the message before sending it. To do this, a special property is set on the message before sending it.
Scheduled Delivery Property ## Scheduled Delivery Property
===========================
The property name used to identify a scheduled message is The property name used to identify a scheduled message is
`"_HQ_SCHED_DELIVERY"` (or the constant `"_HQ_SCHED_DELIVERY"` (or the constant
@ -17,20 +15,20 @@ The specified value must be a positive `long` corresponding to the time
the message must be delivered (in milliseconds). An example of sending a the message must be delivered (in milliseconds). An example of sending a
scheduled message using the JMS API is as follows. scheduled message using the JMS API is as follows.
TextMessage message = session.createTextMessage("This is a scheduled message message which will be delivered in 5 sec."); ``` java
message.setLongProperty("_HQ_SCHED_DELIVERY", System.currentTimeMillis() + 5000); TextMessage message = session.createTextMessage("This is a scheduled message message which will be delivered in 5 sec.");
producer.send(message); message.setLongProperty("_HQ_SCHED_DELIVERY", System.currentTimeMillis() + 5000);
producer.send(message);
... ...
// message will not be received immediately but 5 seconds later
TextMessage messageReceived = (TextMessage) consumer.receive();
// message will not be received immediately but 5 seconds later
TextMessage messageReceived = (TextMessage) consumer.receive();
```
Scheduled messages can also be sent using the core API, by setting the Scheduled messages can also be sent using the core API, by setting the
same property on the core message before sending. same property on the core message before sending.
Example ## Example
=======
See ? for an example which shows how scheduled messages can be used with See ? for an example which shows how scheduled messages can be used with
JMS. JMS.

44
docs/user-manual/en/security.md
View File

@ -1,5 +1,4 @@
Security # Security
========
This chapter describes how security works with ActiveMQ and how you can This chapter describes how security works with ActiveMQ and how you can
configure it. To disable security completely simply set the configure it. To disable security completely simply set the
@ -11,13 +10,12 @@ long. To change this period set the property
`security-invalidation-interval`, which is in milliseconds. The default `security-invalidation-interval`, which is in milliseconds. The default
is `10000` ms. is `10000` ms.
Role based security for addresses ## Role based security for addresses
=================================
ActiveMQ contains a flexible role-based security model for applying ActiveMQ contains a flexible role-based security model for applying
security to queues, based on their addresses. security to queues, based on their addresses.
As explained in ?, ActiveMQ core consists mainly of sets of queues bound As explained in [Using Core](using-core.md), ActiveMQ core consists mainly of sets of queues bound
to addresses. A message is sent to an address and the server looks up 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 set of queues that are bound to that address, the server then routes
the message to those set of queues. the message to those set of queues.
@ -69,7 +67,8 @@ Let's take a simple example, here's a security block from
The '`#`' character signifies "any sequence of words". Words are The '`#`' character signifies "any sequence of words". Words are
delimited by the '`.`' character. For a full description of the wildcard delimited by the '`.`' character. For a full description of the wildcard
syntax please see ?. The above security block applies to any address syntax please see [Understanding the HornetQ Wildcard Syntax](wildcard-syntax.md).
The above security block applies to any address
that starts with the string "globalqueues.europe.": that starts with the string "globalqueues.europe.":
Only users who have the `admin` role can create or delete durable queues Only users who have the `admin` role can create or delete durable queues
@ -88,7 +87,7 @@ security manager. ActiveMQ ships with a user manager that reads user
credentials from a file on disk, and can also plug into JAAS or JBoss credentials from a file on disk, and can also plug into JAAS or JBoss
Application Server security. Application Server security.
For more information on configuring the security manager, please see ?. For more information on configuring the security manager, please see 'Changing the Security Manager'.
There can be zero or more `security-setting` elements in each xml file. There can be zero or more `security-setting` elements in each xml file.
Where more than one match applies to a set of addresses the *more Where more than one match applies to a set of addresses the *more
@ -121,18 +120,16 @@ permissions in more specific security-setting blocks by simply not
specifying them. Otherwise it would not be possible to deny permissions specifying them. Otherwise it would not be possible to deny permissions
in sub-groups of addresses. in sub-groups of addresses.
Secure Sockets Layer (SSL) Transport ## Secure Sockets Layer (SSL) Transport
====================================
When messaging clients are connected to servers, or servers are When messaging clients are connected to servers, or servers are
connected to other servers (e.g. via bridges) over an untrusted network connected to other servers (e.g. via bridges) over an untrusted network
then ActiveMQ allows that traffic to be encrypted using the Secure then ActiveMQ allows that traffic to be encrypted using the Secure
Sockets Layer (SSL) transport. Sockets Layer (SSL) transport.
For more information on configuring the SSL transport, please see ?. For more information on configuring the SSL transport, please see [Configuring the Transport](configuring-transports.md).
Basic user credentials ## Basic user credentials
======================
ActiveMQ ships with a security manager implementation that reads user ActiveMQ ships with a security manager implementation that reads user
credentials, i.e. user names, passwords and role information from an xml credentials, i.e. user names, passwords and role information from an xml
@ -178,8 +175,7 @@ We then have three more users, the user `tim` has the role `admin`. The
user `andy` has the roles `admin` and `guest`, and the user `jeff` has user `andy` has the roles `admin` and `guest`, and the user `jeff` has
the roles `europe-users` and `guest`. the roles `europe-users` and `guest`.
Changing the security manager ## Changing the security manager
=============================
If you do not want to use the default security manager then you can If you do not want to use the default security manager then you can
specify a different one by editing the file `activemq-beans.xml` (or specify a different one by editing the file `activemq-beans.xml` (or
@ -209,8 +205,7 @@ running JBoss Application Server).
These two implementations are discussed in the next two sections. These two implementations are discussed in the next two sections.
JAAS Security Manager ## JAAS Security Manager
=====================
JAAS stands for 'Java Authentication and Authorization Service' and is a JAAS stands for 'Java Authentication and Authorization Service' and is a
standard part of the Java platform. It provides a common API for standard part of the Java platform. It provides a common API for
@ -245,14 +240,12 @@ properties:
- CallbackHandler: the `CallbackHandler` implementation to use if user - CallbackHandler: the `CallbackHandler` implementation to use if user
interaction are required interaction are required
Example ## Example
-------
See ? for an example which shows how ActiveMQ can be configured to use See ? for an example which shows how ActiveMQ can be configured to use
JAAS. JAAS.
JBoss AS Security Manager ## JBoss AS Security Manager
=========================
The JBoss AS security manager is used when running ActiveMQ inside the The JBoss AS security manager is used when running ActiveMQ inside the
JBoss Application server. This allows tight integration with the JBoss JBoss Application server. This allows tight integration with the JBoss
@ -265,8 +258,7 @@ Take a look at one of the default `activemq-jboss-beans.xml` files for
JBoss Application Server that are bundled in the distribution for an JBoss Application Server that are bundled in the distribution for an
example of how this is configured. example of how this is configured.
Configuring Client Login ### Configuring Client Login
------------------------
JBoss can be configured to allow client login, basically this is when a 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 JEE component such as a Servlet or EJB sets security credentials on the
@ -287,20 +279,18 @@ There is more info on using the JBoss client login module
> meaning that the security context has been cleared. If this is the > meaning that the security context has been cleared. If this is the
> case then messages will need to be sent blocking > case then messages will need to be sent blocking
Changing the Security Domain ### Changing the Security Domain
----------------------------
The name of the security domain used by the JBoss AS security manager The name of the security domain used by the JBoss AS security manager
defaults to `java:/jaas/activemq defaults to `java:/jaas/activemq
`. This can be changed by specifying `securityDomainName` `. This can be changed by specifying `securityDomainName`
(e.g. java:/jaas/myDomain). (e.g. java:/jaas/myDomain).
Changing the username/password for clustering ## Changing the username/password for clustering
=============================================
In order for cluster connections to work correctly, each node in the In order for cluster connections to work correctly, each node in the
cluster must make connections to the other nodes. The username/password cluster must make connections to the other nodes. The username/password
they use for this should always be changed from the installation default they use for this should always be changed from the installation default
to prevent a security risk. to prevent a security risk.
Please see ? for instructions on how to do this. Please see [Management](management.md) for instructions on how to do this.

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

@ -1,8 +1,6 @@
Guarantees of sends and commits # Guarantees of sends and commits
===============================
Guarantees of Transaction Completion ## Guarantees of Transaction Completion
====================================
When committing or rolling back a transaction with ActiveMQ, the request 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 to commit or rollback is sent to the server, and the call will block on
@ -26,8 +24,7 @@ of some loss of transaction durability.
This parameter is set in `activemq-configuration.xml` This parameter is set in `activemq-configuration.xml`
Guarantees of Non Transactional Message Sends ## Guarantees of Non Transactional Message Sends
=============================================
If you are sending messages to a server using a non transacted session, 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 ActiveMQ can be configured to block the call to send until the message
@ -53,7 +50,7 @@ of your network. For better performance we recommend either batching
many messages sends together in a transaction since with a transactional many messages sends together in a transaction since with a transactional
session, only the commit / rollback blocks not every send, or, using session, only the commit / rollback blocks not every send, or, using
ActiveMQ's advanced *asynchronous send acknowledgements feature* ActiveMQ's advanced *asynchronous send acknowledgements feature*
described in ?. described in Asynchronous Send Acknowledgements.
If you are using JMS and you're using the JMS service on the server to 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 load your JMS connection factory instances into JNDI then these
@ -75,8 +72,7 @@ send a response back to the client until the message has been persisted
and the server has a guarantee that the data has been persisted to disk. and the server has a guarantee that the data has been persisted to disk.
The default value for this parameter is `true`. The default value for this parameter is `true`.
Guarantees of Non Transactional Acknowledgements ## Guarantees of Non Transactional Acknowledgements
================================================
If you are acknowledging the delivery of a message at the client side If you are acknowledging the delivery of a message at the client side
using a non transacted session, ActiveMQ can be configured to block the using a non transacted session, ActiveMQ can be configured to block the
@ -89,12 +85,11 @@ been sent back. You might want to set this to `true` if you want to
implement a strict *at most once* delivery policy. The default value is implement a strict *at most once* delivery policy. The default value is
`false` `false`
Asynchronous Send Acknowledgements ## Asynchronous Send Acknowledgements
==================================
If you are using a non transacted session but want a guarantee that 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 every message sent to the server has reached it, then, as discussed in
?, you can configure ActiveMQ to block the call to send until the server Guarantees of Non Transactional Message 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. This has received the message, persisted it and sent back a response. This
works well but has a severe performance penalty - each call to send 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 needs to block for at least the time of a network round trip (RTT) - the
@ -128,10 +123,9 @@ successfully reached the server.
The window size for send acknowledgements is determined by the The window size for send acknowledgements is determined by the
confirmation-window-size parameter on the connection factory or client confirmation-window-size parameter on the connection factory or client
session factory. Please see ? for more info on this. session factory. Please see [Client Reconnection and Session Reattachment](client-reconnection.md) for more info on this.
Asynchronous Send Acknowledgements # Asynchronous Send Acknowledgements
----------------------------------
To use the feature using the core API, you implement the interface To use the feature using the core API, you implement the interface
`org.apache.activemq.api.core.client.SendAcknowledgementHandler` and set `org.apache.activemq.api.core.client.SendAcknowledgementHandler` and set

6
docs/user-manual/en/slow-consumers.md
View File

@ -1,5 +1,4 @@
Detecting Slow Consumers #Detecting Slow Consumers
========================
In this section we will discuss how ActiveMQ can be configured to deal 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 with slow consumers. A slow consumer with a server-side queue (e.g. JMS
@ -13,8 +12,7 @@ non-durable JMS subscriber would allow the broker to remove the
subscription and all of its messages freeing up valuable server subscription and all of its messages freeing up valuable server
resources. resources.
Configuration required for detecting slow consumers ## Configuration required for detecting slow consumers
===================================================
By default the server will not detect slow consumers. If slow consumer By default the server will not detect slow consumers. If slow consumer
detection is desired then see ? for more details. detection is desired then see ? for more details.

5
docs/user-manual/en/spring-integration.md
View File

@ -1,5 +1,4 @@
Spring Integration # Spring Integration
==================
ActiveMQ provides a simple bootstrap class, ActiveMQ provides a simple bootstrap class,
`org.apache.activemq.integration.spring.SpringJmsBootstrap`, for `org.apache.activemq.integration.spring.SpringJmsBootstrap`, for
@ -44,7 +43,7 @@ taking advantage of this feature:
As you can see, the `listenerContainer` bean references the components As you can see, the `listenerContainer` bean references the components
defined in the `activemq-jms.xml` file. The `SpringJmsBootstrap` class defined in the `activemq-jms.xml` file. The `SpringJmsBootstrap` class
extends the EmbeddedJMS class talked about in ? and the same defaults extends the EmbeddedJMS class talked about in [JMS API](embedding-activemq.md) and the same defaults
and configuration options apply. Also notice that an `init-method` must and configuration options apply. Also notice that an `init-method` must
be declared with a start value so that the bean's lifecycle is executed. be declared with a start value so that the bean's lifecycle is executed.
See the javadocs for more details on other properties of the bean class. See the javadocs for more details on other properties of the bean class.

22
docs/user-manual/en/syntax.md Normal file
View File

@ -0,0 +1,22 @@
# header 1
## Header 2
### Header 3
#### Header 4
<xml>somexml</xml>
``` java
Somejava s = new SomeJava();
```
> **Note**
>
> This is a Note
> **Warning**
>
> This is a warning
`literal`

46
docs/user-manual/en/thread-pooling.md
View File

@ -1,5 +1,4 @@
Thread management # Thread management
=================
This chapter describes how ActiveMQ uses and pools threads and how you This chapter describes how ActiveMQ uses and pools threads and how you
can manage them. can manage them.
@ -7,8 +6,7 @@ can manage them.
First we'll discuss how threads are managed and used on the server side, First we'll discuss how threads are managed and used on the server side,
then we'll look at the client side. then we'll look at the client side.
Server-Side Thread Management ## Server-Side Thread Management
=============================
Each ActiveMQ Server maintains a single thread pool for general use, and Each ActiveMQ Server maintains a single thread pool for general use, and
a scheduled thread pool for scheduled use. A Java scheduled thread pool a scheduled thread pool for scheduled use. A Java scheduled thread pool
@ -45,8 +43,7 @@ transport configuration. See the ? for more information on this.
There are also a small number of other places where threads are used There are also a small number of other places where threads are used
directly, we'll discuss each in turn. directly, we'll discuss each in turn.
Server Scheduled Thread Pool ### Server Scheduled Thread Pool
----------------------------
The server scheduled thread pool is used for most activities on the The server scheduled thread pool is used for most activities on the
server side that require running periodically or with delays. It maps server side that require running periodically or with delays. It maps
@ -58,8 +55,7 @@ The maximum number of thread used by this pool is configure in
parameter. The default value is `5` threads. A small number of threads parameter. The default value is `5` threads. A small number of threads
is usually sufficient for this pool. is usually sufficient for this pool.
General Purpose Server Thread Pool ### General Purpose Server Thread Pool
----------------------------------
This general purpose thread pool is used for most asynchronous actions This general purpose thread pool is used for most asynchronous actions
on the server side. It maps internally to a on the server side. It maps internally to a
@ -87,8 +83,7 @@ javadoc](http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/ThreadPoo
for more information on unbounded (cached), and bounded (fixed) thread for more information on unbounded (cached), and bounded (fixed) thread
pools. pools.
Expiry Reaper Thread ### Expiry Reaper Thread
--------------------
A single thread is also used on the server side to scan for expired A single thread is also used on the server side to scan for expired
messages in queues. We cannot use either of the thread pools for this messages in queues. We cannot use either of the thread pools for this
@ -96,8 +91,7 @@ since this thread needs to run at its own configurable priority.
For more information on configuring the reaper, please see ?. For more information on configuring the reaper, please see ?.
Asynchronous IO ### Asynchronous IO
---------------
Asynchronous IO has a thread pool for receiving and dispatching events 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 out of the native layer. You will find it on a thread dump with the
@ -109,8 +103,7 @@ that to avoid context switching on libaio that would cause performance
issues. You will find this thread on a thread dump with the prefix issues. You will find this thread on a thread dump with the prefix
ActiveMQ-AIO-writer-pool. ActiveMQ-AIO-writer-pool.
Client-Side Thread Management ## Client-Side Thread Management
=============================
On the client side, ActiveMQ maintains a single static scheduled thread On the client side, ActiveMQ maintains a single static scheduled thread
pool and a single static general thread pool for use by all clients pool and a single static general thread pool for use by all clients
@ -129,17 +122,25 @@ To configure a `ClientSessionFactory` instance to use its own pools,
simply use the appropriate setter methods immediately after creation, simply use the appropriate setter methods immediately after creation,
for example: for example:
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(...) ``` java
ClientSessionFactory myFactory = locator.createClientSessionFactory(); ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(...)
myFactory.setUseGlobalPools(false);
myFactory.setScheduledThreadPoolMaxSize(10); ClientSessionFactory myFactory = locator.createClientSessionFactory();
myFactory.setThreadPoolMaxSize(-1);
myFactory.setUseGlobalPools(false);
myFactory.setScheduledThreadPoolMaxSize(10);
myFactory.setThreadPoolMaxSize(-1);
```
If you're using the JMS API, you can set the same parameters on the If you're using the JMS API, you can set the same parameters on the
ClientSessionFactory and use it to create the `ConnectionFactory` ClientSessionFactory and use it to create the `ConnectionFactory`
instance, for example: instance, for example:
ConnectionFactory myConnectionFactory = ActiveMQJMSClient.createConnectionFactory(myFactory); ``` java
ConnectionFactory myConnectionFactory = ActiveMQJMSClient.createConnectionFactory(myFactory);
```
If you're using JNDI to instantiate `ActiveMQConnectionFactory` If you're using JNDI to instantiate `ActiveMQConnectionFactory`
instances, you can also set these parameters in the JNDI context instances, you can also set these parameters in the JNDI context
@ -148,7 +149,12 @@ environment, e.g. `jndi.properties`. Here's a simple example using the
by default: by default:
java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
java.naming.provider.url=tcp://localhost:5445 java.naming.provider.url=tcp://localhost:5445
connection.ConnectionFactory.useGlobalPools=false connection.ConnectionFactory.useGlobalPools=false
connection.ConnectionFactory.scheduledThreadPoolMaxSize=10 connection.ConnectionFactory.scheduledThreadPoolMaxSize=10
connection.ConnectionFactory.threadPoolMaxSize=-1 connection.ConnectionFactory.threadPoolMaxSize=-1

3
docs/user-manual/en/tools.md
View File

@ -1,5 +1,4 @@
Tools # Tools
=====
ActiveMQ ships with several helpful command line tools. All tools are ActiveMQ ships with several helpful command line tools. All tools are
available from the activemq-tools-\<version\>-jar-with-dependencies.jar. available from the activemq-tools-\<version\>-jar-with-dependencies.jar.

3
docs/user-manual/en/transaction-config.md
View File

@ -1,5 +1,4 @@
Resource Manager Configuration # Resource Manager Configuration
==============================
ActiveMQ has its own Resource Manager for handling the lifespan of JTA ActiveMQ has its own Resource Manager for handling the lifespan of JTA
transactions. When a transaction is started the resource manager is transactions. When a transaction is started the resource manager is

49
docs/user-manual/en/undelivered-messages.md
View File

@ -1,5 +1,4 @@
Message Redelivery and Undelivered Messages # Message Redelivery and Undelivered Messages
===========================================
Messages can be delivered unsuccessfully (e.g. if the transacted session Messages can be delivered unsuccessfully (e.g. if the transacted session
used to consume them is rolled back). Such a message goes back to its used to consume them is rolled back). Such a message goes back to its
@ -23,8 +22,7 @@ There are 2 ways to deal with these undelivered messages:
Both options can be combined for maximum flexibility. Both options can be combined for maximum flexibility.
Delayed Redelivery ## Delayed Redelivery
==================
Delaying redelivery can often be useful in the case that clients Delaying redelivery can often be useful in the case that clients
regularly fail or rollback. Without a delayed redelivery, the system can regularly fail or rollback. Without a delayed redelivery, the system can
@ -32,19 +30,18 @@ get into a "thrashing" state, with delivery being attempted, the client
rolling back, and delivery being re-attempted ad infinitum in quick rolling back, and delivery being re-attempted ad infinitum in quick
succession, consuming valuable CPU and network resources. succession, consuming valuable CPU and network resources.
Configuring Delayed Redelivery ### Configuring Delayed Redelivery
------------------------------
Delayed redelivery is defined in the address-setting configuration: Delayed redelivery is defined in the address-setting configuration:
<!-- delay redelivery of messages for 5s --> <!-- delay redelivery of messages for 5s -->
<address-setting match="jms.queue.exampleQueue"> <address-setting match="jms.queue.exampleQueue">
<!-- default is 1.0 --> <!-- default is 1.0 -->
<redelivery-delay-multiplier>1.5</redelivery-delay-multiplier> <redelivery-delay-multiplier>1.5</redelivery-delay-multiplier>
<!-- default is 0 (no delay) --> <!-- default is 0 (no delay) -->
<redelivery-delay>5000</redelivery-delay> <redelivery-delay>5000</redelivery-delay>
<!-- default is redelivery-delay * 10 --> <!-- default is redelivery-delay * 10 -->
<max-redelivery-delay>50000</max-redelivery-delay> <max-redelivery-delay>50000</max-redelivery-delay>
</address-setting> </address-setting>
@ -63,17 +60,15 @@ redelivery-delay with a max-redelivery-delay to be taken into account.
The max-redelivery-delay is defaulted to redelivery-delay \* 10 The max-redelivery-delay is defaulted to redelivery-delay \* 10
Address wildcards can be used to configure redelivery delay for a set of Address wildcards can be used to configure redelivery delay for a set of
addresses (see ?), so you don't have to specify redelivery delay addresses (see [Understanding the HornetQ Wildcard Syntax](wildcard-syntax.md)), so you don't have to specify redelivery delay
individually for each address. individually for each address.
Example ### Example
-------
See ? for an example which shows how delayed redelivery is configured See ? for an example which shows how delayed redelivery is configured
and used with JMS. and used with JMS.
Dead Letter Addresses ## Dead Letter Addresses
=====================
To prevent a client infinitely receiving the same undelivered message To prevent a client infinitely receiving the same undelivered message
(regardless of what is causing the unsuccessful deliveries), messaging (regardless of what is causing the unsuccessful deliveries), messaging
@ -90,16 +85,15 @@ attempts, they are removed from the queue and sent to the dead letter
address. These *dead letter* messages can later be consumed for further address. These *dead letter* messages can later be consumed for further
inspection. inspection.
Configuring Dead Letter Addresses ### Configuring Dead Letter Addresses
---------------------------------
Dead letter address is defined in the address-setting configuration: Dead letter address is defined in the address-setting configuration:
<!-- undelivered messages in exampleQueue will be sent to the dead letter address <!-- undelivered messages in exampleQueue will be sent to the dead letter address
deadLetterQueue after 3 unsuccessful delivery attempts --> deadLetterQueue after 3 unsuccessful delivery attempts -->
<address-setting match="jms.queue.exampleQueue"> <address-setting match="jms.queue.exampleQueue">
<dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address> <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
<max-delivery-attempts>3</max-delivery-attempts> <max-delivery-attempts>3</max-delivery-attempts>
</address-setting> </address-setting>
If a `dead-letter-address` is not specified, messages will removed after If a `dead-letter-address` is not specified, messages will removed after
@ -113,10 +107,9 @@ addresses and you can set `max-delivery-attempts` to -1 for a specific
address setting to allow infinite redeliveries only for this address. address setting to allow infinite redeliveries only for this address.
Address wildcards can be used to configure dead letter settings for a Address wildcards can be used to configure dead letter settings for a
set of addresses (see ?). set of addresses (see [Understanding the HornetQ Wildcard Syntax](wildcard-syntax.md)).
Dead Letter Properties ### Dead Letter Properties
----------------------
Dead letter messages which are consumed from a dead letter address have Dead letter messages which are consumed from a dead letter address have
the following properties: the following properties:
@ -131,14 +124,12 @@ the following properties:
a String property containing the *original queue* of the dead letter a String property containing the *original queue* of the dead letter
message message
Example ### Example
-------
See ? for an example which shows how dead letter is configured and used See ? for an example which shows how dead letter is configured and used
with JMS. with JMS.
Delivery Count Persistence ## Delivery Count Persistence
==========================
In normal use, ActiveMQ does not update delivery count *persistently* In normal use, ActiveMQ does not update delivery count *persistently*
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

82
docs/user-manual/en/using-core.md
View File

@ -1,5 +1,4 @@
Using Core # Using Core
==========
ActiveMQ core is a completely JMS-agnostic messaging system with its own ActiveMQ core is a completely JMS-agnostic messaging system with its own
non-JMS API. We call this the *core API*. non-JMS API. We call this the *core API*.
@ -8,8 +7,7 @@ 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 API provides all the functionality of JMS but without much of the
complexity. It also provides features that are not available using JMS. complexity. It also provides features that are not available using JMS.
Core Messaging Concepts ## Core Messaging Concepts
=======================
Some of the core messaging concepts are similar to JMS concepts, but Some of the core messaging concepts are similar to JMS concepts, but
core messaging concepts differ in some ways. In general the core core messaging concepts differ in some ways. In general the core
@ -18,8 +16,7 @@ between queues, topics and subscriptions. We'll discuss each of the
major core messaging concepts in turn, but to see the API in detail, major core messaging concepts in turn, but to see the API in detail,
please consult the Javadoc. please consult the Javadoc.
Message ### Message
-------
- A message is the unit of data which is sent between clients and - A message is the unit of data which is sent between clients and
servers. servers.
@ -54,10 +51,9 @@ Message
the message was sent. the message was sent.
- ActiveMQ also supports the sending/consuming of very large messages - ActiveMQ also supports the sending/consuming of very large messages
- much larger than can fit in available RAM at any one time. much larger than can fit in available RAM at any one time.
Address ### Address
-------
A server maintains a mapping between an address and a set of queues. A server maintains a mapping between an address and a set of queues.
Zero or more queues can be bound to a single address. Each queue can be Zero or more queues can be bound to a single address. Each queue can be
@ -80,8 +76,7 @@ messages will also be routed there.
> the topic. A JMS Queue would be implemented as a single address to > the topic. A JMS Queue would be implemented as a single address to
> which one queue is bound - that queue represents the JMS queue. > which one queue is bound - that queue represents the JMS queue.
Queue ### Queue
-----
Queues can be durable, meaning the messages they contain survive a Queues can be durable, meaning the messages they contain survive a
server crash or restart, as long as the messages in them are durable. server crash or restart, as long as the messages in them are durable.
@ -99,8 +94,7 @@ match that filter expression to any queues bound to the address.
Many queues can be bound to a single address. A particular queue is only Many queues can be bound to a single address. A particular queue is only
bound to a maximum of one address. bound to a maximum of one address.
ServerLocator ### ServerLocator
-------------
Clients use `ServerLocator` instances to create `ClientSessionFactory` Clients use `ServerLocator` instances to create `ClientSessionFactory`
instances. `ServerLocator` instances are used to locate servers and instances. `ServerLocator` instances are used to locate servers and
@ -112,8 +106,7 @@ Connection Factory.
`ServerLocator` instances are created using the `ActiveMQClient` factory `ServerLocator` instances are created using the `ActiveMQClient` factory
class. class.
ClientSessionFactory ### ClientSessionFactory
--------------------
Clients use `ClientSessionFactory` instances to create `ClientSession` Clients use `ClientSessionFactory` instances to create `ClientSession`
instances. `ClientSessionFactory` instances are basically the connection instances. `ClientSessionFactory` instances are basically the connection
@ -124,8 +117,7 @@ In JMS terms think of them as JMS Connections.
`ClientSessionFactory` instances are created using the `ServerLocator` `ClientSessionFactory` instances are created using the `ServerLocator`
class. class.
ClientSession ### ClientSession
-------------
A client uses a ClientSession for consuming and producing messages and A client uses a ClientSession for consuming and producing messages and
for grouping them in transactions. ClientSession instances can support for grouping them in transactions. ClientSession instances can support
@ -147,10 +139,9 @@ messages sent is costly since it requires a network round trip for each
message sent. By not blocking and receiving send acknowledgements message sent. By not blocking and receiving send acknowledgements
asynchronously you can create true end to end asynchronous systems which asynchronously you can create true end to end asynchronous systems which
is not possible using the standard JMS API. For more information on this is not possible using the standard JMS API. For more information on this
advanced feature please see the section ?. advanced feature please see the section [Guarantees of sends and commits]{send-guarantees.md).
ClientConsumer ### ClientConsumer
--------------
Clients use `ClientConsumer` instances to consume messages from a queue. Clients use `ClientConsumer` instances to consume messages from a queue.
Core Messaging supports both synchronous and asynchronous message Core Messaging supports both synchronous and asynchronous message
@ -158,8 +149,7 @@ consumption semantics. `ClientConsumer` instances can be configured with
an optional filter expression and will only consume messages which match an optional filter expression and will only consume messages which match
that expression. that expression.
ClientProducer ### ClientProducer
--------------
Clients create `ClientProducer` instances on `ClientSession` instances Clients create `ClientProducer` instances on `ClientSession` instances
so they can send messages. ClientProducer instances can specify an so they can send messages. ClientProducer instances can specify an
@ -175,48 +165,48 @@ message.
> It's an anti-pattern to create new ClientSession, ClientProducer and > It's an anti-pattern to create new ClientSession, ClientProducer and
> ClientConsumer instances for each message you produce or consume. If > ClientConsumer instances for each message you produce or consume. If
> you do this, your application will perform very poorly. This is > you do this, your application will perform very poorly. This is
> discussed further in the section on performance tuning ?. > discussed further in the section on performance tuning [Performance Tuning](perf-tuning.md).
A simple example of using Core ## A simple example of using Core
==============================
Here's a very simple program using the core messaging API to send and Here's a very simple program using the core messaging API to send and
receive a message. Logically it's comprised of two sections: firstly receive a message. Logically it's comprised of two sections: firstly
setting up the producer to write a message to an *addresss*, and setting up the producer to write a message to an *addresss*, and
secondly, creating a *queue* for the consumer, creating the consumer and secondly, creating a *queue* for the consumer, creating the consumer and
*starting* it. *starting* it.
``` java
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(
InVMConnectorFactory.class.getName()));
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration( // In this simple example, we just use one session for both producing and receiving
InVMConnectorFactory.class.getName()));
// In this simple example, we just use one session for both producing and receiving ClientSessionFactory factory = locator.createClientSessionFactory();
ClientSession session = factory.createSession();
ClientSessionFactory factory = locator.createClientSessionFactory(); // A producer is associated with an address ...
ClientSession session = factory.createSession();
// A producer is associated with an address ... ClientProducer producer = session.createProducer("example");
ClientMessage message = session.createMessage(true);
message.getBodyBuffer().writeString("Hello");
ClientProducer producer = session.createProducer("example"); // We need a queue attached to the address ...
ClientMessage message = session.createMessage(true);
message.getBodyBuffer().writeString("Hello");
// We need a queue attached to the address ... session.createQueue("example", "example", true);
session.createQueue("example", "example", true); // And a consumer attached to the queue ...
// And a consumer attached to the queue ... ClientConsumer consumer = session.createConsumer("example");
ClientConsumer consumer = session.createConsumer("example"); // Once we have a queue, we can send the message ...
// Once we have a queue, we can send the message ... producer.send(message);
producer.send(message); // We need to start the session before we can -receive- messages ...
// We need to start the session before we can -receive- messages ... session.start();
ClientMessage msgReceived = consumer.receive();
session.start(); System.out.println("message = " + msgReceived.getBodyBuffer().readString());
ClientMessage msgReceived = consumer.receive();
System.out.println("message = " + msgReceived.getBodyBuffer().readString()); session.close();
```
session.close();

169
docs/user-manual/en/using-jms.md
View File

@ -1,5 +1,4 @@
Using JMS # Using JMS
=========
Although ActiveMQ provides a JMS agnostic messaging API, many users will Although ActiveMQ provides a JMS agnostic messaging API, many users will
be more comfortable using JMS. be more comfortable using JMS.
@ -14,7 +13,7 @@ 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 demonstrate JMS API usage. A good place to start would be to play around
with the simple JMS Queue and Topic example, but we also provide 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 examples for many other parts of the JMS API. A full description of the
examples is available in ?. examples is available in [Examples](examples.md).
In this section we'll go through the main steps in configuring the 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 server for JMS and creating a simple JMS program. We'll also show how to
@ -214,19 +213,39 @@ Any property available on the underlying
this way in addition to the `ha` (boolean) and `type` (String) this way in addition to the `ha` (boolean) and `type` (String)
properties. Here are the different options for the `type`: properties. Here are the different options for the `type`:
type interface #### Configuration for Connection Factory Types
--------------- ------------------------------------ <table>
CF (default) javax.jms.ConnectionFactory <tr>
XA\_CF javax.jms.XAConnectionFactory <th>type</th>
QUEUE\_CF javax.jms.QueueConnectionFactory <th>interface</th>
QUEUE\_XA\_CF javax.jms.XAQueueConnectionFactory </tr>
TOPIC\_CF javax.jms.TopicConnectionFactory <tr>
TOPIC\_XA\_CF javax.jms.XATopicConnectionFactory <td>CF (default)</td>
<td>javax.jms.ConnectionFactory</td>
</tr>
<tr>
<td>XA_CF</td>
<td>javax.jms.XAConnectionFactory</td>
</tr>
<tr>
<td>QUEUE_CF</td>
<td>javax.jms.QueueConnectionFactory</td>
</tr>
<tr>
<td>QUEUE_XA_CF</td>
<td>javax.jms.XAQueueConnectionFactory</td>
</tr>
<tr>
<td>TOPIC_CF</td>
<td>javax.jms.TopicConnectionFactory</td>
</tr>
<tr>
<td>TOPIC_XA_CF</td>
<td>javax.jms.XATopicConnectionFactory</td>
</tr>
</table>
: Configuration for Connection Factory Types ### Destination JNDI
Destination JNDI
----------------
JMS destinations are also typically looked up via JNDI. As with JMS destinations are also typically looked up via JNDI. As with
connection factories, destinations can be configured using special connection factories, destinations can be configured using special
@ -253,8 +272,7 @@ it could do so simply by using the string "dynamicQueues/OrderQueue".
Note, the text that follows `dynamicQueues/` or `dynamicTopics/` must Note, the text that follows `dynamicQueues/` or `dynamicTopics/` must
correspond *exactly* to the name of the destination on the server. correspond *exactly* to the name of the destination on the server.
The code ### The code
--------
Here's the code for the example: Here's the code for the example:
@ -262,49 +280,50 @@ First we'll create a JNDI initial context from which to lookup our JMS
objects. If the above properties are set in `jndi.properties` and it is objects. If the above properties are set in `jndi.properties` and it is
on the classpath then any new, empty `InitialContext` will be on the classpath then any new, empty `InitialContext` will be
initialized using those properties: initialized using those properties:
``` java
InitialContext ic = new InitialContext();
InitialContext ic = new InitialContext(); //Now we'll look up the connection factory from which we can create
//connections to myhost:5445:
Now we'll look up the connection factory from which we can create ConnectionFactory cf = (ConnectionFactory)ic.lookup("ConnectionFactory");
connections to myhost:5445:
ConnectionFactory cf = (ConnectionFactory)ic.lookup("ConnectionFactory"); //And look up the Queue:
And look up the Queue: Queue orderQueue = (Queue)ic.lookup("queues/OrderQueue");
Queue orderQueue = (Queue)ic.lookup("queues/OrderQueue"); //Next we create a JMS connection using the connection factory:
Next we create a JMS connection using the connection factory: Connection connection = cf.createConnection();
Connection connection = cf.createConnection(); //And we create a non transacted JMS Session, with AUTO\_ACKNOWLEDGE
//acknowledge mode:
And we create a non transacted JMS Session, with AUTO\_ACKNOWLEDGE Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
acknowledge mode:
Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); //We create a MessageProducer that will send orders to the queue:
We create a MessageProducer that will send orders to the queue: MessageProducer producer = session.createProducer(orderQueue);
MessageProducer producer = session.createProducer(orderQueue); //And we create a MessageConsumer which will consume orders from the
//queue:
And we create a MessageConsumer which will consume orders from the MessageConsumer consumer = session.createConsumer(orderQueue);
queue:
MessageConsumer consumer = session.createConsumer(orderQueue); //We make sure we start the connection, or delivery won't occur on it:
We make sure we start the connection, or delivery won't occur on it: connection.start();
connection.start(); //We create a simple TextMessage and send it:
We create a simple TextMessage and send it: TextMessage message = session.createTextMessage("This is an order");
producer.send(message);
TextMessage message = session.createTextMessage("This is an order"); //And we consume the message:
producer.send(message);
And we consume the message: TextMessage receivedMessage = (TextMessage)consumer.receive();
System.out.println("Got order: " + receivedMessage.getText());
TextMessage receivedMessage = (TextMessage)consumer.receive(); ```
System.out.println("Got order: " + receivedMessage.getText());
It is as simple as that. For a wide range of working JMS examples please It is as simple as that. For a wide range of working JMS examples please
see the examples directory in the distribution. see the examples directory in the distribution.
@ -317,10 +336,9 @@ see the examples directory in the distribution.
> It is an anti-pattern to create new connections, sessions, producers > It is an anti-pattern to create new connections, sessions, producers
> and consumers for each message you produce or consume. If you do this, > and consumers for each message you produce or consume. If you do this,
> your application will perform very poorly. This is discussed further > your application will perform very poorly. This is discussed further
> in the section on performance tuning ?. > in the section on performance tuning [Performance Tuning](perf-tuning.md).
Directly instantiating JMS Resources without using JNDI ### Directly instantiating JMS Resources without using JNDI
=======================================================
Although it is a very common JMS usage pattern to lookup JMS Although it is a very common JMS usage pattern to lookup JMS
*Administered Objects* (that's JMS Queue, Topic and ConnectionFactory *Administered Objects* (that's JMS Queue, Topic and ConnectionFactory
@ -339,51 +357,52 @@ Here's our simple example, rewritten to not use JNDI at all:
We create the JMS ConnectionFactory object via the ActiveMQJMSClient We create the JMS ConnectionFactory object via the ActiveMQJMSClient
Utility class, note we need to provide connection parameters and specify Utility class, note we need to provide connection parameters and specify
which transport we are using, for more information on connectors please which transport we are using, for more information on connectors please
see ?. see [Configuring the Transport](configuring-transports.md).
``` java
TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName()); TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName());
ConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);
We also create the JMS Queue object via the ActiveMQJMSClient Utility ConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);
class:
Queue orderQueue = ActiveMQJMSClient.createQueue("OrderQueue"); //We also create the JMS Queue object via the ActiveMQJMSClient Utility
//class:
Next we create a JMS connection using the connection factory: Queue orderQueue = ActiveMQJMSClient.createQueue("OrderQueue");
Connection connection = cf.createConnection(); //Next we create a JMS connection using the connection factory:
And we create a non transacted JMS Session, with AUTO\_ACKNOWLEDGE Connection connection = cf.createConnection();
acknowledge mode:
Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); //And we create a non transacted JMS Session, with AUTO\_ACKNOWLEDGE
//acknowledge mode:
We create a MessageProducer that will send orders to the queue: Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
MessageProducer producer = session.createProducer(orderQueue); //We create a MessageProducer that will send orders to the queue:
And we create a MessageConsumer which will consume orders from the MessageProducer producer = session.createProducer(orderQueue);
queue:
MessageConsumer consumer = session.createConsumer(orderQueue); //And we create a MessageConsumer which will consume orders from the
//queue:
We make sure we start the connection, or delivery won't occur on it: MessageConsumer consumer = session.createConsumer(orderQueue);
connection.start(); //We make sure we start the connection, or delivery won't occur on it:
We create a simple TextMessage and send it: connection.start();
TextMessage message = session.createTextMessage("This is an order"); //We create a simple TextMessage and send it:
producer.send(message);
And we consume the message: TextMessage message = session.createTextMessage("This is an order");
producer.send(message);
TextMessage receivedMessage = (TextMessage)consumer.receive(); //And we consume the message:
System.out.println("Got order: " + receivedMessage.getText());
Setting The Client ID TextMessage receivedMessage = (TextMessage)consumer.receive();
===================== System.out.println("Got order: " + receivedMessage.getText());
```
### Setting The Client ID
This represents the client id for a JMS client and is needed for This represents the client id for a JMS client and is needed for
creating durable subscriptions. It is possible to configure this on the creating durable subscriptions. It is possible to configure this on the
@ -391,8 +410,7 @@ connection factory and can be set via the `client-id` element. Any
connection created by this connection factory will have this set as its connection created by this connection factory will have this set as its
client id. client id.
Setting The Batch Size for DUPS\_OK ### Setting The Batch Size for DUPS_OK
===================================
When the JMS acknowledge mode is set to `DUPS_OK` it is possible to When the JMS acknowledge mode is set to `DUPS_OK` it is possible to
configure the consumer so that it sends acknowledgements in batches configure the consumer so that it sends acknowledgements in batches
@ -400,8 +418,7 @@ rather that one at a time, saving valuable bandwidth. This can be
configured via the connection factory via the `dups-ok-batch-size` configured via the connection factory via the `dups-ok-batch-size`
element and is set in bytes. The default is 1024 \* 1024 bytes = 1 MiB. element and is set in bytes. The default is 1024 \* 1024 bytes = 1 MiB.
Setting The Transaction Batch Size ### Setting The Transaction Batch Size
==================================
When receiving messages in a transaction it is possible to configure the When receiving messages in a transaction it is possible to configure the
consumer to send acknowledgements in batches rather than individually consumer to send acknowledgements in batches rather than individually

42
docs/user-manual/en/using-server.md
View File

@ -1,5 +1,4 @@
Using the Server # Using the Server
================
This chapter will familiarise you with how to use the ActiveMQ server. This chapter will familiarise you with how to use the ActiveMQ server.
@ -13,8 +12,7 @@ with a JMS Service and JNDI service enabled.
When running embedded in JBoss Application Server the layout may be When running embedded in JBoss Application Server the layout may be
slightly different but by-and-large will be the same. slightly different but by-and-large will be the same.
Starting and Stopping the standalone server ## Starting and Stopping the standalone server
===========================================
In the distribution you will find a directory called `bin`. In the distribution you will find a directory called `bin`.
@ -42,8 +40,7 @@ used. The configuration can be changed e.g. by running
`./activemq run -- xml:../config/clustered/bootstrap.xml` or another `./activemq run -- xml:../config/clustered/bootstrap.xml` or another
config of your choosing. config of your choosing.
Server JVM settings ## Server JVM settings
===================
The run scripts set some JVM settings for tuning the garbage collection The run scripts set some JVM settings for tuning the garbage collection
policy and heap size. We recommend using a parallel garbage collection policy and heap size. We recommend using a parallel garbage collection
@ -56,8 +53,7 @@ would for any Java program.
If you wish to add any more JVM arguments or tune the existing ones, the If you wish to add any more JVM arguments or tune the existing ones, the
run scripts are the place to do it. run scripts are the place to do it.
Pre-configured Options ## Pre-configured Options
======================
The distribution contains several standard configuration sets for The distribution contains several standard configuration sets for
running: running:
@ -73,8 +69,7 @@ running:
You can of course create your own configuration and specify any You can of course create your own configuration and specify any
configuration when running the run script. configuration when running the run script.
Library Path ## Library Path
============
If you're using the [Asynchronous IO Journal](#aio-journal) on Linux, If you're using the [Asynchronous IO Journal](#aio-journal) on Linux,
you need to specify `java.library.path` as a property on your Java you need to specify `java.library.path` as a property on your Java
@ -83,16 +78,14 @@ options. This is done automatically in the scripts.
If you don't specify `java.library.path` at your Java options then the If you don't specify `java.library.path` at your Java options then the
JVM will use the environment variable `LD_LIBRARY_PATH`. JVM will use the environment variable `LD_LIBRARY_PATH`.
System properties ## System properties
=================
ActiveMQ can take a system property on the command line for configuring ActiveMQ can take a system property on the command line for configuring
logging. logging.
For more information on configuring logging, please see ?. For more information on configuring logging, please see ?.
Configuration files ## Configuration files
===================
The configuration file used to bootstrap the server (e.g. The configuration file used to bootstrap the server (e.g.
`bootstrap.xml` by default) references the specific broker configuration `bootstrap.xml` by default) references the specific broker configuration
@ -149,8 +142,7 @@ respectively. It is also possible to not supply a default. i.e.
`${activemq.remoting.netty.host}`, however the system property *must* be `${activemq.remoting.netty.host}`, however the system property *must* be
supplied in that case. supplied in that case.
Bootstrap File ## Bootstrap File
==============
The stand-alone server is basically a set of POJOs which are The stand-alone server is basically a set of POJOs which are
instantiated by Airline commands. instantiated by Airline commands.
@ -164,19 +156,13 @@ The bootstrap file is very simple. Let's take a look at an example:
<basic-security/> <basic-security/>
<naming bindAddress="localhost" port="1099" rmiBindAddress="localhost" rmiPort="1098"/>
</broker> </broker>
- core - core - Instantiates a core server using the configuration file from the
Instantiates a core server using the configuration file from the
`configuration` attribute. This is the main broker POJO necessary to `configuration` attribute. This is the main broker POJO necessary to
do all the real messaging work. do all the real messaging work.
- jms - jms - This deploys any JMS Objects such as JMS Queues, Topics and
This deploys any JMS Objects such as JMS Queues, Topics and
ConnectionFactory instances from the `activemq-jms.xml` file ConnectionFactory instances from the `activemq-jms.xml` file
specified. It also provides a simple management API for manipulating specified. It also provides a simple management API for manipulating
JMS Objects. On the whole it just translates and delegates its work JMS Objects. On the whole it just translates and delegates its work
@ -184,13 +170,7 @@ The bootstrap file is very simple. Let's take a look at an example:
and ConnectionFactories from server side configuration and don't and ConnectionFactories from server side configuration and don't
require the JMS management interface this can be disabled. require the JMS management interface this can be disabled.
- naming ## The main configuration file.
Instantiates a naming server which implements JNDI. This is used by
JMS clients
The main configuration file.
============================
The configuration for the ActiveMQ core server is contained in The configuration for the ActiveMQ core server is contained in
`activemq-configuration.xml`. This is what the FileConfiguration bean `activemq-configuration.xml`. This is what the FileConfiguration bean

39
docs/user-manual/en/vertx-integration.md
View File

@ -1,5 +1,4 @@
Vert.x Integration # Vert.x Integration
==================
[Vert.x](http://vertx.io/) is a lightweight, high performance [Vert.x](http://vertx.io/) is a lightweight, high performance
application platform for the JVM that's designed for modern mobile, web, application platform for the JVM that's designed for modern mobile, web,
@ -9,20 +8,19 @@ can now redirect and persist any vert.x messages to ActiveMQ and route
those messages to a specified vertx address by configuring ActiveMQ those messages to a specified vertx address by configuring ActiveMQ
vertx incoming and outgoing vertx connector services. vertx incoming and outgoing vertx connector services.
Configuring a Vertx Incoming Connector Service ## Configuring a Vertx Incoming Connector Service
==============================================
Vertx Incoming Connector services receive messages from vertx event bus Vertx Incoming Connector services receive messages from vertx event bus
and route them to a ActiveMQ queue. Such a service can be configured as and route them to a ActiveMQ queue. Such a service can be configured as
follows: follows:
<connector-service name="vertx-incoming-connector"> <connector-service name="vertx-incoming-connector">
<factory-class>org.apache.activemq.integration.vertx.VertxIncomingConnectorServiceFactory</factory-class> <factory-class>org.apache.activemq.integration.vertx.VertxIncomingConnectorServiceFactory</factory-class>
<param key="host" value="127.0.0.1"/> <param key="host" value="127.0.0.1"/>
<param key="port" value="0"/> <param key="port" value="0"/>
<param key="queue" value="jms.queue.vertxQueue"/> <param key="queue" value="jms.queue.vertxQueue"/>
<param key="vertx-address" value="vertx.in.eventaddress"/> <param key="vertx-address" value="vertx.in.eventaddress"/>
</connector-service> </connector-service>
Shown are the required params for the connector service: Shown are the required params for the connector service:
@ -46,21 +44,20 @@ parameters
- `vertx-address`. The vertx address to listen to. default is - `vertx-address`. The vertx address to listen to. default is
org.apache.activemq. org.apache.activemq.
Configuring a Vertx Outgoing Connector Service ## Configuring a Vertx Outgoing Connector Service
==============================================
Vertx Outgoing Connector services fetch vertx messages from a ActiveMQ Vertx Outgoing Connector services fetch vertx messages from a ActiveMQ
queue and put them to vertx event bus. Such a service can be configured queue and put them to vertx event bus. Such a service can be configured
as follows: as follows:
<connector-service name="vertx-outgoing-connector"> <connector-service name="vertx-outgoing-connector">
<factory-class>org.apache.activemq.integration.vertx.VertxOutgoingConnectorServiceFactory</factory-class> <factory-class>org.apache.activemq.integration.vertx.VertxOutgoingConnectorServiceFactory</factory-class>
<param key="host" value="127.0.0.1"/> <param key="host" value="127.0.0.1"/>
<param key="port" value="0"/> <param key="port" value="0"/>
<param key="queue" value="jms.queue.vertxQueue"/> <param key="queue" value="jms.queue.vertxQueue"/>
<param key="vertx-address" value="vertx.out.eventaddress"/> <param key="vertx-address" value="vertx.out.eventaddress"/>
<param key="publish" value="true"/> <param key="publish" value="true"/>
</connector-service> </connector-service>
Shown are the required params for the connector service: Shown are the required params for the connector service:

3
docs/user-manual/en/wildcard-routing.md
View File

@ -1,5 +1,4 @@
Routing Messages With Wild Cards # Routing Messages With Wild Cards
================================
ActiveMQ allows the routing of messages via wildcard addresses. ActiveMQ allows the routing of messages via wildcard addresses.

3
docs/user-manual/en/wildcard-syntax.md
View File

@ -1,5 +1,4 @@
Understanding the ActiveMQ Wildcard Syntax # Understanding the ActiveMQ Wildcard Syntax
==========================================
ActiveMQ uses a specific syntax for representing wildcards in security ActiveMQ uses a specific syntax for representing wildcards in security
settings, address settings and when creating consumers. settings, address settings and when creating consumers.