You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by cl...@apache.org on 2014/12/12 17:32:51 UTC
[4/5] activemq-6 git commit: documentation review fixes
documentation review fixes
Project: http://git-wip-us.apache.org/repos/asf/activemq-6/repo
Commit: http://git-wip-us.apache.org/repos/asf/activemq-6/commit/b4144013
Tree: http://git-wip-us.apache.org/repos/asf/activemq-6/tree/b4144013
Diff: http://git-wip-us.apache.org/repos/asf/activemq-6/diff/b4144013
Branch: refs/heads/master
Commit: b4144013d9756329c6e748fa213e0257d80e447d
Parents: 1491f4a
Author: Andy Taylor <an...@apache.org>
Authored: Thu Dec 11 12:17:29 2014 +0000
Committer: Andy Taylor <an...@apache.org>
Committed: Fri Dec 12 14:46:30 2014 +0000
----------------------------------------------------------------------
docs/user-manual/en/SUMMARY.md | 4 +-
docs/user-manual/en/aerogear-integration.md | 29 +-
docs/user-manual/en/appserver-integration.md | 433 +++++++++-----------
docs/user-manual/en/architecture.md | 43 +-
docs/user-manual/en/client-classpath.md | 9 +-
docs/user-manual/en/client-reconnection.md | 16 +-
docs/user-manual/en/clusters.md | 171 ++++----
docs/user-manual/en/configuring-transports.md | 77 ++--
docs/user-manual/en/connection-ttl.md | 109 +++--
docs/user-manual/en/core-bridges.md | 18 +-
docs/user-manual/en/diverts.md | 9 +-
docs/user-manual/en/duplicate-detection.md | 42 +-
docs/user-manual/en/embedding-activemq.md | 162 ++++----
docs/user-manual/en/filter-expressions.md | 9 +-
docs/user-manual/en/flow-control.md | 85 ++--
docs/user-manual/en/ha.md | 95 ++---
docs/user-manual/en/intercepting-operations.md | 27 +-
docs/user-manual/en/interoperability.md | 58 +--
docs/user-manual/en/jms-bridge.md | 34 +-
docs/user-manual/en/jms-core-mapping.md | 3 +-
docs/user-manual/en/large-messages.md | 156 +++----
docs/user-manual/en/last-value-queues.md | 48 ++-
docs/user-manual/en/libaio.md | 14 +-
docs/user-manual/en/logging.md | 9 +-
docs/user-manual/en/management.md | 249 ++++++-----
docs/user-manual/en/message-expiry.md | 17 +-
docs/user-manual/en/message-grouping.md | 26 +-
docs/user-manual/en/messaging-concepts.md | 61 +--
docs/user-manual/en/paging.md | 30 +-
docs/user-manual/en/perf-tuning.md | 46 +--
docs/user-manual/en/persistence.md | 42 +-
docs/user-manual/en/pre-acknowledge.md | 12 +-
docs/user-manual/en/preface.md | 9 +-
docs/user-manual/en/project-info.md | 42 +-
docs/user-manual/en/project-info.xml | 90 ----
docs/user-manual/en/queue-attributes.md | 18 +-
docs/user-manual/en/rest.md | 112 ++---
docs/user-manual/en/scheduled-messages.md | 24 +-
docs/user-manual/en/security.md | 44 +-
docs/user-manual/en/send-guarantees.md | 24 +-
docs/user-manual/en/slow-consumers.md | 6 +-
docs/user-manual/en/spring-integration.md | 5 +-
docs/user-manual/en/syntax.md | 22 +
docs/user-manual/en/thread-pooling.md | 46 ++-
docs/user-manual/en/tools.md | 3 +-
docs/user-manual/en/transaction-config.md | 3 +-
docs/user-manual/en/undelivered-messages.md | 49 +--
docs/user-manual/en/using-core.md | 82 ++--
docs/user-manual/en/using-jms.md | 171 ++++----
docs/user-manual/en/using-server.md | 42 +-
docs/user-manual/en/vertx-integration.md | 39 +-
docs/user-manual/en/wildcard-routing.md | 3 +-
docs/user-manual/en/wildcard-syntax.md | 3 +-
53 files changed, 1310 insertions(+), 1670 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 79f5d54..bf4804c 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -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)
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/aerogear-integration.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/aerogear-integration.md b/docs/user-manual/en/aerogear-integration.md
index e8c24f8..fcc1f05 100644
--- a/docs/user-manual/en/aerogear-integration.md
+++ b/docs/user-manual/en/aerogear-integration.md
@@ -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
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/appserver-integration.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/appserver-integration.md b/docs/user-manual/en/appserver-integration.md
index 8c4c9d5..e704b89 100644
--- a/docs/user-manual/en/appserver-integration.md
+++ b/docs/user-manual/en/appserver-integration.md
@@ -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;
-
- public void onMessage(Message message)
- {
- try
- {
- //something here fails
- }
- catch (Exception e)
- {
- ctx.setRollbackOnly();
- }
- }
+``` java
+@Resource
+MessageDrivenContextContext ctx;
+
+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)...
- }
-
-Using Bean-Managed Transactions
--------------------------------
+``` 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
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)....
- }
-
-Sending Messages from within JEE components
-===========================================
+``` 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
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;
-
- @Resource(mappedName = "queue/replyQueue")
- Queue replyQueue;
-
- public void onMessage(Message message)
- {
- Connection conn = null;
- try
- {
- //Step 9. We know the client is sending a text message so we cast
- TextMessage textMessage = (TextMessage)message;
-
- //Step 10. get the text from the message.
- String text = textMessage.getText();
-
- System.out.println("message " + text);
-
- conn = connectionFactory.createConnection();
-
- Session sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
- MessageProducer producer = sess.createProducer(replyQueue);
-
- producer.send(sess.createTextMessage("this is a reply"));
-
- }
- catch (Exception e)
- {
- e.printStackTrace();
- }
- finally
- {
- if(conn != null)
- {
- try
- {
- conn.close();
- }
- catch (JMSException e)
- {
- }
- }
- }
- }
- }
+``` 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;
+
+ public void onMessage(Message message)
+ {
+ Connection conn = null;
+ try
+ {
+ //Step 9. We know the client is sending a text message so we cast
+ TextMessage textMessage = (TextMessage)message;
+
+ //Step 10. get the text from the message.
+ String text = textMessage.getText();
+
+ System.out.println("message " + text);
+
+ conn = connectionFactory.createConnection();
+
+ Session sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
+
+ MessageProducer producer = sess.createProducer(replyQueue);
+
+ producer.send(sess.createTextMessage("this is a reply"));
+
+ }
+ catch (Exception e)
+ {
+ e.printStackTrace();
+ }
+ finally
+ {
+ if(conn != null)
+ {
+ try
+ {
+ conn.close();
+ }
+ catch (JMSException e)
+ {
+ }
+ }
+ }
+ }
+}
+```
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.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/architecture.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/architecture.md b/docs/user-manual/en/architecture.md
index fe0eb7f..4bccc22 100644
--- a/docs/user-manual/en/architecture.md
+++ b/docs/user-manual/en/architecture.md
@@ -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.
-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:
-For more information on server configuration files see ?. \$
+For more information on server configuration files see [Server Configuration](server-configuration.md)
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/client-classpath.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/client-classpath.md b/docs/user-manual/en/client-classpath.md
index 7142958..51ee972 100644
--- a/docs/user-manual/en/client-classpath.md
+++ b/docs/user-manual/en/client-classpath.md
@@ -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`.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/client-reconnection.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/client-reconnection.md b/docs/user-manual/en/client-reconnection.md
index 4ee441c..de434b8 100644
--- a/docs/user-manual/en/client-reconnection.md
+++ b/docs/user-manual/en/client-reconnection.md
@@ -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:
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/clusters.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/clusters.md b/docs/user-manual/en/clusters.md
index 6a1786c..ff61884 100644
--- a/docs/user-manual/en/clusters.md
+++ b/docs/user-manual/en/clusters.md
@@ -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
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/configuring-transports.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/configuring-transports.md b/docs/user-manual/en/configuring-transports.md
index f1d6194..af0c2b2 100644
--- a/docs/user-manual/en/configuring-transports.md
+++ b/docs/user-manual/en/configuring-transports.md
@@ -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
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/connection-ttl.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/connection-ttl.md b/docs/user-manual/en/connection-ttl.md
index 80af334..31a03fa 100644
--- a/docs/user-manual/en/connection-ttl.md
+++ b/docs/user-manual/en/connection-ttl.md
@@ -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;
-
- try
- {
- locator = ActiveMQClient.createServerLocatorWithoutHA(..);
-
- sf = locator.createClientSessionFactory();;
-
- 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();
- }
- }
+``` java
+ServerLocator locator = null;
+ClientSessionFactory sf = null;
+ClientSession session = null;
+
+try
+{
+ locator = ActiveMQClient.createServerLocatorWithoutHA(..);
+
+ sf = locator.createClientSessionFactory();;
+
+ 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();
+ }
+}
+```
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
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/core-bridges.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/core-bridges.md b/docs/user-manual/en/core-bridges.md
index 6b6b90f..b1e4e6e 100644
--- a/docs/user-manual/en/core-bridges.md
+++ b/docs/user-manual/en/core-bridges.md
@@ -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).
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/diverts.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/diverts.md b/docs/user-manual/en/diverts.md
index 60b00f7..eddfba3 100644
--- a/docs/user-manual/en/diverts.md
+++ b/docs/user-manual/en/diverts.md
@@ -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
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/b4144013/docs/user-manual/en/duplicate-detection.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/duplicate-detection.md b/docs/user-manual/en/duplicate-detection.md
index b7776eb..bc18c99 100644
--- a/docs/user-manual/en/duplicate-detection.md
+++ b/docs/user-manual/en/duplicate-detection.md
@@ -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).