diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 79f5d546ff..bf4804c360 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) diff --git a/docs/user-manual/en/aerogear-integration.md b/docs/user-manual/en/aerogear-integration.md index e8c24f8b93..fcc1f05c31 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 diff --git a/docs/user-manual/en/appserver-integration.md b/docs/user-manual/en/appserver-integration.md index 8c4c9d5842..e704b8978a 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; +``` 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 jndiParameters = new Hashtable(); - 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. diff --git a/docs/user-manual/en/architecture.md b/docs/user-manual/en/architecture.md index fe0eb7f6b0..4bccc22a64 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. ![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) diff --git a/docs/user-manual/en/client-classpath.md b/docs/user-manual/en/client-classpath.md index 7142958184..51ee972212 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`. diff --git a/docs/user-manual/en/client-reconnection.md b/docs/user-manual/en/client-reconnection.md index 4ee441c0c7..de434b8798 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: diff --git a/docs/user-manual/en/clusters.md b/docs/user-manual/en/clusters.md index 6a1786c5f5..ff61884195 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-stacks.xml -### 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 map = new HashMap(); - map.put("host", "myhost"); - map.put("port", "5445"); - TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map); - HashMap map2 = new HashMap(); - map2.put("host", "myhost2"); - map2.put("port", "5446"); - TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2); +``` java +HashMap map = new HashMap(); +map.put("host", "myhost"); +map.put("port", "5445"); +TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map); +HashMap map2 = new HashMap(); +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 map = new HashMap(); - map.put("host", "myhost"); - map.put("port", "5445"); - TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map); - HashMap map2 = new HashMap(); - map2.put("host", "myhost2"); - map2.put("port", "5446"); - TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2); +``` java +HashMap map = new HashMap(); +map.put("host", "myhost"); +map.put("port", "5445"); +TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map); +HashMap map2 = new HashMap(); +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 diff --git a/docs/user-manual/en/configuring-transports.md b/docs/user-manual/en/configuring-transports.md index f1d61940c5..af0c2b29e2 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 connectionParams = new HashMap(); +``` java +Map connectionParams = new HashMap(); - 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 connectionParams = new HashMap(); +``` java +Map connectionParams = new HashMap(); - 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 diff --git a/docs/user-manual/en/connection-ttl.md b/docs/user-manual/en/connection-ttl.md index 80af334038..31a03fa249 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; +``` 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 diff --git a/docs/user-manual/en/core-bridges.md b/docs/user-manual/en/core-bridges.md index 6b6b90f26b..b1e4e6e6d5 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). diff --git a/docs/user-manual/en/diverts.md b/docs/user-manual/en/diverts.md index 60b00f7c06..eddfba3375 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 diff --git a/docs/user-manual/en/duplicate-detection.md b/docs/user-manual/en/duplicate-detection.md index b7776eb0a8..bc18c997fe 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). diff --git a/docs/user-manual/en/embedding-activemq.md b/docs/user-manual/en/embedding-activemq.md index 0c29d598ea..1042c07812 100644 --- a/docs/user-manual/en/embedding-activemq.md +++ b/docs/user-manual/en/embedding-activemq.md @@ -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 transports = new HashSet(); - - transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName())); - transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName())); +Configuration config = new ConfigurationImpl(); +HashSet transports = new HashSet(); + +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(); +``` diff --git a/docs/user-manual/en/filter-expressions.md b/docs/user-manual/en/filter-expressions.md index c1dfca5dd0..28d4d4d66e 100644 --- a/docs/user-manual/en/filter-expressions.md +++ b/docs/user-manual/en/filter-expressions.md @@ -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 diff --git a/docs/user-manual/en/flow-control.md b/docs/user-manual/en/flow-control.md index bdaac25eef..bf826bbde9 100644 --- a/docs/user-manual/en/flow-control.md +++ b/docs/user-manual/en/flow-control.md @@ -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. diff --git a/docs/user-manual/en/ha.md b/docs/user-manual/en/ha.md index a35536c2a9..e2e46b8b17 100644 --- a/docs/user-manual/en/ha.md +++ b/docs/user-manual/en/ha.md @@ -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 -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` -### 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 -### 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: -### 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: -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: -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 diff --git a/docs/user-manual/en/intercepting-operations.md b/docs/user-manual/en/intercepting-operations.md index 7d78976595..889129940e 100644 --- a/docs/user-manual/en/intercepting-operations.md +++ b/docs/user-manual/en/intercepting-operations.md @@ -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. diff --git a/docs/user-manual/en/interoperability.md b/docs/user-manual/en/interoperability.md index 58b22576a2..78d70761a1 100644 --- a/docs/user-manual/en/interoperability.md +++ b/docs/user-manual/en/interoperability.md @@ -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 diff --git a/docs/user-manual/en/jms-bridge.md b/docs/user-manual/en/jms-bridge.md index 437a177b9b..062d097d41 100644 --- a/docs/user-manual/en/jms-bridge.md +++ b/docs/user-manual/en/jms-bridge.md @@ -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. -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: -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 diff --git a/docs/user-manual/en/jms-core-mapping.md b/docs/user-manual/en/jms-core-mapping.md index 0be2829f1a..19ff8a4306 100644 --- a/docs/user-manual/en/jms-core-mapping.md +++ b/docs/user-manual/en/jms-core-mapping.md @@ -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. diff --git a/docs/user-manual/en/large-messages.md b/docs/user-manual/en/large-messages.md index b04f20173f..dc459b13ab 100644 --- a/docs/user-manual/en/large-messages.md +++ b/docs/user-manual/en/large-messages.md @@ -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. diff --git a/docs/user-manual/en/last-value-queues.md b/docs/user-manual/en/last-value-queues.md index eca5eb5bab..9246e57ceb 100644 --- a/docs/user-manual/en/last-value-queues.md +++ b/docs/user-manual/en/last-value-queues.md @@ -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. diff --git a/docs/user-manual/en/libaio.md b/docs/user-manual/en/libaio.md index 1e5f9aebcb..a5ec2d85c9 100644 --- a/docs/user-manual/en/libaio.md +++ b/docs/user-manual/en/libaio.md @@ -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 diff --git a/docs/user-manual/en/logging.md b/docs/user-manual/en/logging.md index 32ef718fa4..e8c6700f01 100644 --- a/docs/user-manual/en/logging.md +++ b/docs/user-manual/en/logging.md @@ -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 diff --git a/docs/user-manual/en/management.md b/docs/user-manual/en/management.md index 5c37827621..39695141d3 100644 --- a/docs/user-manual/en/management.md +++ b/docs/user-manual/en/management.md @@ -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=""` or the resource name `core.acceptor.`). 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=` or the resource name `core.divert.`). 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.`). 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.`). 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.`). 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.`). 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=" my.org.apache.activemq -### 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" /> -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: -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 diff --git a/docs/user-manual/en/message-expiry.md b/docs/user-manual/en/message-expiry.md index a42939c028..3d75302624 100644 --- a/docs/user-manual/en/message-expiry.md +++ b/docs/user-manual/en/message-expiry.md @@ -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. diff --git a/docs/user-manual/en/message-grouping.md b/docs/user-manual/en/message-grouping.md index 2a0da9e20e..7b3d0bd2a1 100644 --- a/docs/user-manual/en/message-grouping.md +++ b/docs/user-manual/en/message-grouping.md @@ -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 diff --git a/docs/user-manual/en/messaging-concepts.md b/docs/user-manual/en/messaging-concepts.md index 284473b0c6..f33d54ef2d 100644 --- a/docs/user-manual/en/messaging-concepts.md +++ b/docs/user-manual/en/messaging-concepts.md @@ -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). diff --git a/docs/user-manual/en/paging.md b/docs/user-manual/en/paging.md index 392c9ae110..491b09f6db 100644 --- a/docs/user-manual/en/paging.md +++ b/docs/user-manual/en/paging.md @@ -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. diff --git a/docs/user-manual/en/perf-tuning.md b/docs/user-manual/en/perf-tuning.md index f1410af174..919f93683a 100644 --- a/docs/user-manual/en/perf-tuning.md +++ b/docs/user-manual/en/perf-tuning.md @@ -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 diff --git a/docs/user-manual/en/persistence.md b/docs/user-manual/en/persistence.md index e2c6f58e98..b02f96888b 100644 --- a/docs/user-manual/en/persistence.md +++ b/docs/user-manual/en/persistence.md @@ -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 diff --git a/docs/user-manual/en/pre-acknowledge.md b/docs/user-manual/en/pre-acknowledge.md index 1bec75e9f0..4a78e7090d 100644 --- a/docs/user-manual/en/pre-acknowledge.md +++ b/docs/user-manual/en/pre-acknowledge.md @@ -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. diff --git a/docs/user-manual/en/preface.md b/docs/user-manual/en/preface.md index 8cc971785f..27f4b9b360 100644 --- a/docs/user-manual/en/preface.md +++ b/docs/user-manual/en/preface.md @@ -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) . diff --git a/docs/user-manual/en/project-info.md b/docs/user-manual/en/project-info.md index 2465981294..b6099ac48c 100644 --- a/docs/user-manual/en/project-info.md +++ b/docs/user-manual/en/project-info.md @@ -1,50 +1,30 @@ -Project Information -=================== +# Project Information -The official ActiveMQ project page is . +The official ActiveMQ project page is . -Software Download -================= +## Software Download The software can be download from the Download -page: +page: -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 +- ActiveMQ Git repository is - All release tags are available from - + -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. diff --git a/docs/user-manual/en/project-info.xml b/docs/user-manual/en/project-info.xml deleted file mode 100644 index 51a747097e..0000000000 --- a/docs/user-manual/en/project-info.xml +++ /dev/null @@ -1,90 +0,0 @@ - - - - - - - - - - - - - - - - - - - -%BOOK_ENTITIES; -]> - - Project Information - The official ActiveMQ project page is http://activemq.org/. -
- Software Download - The software can be download from the Download page:http://activemq.org/downloads.html -
-
- Project Information - - - - Please take a look at our project wiki - - - If you have any user questions please use our user - forum - - - If you have development related questions, please use our developer forum - - - Pop in and chat to us in our IRC channel - - - Our project blog - - - Follow us on twitter - - - ActiveMQ Git repository is https://github.com/activemq/activemq - - - All release tags are available from https://github.com/activemq/activemq/tags - - - - 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. -
- diff --git a/docs/user-manual/en/queue-attributes.md b/docs/user-manual/en/queue-attributes.md index d2dafa5280..d53467350e 100644 --- a/docs/user-manual/en/queue-attributes.md +++ b/docs/user-manual/en/queue-attributes.md @@ -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 diff --git a/docs/user-manual/en/rest.md b/docs/user-manual/en/rest.md index c48ffc117d..988d553150 100644 --- a/docs/user-manual/en/rest.md +++ b/docs/user-manual/en/rest.md @@ -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! -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. $199.99 -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.: $199.99 -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. ... -### 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: -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: -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: jms.topic.foo -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:
jfdiwe3321
-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 diff --git a/docs/user-manual/en/scheduled-messages.md b/docs/user-manual/en/scheduled-messages.md index e8f4cad0db..22812e2d49 100644 --- a/docs/user-manual/en/scheduled-messages.md +++ b/docs/user-manual/en/scheduled-messages.md @@ -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. diff --git a/docs/user-manual/en/security.md b/docs/user-manual/en/security.md index 6871334e5a..efc610a483 100644 --- a/docs/user-manual/en/security.md +++ b/docs/user-manual/en/security.md @@ -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. diff --git a/docs/user-manual/en/send-guarantees.md b/docs/user-manual/en/send-guarantees.md index 439f70eb91..40278975ea 100644 --- a/docs/user-manual/en/send-guarantees.md +++ b/docs/user-manual/en/send-guarantees.md @@ -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 diff --git a/docs/user-manual/en/slow-consumers.md b/docs/user-manual/en/slow-consumers.md index ae03d304d7..5b045654c4 100644 --- a/docs/user-manual/en/slow-consumers.md +++ b/docs/user-manual/en/slow-consumers.md @@ -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. diff --git a/docs/user-manual/en/spring-integration.md b/docs/user-manual/en/spring-integration.md index 570eac5a83..00dae1c660 100644 --- a/docs/user-manual/en/spring-integration.md +++ b/docs/user-manual/en/spring-integration.md @@ -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. diff --git a/docs/user-manual/en/syntax.md b/docs/user-manual/en/syntax.md new file mode 100644 index 0000000000..6e81a3443b --- /dev/null +++ b/docs/user-manual/en/syntax.md @@ -0,0 +1,22 @@ +# header 1 +## Header 2 +### Header 3 +#### Header 4 + + somexml + +``` java + Somejava s = new SomeJava(); +``` + +> **Note** +> +> This is a Note + + + +> **Warning** +> +> This is a warning + +`literal` diff --git a/docs/user-manual/en/thread-pooling.md b/docs/user-manual/en/thread-pooling.md index 3dee1eabd0..4a7613e5bb 100644 --- a/docs/user-manual/en/thread-pooling.md +++ b/docs/user-manual/en/thread-pooling.md @@ -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 + diff --git a/docs/user-manual/en/tools.md b/docs/user-manual/en/tools.md index a97aa7958b..cb1845122c 100644 --- a/docs/user-manual/en/tools.md +++ b/docs/user-manual/en/tools.md @@ -1,5 +1,4 @@ -Tools -===== +# Tools ActiveMQ ships with several helpful command line tools. All tools are available from the activemq-tools-\-jar-with-dependencies.jar. diff --git a/docs/user-manual/en/transaction-config.md b/docs/user-manual/en/transaction-config.md index 3bdbbc82be..12f1bf80bf 100644 --- a/docs/user-manual/en/transaction-config.md +++ b/docs/user-manual/en/transaction-config.md @@ -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 diff --git a/docs/user-manual/en/undelivered-messages.md b/docs/user-manual/en/undelivered-messages.md index d449102fbf..bc7de7a7f9 100644 --- a/docs/user-manual/en/undelivered-messages.md +++ b/docs/user-manual/en/undelivered-messages.md @@ -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: - - 1.5 - - 5000 - - 50000 + + 1.5 + + 5000 + + 50000 @@ -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: + deadLetterQueue after 3 unsuccessful delivery attempts --> - jms.queue.deadLetterQueue - 3 + jms.queue.deadLetterQueue + 3 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 diff --git a/docs/user-manual/en/using-core.md b/docs/user-manual/en/using-core.md index 6c9743fe54..a23883ed87 100644 --- a/docs/user-manual/en/using-core.md +++ b/docs/user-manual/en/using-core.md @@ -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(); +``` diff --git a/docs/user-manual/en/using-jms.md b/docs/user-manual/en/using-jms.md index 595dc0e63a..f3f4ce13b3 100644 --- a/docs/user-manual/en/using-jms.md +++ b/docs/user-manual/en/using-jms.md @@ -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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
typeinterface
CF (default)javax.jms.ConnectionFactory
XA_CFjavax.jms.XAConnectionFactory
QUEUE_CFjavax.jms.QueueConnectionFactory
QUEUE_XA_CFjavax.jms.XAQueueConnectionFactory
TOPIC_CFjavax.jms.TopicConnectionFactory
TOPIC_XA_CFjavax.jms.XATopicConnectionFactory
- : 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 diff --git a/docs/user-manual/en/using-server.md b/docs/user-manual/en/using-server.md index 999864662c..55837cd558 100644 --- a/docs/user-manual/en/using-server.md +++ b/docs/user-manual/en/using-server.md @@ -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: - - -- 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 diff --git a/docs/user-manual/en/vertx-integration.md b/docs/user-manual/en/vertx-integration.md index 0b89d793b7..ea4d6f8ffb 100644 --- a/docs/user-manual/en/vertx-integration.md +++ b/docs/user-manual/en/vertx-integration.md @@ -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: - - org.apache.activemq.integration.vertx.VertxIncomingConnectorServiceFactory - - - - - + + org.apache.activemq.integration.vertx.VertxIncomingConnectorServiceFactory + + + + + 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: - - org.apache.activemq.integration.vertx.VertxOutgoingConnectorServiceFactory - - - - - - + + org.apache.activemq.integration.vertx.VertxOutgoingConnectorServiceFactory + + + + + + Shown are the required params for the connector service: diff --git a/docs/user-manual/en/wildcard-routing.md b/docs/user-manual/en/wildcard-routing.md index cabf9bdac3..74915718de 100644 --- a/docs/user-manual/en/wildcard-routing.md +++ b/docs/user-manual/en/wildcard-routing.md @@ -1,5 +1,4 @@ -Routing Messages With Wild Cards -================================ +# Routing Messages With Wild Cards ActiveMQ allows the routing of messages via wildcard addresses. diff --git a/docs/user-manual/en/wildcard-syntax.md b/docs/user-manual/en/wildcard-syntax.md index 3fe7b379e8..da599d8536 100644 --- a/docs/user-manual/en/wildcard-syntax.md +++ b/docs/user-manual/en/wildcard-syntax.md @@ -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.