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)
* [Preface](preface.md)
* [Project Info](project-info.md)
* [Messaging Concepts](messaging-concepts.md)
* [Project Info](project-info/project-info.md)
* [Messaging Concepts](messaging-concepts/messaging-concepts.md)
* [Architecture](architecture.md)
* [Using the Server](using-server.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
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
devices.
Configuring an AeroGear Connector Service
=========================================
## Configuring an AeroGear Connector Service
AeroGear Connector services are configured in the connector-services
configuration:
@ -64,20 +62,21 @@ parameters
More in depth explanations of the AeroGear related parameters can be
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
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.
> **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
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:
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
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.
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
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
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
annotations:
@MessageDriven(name = "MDBExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
})
@ResourceAdapter("activemq-ra.rar")
public class MDBExample implements MessageListener
{
public void onMessage(Message message)...
}
``` java
@MessageDriven(name = "MDBExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
})
@ResourceAdapter("activemq-ra.rar")
public class MDBExample implements MessageListener
{
public void onMessage(Message message)...
}
```
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
@ -77,8 +77,7 @@ file and change `rar-name` element.
All the examples shipped with the ActiveMQ distribution use the
annotation.
Using Container-Managed Transactions
------------------------------------
### Using Container-Managed Transactions
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
@ -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
configured as follows:
@MessageDriven(name = "MDB_CMP_TxRequiredExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
})
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MDB_CMP_TxRequiredExample implements MessageListener
{
public void onMessage(Message message)...
}
``` java
@MessageDriven(name = "MDB_CMP_TxRequiredExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
})
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MDB_CMP_TxRequiredExample implements MessageListener
{
public void onMessage(Message message)...
}
```
The `TransactionManagement` annotation tells the container to manage the
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`.
The code for this would look something like:
@Resource
MessageDrivenContextContext ctx;
``` java
@Resource
MessageDrivenContextContext ctx;
public void onMessage(Message message)
{
try
{
//something here fails
}
catch (Exception e)
{
ctx.setRollbackOnly();
}
}
public void onMessage(Message message)
{
try
{
//something here fails
}
catch (Exception e)
{
ctx.setRollbackOnly();
}
}
```
If you do not want the overhead of an XA transaction being created every
time but you would still like the message delivered within a transaction
(i.e. you are only using a JMS resource) then you can configure the MDB
to use a local transaction. This would be configured as such:
@MessageDriven(name = "MDB_CMP_TxLocalExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
@ActivationConfigProperty(propertyName = "useLocalTx", propertyValue = "true")
})
@TransactionManagement(value = TransactionManagementType.CONTAINER)
@TransactionAttribute(value = TransactionAttributeType.NOT_SUPPORTED)
@ResourceAdapter("activemq-ra.rar")
public class MDB_CMP_TxLocalExample implements MessageListener
{
public void onMessage(Message message)...
}
``` java
@MessageDriven(name = "MDB_CMP_TxLocalExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
@ActivationConfigProperty(propertyName = "useLocalTx", propertyValue = "true")
})
@TransactionManagement(value = TransactionManagementType.CONTAINER)
@TransactionAttribute(value = TransactionAttributeType.NOT_SUPPORTED)
@ResourceAdapter("activemq-ra.rar")
public class MDB_CMP_TxLocalExample implements MessageListener
{
public void onMessage(Message message)...
}
```
Using Bean-Managed Transactions
-------------------------------
### Using Bean-Managed Transactions
Message-driven beans can also be configured to use Bean-Managed
Transactions (BMT). In this case a User Transaction is created. This
would be configured as follows:
@MessageDriven(name = "MDB_BMPExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
@ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Dups-ok-acknowledge")
})
@TransactionManagement(value= TransactionManagementType.BEAN)
@ResourceAdapter("activemq-ra.rar")
public class MDB_BMPExample implements MessageListener
{
public void onMessage(Message message)
}
``` java
@MessageDriven(name = "MDB_BMPExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
@ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Dups-ok-acknowledge")
})
@TransactionManagement(value= TransactionManagementType.BEAN)
@ResourceAdapter("activemq-ra.rar")
public class MDB_BMPExample implements MessageListener
{
public void onMessage(Message message)
}
```
When using Bean-Managed Transactions the message delivery to the MDB
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
the following:
@Resource
MessageDrivenContext ctx;
``` java
@Resource
MessageDrivenContext ctx;
public void onMessage(Message message)
{
UserTransaction tx;
try
{
TextMessage textMessage = (TextMessage)message;
public void onMessage(Message message)
{
UserTransaction tx;
try
{
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)
{
tx.rollback();
}
}
}
catch (Exception e)
{
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
simple define your message selector as follows:
@MessageDriven(name = "MDBMessageSelectorExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
@ActivationConfigProperty(propertyName = "messageSelector", propertyValue = "color = 'RED'")
})
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MDBMessageSelectorExample implements MessageListener
{
public void onMessage(Message message)....
}
``` java
@MessageDriven(name = "MDBMessageSelectorExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
@ActivationConfigProperty(propertyName = "messageSelector", propertyValue = "color = 'RED'")
})
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MDBMessageSelectorExample implements MessageListener
{
public void onMessage(Message message)....
}
```
Sending Messages from within JEE components
===========================================
## Sending Messages from within JEE components
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
@ -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
of this from within an MDB:
@MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
})
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MDBMessageSendTxExample implements MessageListener
{
@Resource(mappedName = "java:/JmsXA")
ConnectionFactory connectionFactory;
``` java
@MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
})
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MDBMessageSendTxExample implements MessageListener
{
@Resource(mappedName = "java:/JmsXA")
ConnectionFactory connectionFactory;
@Resource(mappedName = "queue/replyQueue")
Queue replyQueue;
@Resource(mappedName = "queue/replyQueue")
Queue replyQueue;
public void onMessage(Message message)
{
Connection conn = null;
try
{
//Step 9. We know the client is sending a text message so we cast
TextMessage textMessage = (TextMessage)message;
public void onMessage(Message message)
{
Connection conn = null;
try
{
//Step 9. We know the client is sending a text message so we cast
TextMessage textMessage = (TextMessage)message;
//Step 10. get the text from the message.
String text = textMessage.getText();
//Step 10. get the text from the message.
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)
{
e.printStackTrace();
}
finally
{
if(conn != null)
{
try
{
conn.close();
}
catch (JMSException e)
{
}
}
}
}
}
}
catch (Exception e)
{
e.printStackTrace();
}
finally
{
if(conn != null)
{
try
{
conn.close();
}
catch (JMSException e)
{
}
}
}
}
}
```
In JBoss Application Server you can use the JMS JCA adapter for sending
messages from EJBs (including Session, Entity and Message-Driven Beans),
Servlets (including jsps) and custom MBeans.
MDB and Consumer pool size
==========================
## MDB and Consumer pool size
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
@ -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
an Activation Config Property on the MDB itself
@MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
@ActivationConfigProperty(propertyName = "maxSession", propertyValue = "1")
})
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MyMDB implements MessageListener
{ ....}
``` java
@MessageDriven(name = "MDBMessageSendTxExample", activationConfig =
{
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
@ActivationConfigProperty(propertyName = "maxSession", propertyValue = "1")
})
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MyMDB implements MessageListener
{ ....}
```
Configuring the JCA Adaptor
===========================
## Configuring the JCA Adaptor
The Java Connector Architecture (JCA) Adapter is what allows ActiveMQ to
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
for controlling the consumption of messages via MDBs.
Global Properties
-----------------
### Global Properties
The first element you see is `resourceadapter-class` which should be
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
--------------------------------------------------------------------------- --------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
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.
ha boolean True if high availability is needed.
useLocalTx boolean True will enable local transaction optimisation.
@ -485,8 +494,7 @@ The following table explains what each property is for.
: Global Configuration Properties
Adapter Outbound Configuration
------------------------------
### Adapter Outbound Configuration
The outbound configuration should remain unchanged as they define
connection factories that are used by Java EE components. These
@ -545,8 +553,7 @@ addition to the global configuration properties.
: Outbound Configuration Properties
Adapter Inbound Configuration
-----------------------------
### Adapter Inbound Configuration
The inbound configuration should again remain unchanged. This controls
what forwards messages onto MDBs. It is possible to override properties
@ -572,16 +579,13 @@ to the global 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
separate from the application server. If this is the case you will only
need the activemq client libs installed. This section explains what
config to create and what jar dependencies are needed.
###
There are two configuration files needed to do this, one for the
incoming adapter used for MDB's and one for outgoing connections managed
by the JCA managed connection pool used by outgoing JEE components
@ -700,15 +704,13 @@ This is a list of the ActiveMQ and third party jars needed
: 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
server that doesn't have ActiveMQ installed to use a remote instance of
ActiveMQ
Configuring JBoss 5
-------------------
### Configuring JBoss 5
Firstly download and install JBoss AS 5 as per the JBoss installation
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
the remote server. You will however, have to make sure that your MDB's
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
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
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
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
'message-driven-bean'
High Availability JNDI (HA-JNDI)
================================
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
*XA recovery* deals with system or application failures to ensure that
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
(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
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
- `[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).
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
> specified in `conf/jbossts-properties.xml`.
### Configuration Settings
#### Configuration Settings
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
Recovery.
Example
-------
## Example
See ? which shows how to configure XA Recovery and recover messages
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
architecture.
Core Architecture
=================
## Core Architecture
ActiveMQ core is designed simply as set of Plain Old Java Objects
(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.
This allows ActiveMQ to be easily embedded in your own project, or
instantiated in any dependency injection framework such as JBoss
Microcontainer, Spring or Google Guice.
instantiated in any dependency injection framework such as Spring or
Google Guice.
Each ActiveMQ server has its own ultra high performance persistent
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
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
application that requires messaging functionality internally but you
don't want to expose that as a ActiveMQ server you can directly
instantiate and embed ActiveMQ servers in your own application.
For more information on embedding ActiveMQ, see ?.
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
(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)
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
fully independent messaging server not dependent on a JEE application
server.
The standard stand-alone messaging server configuration comprises a core
messaging server, a JMS service and a JNDI service.
messaging server and a JMS service.
The role of the JMS Service is to deploy any JMS Queue, Topic and
ConnectionFactory instances from any server side `activemq-jms.xml`
configuration files. It also provides a simple management API for
creating and destroying Queues, Topics and ConnectionFactory instances
creating and destroying Queues and Topics
which can be accessed via JMX or the connection. It is a separate
service to the ActiveMQ core server, since the core server is JMS
agnostic. If you don't want to deploy any JMS Queue, Topic or
ConnectionFactory instances via server side XML configuration and don't
require a JMS management API on the server side then you can disable
this service.
We also include a JNDI server since JNDI is a common requirement when
using JMS to lookup Queues, Topics and ConnectionFactory instances. If
you do not require JNDI then this service can also be disabled. ActiveMQ
allows you to programmatically create JMS and core objects directly on
the client side as opposed to looking them up from JNDI, so a JNDI
server is not always a requirement.
agnostic. If you don't want to deploy any JMS Queue or Topic via
server side XML configuration and don't require a JMS management
API on the server side then you can disable this service.
The stand-alone server configuration uses JBoss Microcontainer to
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)
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
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
> 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
need `activemq-core-client.jar`, `activemq-commons.jar`, and `netty.jar`
on your client classpath.
JMS Client
==========
## JMS Client
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`.

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
re-attach to the server in the event that a failure is detected in the
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
network failure, and the target server was not restarted, then the
sessions will still be existent on the server, assuming the client
hasn't been disconnected for more than connection-ttl ?.
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
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
re-attachment will occur)
Session reconnection
====================
## Session reconnection
Alternatively, the server might have actually been restarted after
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
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
failover/reconnect and what you need to do to maintain *once and only
once*delivery guarantees.
Configuring reconnection/reattachment attributes
================================================
## Configuring reconnection/reattachment attributes
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
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
other nodes in the core configuration file `activemq-configuration.xml`.
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
have to declare an explicit bridge for each node. These cluster
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
> form properly.
Server discovery
================
## Server discovery
Server discovery is a mechanism by which servers can propagate their
connection details to:
@ -72,20 +69,19 @@ techniques like
[JGroups](http://www.jgroups.org/), or by providing a list of initial
connectors.
Dynamic Discovery
-----------------
### Dynamic Discovery
Server discovery uses
[UDP](http://en.wikipedia.org/wiki/User_Datagram_Protocol) multicast or
[JGroups](http://www.jgroups.org/) to broadcast server connection
settings.
### Broadcast Groups
#### Broadcast Groups
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
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
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.
- `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
`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>
### Discovery Groups
#### Discovery Groups
While the broadcast group defines how connector information is
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
> 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
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
> 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
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.
#### 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
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
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 =
ActiveMQJMSClient.createConnectionFactory(new DiscoveryGroupConfiguration(groupAddress, groupPort,
new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1)), JMSFactoryType.CF);
ConnectionFactory jmsConnectionFactory =
ActiveMQJMSClient.createConnectionFactory(new DiscoveryGroupConfiguration(groupAddress, groupPort,
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
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
parameter is `10000` milliseconds.
#### Configuring client discovery using Core
##### Configuring client discovery using Core
If you're using the core API to directly instantiate
`ClientSessionFactory` instances, then you can specify the discovery
group parameters directly when creating the session factory. Here's an
example:
final String groupAddress = "231.7.7.7";
final int groupPort = 9876;
ServerLocator factory = ActiveMQClient.createServerLocatorWithHA(new DiscoveryGroupConfiguration(groupAddress, groupPort,
new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1))));
ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session1 = factory.createSession();
ClientSession session2 = factory.createSession();
``` java
final String groupAddress = "231.7.7.7";
final int groupPort = 9876;
ServerLocator factory = ActiveMQClient.createServerLocatorWithHA(new DiscoveryGroupConfiguration(groupAddress, groupPort,
new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1))));
ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session1 = factory.createSession();
ClientSession session2 = factory.createSession();
```
The `refresh-timeout` can be set directly on the
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
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.
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
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
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.
### Configuring a Client Connection
#### Configuring a Client Connection
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
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
connection factory. Here's an example:
HashMap<String, Object> map = new HashMap<String, Object>();
map.put("host", "myhost");
map.put("port", "5445");
TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
HashMap<String, Object> map2 = new HashMap<String, Object>();
map2.put("host", "myhost2");
map2.put("port", "5446");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
``` java
HashMap<String, Object> map = new HashMap<String, Object>();
map.put("host", "myhost");
map.put("port", "5445");
TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
HashMap<String, Object> map2 = new HashMap<String, Object>();
map2.put("host", "myhost2");
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:
HashMap<String, Object> map = new HashMap<String, Object>();
map.put("host", "myhost");
map.put("port", "5445");
TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
HashMap<String, Object> map2 = new HashMap<String, Object>();
map2.put("host", "myhost2");
map2.put("port", "5446");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
``` java
HashMap<String, Object> map = new HashMap<String, Object>();
map.put("host", "myhost");
map.put("port", "5445");
TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
HashMap<String, Object> map2 = new HashMap<String, Object>();
map2.put("host", "myhost2");
map2.put("port", "5446");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session = factory.createSession();
ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
ClientSessionFactory factory = locator.createSessionFactory();
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
ActiveMQ will load balance messages arriving at a particular node from a
client.
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.
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
connections in general.
Configuring Cluster Connections
-------------------------------
### Configuring Cluster Connections
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
@ -665,7 +666,7 @@ specified. The following shows all the available configuration options
This parameter determines the interval in milliseconds between retry
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`
milliseconds.
@ -697,7 +698,7 @@ specified. The following shows all the available configuration options
the target node.
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.
- `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
connection has been made.
Cluster User Credentials
------------------------
### Cluster User Credentials
When creating connections between nodes of a cluster to form a cluster
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
> 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
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
using the setter on the `ActiveMQConnectionFactory` before using it:
ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactory(...);
jmsConnectionFactory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
``` java
ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactory(...);
jmsConnectionFactory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
```
If you're using the core API, you can set the load balancing policy
directly on the `ServerLocator` instance you are using:
ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
``` java
ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
locator.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
```
The set of servers over which the factory load balances can be
determined in one of two ways:
@ -873,8 +876,7 @@ determined in one of two ways:
- 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
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 means you can explicitly create any cluster topology you want.
Message Redistribution
======================
## Message Redistribution
Another important part of clustering is message redistribution. Earlier
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
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`
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.
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
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
redistribute immediately since the new consumer will arrive shortly.
Cluster topologies
==================
## Cluster topologies
ActiveMQ clusters can be connected together in many different
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
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
cluster.
Chain cluster
-------------
### Chain cluster
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
@ -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
which does have consumers.
Scaling Down
============
### Scaling Down
ActiveMQ supports scaling down a cluster with no message loss (even for
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
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
ActiveMQ transports and where and how they're configured.
Understanding Acceptors
=======================
## Understanding Acceptors
One of the most important concepts in ActiveMQ transports is the
*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
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
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.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
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
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,
5446);
connectionParams.put(org.apache.activemq.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME,
5446);
TransportConfiguration transportConfiguration =
new TransportConfiguration(
"org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
connectionParams);
TransportConfiguration transportConfiguration =
new TransportConfiguration(
"org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
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
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`:
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 =
new TransportConfiguration(
"org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
connectionParams);
TransportConfiguration transportConfiguration =
new TransportConfiguration(
"org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory",
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
[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.
Single Port Support
-------------------
## Single Port Support
As of version 2.4 ActiveMQ now supports using a single port for all
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
Configuring Netty TCP
---------------------
## Configuring 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.
@ -320,8 +317,7 @@ Netty for simple TCP:
connector will let the system pick up an ephemeral port. valid ports
are 0 to 65535
Configuring Netty SSL
---------------------
## Configuring Netty SSL
Netty SSL is similar to the Netty TCP transport but it provides
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
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
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
first call to receive a session id. Used the http connector is
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
explain how ActiveMQ deals with crashed clients and clients which have
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
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
session and session factory in a finally block:
ServerLocator locator = null;
ClientSessionFactory sf = null;
ClientSession session = null;
``` java
ServerLocator locator = null;
ClientSessionFactory sf = null;
ClientSession session = null;
try
{
locator = ActiveMQClient.createServerLocatorWithoutHA(..);
try
{
locator = ActiveMQClient.createServerLocatorWithoutHA(..);
sf = locator.createClientSessionFactory();;
sf = locator.createClientSessionFactory();;
session = sf.createSession(...);
... do some stuff with the session...
}
finally
{
if (session != null)
{
session.close();
}
if (sf != null)
{
sf.close();
}
session = sf.createSession(...);
... do some stuff with the session...
}
finally
{
if (session != null)
{
session.close();
}
if (sf != null)
{
sf.close();
}
if(locator != null)
{
locator.close();
}
}
if(locator != null)
{
locator.close();
}
}
```
And here's an example of a well behaved JMS client application:
Connection jmsConnection = null;
``` java
Connection jmsConnection = null;
try
{
ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(...);
try
{
ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(...);
jmsConnection = jmsConnectionFactory.createConnection();
jmsConnection = jmsConnectionFactory.createConnection();
... do some stuff with the connection...
}
finally
{
if (connection != null)
{
connection.close();
}
}
... do some stuff with the connection...
}
finally
{
if (connection != null)
{
connection.close();
}
}
```
Unfortunately users don't always write well behaved applications, and
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
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
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
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
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
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
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
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
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**
>
@ -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
> 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
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
specified then only messages which match the filter expression
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
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.
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).
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` to use for the connection used to forward
messages to the target node. This attribute is described in section
?
[Reconnection and Session Reattachment](client-reconnection.md)
> **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)
as well as the server connection parameters (host, port etc). For
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 -
`discovery-group-name`. This attribute points to a `discovery-group`
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
simple server configuration.
@ -43,8 +42,7 @@ use diverts.
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
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
details.
Non-exclusive Divert
====================
## Non-exclusive Divert
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

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,
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
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
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:
...
``` 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:
...
``` 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
`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
> 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
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`.
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
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`.
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).
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
that.
Simple Config File Embedding
============================
## Simple Config File Embedding
The simplest way to embed ActiveMQ is to use the embedded wrapper
classes and configure ActiveMQ through its configuration files. There
are two different helper classes for this depending on whether your
using the ActiveMQ Core API or JMS.
Core API Only
-------------
## Core API Only
For instantiating a core ActiveMQ Server only, the steps are pretty
simple. The example requires that you have defined a configuration file
`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();
embedded.start();
EmbeddedActiveMQ embedded = new EmbeddedActiveMQ();
embedded.start();
ClientSessionFactory nettyFactory = ActiveMQClient.createClientSessionFactory(
new TransportConfiguration(
InVMConnectorFactory.class.getName()));
ClientSessionFactory nettyFactory = ActiveMQClient.createClientSessionFactory(
new TransportConfiguration(
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
allow you to specify a different config file name as well as other
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
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
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();
jms.start();
EmbeddedJMS jms = new EmbeddedJMS();
jms.start();
// This assumes we have configured activemq-jms.xml with the appropriate config information
ConnectionFactory connectionFactory = jms.lookup("ConnectionFactory");
Destination destination = jms.lookup("/example/queue");
// This assumes we have configured activemq-jms.xml with the appropriate config information
ConnectionFactory connectionFactory = jms.lookup("ConnectionFactory");
Destination destination = jms.lookup("/example/queue");
... regular JMS code ...
... regular JMS code ...
```
By default, the `EmbeddedJMS` class will store component entries defined
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
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
core, non-JMS ActiveMQ Server instance:
@ -108,43 +107,49 @@ core, non-JMS ActiveMQ Server instance:
Create the configuration object - this contains configuration
information for a ActiveMQ instance. The setter methods of this class
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
`NettyAcceptorFactory` on the transports the same way you would through
the main configuration file.
import org.apache.activemq.core.config.Configuration;
import org.apache.activemq.core.config.impl.ConfigurationImpl;
``` java
import org.apache.activemq.core.config.Configuration;
import org.apache.activemq.core.config.impl.ConfigurationImpl;
...
...
Configuration config = new ConfigurationImpl();
HashSet<TransportConfiguration> transports = new HashSet<TransportConfiguration>();
transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));
Configuration config = new ConfigurationImpl();
HashSet<TransportConfiguration> transports = new HashSet<TransportConfiguration>();
transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));
config.setAcceptorConfigurations(transports);
config.setAcceptorConfigurations(transports);
```
You need to instantiate an instance of
`org.apache.activemq.api.core.server.embedded.EmbeddedActiveMQ` and add
the configuration object to it.
import org.apache.activemq.api.core.server.ActiveMQ;
import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
``` java
import org.apache.activemq.api.core.server.ActiveMQ;
import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
...
...
EmbeddedActiveMQ server = new EmbeddedActiveMQ();
server.setConfiguration(config);
EmbeddedActiveMQ server = new EmbeddedActiveMQ();
server.setConfiguration(config);
server.start();
server.start();
```
You also have the option of instantiating `ActiveMQServerImpl` directly:
ActiveMQServer server = new ActiveMQServerImpl(config);
server.start();
``` java
ActiveMQServer server = new ActiveMQServerImpl(config);
server.start();
```
For JMS POJO instantiation, you work with the EmbeddedJMS class instead
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
an example of this:
// Step 1. Create ActiveMQ core configuration, and set the properties accordingly
Configuration configuration = new ConfigurationImpl();
configuration.setPersistenceEnabled(false);
configuration.setSecurityEnabled(false);
configuration.getAcceptorConfigurations().add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
``` java
// Step 1. Create ActiveMQ core configuration, and set the properties accordingly
Configuration configuration = new ConfigurationImpl();
configuration.setPersistenceEnabled(false);
configuration.setSecurityEnabled(false);
configuration.getAcceptorConfigurations().add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
// Step 2. Create the JMS configuration
JMSConfiguration jmsConfig = new JMSConfigurationImpl();
// Step 2. Create the JMS configuration
JMSConfiguration jmsConfig = new JMSConfigurationImpl();
// Step 3. Configure the JMS ConnectionFactory
TransportConfiguration connectorConfig = new TransportConfiguration(NettyConnectorFactory.class.getName());
ConnectionFactoryConfiguration cfConfig = new ConnectionFactoryConfigurationImpl("cf", connectorConfig, "/cf");
jmsConfig.getConnectionFactoryConfigurations().add(cfConfig);
// Step 3. Configure the JMS ConnectionFactory
TransportConfiguration connectorConfig = new TransportConfiguration(NettyConnectorFactory.class.getName());
ConnectionFactoryConfiguration cfConfig = new ConnectionFactoryConfigurationImpl("cf", connectorConfig, "/cf");
jmsConfig.getConnectionFactoryConfigurations().add(cfConfig);
// Step 4. Configure the JMS Queue
JMSQueueConfiguration queueConfig = new JMSQueueConfigurationImpl("queue1", null, false, "/queue/queue1");
jmsConfig.getQueueConfigurations().add(queueConfig);
// Step 4. Configure the JMS Queue
JMSQueueConfiguration queueConfig = new JMSQueueConfigurationImpl("queue1", null, false, "/queue/queue1");
jmsConfig.getQueueConfigurations().add(queueConfig);
// Step 5. Start the JMS Server using the ActiveMQ core server and the JMS configuration
EmbeddedJMS jmsServer = new EmbeddedJMS();
jmsServer.setConfiguration(configuration);
jmsServer.setJmsConfiguration(jmsConfig);
jmsServer.start();
// Step 5. Start the JMS Server using the ActiveMQ core server and the JMS configuration
EmbeddedJMS jmsServer = new EmbeddedJMS();
jmsServer.setConfiguration(configuration);
jmsServer.setJmsConfiguration(jmsConfig);
jmsServer.start();
```
Please see ? for an example which shows how to setup and run ActiveMQ
embedded with JMS.
Dependency Frameworks
=====================
## Dependency Frameworks
You may also choose to use a dependency injection framework such as
JBoss Micro Container or Spring Framework. See ? for more details on
@ -221,5 +227,7 @@ be:
`ActiveMQBootstrapServer` provides an easy encapsulation of JBoss Micro
Container.
ActiveMQBootstrapServer bootStrap = new ActiveMQBootstrapServer(new String[] {"activemq-beans.xml"});
bootStrap.run();
``` java
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
SQL 92 expression syntax.
@ -17,13 +16,13 @@ Filter expressions are used in several places in ActiveMQ
filter expression will enter the queue.
- 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
matching messages will be diverted (see ?).
matching messages will be diverted (see [Diverts](diverts.md)).
- 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
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
server, or a server and another server in order to prevent the client or
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
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
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
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
two extremes:
Fast consumers
: Fast consumers can process messages as fast as they consume them (or
even faster)
### Fast consumers
Fast consumers can process messages as fast as they consume them (or
even faster)
To allow fast consumers, set the `consumer-window-size` to -1. This
will allow *unbounded* message buffering on the client side.
To allow fast consumers, set the `consumer-window-size` to -1. This
will allow *unbounded* message buffering on the client side.
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
them.
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
them.
Slow consumers
: Slow consumers takes significant time to process each message and it
is desirable to prevent buffering messages on the client side so
that they can be delivered to another consumer instead.
### Slow consumers
Slow consumers takes significant time to process each message and it
is desirable to prevent buffering messages on the client side so
that they can be delivered to another consumer instead.
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
consumers, the fast consumer processes all of its messages very
quickly until its buffer is empty. At this point there are still
messages awaiting to be processed in the buffer of the slow consumer
thus preventing them being processed by the fast consumer. The fast
consumer is therefore sitting idle when it could be processing the
other messages.
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
consumers, the fast consumer processes all of its messages very
quickly until its buffer is empty. At this point there are still
messages awaiting to be processed in the buffer of the slow consumer
thus preventing them being processed by the fast consumer. The fast
consumer is therefore sitting idle when it could be processing the
other messages.
To allow slow consumers, set the `consumer-window-size` to 0 (for no
buffer at all). This will prevent the slow consumer from buffering
any messages on the client side. Messages will remain on the server
side ready to be consumed by other consumers.
To allow slow consumers, set the `consumer-window-size` to 0 (for no
buffer at all). This will prevent the slow consumer from buffering
any messages on the client side. Messages will remain on the server
side ready to be consumed by other consumers.
Setting this to 0 can give deterministic distribution between
multiple consumers on a queue.
Setting this to 0 can give deterministic distribution between
multiple consumers on a queue.
Most of the consumers cannot be clearly identified as fast or slow
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
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
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
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
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
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
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
`ServerLocator.setProducerWindowSize(int producerWindowSize)` method.
### Using JMS
#### Using JMS
If JNDI is used to instantiate and look up the connection factory, the
producer window size can be configured in the JNDI context environment,
@ -208,7 +202,7 @@ size can be set via the
`ActiveMQConnectionFactory.setProducerWindowSize(int
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
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
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`
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
> 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,
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.
### Using Core API
#### Using Core API
If the ActiveMQ core API is being used the rate can be set via the
`ServerLocator.setProducerMaxRate(int producerMaxRate)` method or
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
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
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
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
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
live server coming back up and automatically stop.
HA Policies
-----------
### HA Policies
ActiveMQ supports two different strategies for backing up a server
*shared store* and *replication*. Which is configured via the
@ -95,8 +92,7 @@ or
</ha-policy>
Data Replication
----------------
### Data Replication
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
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
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
have to determine which one has the latest data.
The replicating live and backup pair must be part of a cluster. The
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:
- 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
reconnecting with the live. This avoids a split brain situation.
### Configuration
#### Configuration
To configure the live and backup servers to be a replicating pair,
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>
</ha-policy>
### All Replication Configuration
#### All Replication Configuration
The following table lists all the `ha-policy` configuration elements for
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
`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*
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)
### Configuration
#### Configuration
To configure the live and backup servers to share their store, configure
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
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**
>
@ -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
defined even if not part of a cluster. The Cluster Connection info
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.
Failing Back to live Server
---------------------------
### Failing Back to live Server
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
@ -396,7 +390,7 @@ or `slave` like so:
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
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
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>
</ha-policy>
### All Shared Store Configuration
#### All Shared Store Configuration
The following table lists all the `ha-policy` configuration elements for
HA strategy shared store for `master`:
@ -419,19 +413,18 @@ HA strategy shared store for `master`:
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
`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
HA strategy Shared Store for `slave`:
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.
`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
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)
### Configuring Connectors and Acceptors
#### Configuring Connectors and Acceptors
If the HA Policy is colocated then connectors and acceptors will be
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>
### Configuring Directories
#### Configuring Directories
Directories for the Journal, Large messages and Paging will be set
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.
`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.
when configured for scale down a server can copy all its messages and
@ -568,8 +560,7 @@ this would look like:
</ha-policy>
Scale Down with groups
----------------------
#### Scale Down with groups
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
@ -588,8 +579,7 @@ like so:
In this scenario only servers that belong to the group `my-group` will
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
slave is configured to scale down then after failover has occurred,
@ -630,8 +620,7 @@ typical configuration would look like:
</ha-policy>
Scale Down and Clients
----------------------
#### Scale Down and Clients
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
@ -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
be high enough to deal with the time needed to scale down.
Failover Modes
==============
## Failover Modes
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
connections to the same server (e.g. in case of transient network
problems). This is similar to failover, except it is reconnecting to the
same server and is discussed in ?
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
temporary queues, those queues will be automatically recreated during
failover on the backup node, since the backup node will not have any
knowledge of non persistent queues.
Automatic Client Failover
-------------------------
### Automatic Client Failover
ActiveMQ clients can be configured to receive knowledge of all live and
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
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
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
@ -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
explicitly or probably the most common way of doing this is to use
*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
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
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
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
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
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
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
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
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
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.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
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
> 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
call is unblocked. If the transaction had indeed been committed on the
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,
> 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
lost in the event of failover.
If you wish to provide *once and only once* delivery guarantees for non
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
connection failure: `java.jms.ExceptionListener`. Please consult the JMS
@ -867,8 +853,7 @@ following:
: JMSException error codes
Application-Level Failover
--------------------------
### Application-Level Failover
In some cases you may not want automatic client failover, and prefer to
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
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
makes interceptors powerful, but also potentially dangerous.
Implementing The Interceptors
=============================
## Implementing The Interceptors
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
{
boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException;
}
public interface Interceptor
{
boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException;
}
```
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
further by the server.
Configuring The Interceptors
============================
## Configuring The Interceptors
Both incoming and outgoing interceptors are configured in
`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
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
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
and invoked.
Example
=======
## Example
See ? for an example which shows how to use interceptors to add
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
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
it a good choice for interoperability.
Native Stomp support
--------------------
## Native Stomp support
ActiveMQ provides native support for Stomp. To be able to send and
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
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
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
`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
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
> 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
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
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`
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
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,
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
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
[min-large-message-size](#large-messages.core.config).
Stomp Over Web Sockets
----------------------
### Stomp Over Web Sockets
ActiveMQ also support Stomp over [Web
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
topic.
StompConnect
------------
### StompConnect
[StompConnect](http://stomp.codehaus.org/StompConnect) is a server that
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
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
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
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
to map onto the underlying session created for the connection so you can
use the normal ActiveMQ security configuration.
AMQP Links
----------
### AMQP Links
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
@ -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
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
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
> 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
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
> support single transactions per session
OpenWire
========
## OpenWire
ActiveMQ now supports the
[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.
@ -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
> 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
> 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
@ -183,8 +182,7 @@ server.
</bean>
</deployment>
JMS Bridge Parameters
=====================
## JMS Bridge Parameters
The main bean deployed is the `JMSBridge` bean. The bean is configurable
by the parameters passed to its constructor.
@ -268,7 +266,7 @@ by the parameters passed to its constructor.
- `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
@ -333,8 +331,7 @@ look something like this:
<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 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
`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
destinations.
@ -358,14 +354,12 @@ ActiveMQ that looks up the destination using JNDI.
A new implementation can be provided by implementing
`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
more detail.
AT\_MOST\_ONCE
--------------
### AT_MOST_ONCE
With this QoS mode messages will reach the destination from the source
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.
DUPLICATES\_OK
--------------
### DUPLICATES_OK
With this QoS mode, the messages are consumed from the source and then
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.
ONCE\_AND\_ONLY\_ONCE
---------------------
### ONCE_AND_ONLY_ONCE
This QoS mode ensures messages will reach the destination from the
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
> 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
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
you will have to bear in mind timeout issues.
Examples
--------
### Examples
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

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
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
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
or the server.
Configuring the server
======================
## Configuring the server
Large messages are stored on a disk directory on the server side, as
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
directory.
Configuring Parameters
======================
## Configuring Parameters
Any message larger than a certain size is considered a large message.
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.
Using Core API
--------------
### Using Core API
If the ActiveMQ Core API is used, the minimal large message size is
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.
Using JMS
---------
### Using JMS
If JNDI is used to instantiate and look up the connection factory, the
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
`ActiveMQConnectionFactory.setMinLargeMessageSize`.
Compressed Large Messages
-------------------------
### Compressed Large Messages
You can choose to send large messages in compressed form using `
compress-large-messages` attributes.
### `compress-large-messages`
#### `compress-large-messages`
If you specify the boolean property `compress-large-messages` on 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
connection.ConnectionFactory.compressLargeMessages=true
Streaming large messages
========================
## Streaming large messages
ActiveMQ supports setting the body of messages using input and output
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
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`
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:
...
ClientMessage msg = consumer.receive(...);
``` java
ClientMessage msg = consumer.receive(...);
// This will block here until the stream was transferred
msg.saveOutputStream(someOutputStream);
// This will block here until the stream was transferred
msg.saveOutputStream(someOutputStream);
ClientMessage msg2 = consumer.receive(...);
ClientMessage msg2 = consumer.receive(...);
// This will not wait the transfer to finish
msg.setOutputStream(someOtherOutputStream);
...
// This will not wait the transfer to finish
msg.setOutputStream(someOtherOutputStream);
```
Set the input stream when sending a core message:
...
ClientMessage msg = session.createMessage();
msg.setInputStream(dataInputStream);
...
``` java
ClientMessage msg = session.createMessage();
msg.setInputStream(dataInputStream);
```
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
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
?) 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.
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
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);
File outputFile = new File("huge_message_received.dat");
FileOutputStream fileOutputStream = new FileOutputStream(outputFile);
BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream);
// This will block until the entire content is saved on disk
messageReceived.setObjectProperty("JMS_HQ_SaveStream", bufferedOutput);
``` java
BytesMessage messageReceived = (BytesMessage)messageConsumer.receive(120000);
File outputFile = new File("huge_message_received.dat");
FileOutputStream fileOutputStream = new FileOutputStream(outputFile);
BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream);
// 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
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.
messageReceived.setObjectProperty("JMS_HQ_OutputStream", bufferedOutput);
``` java
// This won't wait the stream to finish. You need to keep the consumer active.
messageReceived.setObjectProperty("JMS_HQ_OutputStream", bufferedOutput);
```
> **Note**
>
> When using JMS, Streaming large messages are only supported on
> `StreamMessage` and `BytesMessage`.
Streaming Alternative
=====================
## Streaming Alternative
If you choose not to use the `InputStream` or `OutputStream` capability
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.
ClientMessage msg = consumer.receive();
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
}
``` java
ClientMessage msg = consumer.receive();
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
}
```
If using JMS API, `BytesMessage` and `StreamMessage` also supports it
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)
{
int numberOfBytes = rm.readBytes(data);
// Do whatever you want with the data
}
Large message example
=====================
## Large message example
Please see ? for an example which shows how large message is configured
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
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
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:
@ -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
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"`
(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
kept in the queue:
// send 1st message with Last-Value property set to STOCK_NAME
TextMessage message = session.createTextMessage("1st message with Last-Value property set");
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
producer.send(message);
``` java
// send 1st message with Last-Value property set to STOCK_NAME
TextMessage message = session.createTextMessage("1st message with Last-Value property set");
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
producer.send(message);
// send 2nd message with Last-Value property set to STOCK_NAME
message = session.createTextMessage("2nd message with Last-Value property set");
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
producer.send(message);
...
// only the 2nd message will be received: it is the latest with
// the Last-Value property set
TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
System.out.format("Received message: %s\n", messageReceived.getText());
// send 2nd message with Last-Value property set to STOCK_NAME
message = session.createTextMessage("2nd message with Last-Value property set");
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
producer.send(message);
...
// only the 2nd message will be received: it is the latest with
// the Last-Value property set
TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
System.out.format("Received message: %s\n", messageReceived.getText());
```
Example
=======
## Example
See ? for an example which shows how last value queues are configured
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
and Linux libaio.
@ -10,7 +9,7 @@ processed asynchronously. Some time later the OS will call our code back
when they have been processed.
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:
@ -21,16 +20,14 @@ These are the native libraries distributed by ActiveMQ:
When using libaio, ActiveMQ will always try loading these files as long
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
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
those platforms with the release.
Install requirements
--------------------
## Install requirements
> **Note**
>
@ -76,8 +73,7 @@ Or on Debian systems:
> the version and Linux distribution. (for example gcc-c++ on Fedora
> versus g++ on Debian systems)
Invoking the compilation
------------------------
## Invoking the compilation
In the distribution, in the `native-src` directory, execute the shell
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
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
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
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.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
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
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
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
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
> *all messages*.
Core Management API
-------------------
### Core Management API
ActiveMQ defines a core management API to manage core resources. For
full details of the API please consult the javadoc. In summary:
### Core Server Management
#### Core Server Management
- 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
> you use to call it.
### Core Address Management
#### Core Address Management
Core addresses can be managed using the `AddressControl` class (with 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
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
`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
`listMessageCounter()` and `listMessageCounterHistory()` methods
(see ?). The message counters can also be reset for a single queue
using the `resetMessageCounter()` method.
(see Message Counters section). The message counters can also be
reset for a single queue using the `resetMessageCounter()` method.
- 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
any.
### Other Core Resources Management
#### Other Core Resources Management
ActiveMQ allows to start and stop its remote resources (acceptors,
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
`core.acceptor.<the
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
@ -261,7 +258,7 @@ transactions). These resources are:
`org.apache.activemq:module=Core,type=Divert,name=<the divert name>`
or the resource name `core.divert.<the divert name>`). Diverts
parameters can be retrieved using the `DivertControl` attributes
(see ?)
(see [Diverting and Splitting Message Flows)](diverts.md))
- Bridges
@ -271,7 +268,7 @@ transactions). These resources are:
name>"` or the resource name
`core.bridge.<the bridge
name>`). Bridges parameters can be retrieved
using the `BridgeControl` attributes (see ?)
using the `BridgeControl` attributes (see [Core bridges](core-bridges.md))
- Broadcast groups
@ -281,7 +278,7 @@ transactions). These resources are:
name>"` or the resource name
`core.broadcastgroup.<the broadcast group name>`). Broadcast groups
parameters can be retrieved using the `BroadcastGroupControl`
attributes (see ?)
attributes (see [Clusters](clusters.md))
- Discovery groups
@ -292,7 +289,7 @@ transactions). These resources are:
`core.discovery.<the
discovery group name>`). Discovery groups
parameters can be retrieved using the `DiscoveryGroupControl`
attributes (see ?)
attributes (see [Clusters](clusters.md))
- Cluster connections
@ -302,15 +299,14 @@ transactions). These resources are:
connection name>"` or the resource name
`core.clusterconnection.<the cluster connection name>`). Cluster
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
objects* (i.e. JMS queues, topics and connection factories).
### JMS Server Management
#### JMS Server Management
JMS Resources (connection factories and destinations) can be created
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
first `key` will be associated to the first transport configuration
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
@ -364,7 +361,7 @@ using the `JMSServerControl` class (with the ObjectName
`listConnectionIDs()` and all the sessions for a given connection ID
can be listed using `listSessions()`.
### JMS ConnectionFactory Management
#### JMS ConnectionFactory Management
JMS Connection Factories can be managed using the
`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
non-durable messages, etc.)
### JMS Queue Management
#### JMS Queue Management
JMS queues can be managed using the `JMSQueueControl` class (with the
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
`listMessageCounter()` and `listMessageCounterHistory()` methods
(see ?)
(see Message Counters section)
- Retrieving the queue attributes
@ -455,7 +452,7 @@ operations on a core queue.*
will not deliver them. When resumed again it will deliver the
enqueued messages, if any.
### JMS Topic Management
#### JMS Topic Management
JMS Topics can be managed using the `TopicControl` class (with the
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
selector)
Using Management Via JMX
========================
## Using Management Via JMX
ActiveMQ can be managed using
[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
proxies of the MBeans.
Configuring JMX
---------------
### Configuring JMX
By default, JMX is enabled to manage ActiveMQ. It can be disabled by
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 -->
<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
`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" />
</bean>
Example
-------
### Example
See ? for an example which shows how to use a remote connection to JMX
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
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
`exampleQueue`:
ClientSession session = ...
ClientRequestor requestor = new ClientRequestor(session, "jms.queue.activemq.management");
ClientMessage message = session.createMessage(false);
ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount");
session.start();
ClientMessage reply = requestor.request(m);
int count = (Integer) ManagementHelper.getResult(reply);
System.out.println("There are " + count + " messages in exampleQueue");
``` java
ClientSession session = ...
ClientRequestor requestor = new ClientRequestor(session, "jms.queue.activemq.management");
ClientMessage message = session.createMessage(false);
ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount");
session.start();
ClientMessage reply = requestor.request(m);
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
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
`exampleTopic`, etc.).
Configuring Core Management
---------------------------
### Configuring Core Management
The management address to send management messages is configured in
`activemq-configuration.xml`:
@ -655,8 +649,7 @@ configured in activemq-configuration.xml:
<permission type="manage" roles="admin" />
</security-setting>
Using Management Via JMS
========================
## Using Management Via JMS
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
`exampleQueue`:
``` java
Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
QueueSession session = ...
QueueRequestor requestor = new QueueRequestor(session, managementQueue);
connection.start();
Message message = session.createMessage();
JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "messageCount");
Message reply = requestor.request(message);
int count = (Integer)JMSManagementHelper.getResult(reply);
System.out.println("There are " + count + " messages in exampleQueue");
Configuring JMS Management
--------------------------
QueueSession session = ...
QueueRequestor requestor = new QueueRequestor(session, managementQueue);
connection.start();
Message message = session.createMessage();
JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "messageCount");
Message reply = requestor.request(message);
int count = (Integer)JMSManagementHelper.getResult(reply);
System.out.println("There are " + count + " messages in exampleQueue");
```
### Configuring JMS Management
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
ActiveMQ server.
Management Notifications
========================
## Management Notifications
ActiveMQ emits *notifications* to inform listeners of potentially
interesting events (creation of new resources, security violation,
@ -727,10 +717,9 @@ These notifications can be received by 3 different ways:
- 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:
- `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
*JMS* resources
Core Messages Notifications
---------------------------
### Core Messages Notifications
ActiveMQ defines a special *management notification address*. Core
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
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
is configured in `activemq-configuration.xml`:
@ -767,8 +755,7 @@ is configured in `activemq-configuration.xml`:
By default, the address is `activemq.notifications`.
JMS Messages Notifications
--------------------------
### JMS Messages Notifications
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
or set a `MessageListener`:
Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic");
``` java
Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic");
Session session = ...
MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
notificationConsumer.setMessageListener(new MessageListener()
{
public void onMessage(Message notif)
{
System.out.println("------------------------");
System.out.println("Received notification:");
try
{
Enumeration propertyNames = notif.getPropertyNames();
while (propertyNames.hasMoreElements())
{
String propertyName = (String)propertyNames.nextElement();
System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName));
}
}
catch (JMSException e)
{
}
System.out.println("------------------------");
}
});
Example
-------
Session session = ...
MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
notificationConsumer.setMessageListener(new MessageListener()
{
public void onMessage(Message notif)
{
System.out.println("------------------------");
System.out.println("Received notification:");
try
{
Enumeration propertyNames = notif.getPropertyNames();
while (propertyNames.hasMoreElements())
{
String propertyName = (String)propertyNames.nextElement();
System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName));
}
}
catch (JMSException e)
{
}
System.out.println("------------------------");
}
});
```
### Example
See ? for an example which shows how to use a JMS `MessageListener` to
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
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_ConnectionName`, `_HQ_ConsumerName`, `_HQ_SessionName`
Message Counters
================
## Message Counters
Message counters can be used to obtain information on queues *over time*
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`
from `countDelta`.
Configuring Message Counters
----------------------------
### Configuring Message Counters
By default, message counters are disabled as it might have a small
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,
to retrieve message counters on a JMS Queue using JMX:
// retrieve a connection to ActiveMQ's MBeanServer
MBeanServerConnection mbsc = ...
JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
on,
JMSQueueControl.class,
false);
// message counters are retrieved as a JSON String
String counters = queueControl.listMessageCounter();
// use the MessageCounterInfo helper class to manipulate message counters more easily
MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);
System.out.format("%s message(s) in the queue (since last sample: %s)\n",
messageCounter.getMessageCount(),
messageCounter.getMessageCountDelta());
``` java
// retrieve a connection to ActiveMQ's MBeanServer
MBeanServerConnection mbsc = ...
JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
on,
JMSQueueControl.class,
false);
// message counters are retrieved as a JSON String
String counters = queueControl.listMessageCounter();
// use the MessageCounterInfo helper class to manipulate message counters more easily
MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);
System.out.format("%s message(s) in the queue (since last sample: %s)\n",
messageCounter.getMessageCount(),
messageCounter.getMessageCountDelta());
```
Example
-------
### Example
See ? for an example which shows how to use message counters to retrieve
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
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
configure each resource in turn.
JMS Queues
----------
### JMS Queues
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
@ -1055,7 +1038,7 @@ configuration options, apart from security roles, relate to address
settings for a particular address. The default address settings are
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
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
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
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
setting see ?
setting see [Security](security.md)
It is also possible via the metrics tab to view statistics for this
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
appear at the bottom of the screen.
JMS Topics
----------
### JMS Topics
Creating and configuring JMS Topics is almost identical to creating
queues. The only difference is that the configuration will be applied to
the queue representing a subscription.
JMS Connection Factories
------------------------
### JMS Connection Factories
The format for creating connection factories is the same as for JMS
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.
@ -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.
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
message:
@ -44,8 +42,7 @@ following properties:
a Long property containing the *actual expiration time* of the
expired message
Configuring Expiry Addresses
============================
## Configuring Expiry Addresses
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
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
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
highest priority, default is 3)
Example
=======
## Example
See ? for an example which shows how message expiry is configured and
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
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
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
\_HQ\_GROUP\_ID property.
_HQ_GROUP_ID property.
This will ensure that all messages for a particular stock will always be
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
> from your non-grouped messages.
Using Core API
==============
## Using Core API
The property name used to identify the message group is `"_HQ_GROUP_ID"`
(or the constant `MessageImpl.HDR_GROUP_ID`). Alternatively, you can set
`autogroup` to true on the `SessionFactory` which will pick a random
unique id.
Using JMS
=========
## Using JMS
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
connection.ConnectionFactory.groupID=Group-0
Example
=======
## Example
See ? for an example which shows how message groups are configured and
used with JMS.
Example
=======
## Example
See ? for an example which shows how message groups are configured via a
connection factory.
Clustered Grouping
==================
## Clustered Grouping
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
@ -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
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:
@ -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
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
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
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
capable of, then you can skip this chapter.
Messaging Concepts
==================
## Messaging Concepts
Messaging systems allow you to loosely couple heterogeneous systems
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
each other.
Messaging styles
================
## Messaging styles
Messaging systems normally support two main styles of asynchronous
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.
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
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
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
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
delivered to each subscription.
Delivery guarantees
===================
## Delivery guarantees
A key feature of most messaging systems is *reliable messaging*. With
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
require.
Transactions
============
## Transactions
Messaging systems typically support the sending and acknowledgement of
multiple messages in a single local transaction. ActiveMQ also supports
the sending and acknowledgement of message as part of a large global
transaction - using the Java mapping of XA: JTA.
Durability
==========
## Durability
Messages are either durable or non durable. Durable messages will be
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
restart.
Messaging APIs and protocols
============================
## Messaging APIs and protocols
How do client applications interact with messaging systems in order to
send and consume messages?
@ -176,8 +167,7 @@ and some emerging standards in this space.
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
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.
System specific APIs
--------------------
### System specific APIs
Many systems provide their own programmatic API for which to interact
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
the JMS API.
RESTful API
-----------
### RESTful API
[REST](http://en.wikipedia.org/wiki/Representational_State_Transfer)
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
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
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
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
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
able to interact with ActiveMQ.
High Availability
=================
## High Availability
High Availability (HA) means that the system should remain operational
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
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
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
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
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
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
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
configured to activate it.
Page Files
==========
## Page Files
Messages are stored per address on the file system. Each address has an
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
it will ignore messages that don't match the criteria.
Configuration
=============
## Configuration
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 Mode
===========
## Paging Mode
As soon as messages delivered to an address exceed the configured size,
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
> max-size-bytes.
Configuration
-------------
## Configuration
Configuration is done at the address settings, done at the main
configuration file (`activemq-configuration.xml`).
@ -90,8 +85,7 @@ This is the list of available parameters on the address settings.
: Paging Address Settings
Dropping messages
=================
## Dropping messages
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.
@ -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
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
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
settings
Blocking producers
==================
## Blocking producers
Instead of paging messages when the max size is reached, an address can
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
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
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
undesirable state.
Example
=======
## Example
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
performance.
Tuning persistence
==================
## Tuning persistence
- Put the message journal on its own physical volume. If the disk is
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
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
JMS API
@ -78,8 +75,7 @@ JMS API
ActiveMQ will only require a network round trip on the commit, not
on every send or acknowledgement.
Other Tunings
=============
## Other Tunings
There are various other places in ActiveMQ where we can perform some
tuning:
@ -89,12 +85,13 @@ tuning:
reached the server by the time the call to send() returns, don't set
durable messages to be sent blocking, instead use asynchronous send
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
acknowledged `before` they are sent to the client. This reduces the
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
security by setting the `security-enabled` parameter to `false` in
@ -107,20 +104,22 @@ tuning:
- Sync transactions lazily. Setting `journal-sync-transactional` to
`false` in `activemq-configuration.xml` can give you better
transactional persistent performance at the expense of some
possibility of loss of transactions on failure. See ? for more
information.
possibility of loss of transactions on failure. See [Guarantees of sends and commits](send-guarantees.md)
for more information.
- Sync non transactional lazily. Setting
`journal-sync-non-transactional` to `false` in
`activemq-configuration.xml` can give you better non-transactional
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
`block-on-non-durable-send` to `false` in `activemq-jms.xml` (if
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
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
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)
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
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.
@ -145,12 +144,12 @@ tuning:
the wire, so if you re-use `SimpleString` instances between calls
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
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**
>
@ -180,10 +179,10 @@ Tuning Transport Settings
`activemq-configuration.xml` and JMS connection factory
(`ThroughputConnectionFactory`) in `activemq-jms.xml`which can be
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
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.
- 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.
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
@ -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
platform and application usage patterns.
Avoiding Anti-Patterns
======================
## Avoiding Anti-Patterns
- Re-use connections / sessions / consumers / producers. Probably the
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
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
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
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
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.
@ -118,16 +117,16 @@ The standard ActiveMQ core server uses two instances of the journal:
(configurable), and it is located at the journal folder.
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
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
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
`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
is `true`
Configuring the jms journal
===========================
## Configuring the jms 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
`activemq-configuration.xml`
@ -283,8 +280,7 @@ The message journal is configured using the following attributes in
The default for this parameter is `30`
An important note on disabling disk write cache.
================================================
## An important note on disabling disk write cache.
> **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
> disk and clicking properties.
Installing AIO
==============
## Installing AIO
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
@ -344,8 +339,7 @@ Using aptitude, (e.g. on Ubuntu or Debian system):
apt-get install libaio
Configuring ActiveMQ for Zero Persistence
=========================================
## Configuring ActiveMQ for Zero Persistence
In some situations, zero persistence is sometimes required for a
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
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
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
- JournalPrefix: Use the prefix for your selected journal, as
discussed [here](#persistence.journallist)
discussed above
- 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
[here](#persistence.journallist)
- FileSize: Use the size for your selected journal, as discussed above
- 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:
@ -41,8 +40,7 @@ arrive soon, overriding the previous price.
> the transaction. This may be stating the obvious but we like to be
> 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.
`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
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
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
> message inside the MDB.
Example
=======
## Example
See ? for an example which shows how to use pre-acknowledgement mode
with JMS.

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

@ -1,5 +1,4 @@
Preface
=======
# Preface
What is ActiveMQ?
@ -8,11 +7,11 @@ What is ActiveMQ?
system.
- 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
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:
@ -47,6 +46,6 @@ Why use ActiveMQ? Here are just a few of the reasons:
routing of messages in a highly flexible way.
- 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
page:<http://activemq.org/downloads.html>
page:<http://activemq.apache.org/download.html>
Project Information
===================
- Please take a look at our project
[wiki](http://www.jboss.org/community/wiki/ActiveMQ)
## Project Information
- 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
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
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/activemq/activemq>
- ActiveMQ Git repository is <https://github.com/apache/activemq-6>
- 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
create ActiveMQ, for a full list of the people who made it happen, take
a look at our [team
page](http://jboss.org.apache.activemq/community/team.html).
create ActiveMQ.

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
them using the configuration file or by using the core API. This chapter
will explain how to configure each attribute and what effect the
attribute has.
Predefined Queues
=================
## Predefined Queues
Queues can be predefined via configuration at a core level or at a JMS
level. Firstly let's look at a JMS level.
@ -59,11 +57,10 @@ which are.
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.
Using the API
=============
## Using the 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
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.
Configuring Queues Via Address Settings
=======================================
## Configuring Queues Via Address Settings
There are some attributes that are defined against an address wildcard
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
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
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
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
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
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
of the REST interface?
@ -54,8 +52,7 @@ of the REST interface?
ActiveMQ on the back end without sacrificing the simplicity of a
REST interface.
Installation and Configuration
==============================
## Installation and Configuration
ActiveMQ's REST interface is installed as a Web archive (WAR). It
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
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
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
> 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
have the ActiveMQ core and JMS jars along with Netty, Resteasy, and the
@ -293,8 +288,7 @@ WEB-INF/classes directory!
</dependencies>
</project>
REST Configuration
------------------
### REST Configuration
The ActiveMQ REST implementation does have some configuration options.
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
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
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
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
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
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
with a Queue resource.
@ -441,8 +432,7 @@ with a Queue resource.
want the ActiveMQ REST server to push messages to. The semantics of
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
with a Topic resource.
@ -462,8 +452,7 @@ with a Topic resource.
you want the ActiveMQ REST server to push messages to. The semantics
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
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
> `msg-create` URL again.
Duplicate Detection
-------------------
### Duplicate Detection
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.
@ -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
`DUPLICATE_DETECTION_ID` once.
Persistent Messages
-------------------
### Persistent Messages
By default, posted messages are not durable and will not be persisted in
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>
</order>
TTL, Expiration and Priority
----------------------------
### TTL, Expiration and Priority
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.
@ -712,8 +698,7 @@ the priority of the message. i.e.:
<cost>$199.99</cost>
</order>
Consuming Messages via Pull
===========================
## Consuming Messages via Pull
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
@ -769,8 +754,7 @@ parameters (`application/x-www-form-urlencoded`) described below.
> then one consumer might buffer messages while the other consumer gets
> none.
Auto-Acknowledge
----------------
### Auto-Acknowledge
This section focuses on the auto-acknowledge protocol for consuming
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
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.
@ -858,7 +842,7 @@ pull subscription.
although, as you'll see later, it is transmitted with each response
just to remind you.
### Consuming Messages
#### Consuming Messages
After you have created a consumer resource, you are ready to start
pulling messages from the server. Notice that when you created the
@ -935,7 +919,7 @@ resource.
<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
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
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
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
messaging, then you must use the acknowledgement protocol.
Manual Acknowledgement
----------------------
### Manual Acknowledgement
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
@ -995,7 +978,7 @@ in.
- `msg-consumer`. This is a URL pointing back to the consumer or
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.
@ -1067,7 +1050,7 @@ topic pull subscription.
although, as you'll see later, it is transmitted with each response
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
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
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
`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
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
`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
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,
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
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
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
server-side consumer resource (and underlying JMS session).
Pushing Messages
================
## Pushing Messages
You can configure the ActiveMQ REST server to push messages to a
registered URL either remotely through the REST interface, or by
creating a pre-configured XML file for the ActiveMQ REST server to load
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
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"/>
</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
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"/>
</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
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
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
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>
</push-topic-registration>
Pushing to Authenticated Servers
--------------------------------
### Pushing to Authenticated Servers
Push subscriptions only support BASIC and DIGEST authentication out of
the box. Here is an example of adding BASIC authentication:
@ -1450,8 +1425,7 @@ headers might look like:
<header name="secret-header">jfdiwe3321</header>
</push-topic registration>
Creating Destinations
=====================
## Creating Destinations
You can create a durable queue or topic through the REST interface.
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
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
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
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
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.
-------------------------------------------- -----------------------------------------------------------------------
Mixing JMS and REST
===================
## Mixing JMS and REST
The ActiveMQ REST interface supports mixing JMS and REST producers 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
installed.
JMS Producers - REST Consumers
------------------------------
### JMS Producers - REST Consumers
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
@ -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 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,
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
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.
Scheduled Delivery Property
===========================
## Scheduled Delivery Property
The property name used to identify a scheduled message is
`"_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
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.");
message.setLongProperty("_HQ_SCHED_DELIVERY", System.currentTimeMillis() + 5000);
producer.send(message);
``` java
TextMessage message = session.createTextMessage("This is a scheduled message message which will be delivered in 5 sec.");
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
same property on the core message before sending.
Example
=======
## Example
See ? for an example which shows how scheduled messages can be used with
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
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
is `10000` ms.
Role based security for addresses
=================================
## Role based security for addresses
ActiveMQ contains a flexible role-based security model for applying
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
the set of queues that are bound to that address, the server then routes
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
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.":
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
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.
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
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
connected to other servers (e.g. via bridges) over an untrusted network
then ActiveMQ allows that traffic to be encrypted using the Secure
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
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
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
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.
JAAS Security Manager
=====================
## JAAS Security Manager
JAAS stands for 'Java Authentication and Authorization Service' and is a
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
interaction are required
Example
-------
## Example
See ? for an example which shows how ActiveMQ can be configured to use
JAAS.
JBoss AS Security Manager
=========================
## JBoss AS Security Manager
The JBoss AS security manager is used when running ActiveMQ inside the
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
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
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
> 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
defaults to `java:/jaas/activemq
`. This can be changed by specifying `securityDomainName`
(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
cluster must make connections to the other nodes. The username/password
they use for this should always be changed from the installation default
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
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`
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,
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
session, only the commit / rollback blocks not every send, or, using
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
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.
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
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
`false`
Asynchronous Send Acknowledgements
==================================
## Asynchronous Send Acknowledgements
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
?, 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
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
@ -128,10 +123,9 @@ successfully reached the server.
The window size for send acknowledgements is determined by the
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
`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
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
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
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,
`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
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
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.

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
can manage them.
@ -7,8 +6,7 @@ can manage them.
First we'll discuss how threads are managed and used on the server 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
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
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
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
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
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
pools.
Expiry Reaper Thread
--------------------
### Expiry Reaper Thread
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
@ -96,8 +91,7 @@ since this thread needs to run at its own configurable priority.
For more information on configuring the reaper, please see ?.
Asynchronous IO
---------------
### Asynchronous IO
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
@ -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
ActiveMQ-AIO-writer-pool.
Client-Side Thread Management
=============================
## Client-Side Thread Management
On the client side, ActiveMQ maintains a single static scheduled thread
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,
for example:
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(...)
ClientSessionFactory myFactory = locator.createClientSessionFactory();
myFactory.setUseGlobalPools(false);
myFactory.setScheduledThreadPoolMaxSize(10);
myFactory.setThreadPoolMaxSize(-1);
``` java
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(...)
ClientSessionFactory myFactory = locator.createClientSessionFactory();
myFactory.setUseGlobalPools(false);
myFactory.setScheduledThreadPoolMaxSize(10);
myFactory.setThreadPoolMaxSize(-1);
```
If you're using the JMS API, you can set the same parameters on the
ClientSessionFactory and use it to create the `ConnectionFactory`
instance, for example:
ConnectionFactory myConnectionFactory = ActiveMQJMSClient.createConnectionFactory(myFactory);
``` java
ConnectionFactory myConnectionFactory = ActiveMQJMSClient.createConnectionFactory(myFactory);
```
If you're using JNDI to instantiate `ActiveMQConnectionFactory`
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:
java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
java.naming.provider.url=tcp://localhost:5445
connection.ConnectionFactory.useGlobalPools=false
connection.ConnectionFactory.scheduledThreadPoolMaxSize=10
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
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
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
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.
Delayed Redelivery
==================
## Delayed Redelivery
Delaying redelivery can often be useful in the case that clients
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
succession, consuming valuable CPU and network resources.
Configuring Delayed Redelivery
------------------------------
### Configuring Delayed Redelivery
Delayed redelivery is defined in the address-setting configuration:
<!-- delay redelivery of messages for 5s -->
<address-setting match="jms.queue.exampleQueue">
<!-- default is 1.0 -->
<redelivery-delay-multiplier>1.5</redelivery-delay-multiplier>
<!-- default is 0 (no delay) -->
<redelivery-delay>5000</redelivery-delay>
<!-- default is redelivery-delay * 10 -->
<max-redelivery-delay>50000</max-redelivery-delay>
<!-- default is 1.0 -->
<redelivery-delay-multiplier>1.5</redelivery-delay-multiplier>
<!-- default is 0 (no delay) -->
<redelivery-delay>5000</redelivery-delay>
<!-- default is redelivery-delay * 10 -->
<max-redelivery-delay>50000</max-redelivery-delay>
</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
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.
Example
-------
### Example
See ? for an example which shows how delayed redelivery is configured
and used with JMS.
Dead Letter Addresses
=====================
## Dead Letter Addresses
To prevent a client infinitely receiving the same undelivered message
(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
inspection.
Configuring Dead Letter Addresses
---------------------------------
### Configuring Dead Letter Addresses
Dead letter address is defined in the address-setting configuration:
<!-- 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">
<dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
<max-delivery-attempts>3</max-delivery-attempts>
<dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
<max-delivery-attempts>3</max-delivery-attempts>
</address-setting>
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 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
the following properties:
@ -131,14 +124,12 @@ the following properties:
a String property containing the *original queue* of the dead letter
message
Example
-------
### Example
See ? for an example which shows how dead letter is configured and used
with JMS.
Delivery Count Persistence
==========================
## Delivery Count Persistence
In normal use, ActiveMQ does not update delivery count *persistently*
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
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
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
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,
please consult the Javadoc.
Message
-------
### Message
- A message is the unit of data which is sent between clients and
servers.
@ -54,10 +51,9 @@ Message
the message was sent.
- 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.
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
> which one queue is bound - that queue represents the JMS queue.
Queue
-----
### Queue
Queues can be durable, meaning the messages they contain survive a
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
bound to a maximum of one address.
ServerLocator
-------------
### ServerLocator
Clients use `ServerLocator` instances to create `ClientSessionFactory`
instances. `ServerLocator` instances are used to locate servers and
@ -112,8 +106,7 @@ Connection Factory.
`ServerLocator` instances are created using the `ActiveMQClient` factory
class.
ClientSessionFactory
--------------------
### ClientSessionFactory
Clients use `ClientSessionFactory` instances to create `ClientSession`
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`
class.
ClientSession
-------------
### ClientSession
A client uses a ClientSession for consuming and producing messages and
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
asynchronously you can create true end to end asynchronous systems which
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.
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
that expression.
ClientProducer
--------------
### ClientProducer
Clients create `ClientProducer` instances on `ClientSession` instances
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
> ClientConsumer instances for each message you produce or consume. If
> 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
receive a message. Logically it's comprised of two sections: firstly
setting up the producer to write a message to an *addresss*, and
secondly, creating a *queue* for the consumer, creating the consumer and
*starting* it.
``` java
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(
InVMConnectorFactory.class.getName()));
ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(
InVMConnectorFactory.class.getName()));
// In this simple example, we just use one session for both producing and receiving
// In this simple example, we just use one session for both producing and receiving
ClientSessionFactory factory = locator.createClientSessionFactory();
ClientSession session = factory.createSession();
ClientSessionFactory factory = locator.createClientSessionFactory();
ClientSession session = factory.createSession();
// A producer is associated with an address ...
// 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");
ClientMessage message = session.createMessage(true);
message.getBodyBuffer().writeString("Hello");
// We need a queue attached to the address ...
// 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();
ClientMessage msgReceived = consumer.receive();
System.out.println("message = " + msgReceived.getBodyBuffer().readString());
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
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
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 is available in ?.
examples is available in [Examples](examples.md).
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
@ -214,19 +213,39 @@ Any property available on the underlying
this way in addition to the `ha` (boolean) and `type` (String)
properties. Here are the different options for the `type`:
type interface
--------------- ------------------------------------
CF (default) javax.jms.ConnectionFactory
XA\_CF javax.jms.XAConnectionFactory
QUEUE\_CF javax.jms.QueueConnectionFactory
QUEUE\_XA\_CF javax.jms.XAQueueConnectionFactory
TOPIC\_CF javax.jms.TopicConnectionFactory
TOPIC\_XA\_CF javax.jms.XATopicConnectionFactory
#### Configuration for Connection Factory Types
<table>
<tr>
<th>type</th>
<th>interface</th>
</tr>
<tr>
<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
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
correspond *exactly* to the name of the destination on the server.
The code
--------
### The code
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
on the classpath then any new, empty `InitialContext` will be
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
connections to myhost:5445:
ConnectionFactory cf = (ConnectionFactory)ic.lookup("ConnectionFactory");
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
acknowledge mode:
Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
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
queue:
MessageConsumer consumer = session.createConsumer(orderQueue);
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");
producer.send(message);
//And we consume the 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
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
> and consumers for each message you produce or consume. If you do this,
> 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
*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
Utility class, note we need to provide connection parameters and specify
which transport we are using, for more information on connectors please
see ?.
see [Configuring the Transport](configuring-transports.md).
TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName());
ConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);
``` java
TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName());
We also create the JMS Queue object via the ActiveMQJMSClient Utility
class:
ConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);
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
acknowledge mode:
Connection connection = cf.createConnection();
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
queue:
MessageProducer producer = session.createProducer(orderQueue);
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");
producer.send(message);
//We create a simple TextMessage and send it:
And we consume the message:
TextMessage message = session.createTextMessage("This is an order");
producer.send(message);
TextMessage receivedMessage = (TextMessage)consumer.receive();
System.out.println("Got order: " + receivedMessage.getText());
//And we consume the message:
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
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
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
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`
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
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.
@ -13,8 +12,7 @@ with a JMS Service and JNDI service enabled.
When running embedded in JBoss Application Server the layout may be
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`.
@ -42,8 +40,7 @@ used. The configuration can be changed e.g. by running
`./activemq run -- xml:../config/clustered/bootstrap.xml` or another
config of your choosing.
Server JVM settings
===================
## Server JVM settings
The run scripts set some JVM settings for tuning the 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
run scripts are the place to do it.
Pre-configured Options
======================
## Pre-configured Options
The distribution contains several standard configuration sets for
running:
@ -73,8 +69,7 @@ running:
You can of course create your own configuration and specify any
configuration when running the run script.
Library Path
============
## Library Path
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
@ -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
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
logging.
For more information on configuring logging, please see ?.
Configuration files
===================
## Configuration files
The configuration file used to bootstrap the server (e.g.
`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
supplied in that case.
Bootstrap File
==============
## Bootstrap File
The stand-alone server is basically a set of POJOs which are
instantiated by Airline commands.
@ -164,19 +156,13 @@ The bootstrap file is very simple. Let's take a look at an example:
<basic-security/>
<naming bindAddress="localhost" port="1099" rmiBindAddress="localhost" rmiPort="1098"/>
</broker>
- core
Instantiates a core server using the configuration file from the
- core - Instantiates a core server using the configuration file from the
`configuration` attribute. This is the main broker POJO necessary to
do all the real messaging work.
- jms
This deploys any JMS Objects such as JMS Queues, Topics and
- jms - This deploys any JMS Objects such as JMS Queues, Topics and
ConnectionFactory instances from the `activemq-jms.xml` file
specified. It also provides a simple management API for manipulating
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
require the JMS management interface this can be disabled.
- naming
Instantiates a naming server which implements JNDI. This is used by
JMS clients
The main configuration file.
============================
## The main configuration file.
The configuration for the ActiveMQ core server is contained in
`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
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
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
and route them to a ActiveMQ queue. Such a service can be configured as
follows:
<connector-service name="vertx-incoming-connector">
<factory-class>org.apache.activemq.integration.vertx.VertxIncomingConnectorServiceFactory</factory-class>
<param key="host" value="127.0.0.1"/>
<param key="port" value="0"/>
<param key="queue" value="jms.queue.vertxQueue"/>
<param key="vertx-address" value="vertx.in.eventaddress"/>
</connector-service>
<connector-service name="vertx-incoming-connector">
<factory-class>org.apache.activemq.integration.vertx.VertxIncomingConnectorServiceFactory</factory-class>
<param key="host" value="127.0.0.1"/>
<param key="port" value="0"/>
<param key="queue" value="jms.queue.vertxQueue"/>
<param key="vertx-address" value="vertx.in.eventaddress"/>
</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
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
queue and put them to vertx event bus. Such a service can be configured
as follows:
<connector-service name="vertx-outgoing-connector">
<factory-class>org.apache.activemq.integration.vertx.VertxOutgoingConnectorServiceFactory</factory-class>
<param key="host" value="127.0.0.1"/>
<param key="port" value="0"/>
<param key="queue" value="jms.queue.vertxQueue"/>
<param key="vertx-address" value="vertx.out.eventaddress"/>
<param key="publish" value="true"/>
</connector-service>
<connector-service name="vertx-outgoing-connector">
<factory-class>org.apache.activemq.integration.vertx.VertxOutgoingConnectorServiceFactory</factory-class>
<param key="host" value="127.0.0.1"/>
<param key="port" value="0"/>
<param key="queue" value="jms.queue.vertxQueue"/>
<param key="vertx-address" value="vertx.out.eventaddress"/>
<param key="publish" value="true"/>
</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.

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
settings, address settings and when creating consumers.