You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by cl...@apache.org on 2014/12/08 16:49:46 UTC
[15/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/embedding-activemq.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/embedding-activemq.xml b/docs/user-manual/en/embedding-activemq.xml
deleted file mode 100644
index e19d786..0000000
--- a/docs/user-manual/en/embedding-activemq.xml
+++ /dev/null
@@ -1,270 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
-"../../../lib/docbook-support/support/docbook-dtd/docbookx.dtd"> -->
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="embedding-activemq">
- <title>Embedding ActiveMQ</title>
-
- <para>ActiveMQ is designed as set of simple Plain Old Java Objects (POJOs).
- This means ActiveMQ can be instantiated and run in any dependency injection
- framework such as JBoss Microcontainer, Spring or Google Guice. It also
- means that if you have an application that could use messaging functionality
- internally, then it can <emphasis>directly instantiate</emphasis> ActiveMQ
- clients and servers in its own application code to perform that
- functionality. We call this <emphasis>embedding</emphasis> ActiveMQ.</para>
-
- <para>Examples of applications that might want to do this include any
- application that needs very high performance, transactional, persistent
- messaging but doesn't want the hassle of writing it all from scratch.</para>
-
- <para>Embedding ActiveMQ can be done in very few easy steps. Instantiate the
- 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.</para>
-
- <section>
- <title>Simple Config File Embedding</title>
-
- <para>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.</para>
-
- <section>
- <title>Core API Only</title>
- <para>For instantiating a core ActiveMQ Server only, the steps are pretty
- simple. The example requires that you have defined a configuration file
- <literal>activemq-configuration.xml</literal> in your
- classpath:</para>
- <programlisting>
-import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
-
-...
-
-EmbeddedActiveMQ embedded = new EmbeddedActiveMQ();
-embedded.start();
-
-ClientSessionFactory nettyFactory = ActiveMQClient.createClientSessionFactory(
- new TransportConfiguration(
- InVMConnectorFactory.class.getName()));
-
-ClientSession session = factory.createSession();
-
-session.createQueue("example", "example", true);
-
-ClientProducer producer = session.createProducer("example");
-
-ClientMessage message = session.createMessage(true);
-
-message.getBody().writeString("Hello");
-
-producer.send(message);
-
-session.start();
-
-ClientConsumer consumer = session.createConsumer("example");
-
-ClientMessage msgReceived = consumer.receive();
-
-System.out.println("message = " + msgReceived.getBody().readString());
-
-session.close();</programlisting>
-
-<para>The <literal>EmbeddedActiveMQ</literal> 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.</para>
- </section>
-
- <section id="simple.embedded.jms">
- <title>JMS API</title>
-
- <para>JMS embedding is simple as well. This example requires that you
- have defined the config files
- <literal>activemq-configuration.xml</literal>,
- <literal>activemq-jms.xml</literal>, and a
- <literal>activemq-users.xml</literal> if you have security enabled. Let's
- also assume that a queue and connection factory has been defined in the
- <literal>activemq-jms.xml</literal> config file.</para>
-
- <programlisting>
-import org.apache.activemq.jms.server.embedded.EmbeddedJMS;
-
-...
-
-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");
-
-... regular JMS code ...</programlisting>
- <para>By default, the <literal>EmbeddedJMS</literal>
- class will store component entries defined within your
- <literal>activemq-jms.xml</literal> file in an internal concurrent hash
- map. The <literal>EmbeddedJMS.lookup()</literal> method returns
- components stored in this map. If you want to use JNDI, call the
- <literal>EmbeddedJMS.setContext()</literal> 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.</para>
- </section>
- </section>
-
- <section>
- <title>POJO instantiation - Embedding Programmatically</title>
-
- <para>You can follow this step-by-step guide to programmatically embed the
- core, non-JMS ActiveMQ Server instance:</para>
-
- <para>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 <xref
- linkend="server.configuration" /> section.</para>
-
- <para>The acceptors are configured through
- <literal>ConfigurationImpl</literal>. Just add the
- <literal>NettyAcceptorFactory</literal> on the transports the same way you
- would through the main configuration file.</para>
-
- <programlisting>
-import org.apache.activemq.core.config.Configuration;
-import org.apache.activemq.core.config.impl.ConfigurationImpl;
-
-...
-
-Configuration config = new ConfigurationImpl();
-HashSet<TransportConfiguration> transports = new HashSet<TransportConfiguration>();
-
-transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
-transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));
-
-config.setAcceptorConfigurations(transports);</programlisting>
-
- <para>You need to instantiate an instance of
- <literal>org.apache.activemq.api.core.server.embedded.EmbeddedActiveMQ</literal>
- and add the configuration object to it.</para>
-
- <programlisting>
-import org.apache.activemq.api.core.server.ActiveMQ;
-import org.apache.activemq.core.server.embedded.EmbeddedActiveMQ;
-
-...
-
-EmbeddedActiveMQ server = new EmbeddedActiveMQ();
-server.setConfiguration(config);
-
-server.start();</programlisting>
-
- <para>You also have the option of instantiating
- <literal>ActiveMQServerImpl</literal> directly:</para>
-
- <programlisting>
-ActiveMQServer server = new ActiveMQServerImpl(config);
-server.start();</programlisting>
-
- <para>For JMS POJO instantiation, you work with the EmbeddedJMS class
- instead as described earlier. First you define the configuration
- programmatically for your ConnectionFactory and Destination objects, then
- set the JmsConfiguration property of the EmbeddedJMS class. Here is an
- example of this:</para>
-
- <programlisting>
-// 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 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 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();</programlisting>
-
- <para>Please see <xref linkend="examples.embedded.jms" /> for an example which
- shows how to setup and run ActiveMQ embedded with JMS.</para>
- </section>
-
- <section>
- <title>Dependency Frameworks</title>
-
- <para>You may also choose to use a dependency injection framework such as
- <trademark>JBoss Micro Container</trademark> or <trademark>Spring
- Framework</trademark>. See <xref linkend="spring.integration" /> for more
- details on Spring and ActiveMQ, but here's how you would do things with the
- JBoss Micro Container.</para>
-
- <para>ActiveMQ standalone uses JBoss Micro Container as the injection
- framework. <literal>ActiveMQBootstrapServer</literal> and
- <literal>activemq-beans.xml</literal> which are part of the ActiveMQ
- distribution provide a very complete implementation of what's needed to
- bootstrap the server using JBoss Micro Container.</para>
-
- <para>When using JBoss Micro Container, you need to provide an XML file
- declaring the <literal>ActiveMQServer</literal> and
- <literal>Configuration</literal> object, you can also inject a security
- manager and a MBean server if you want, but those are optional.</para>
-
- <para>A very basic XML Bean declaration for the JBoss Micro Container
- would be:</para>
-
- <programlisting>
-<?xml version="1.0" encoding="UTF-8"?>
-<deployment xmlns="urn:jboss:bean-deployer:2.0">
- <!-- The core configuration -->
- <bean name="Configuration"
- class="org.apache.activemq.core.config.impl.FileConfiguration">
- </bean>
-
- <!-- The core server -->
- <bean name="ActiveMQServer"
- class="org.apache.activemq.core.server.impl.ActiveMQServerImpl">
- <constructor>
- <parameter>
- <inject bean="Configuration"/>
- </parameter>
- </constructor>
- </bean>
-</deployment></programlisting>
-
- <para><literal>ActiveMQBootstrapServer</literal> provides an easy
- encapsulation of JBoss Micro Container.</para>
-
- <programlisting>
-ActiveMQBootstrapServer bootStrap = new ActiveMQBootstrapServer(new String[] {"activemq-beans.xml"});
-bootStrap.run();</programlisting>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/examples.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/examples.md b/docs/user-manual/en/examples.md
new file mode 100644
index 0000000..52f45fa
--- /dev/null
+++ b/docs/user-manual/en/examples.md
@@ -0,0 +1,826 @@
+Examples
+========
+
+The ActiveMQ distribution comes with over 70 run out-of-the-box examples
+demonstrating many of the features.
+
+The examples are available in the distribution, in the `examples`
+directory. Examples are split into JMS and core examples. JMS examples
+show how a particular feature can be used by a normal JMS client. Core
+examples show how the equivalent feature can be used by a core messaging
+client.
+
+A set of Java EE examples are also provided which need WildFly installed
+to be able to run.
+
+JMS Examples
+============
+
+To run a JMS example, simply `cd` into the appropriate example directory
+and type `mvn verify` (For details please read the readme.html in each
+example directory).
+
+Here's a listing of the examples with a brief description.
+
+JMS AeroGear
+------------
+
+This example shows how you can send a message to a mobile device by
+leveraging AeroGears push technology which provides support for
+different push notification technologies like Google Cloud Messaging,
+Apple's APNs or Mozilla's SimplePush.
+
+Applet
+------
+
+This example shows you how to send and receive JMS messages from an
+Applet.
+
+Application-Layer Failover
+--------------------------
+
+ActiveMQ also supports Application-Layer failover, useful in the case
+that replication is not enabled on the server side.
+
+With Application-Layer failover, it's up to the application to register
+a JMS `ExceptionListener` with ActiveMQ which will be called by ActiveMQ
+in the event that connection failure is detected.
+
+The code in the `ExceptionListener` then recreates the JMS connection,
+session, etc on another node and the application can continue.
+
+Application-layer failover is an alternative approach to High
+Availability (HA). Application-layer failover differs from automatic
+failover in that some client side coding is required in order to
+implement this. Also, with Application-layer failover, since the old
+session object dies and a new one is created, any uncommitted work in
+the old session will be lost, and any unacknowledged messages might be
+redelivered.
+
+Core Bridge Example
+-------------------
+
+The `bridge` example demonstrates a core bridge deployed on one server,
+which consumes messages from a local queue and forwards them to an
+address on a second server.
+
+Core bridges are used to create message flows between any two ActiveMQ
+servers which are remotely separated. Core bridges are resilient and
+will cope with temporary connection failure allowing them to be an ideal
+choice for forwarding over unreliable connections, e.g. a WAN.
+
+Browser
+-------
+
+The `browser` example shows you how to use a JMS `QueueBrowser` with
+ActiveMQ.
+
+Queues are a standard part of JMS, please consult the JMS 1.1
+specification for full details.
+
+A `QueueBrowser` is used to look at messages on the queue without
+removing them. It can scan the entire content of a queue or only
+messages matching a message selector.
+
+Client Kickoff
+--------------
+
+The `client-kickoff` example shows how to terminate client connections
+given an IP address using the JMX management API.
+
+Client side failover listener
+-----------------------------
+
+The `client-side-failoverlistener` example shows how to register a
+listener to monitor failover events
+
+Client-Side Load-Balancing
+--------------------------
+
+The `client-side-load-balancing` example demonstrates how sessions
+created from a single JMS `Connection` can be created to different nodes
+of the cluster. In other words it demonstrates how ActiveMQ does
+client-side load-balancing of sessions across the cluster.
+
+Clustered Durable Subscription
+------------------------------
+
+This example demonstrates a clustered JMS durable subscription
+
+Clustered Grouping
+------------------
+
+This is similar to the message grouping example except that it
+demonstrates it working over a cluster. Messages sent to different nodes
+with the same group id will be sent to the same node and the same
+consumer.
+
+Clustered Queue
+---------------
+
+The `clustered-queue` example demonstrates a JMS queue deployed on two
+different nodes. The two nodes are configured to form a cluster. We then
+create a consumer for the queue on each node, and we create a producer
+on only one of the nodes. We then send some messages via the producer,
+and we verify that both consumers receive the sent messages in a
+round-robin fashion.
+
+Clustering with JGroups
+-----------------------
+
+The `clustered-jgroups` example demonstrates how to form a two node
+cluster using JGroups as its underlying topology discovery technique,
+rather than the default UDP broadcasting. We then create a consumer for
+the queue on each node, and we create a producer on only one of the
+nodes. We then send some messages via the producer, and we verify that
+both consumers receive the sent messages in a round-robin fashion.
+
+Clustered Standalone
+--------------------
+
+The `clustered-standalone` example demonstrates how to configure and
+starts 3 cluster nodes on the same machine to form a cluster. A
+subscriber for a JMS topic is created on each node, and we create a
+producer on only one of the nodes. We then send some messages via the
+producer, and we verify that the 3 subscribers receive all the sent
+messages.
+
+Clustered Static Discovery
+--------------------------
+
+This example demonstrates how to configure a cluster using a list of
+connectors rather than UDP for discovery
+
+Clustered Static Cluster One Way
+--------------------------------
+
+This example demonstrates how to set up a cluster where cluster
+connections are one way, i.e. server A -\> Server B -\> Server C
+
+Clustered Topic
+---------------
+
+The `clustered-topic` example demonstrates a JMS topic deployed on two
+different nodes. The two nodes are configured to form a cluster. We then
+create a subscriber on the topic on each node, and we create a producer
+on only one of the nodes. We then send some messages via the producer,
+and we verify that both subscribers receive all the sent messages.
+
+Message Consumer Rate Limiting
+------------------------------
+
+With ActiveMQ you can specify a maximum consume rate at which a JMS
+MessageConsumer will consume messages. This can be specified when
+creating or deploying the connection factory.
+
+If this value is specified then ActiveMQ will ensure that messages are
+never consumed at a rate higher than the specified rate. This is a form
+of consumer throttling.
+
+Dead Letter
+-----------
+
+The `dead-letter` example shows you how to define and deal with dead
+letter 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 the JMS destination ready to be redelivered.
+However, this means it is possible for a message to be delivered again
+and again without any success and remain in the destination, clogging
+the system.
+
+To prevent this, messaging systems define dead letter messages: after a
+specified unsuccessful delivery attempts, the message is removed from
+the destination and put instead in a dead letter destination where they
+can be consumed for further investigation.
+
+Delayed Redelivery
+------------------
+
+The `delayed-redelivery` example demonstrates how ActiveMQ can be
+configured to provide a delayed redelivery in the case a message needs
+to be redelivered.
+
+Delaying redelivery can often be useful in the case that clients
+regularly fail or roll-back. Without a delayed redelivery, the system
+can get into a "thrashing" state, with delivery being attempted, the
+client rolling back, and delivery being re-attempted in quick
+succession, using up valuable CPU and network resources.
+
+Divert
+------
+
+ActiveMQ diverts allow messages to be transparently "diverted" or copied
+from one address to another with just some simple configuration defined
+on the server side.
+
+Durable Subscription
+--------------------
+
+The `durable-subscription` example shows you how to use a durable
+subscription with ActiveMQ. Durable subscriptions are a standard part of
+JMS, please consult the JMS 1.1 specification for full details.
+
+Unlike non-durable subscriptions, the key function of durable
+subscriptions is that the messages contained in them persist longer than
+the lifetime of the subscriber - i.e. they will accumulate messages sent
+to the topic even if there is no active subscriber on them. They will
+also survive server restarts or crashes. Note that for the messages to
+be persisted, the messages sent to them must be marked as durable
+messages.
+
+Embedded
+--------
+
+The `embedded` example shows how to embed JMS within your own code using
+POJO instantiation and no config files.
+
+Embedded Simple
+---------------
+
+The `embedded` example shows how to embed JMS within your own code using
+regular ActiveMQ XML files.
+
+Message Expiration
+------------------
+
+The `expiry` example shows you how to define and deal with message
+expiration. Messages can be retained in the messaging system for a
+limited period of time before being removed. JMS specification states
+that clients should not receive messages that have been expired (but it
+does not guarantee this will not happen).
+
+ActiveMQ can assign an expiry address to a given queue so that when
+messages are expired, they are removed from the queue and sent to the
+expiry address. These "expired" messages can later be consumed from the
+expiry address for further inspection.
+
+ActiveMQ Resource Adapter example
+---------------------------------
+
+This examples shows how to build the activemq resource adapters a rar
+for deployment in other Application Server's
+
+HTTP Transport
+--------------
+
+The `http-transport` example shows you how to configure ActiveMQ to use
+the HTTP protocol as its transport layer.
+
+Instantiate JMS Objects Directly
+--------------------------------
+
+Usually, JMS Objects such as `ConnectionFactory`, `Queue` and `Topic`
+instances are looked up from JNDI before being used by the client code.
+This objects are called "administered objects" in JMS terminology.
+
+However, in some cases a JNDI server may not be available or desired. To
+come to the rescue ActiveMQ also supports the direct instantiation of
+these administered objects on the client side so you don't have to use
+JNDI for JMS.
+
+Interceptor
+-----------
+
+ActiveMQ allows an application to use an interceptor to hook into the
+messaging system. Interceptors allow you to handle various message
+events in ActiveMQ.
+
+JAAS
+----
+
+The `jaas` example shows you how to configure ActiveMQ to use JAAS for
+security. ActiveMQ can leverage JAAS to delegate user authentication and
+authorization to existing security infrastructure.
+
+JMS Auto Closable
+-----------------
+
+The `jms-auto-closeable` example shows how JMS resources, such as
+connections, sessions and consumers, in JMS 2 can be automatically
+closed on error.
+
+JMS Completion Listener
+-----------------------
+
+The `jms-completion-listener` example shows how to send a message
+asynchronously to ActiveMQ and use a CompletionListener to be notified
+of the Broker receiving it.
+
+JMS Bridge
+----------
+
+The `jms-brige` example shows how to setup a bridge between two
+standalone ActiveMQ servers.
+
+JMS Context
+-----------
+
+The `jms-context` example shows how to send and receive a message to a
+JMS Queue using ActiveMQ by using a JMS Context.
+
+A JMSContext is part of JMS 2.0 and combines the JMS Connection and
+Session Objects into a simple Interface.
+
+JMS Shared Consumer
+-------------------
+
+The `jms-shared-consumer` example shows you how can use shared consumers
+to share a subscription on a topic. In JMS 1.1 this was not allowed and
+so caused a scalability issue. In JMS 2 this restriction has been lifted
+so you can share the load across different threads and connections.
+
+JMX Management
+--------------
+
+The `jmx` example shows how to manage ActiveMQ using JMX.
+
+Large Message
+-------------
+
+The `large-message` example shows you how to send and receive very large
+messages with ActiveMQ. ActiveMQ supports the sending and receiving of
+huge messages, much larger than can fit in available RAM on the client
+or server. Effectively the only limit to message size is the amount of
+disk space you have on the server.
+
+Large messages are persisted on the server so they can survive a server
+restart. In other words ActiveMQ doesn't just do a simple socket stream
+from the sender to the consumer.
+
+Last-Value Queue
+----------------
+
+The `last-value-queue` example shows you how to define and deal with
+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 is put in the queue. In other words, a last-value
+queue only retains the last value.
+
+A typical example for last-value queue is for stock prices, where you
+are only interested by the latest price for a particular stock.
+
+Management
+----------
+
+The `management` example shows how to manage ActiveMQ using JMS Messages
+to invoke management operations on the server.
+
+Management Notification
+-----------------------
+
+The `management-notification` example shows how to receive management
+notifications from ActiveMQ using JMS messages. ActiveMQ servers emit
+management notifications when events of interest occur (consumers are
+created or closed, addresses are created or deleted, security
+authentication fails, etc.).
+
+Message Counter
+---------------
+
+The `message-counters` example shows you how to use message counters to
+obtain message information for a JMS queue.
+
+Message Group
+-------------
+
+The `message-group` example shows you how to configure and use message
+groups with ActiveMQ. Message groups allow you to pin messages so they
+are only consumed by a single consumer. Message groups are sets of
+messages that has the following characteristics:
+
+- Messages in a message group share the same group id, i.e. they have
+ same JMSXGroupID string property values
+
+- The consumer that receives the first message of a group will receive
+ all the messages that belongs to the group
+
+Message Group
+-------------
+
+The `message-group2` example shows you how to configure and use message
+groups with ActiveMQ via a connection factory.
+
+Message Priority
+----------------
+
+Message Priority can be used to influence the delivery order for
+messages.
+
+It can be retrieved by the message's standard header field 'JMSPriority'
+as defined in JMS specification version 1.1.
+
+The value is of type integer, ranging from 0 (the lowest) to 9 (the
+highest). When messages are being delivered, their priorities will
+effect their order of delivery. Messages of higher priorities will
+likely be delivered before those of lower priorities.
+
+Messages of equal priorities are delivered in the natural order of their
+arrival at their destinations. Please consult the JMS 1.1 specification
+for full details.
+
+Multiple Failover
+-----------------
+
+This example demonstrates how to set up a live server with multiple
+backups
+
+Multiple Failover Failback
+--------------------------
+
+This example demonstrates how to set up a live server with multiple
+backups but forcing failover back to the original live server
+
+No Consumer Buffering
+---------------------
+
+By default, ActiveMQ consumers buffer messages from the server in a
+client side buffer before you actually receive them on the client side.
+This improves performance since otherwise every time you called
+receive() or had processed the last message in a
+`MessageListener onMessage()` method, the ActiveMQ client would have to
+go the server to request the next message, which would then get sent to
+the client side, if one was available.
+
+This would involve a network round trip for every message and reduce
+performance. Therefore, by default, ActiveMQ pre-fetches messages into a
+buffer on each consumer.
+
+In some case buffering is not desirable, and ActiveMQ allows it to be
+switched off. This example demonstrates that.
+
+Non-Transaction Failover With Server Data Replication
+-----------------------------------------------------
+
+The `non-transaction-failover` example demonstrates two servers coupled
+as a live-backup pair for high availability (HA), and a client using a
+*non-transacted* JMS session failing over from live to backup when the
+live server is crashed.
+
+ActiveMQ implements failover of client connections between live and
+backup servers. This is implemented by the replication of state between
+live and backup nodes. When replication is configured and a live node
+crashes, the client connections can carry and continue to send and
+consume messages. When non-transacted sessions are used, once and only
+once message delivery is not guaranteed and it is possible that some
+messages will be lost or delivered twice.
+
+OpenWire
+--------
+
+The `Openwire` example shows how to configure a ActiveMQ server to
+communicate with an ActiveMQ JMS client that uses open-wire protocol.
+
+Paging
+------
+
+The `paging` example shows how ActiveMQ can support huge queues even
+when the server is running in limited RAM. It does this by transparently
+*paging* messages to disk, and *depaging* them when they are required.
+
+Pre-Acknowledge
+---------------
+
+Standard JMS supports three acknowledgement modes:`
+ AUTO_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE`, and
+`DUPS_OK_ACKNOWLEDGE`. For a full description on these modes please
+consult the JMS specification, or any JMS tutorial.
+
+All of these standard modes involve sending acknowledgements from the
+client to the server. However in some cases, you really don't mind
+losing messages in event of failure, so it would make sense to
+acknowledge the message on the server before delivering it to the
+client. This example demonstrates how ActiveMQ allows this with an extra
+acknowledgement mode.
+
+Message Producer Rate Limiting
+------------------------------
+
+The `producer-rte-limit` example demonstrates how, with ActiveMQ, you
+can specify a maximum send rate at which a JMS message producer will
+send messages.
+
+Proton Qpid
+-----------
+
+ActiveMQ can be configured to accept requests from any AMQP client that
+supports the 1.0 version of the protocol. This `proton-j` example shows
+a simply qpid java 1.0 client example.
+
+Proton Ruby
+-----------
+
+ActiveMQ can be configured to accept requests from any AMQP client that
+supports the 1.0 version of the protocol. This example shows a simply
+proton ruby client that sends and receives messages
+
+Queue
+-----
+
+A simple example demonstrating a JMS queue.
+
+Message Redistribution
+----------------------
+
+The `queue-message-redistribution` example demonstrates message
+redistribution between queues with the same name deployed in different
+nodes of a cluster.
+
+Queue Requestor
+---------------
+
+A simple example demonstrating a JMS queue requestor.
+
+Queue with Message Selector
+---------------------------
+
+The `queue-selector` example shows you how to selectively consume
+messages using message selectors with queue consumers.
+
+Reattach Node example
+---------------------
+
+The `Reattach Node` example shows how a client can try to reconnect to
+the same server instead of failing the connection immediately and
+notifying any user ExceptionListener objects. ActiveMQ can be configured
+to automatically retry the connection, and reattach to the server when
+it becomes available again across the network.
+
+Replicated Failback example
+---------------------------
+
+An example showing how failback works when using replication, In this
+example a live server will replicate all its Journal to a backup server
+as it updates it. When the live server crashes the backup takes over
+from the live server and the client reconnects and carries on from where
+it left off.
+
+Replicated Failback static example
+----------------------------------
+
+An example showing how failback works when using replication, but this
+time with static connectors
+
+Replicated multiple failover example
+------------------------------------
+
+An example showing how to configure multiple backups when using
+replication
+
+Replicated Failover transaction example
+---------------------------------------
+
+An example showing how failover works with a transaction when using
+replication
+
+Request-Reply example
+---------------------
+
+A simple example showing the JMS request-response pattern.
+
+Rest example
+------------
+
+An example showing how to use the ActiveMQ Rest API
+
+Scheduled Message
+-----------------
+
+The `scheduled-message` example shows you how to send a scheduled
+message to a JMS Queue with ActiveMQ. Scheduled messages won't get
+delivered until a specified time in the future.
+
+Security
+--------
+
+The `security` example shows you how configure and use role based queue
+security with ActiveMQ.
+
+Send Acknowledgements
+---------------------
+
+The `send-acknowledgements` example shows you how to use ActiveMQ's
+advanced *asynchronous send acknowledgements* feature to obtain
+acknowledgement from the server that sends have been received and
+processed in a separate stream to the sent messages.
+
+Spring Integration
+------------------
+
+This example shows how to use embedded JMS using ActiveMQ's Spring
+integration.
+
+SSL Transport
+-------------
+
+The `ssl-enabled` shows you how to configure SSL with ActiveMQ to send
+and receive message.
+
+Static Message Selector
+-----------------------
+
+The `static-selector` example shows you how to configure a ActiveMQ core
+queue with static message selectors (filters).
+
+Static Message Selector Using JMS
+---------------------------------
+
+The `static-selector-jms` example shows you how to configure a ActiveMQ
+queue with static message selectors (filters) using JMS.
+
+Stomp
+-----
+
+The `stomp` example shows you how to configure a ActiveMQ server to send
+and receive Stomp messages.
+
+Stomp1.1
+--------
+
+The `stomp` example shows you how to configure a ActiveMQ server to send
+and receive Stomp messages via a Stomp 1.1 connection.
+
+Stomp1.2
+--------
+
+The `stomp` example shows you how to configure a ActiveMQ server to send
+and receive Stomp messages via a Stomp 1.2 connection.
+
+Stomp Over Web Sockets
+----------------------
+
+The `stomp-websockets` example shows you how to configure a ActiveMQ
+server to send and receive Stomp messages directly from Web browsers
+(provided they support Web Sockets).
+
+Symmetric Cluster
+-----------------
+
+The `symmetric-cluster` example demonstrates a symmetric cluster set-up
+with ActiveMQ.
+
+ActiveMQ has extremely flexible clustering which allows you to set-up
+servers in many different topologies. The most common topology that
+you'll perhaps be familiar with if you are used to application server
+clustering is a symmetric cluster.
+
+With a symmetric cluster, the cluster is homogeneous, i.e. each node is
+configured the same as every other node, and every node is connected to
+every other node in the cluster.
+
+Temporary Queue
+---------------
+
+A simple example demonstrating how to use a JMS temporary queue.
+
+Topic
+-----
+
+A simple example demonstrating a JMS topic.
+
+Topic Hierarchy
+---------------
+
+ActiveMQ supports topic hierarchies. With a topic hierarchy you can
+register a subscriber with a wild-card and that subscriber will receive
+any messages sent to an address that matches the wild card.
+
+Topic Selector 1
+----------------
+
+The `topic-selector-example1` example shows you how to send message to a
+JMS Topic, and subscribe them using selectors with ActiveMQ.
+
+Topic Selector 2
+----------------
+
+The `topic-selector-example2` example shows you how to selectively
+consume messages using message selectors with topic consumers.
+
+Transaction Failover
+--------------------
+
+The `transaction-failover` example demonstrates two servers coupled as a
+live-backup pair for high availability (HA), and a client using a
+transacted JMS session failing over from live to backup when the live
+server is crashed.
+
+ActiveMQ implements failover of client connections between live and
+backup servers. This is implemented by the sharing of a journal between
+the servers. When a live node crashes, the client connections can carry
+and continue to send and consume messages. When transacted sessions are
+used, once and only once message delivery is guaranteed.
+
+Failover Without Transactions
+-----------------------------
+
+The `stop-server-failover` example demonstrates failover of the JMS
+connection from one node to another when the live server crashes using a
+JMS non-transacted session.
+
+Transactional Session
+---------------------
+
+The `transactional` example shows you how to use a transactional Session
+with ActiveMQ.
+
+XA Heuristic
+------------
+
+The `xa-heuristic` example shows you how to make an XA heuristic
+decision through ActiveMQ Management Interface. A heuristic decision is
+a unilateral decision to commit or rollback an XA transaction branch
+after it has been prepared.
+
+XA Receive
+----------
+
+The `xa-receive` example shows you how message receiving behaves in an
+XA transaction in ActiveMQ.
+
+XA Send
+-------
+
+The `xa-send` example shows you how message sending behaves in an XA
+transaction in ActiveMQ.
+
+XA with Transaction Manager
+---------------------------
+
+The `xa-with-jta` example shows you how to use JTA interfaces to control
+transactions with ActiveMQ.
+
+Core API Examples
+=================
+
+To run a core example, simply `cd` into the appropriate example
+directory and type `ant`
+
+Embedded
+--------
+
+The `embedded` example shows how to embed the ActiveMQ server within
+your own code.
+
+Java EE Examples
+================
+
+Most of the Java EE examples can be run the following way. Simply
+navigate into the appropriate example directory and type `mvn verify`.
+This will use Arquillian to run the Application Server and deploy the
+application. Note that you must have WildFly installed and the
+JBOSS\_HOME environment variable set. Please refer to the examples
+documentation for further instructions.
+
+> **Note**
+>
+> When running the Java EE examples you may see warning messages in the
+> WildFly log about incompatible client and server versions. This is
+> normal if a newer version of the ActiveMQ project is being used with a
+> version of WildFly that ships an older version of ActiveMQ. These
+> examples should still complete without any functional errors.
+
+EJB/JMS Transaction
+-------------------
+
+An example that shows using an EJB and JMS together within a
+transaction.
+
+Resource Adapter Configuration
+------------------------------
+
+This example demonstrates how to configure several properties on the
+ActiveMQ JCA resource adaptor.
+
+Resource Adapter Remote Server Configuration
+--------------------------------------------
+
+This example demonstrates how to configure the ActiveMQ resource adapter
+to talk to a remote ActiveMQ server
+
+JMS Bridge
+----------
+
+An example demonstrating the use of the ActiveMQ JMS bridge.
+
+MDB (Message Driven Bean)
+-------------------------
+
+A simple set of examples of message driven beans, including failover
+examples.
+
+Servlet Transport
+-----------------
+
+An example of how to use the ActiveMQ servlet transport.
+
+Servlet SSL Transport
+---------------------
+
+An example of how to use the ActiveMQ servlet transport over SSL.
+
+XA Recovery
+-----------
+
+An example of how XA recovery works within the JBoss Application server
+using ActiveMQ.
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/examples.xml
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/examples.xml b/docs/user-manual/en/examples.xml
deleted file mode 100644
index 3d909fb..0000000
--- a/docs/user-manual/en/examples.xml
+++ /dev/null
@@ -1,693 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Licensed to the Apache Software Foundation (ASF) under one or more -->
-<!-- contributor license agreements. See the NOTICE file distributed with -->
-<!-- this work for additional information regarding copyright ownership. -->
-<!-- The ASF licenses this file to You under the Apache License, Version 2.0 -->
-<!-- (the "License"); you may not use this file except in compliance with -->
-<!-- the License. You may obtain a copy of the License at -->
-<!-- -->
-<!-- http://www.apache.org/licenses/LICENSE-2.0 -->
-<!-- -->
-<!-- Unless required by applicable law or agreed to in writing, software -->
-<!-- distributed under the License is distributed on an "AS IS" BASIS, -->
-<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -->
-<!-- See the License for the specific language governing permissions and -->
-<!-- limitations under the License. -->
-<!-- ============================================================================= -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="examples">
- <title>Examples</title>
- <para>The ActiveMQ distribution comes with over 70 run out-of-the-box examples demonstrating many
- of the features.</para>
- <para>The examples are available in the distribution, in the <literal>examples</literal>
- directory. Examples are split into JMS and core examples. JMS examples show how a particular
- feature can be used by a normal JMS client. Core examples show how the equivalent feature
- can be used by a core messaging client.</para>
- <para>A set of Java EE examples are also provided which need WildFly
- installed to be able to run.</para>
- <section>
- <title>JMS Examples</title>
- <para>To run a JMS example, simply <literal>cd</literal> into the appropriate example
- directory and type <literal>mvn verify</literal> (For details please read the readme.html
- in each example directory).</para>
- <para>Here's a listing of the examples with a brief description.</para>
- <section id="examples.aerogear">
- <title>JMS AeroGear</title>
- <para>This example shows how you can send a message to a mobile device by leveraging
- AeroGears push technology which provides support for different push notification technologies
- like Google Cloud Messaging, Apple's APNs or Mozilla's SimplePush.</para>
- </section>
- <section id="examples.applet">
- <title>Applet</title>
- <para>This example shows you how to send and receive JMS messages from an Applet.</para>
- </section>
- <section id="application-level-failover">
- <title>Application-Layer Failover</title>
- <para>ActiveMQ also supports Application-Layer failover, useful in the case that
- replication is not enabled on the server side.</para>
- <para>With Application-Layer failover, it's up to the application to register a JMS
- <literal>ExceptionListener</literal> with ActiveMQ which will be called by
- ActiveMQ in the event that connection failure is detected.</para>
- <para>The code in the <literal>ExceptionListener</literal> then recreates the JMS
- connection, session, etc on another node and the application can continue.</para>
- <para>Application-layer failover is an alternative approach to High Availability (HA).
- Application-layer failover differs from automatic failover in that some client side
- coding is required in order to implement this. Also, with Application-layer
- failover, since the old session object dies and a new one is created, any
- uncommitted work in the old session will be lost, and any unacknowledged messages
- might be redelivered.</para>
- </section>
- <section id="examples.bridge">
- <title>Core Bridge Example</title>
- <para>The <literal>bridge</literal> example demonstrates a core bridge deployed on one
- server, which consumes messages from a local queue and forwards them to an address
- on a second server.</para>
- <para>Core bridges are used to create message flows between any two ActiveMQ servers
- which are remotely separated. Core bridges are resilient and will cope with
- temporary connection failure allowing them to be an ideal choice for forwarding over
- unreliable connections, e.g. a WAN.</para>
- </section>
- <section id="examples.browsers">
- <title>Browser</title>
- <para>The <literal>browser</literal> example shows you how to use a JMS <literal
- >QueueBrowser</literal> with ActiveMQ.</para>
- <para>Queues are a standard part of JMS, please consult the JMS 1.1 specification for
- full details.</para>
- <para> A <literal>QueueBrowser</literal> is used to look at messages on the queue
- without removing them. It can scan the entire content of a queue or only messages
- matching a message selector.</para>
- </section>
- <section>
- <title>Client Kickoff</title>
- <para>The <literal>client-kickoff</literal> example shows how to terminate client
- connections given an IP address using the JMX management API.</para>
- </section>
- <section>
- <title>Client side failover listener</title>
- <para>The <literal>client-side-failoverlistener</literal> example shows how to register a listener to monitor
- failover events</para>
- </section>
- <section>
- <title>Client-Side Load-Balancing</title>
- <para>The <literal>client-side-load-balancing</literal> example demonstrates how
- sessions created from a single JMS <literal>Connection</literal> can
- be created to different nodes of the cluster. In other words it demonstrates how
- ActiveMQ does client-side load-balancing of sessions across the cluster.</para>
- </section>
- <section id="examples.clustered.durable">
- <title>Clustered Durable Subscription</title>
- <para>This example demonstrates a clustered JMS durable subscription</para>
- </section>
- <section id="examples.clustered.grouping">
- <title>Clustered Grouping</title>
- <para>This is similar to the message grouping example except that it demonstrates it
- working over a cluster. Messages sent to different nodes with the same group id will
- be sent to the same node and the same consumer.</para>
- </section>
- <section id="examples.clustered.queue">
- <title>Clustered Queue</title>
- <para>The <literal>clustered-queue</literal> example demonstrates a JMS queue deployed
- on two different nodes. The two nodes are configured to form a cluster. We then
- create a consumer for the queue on each node, and we create a producer on only one
- of the nodes. We then send some messages via the producer, and we verify that both
- consumers receive the sent messages in a round-robin fashion.</para>
- </section>
- <section id="examples.clustered.jgroups">
- <title>Clustering with JGroups</title>
- <para>The <literal>clustered-jgroups</literal> example demonstrates how to form a two
- node cluster using JGroups as its underlying topology discovery technique, rather than
- the default UDP broadcasting. We then create a consumer for the queue on each node,
- and we create a producer on only one of the nodes. We then send some messages via the
- producer, and we verify that both consumers receive the sent messages in a round-robin fashion.</para>
- </section>
- <section id="examples.clustered.standalone">
- <title>Clustered Standalone</title>
- <para>The <literal>clustered-standalone</literal> example demonstrates how to configure
- and starts 3 cluster nodes on the same machine to form a cluster. A subscriber for a
- JMS topic is created on each node, and we create a producer on only one of the
- nodes. We then send some messages via the producer, and we verify that the 3
- subscribers receive all the sent messages.</para>
- </section>
- <section id="examples.clustered.static.discovery">
- <title>Clustered Static Discovery</title>
- <para>This example demonstrates how to configure a cluster using a list of connectors rather
- than UDP for discovery</para>
- </section>
- <section id="examples.clustered.static.oneway">
- <title>Clustered Static Cluster One Way</title>
- <para>This example demonstrates how to set up a cluster where cluster connections are one way,
- i.e. server A -> Server B -> Server C</para>
- </section>
- <section>
- <title>Clustered Topic</title>
- <para>The <literal>clustered-topic</literal> example demonstrates a JMS topic deployed
- on two different nodes. The two nodes are configured to form a cluster. We then
- create a subscriber on the topic on each node, and we create a producer on only one
- of the nodes. We then send some messages via the producer, and we verify that both
- subscribers receive all the sent messages.</para>
- </section>
- <section id="examples.consumer-rate-limit">
- <title>Message Consumer Rate Limiting</title>
- <para>With ActiveMQ you can specify a maximum consume rate at which a JMS MessageConsumer
- will consume messages. This can be specified when creating or deploying the
- connection factory.</para>
- <para>If this value is specified then ActiveMQ will ensure that messages are never
- consumed at a rate higher than the specified rate. This is a form of consumer
- throttling.</para>
- </section>
- <section id="examples.dead-letter">
- <title>Dead Letter</title>
- <para>The <literal>dead-letter</literal> example shows you how to define and deal with
- dead letter messages. Messages can be delivered unsuccessfully (e.g. if the
- transacted session used to consume them is rolled back). </para>
- <para>Such a message goes back to the JMS destination ready to be redelivered. However,
- this means it is possible for a message to be delivered again and again without any
- success and remain in the destination, clogging the system.</para>
- <para>To prevent this, messaging systems define dead letter messages: after a specified
- unsuccessful delivery attempts, the message is removed from the destination and put
- instead in a dead letter destination where they can be consumed for further
- investigation.</para>
- </section>
- <section id="examples.delayed-redelivery">
- <title>Delayed Redelivery</title>
- <para>The <literal>delayed-redelivery</literal> example demonstrates how ActiveMQ can be
- configured to provide a delayed redelivery in the case a message needs to be
- redelivered.</para>
- <para>Delaying redelivery can often be useful in the case that clients regularly fail or
- roll-back. Without a delayed redelivery, the system can get into a "thrashing"
- state, with delivery being attempted, the client rolling back, and delivery being
- re-attempted in quick succession, using up valuable CPU and network
- resources.</para>
- </section>
- <section id="divert-example">
- <title>Divert</title>
- <para>ActiveMQ diverts allow messages to be transparently "diverted" or copied from one
- address to another with just some simple configuration defined on the server
- side.</para>
- </section>
- <section>
- <title>Durable Subscription</title>
- <para>The <literal>durable-subscription</literal> example shows you how to use a durable
- subscription with ActiveMQ. Durable subscriptions are a standard part of JMS, please
- consult the JMS 1.1 specification for full details.</para>
- <para>Unlike non-durable subscriptions, the key function of durable subscriptions is
- that the messages contained in them persist longer than the lifetime of the
- subscriber - i.e. they will accumulate messages sent to the topic even if there is
- no active subscriber on them. They will also survive server restarts or crashes.
- Note that for the messages to be persisted, the messages sent to them must be marked
- as durable messages. </para>
- </section>
- <section id="examples.embedded.jms">
- <title>Embedded</title>
- <para>The <literal>embedded</literal> example shows how to embed JMS
- within your own code using POJO instantiation and no config files.</para>
- </section>
- <section id="examples.embedded.jms.simple">
- <title>Embedded Simple</title>
- <para>The <literal>embedded</literal> example shows how to embed JMS within your own code using regular ActiveMQ XML files.</para>
- </section>
- <section id="examples.expiry">
- <title>Message Expiration</title>
- <para>The <literal>expiry</literal> example shows you how to define and deal with
- message expiration. Messages can be retained in the messaging system for a limited
- period of time before being removed. JMS specification states that clients should
- not receive messages that have been expired (but it does not guarantee this will not
- happen).</para>
- <para>ActiveMQ can assign an expiry address to a given queue so that when messages
- are expired, they are removed from the queue and sent to the expiry address.
- These "expired" messages can later be consumed from the expiry address for
- further inspection.</para>
- </section>
- <section id="examples.activemq-ra-rar">
- <title>ActiveMQ Resource Adapter example</title>
- <para>This examples shows how to build the activemq resource adapters a rar for deployment in other Application
- Server's</para>
- </section>
- <section>
- <title>HTTP Transport</title>
- <para>The <literal>http-transport</literal> example shows you how to configure ActiveMQ
- to use the HTTP protocol as its transport layer.</para>
- </section>
- <section>
- <title>Instantiate JMS Objects Directly</title>
- <para>Usually, JMS Objects such as <literal>ConnectionFactory</literal>, <literal
- >Queue</literal> and <literal>Topic</literal> instances are looked up from JNDI
- before being used by the client code. This objects are called "administered objects"
- in JMS terminology.</para>
- <para>However, in some cases a JNDI server may not be available or desired. To come to
- the rescue ActiveMQ also supports the direct instantiation of these administered
- objects on the client side so you don't have to use JNDI for JMS.</para>
- </section>
- <section id="examples.interceptor">
- <title>Interceptor</title>
- <para>ActiveMQ allows an application to use an interceptor to hook into the messaging
- system. Interceptors allow you to handle various message events in ActiveMQ.</para>
- </section>
- <section id="examples.jaas">
- <title>JAAS</title>
- <para>The <literal>jaas</literal> example shows you how to configure ActiveMQ to use JAAS
- for security. ActiveMQ can leverage JAAS to delegate user authentication and
- authorization to existing security infrastructure.</para>
- </section>
- <section id="examples.jms.auto-closeable">
- <title>JMS Auto Closable</title>
- <para>The <literal>jms-auto-closeable</literal> example shows how JMS resources, such
- as connections, sessions and consumers, in JMS 2 can be automatically closed on error.</para>
- </section>
- <section id="examples.jms.completion-listener">
- <title>JMS Completion Listener</title>
- <para>The <literal>jms-completion-listener</literal> example shows how to send a message
- asynchronously to ActiveMQ and use a CompletionListener to be notified of the Broker
- receiving it.</para>
- </section>
- <section id="examples.jms.jms-bridge">
- <title>JMS Bridge</title>
- <para>The <literal>jms-brige</literal> example shows how to setup a bridge
- between two standalone ActiveMQ servers.</para>
- </section>
- <section id="examples.jms.jms-context">
- <title>JMS Context</title>
- <para>The <literal>jms-context</literal> example shows how to send and receive a message
- to a JMS Queue using ActiveMQ by using a JMS Context.</para>
- <para>A JMSContext is part of JMS 2.0 and combines the JMS Connection and Session Objects
- into a simple Interface.</para>
- </section>
- <section id="examples.jms.jms-shared-consumer">
- <title>JMS Shared Consumer</title>
- <para>The <literal>jms-shared-consumer</literal> example shows you how can use shared
- consumers to share a subscription on a topic. In JMS 1.1 this was not allowed and so caused
- a scalability issue. In JMS 2 this restriction has been lifted so you can share the load
- across different threads and connections.</para>
- </section>
- <section id="examples.jmx">
- <title>JMX Management</title>
- <para>The <literal>jmx</literal> example shows how to manage ActiveMQ using JMX.</para>
- </section>
- <section id="examples.large-message">
- <title>Large Message</title>
- <para>The <literal>large-message</literal> example shows you how to send and receive
- very large messages with ActiveMQ. ActiveMQ supports the sending and receiving of huge
- messages, much larger than can fit in available RAM on the client or server.
- Effectively the only limit to message size is the amount of disk space you have on
- the server.</para>
- <para>Large messages are persisted on the server so they can survive a server restart.
- In other words ActiveMQ doesn't just do a simple socket stream from the sender to the
- consumer.</para>
- </section>
- <section id="examples.last-value-queue">
- <title>Last-Value Queue</title>
- <para>The <literal>last-value-queue</literal> example shows you how to define and deal
- with 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 is put in the queue. In other words, a last-value queue only retains the
- last value.</para>
- <para>A typical example for last-value queue is for stock prices, where you are only
- interested by the latest price for a particular stock.</para>
- </section>
- <section id="examples.management">
- <title>Management</title>
- <para>The <literal>management</literal> example shows how to manage ActiveMQ using JMS
- Messages to invoke management operations on the server.</para>
- </section>
- <section id="examples.management-notifications">
- <title>Management Notification</title>
- <para>The <literal>management-notification</literal> example shows how to receive
- management notifications from ActiveMQ using JMS messages. ActiveMQ servers emit
- management notifications when events of interest occur (consumers are created or
- closed, addresses are created or deleted, security authentication fails,
- etc.).</para>
- </section>
- <section id="examples.message-counters">
- <title>Message Counter</title>
- <para>The <literal>message-counters</literal> example shows you how to use message
- counters to obtain message information for a JMS queue.</para>
- </section>
- <section id="examples.message-group">
- <title>Message Group</title>
- <para>The <literal>message-group</literal> example shows you how to configure and use
- message groups with ActiveMQ. Message groups allow you to pin messages so they are
- only consumed by a single consumer. Message groups are sets of messages that has the
- following characteristics:</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>Messages in a message group share the same group id, i.e. they have
- same JMSXGroupID string property values</para>
- </listitem>
- <listitem>
- <para>The consumer that receives the first message of a group will receive
- all the messages that belongs to the group</para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section id="examples.message-group2">
- <title>Message Group</title>
- <para>The <literal>message-group2</literal> example shows you how to configure and use
- message groups with ActiveMQ via a connection factory.</para>
- </section>
- <section id="examples.message-priority">
- <title>Message Priority</title>
- <para>Message Priority can be used to influence the delivery order for messages.</para>
- <para>It can be retrieved by the message's standard header field 'JMSPriority' as
- defined in JMS specification version 1.1. </para>
- <para>The value is of type integer, ranging from 0 (the lowest) to 9 (the highest). When
- messages are being delivered, their priorities will effect their order of delivery.
- Messages of higher priorities will likely be delivered before those of lower
- priorities. </para>
- <para>Messages of equal priorities are delivered in the natural order of their arrival
- at their destinations. Please consult the JMS 1.1 specification for full
- details.</para>
- </section>
- <section id="examples.multiple.failover">
- <title>Multiple Failover</title>
- <para>This example demonstrates how to set up a live server with multiple backups</para>
- </section>
- <section id="examples.multiple.failover.failback">
- <title>Multiple Failover Failback</title>
- <para>This example demonstrates how to set up a live server with multiple backups but
- forcing failover back to the original live server</para>
- </section>
- <section id="examples.no-consumer-buffering">
- <title>No Consumer Buffering</title>
- <para>By default, ActiveMQ consumers buffer messages from the server in a client side
- buffer before you actually receive them on the client side. This improves
- performance since otherwise every time you called receive() or had processed the
- last message in a <literal>MessageListener onMessage()</literal> method, the ActiveMQ
- client would have to go the server to request the next message, which would then get
- sent to the client side, if one was available.</para>
- <para>This would involve a network round trip for every message and reduce performance.
- Therefore, by default, ActiveMQ pre-fetches messages into a buffer on each
- consumer.</para>
- <para>In some case buffering is not desirable, and ActiveMQ allows it to be switched off.
- This example demonstrates that.</para>
- </section>
- <section id="examples.non-transaction-failover">
- <title>Non-Transaction Failover With Server Data Replication</title>
- <para>The <literal>non-transaction-failover</literal> example demonstrates two servers coupled
- as a live-backup pair for high availability (HA), and a client using a <emphasis>non-transacted
- </emphasis> JMS session failing over from live to backup when the live server is
- crashed.</para>
- <para>ActiveMQ implements failover of client connections between
- live and backup servers. This is implemented by the replication of state between
- live and backup nodes. When replication is configured and a live node crashes, the
- client connections can carry and continue to send and consume messages. When non-transacted
- sessions are used, once and only once message delivery is not guaranteed and it is possible
- that some messages will be lost or delivered twice.</para>
- </section>
- <section id="examples.openwire">
- <title>OpenWire</title>
- <para>The <literal>Openwire</literal> example shows how to configure a ActiveMQ
- server to communicate with an ActiveMQ JMS client that uses open-wire protocol.</para>
- </section>
- <section id="examples.paging">
- <title>Paging</title>
- <para>The <literal>paging</literal> example shows how ActiveMQ can support huge queues
- even when the server is running in limited RAM. It does this by transparently
- <emphasis>paging</emphasis> messages to disk, and <emphasis>depaging</emphasis>
- them when they are required.</para>
- </section>
- <section id="examples.pre-acknowledge">
- <title>Pre-Acknowledge</title>
- <para>Standard JMS supports three acknowledgement modes:<literal>
- AUTO_ACKNOWLEDGE</literal>, <literal>CLIENT_ACKNOWLEDGE</literal>, and <literal
- >DUPS_OK_ACKNOWLEDGE</literal>. For a full description on these modes please
- consult the JMS specification, or any JMS tutorial.</para>
- <para>All of these standard modes involve sending acknowledgements from the client to
- the server. However in some cases, you really don't mind losing messages in event of
- failure, so it would make sense to acknowledge the message on the server before
- delivering it to the client. This example demonstrates how ActiveMQ allows this with
- an extra acknowledgement mode.</para>
- </section>
- <section id="producer-rate-limiting-example">
- <title>Message Producer Rate Limiting</title>
- <para>The <literal>producer-rte-limit</literal> example demonstrates how, with ActiveMQ,
- you can specify a maximum send rate at which a JMS message producer will send
- messages.</para>
- </section>
- <section id="examples.proton-qpid">
- <title>Proton Qpid</title>
- <para>ActiveMQ can be configured to accept requests from any AMQP client that supports the
- 1.0 version of the protocol. This <literal>proton-j</literal> example shows a simply
- qpid java 1.0 client example.</para>
- </section>
- <section id="examples.proton-ruby">
- <title>Proton Ruby</title>
- <para>ActiveMQ can be configured to accept requests from any AMQP client that supports the
- 1.0 version of the protocol. This example shows a simply proton ruby client
- that sends and receives messages</para>
- </section>
- <section id="examples.queue">
- <title>Queue</title>
- <para>A simple example demonstrating a JMS queue.</para>
- </section>
- <section id="examples.message-redistribution">
- <title>Message Redistribution</title>
- <para>The <literal>queue-message-redistribution</literal> example demonstrates message
- redistribution between queues with the same name deployed in different nodes of a
- cluster.</para>
- </section>
- <section id="examples.queue-requestor">
- <title>Queue Requestor</title>
- <para>A simple example demonstrating a JMS queue requestor.</para>
- </section>
- <section id="examples.queue-message-selector">
- <title>Queue with Message Selector</title>
- <para>The <literal>queue-selector</literal> example shows you how to selectively consume
- messages using message selectors with queue consumers.</para>
- </section>
- <section id="examples.reattach-node">
- <title>Reattach Node example</title>
- <para>The <literal>Reattach Node</literal> example shows how a client can try to reconnect to
- the same server instead of failing the connection immediately and
- notifying any user ExceptionListener objects. ActiveMQ can be configured to automatically
- retry the connection, and reattach to the server when it becomes available again across
- the network.</para>
- </section>
- <section id="examples.replicated-failback">
- <title>Replicated Failback example</title>
- <para>An example showing how failback works when using replication, In this example a live server will replicate
- all its Journal to a backup server as it updates it. When the live server crashes the backup takes over
- from the live server and the client reconnects and carries on from where it left off.</para>
- </section>
- <section id="examples.replicated-failback-static">
- <title>Replicated Failback static example</title>
- <para>An example showing how failback works when using replication, but this time with static connectors</para>
- </section>
- <section id="examples.replicated-multiple-failover">
- <title>Replicated multiple failover example</title>
- <para>An example showing how to configure multiple backups when using replication</para>
- </section>
- <section id="examples.replicated-failover-transaction">
- <title>Replicated Failover transaction example</title>
- <para>An example showing how failover works with a transaction when using replication</para>
- </section>
- <section id="examples.request-reply">
- <title>Request-Reply example</title>
- <para>A simple example showing the JMS request-response pattern.</para>
- </section>
- <section id="examples.rest">
- <title>Rest example</title>
- <para>An example showing how to use the ActiveMQ Rest API</para>
- </section>
- <section id="examples.scheduled-message">
- <title>Scheduled Message</title>
- <para>The <literal>scheduled-message</literal> example shows you how to send a scheduled
- message to a JMS Queue with ActiveMQ. Scheduled messages won't get delivered until a
- specified time in the future.</para>
- </section>
- <section id="examples.security">
- <title>Security</title>
- <para>The <literal>security</literal> example shows you how configure and use role based
- queue security with ActiveMQ.</para>
- </section>
- <section id="asynchronous-send-acknowledgements-example">
- <title>Send Acknowledgements</title>
- <para>The <literal>send-acknowledgements</literal> example shows you how to use
- ActiveMQ's advanced <emphasis>asynchronous send acknowledgements</emphasis> feature
- to obtain acknowledgement from the server that sends have been received and
- processed in a separate stream to the sent messages. </para>
- </section>
- <section id="examples.jms.spring.integration">
- <title>Spring Integration</title>
- <para>This example shows how to use embedded JMS using ActiveMQ's Spring integration.</para>
- </section>
- <section id="examples.ssl-transport">
- <title>SSL Transport</title>
- <para>The <literal>ssl-enabled</literal> shows you how to configure SSL with ActiveMQ to
- send and receive message.</para>
- </section>
- <section id="examples.static-message-selector">
- <title>Static Message Selector</title>
- <para>The <literal>static-selector</literal> example shows you how to configure a
- ActiveMQ core queue with static message selectors (filters).</para>
- </section>
- <section id="examples.static-message-selector-jms">
- <title>Static Message Selector Using JMS</title>
- <para>The <literal>static-selector-jms</literal> example shows you how to configure a
- ActiveMQ queue with static message selectors (filters) using JMS.</para>
- </section>
- <section id="examples.stomp">
- <title>Stomp</title>
- <para>The <literal>stomp</literal> example shows you how to configure a
- ActiveMQ server to send and receive Stomp messages.</para>
- </section>
- <section id="examples.stomp1.1">
- <title>Stomp1.1</title>
- <para>The <literal>stomp</literal> example shows you how to configure a
- ActiveMQ server to send and receive Stomp messages via a Stomp 1.1 connection.</para>
- </section>
- <section id="examples.stomp1.2">
- <title>Stomp1.2</title>
- <para>The <literal>stomp</literal> example shows you how to configure a
- ActiveMQ server to send and receive Stomp messages via a Stomp 1.2 connection.</para>
- </section>
- <section id="examples.stomp-web-socket">
- <title>Stomp Over Web Sockets</title>
- <para>The <literal>stomp-websockets</literal> example shows you how to configure a
- ActiveMQ server to send and receive Stomp messages directly from Web browsers (provided
- they support Web Sockets).</para>
- </section>
- <section id="examples.symmetric-cluster">
- <title>Symmetric Cluster</title>
- <para>The <literal>symmetric-cluster</literal> example demonstrates a symmetric cluster
- set-up with ActiveMQ.</para>
- <para>ActiveMQ has extremely flexible clustering which allows you to set-up servers in
- many different topologies. The most common topology that you'll perhaps be familiar
- with if you are used to application server clustering is a symmetric cluster.</para>
- <para>With a symmetric cluster, the cluster is homogeneous, i.e. each node is configured
- the same as every other node, and every node is connected to every other node in the
- cluster.</para>
- </section>
- <section id="examples.temporary-queue">
- <title>Temporary Queue</title>
- <para>A simple example demonstrating how to use a JMS temporary queue.</para>
- </section>
- <section id="examples.topic">
- <title>Topic</title>
- <para>A simple example demonstrating a JMS topic.</para>
- </section>
- <section id="topic-hierarchy-example">
- <title>Topic Hierarchy</title>
- <para>ActiveMQ supports topic hierarchies. With a topic hierarchy you can register a
- subscriber with a wild-card and that subscriber will receive any messages sent to an
- address that matches the wild card.</para>
- </section>
- <section id="examples.topic-selector-1">
- <title>Topic Selector 1</title>
- <para>The <literal>topic-selector-example1</literal> example shows you how to send
- message to a JMS Topic, and subscribe them using selectors with ActiveMQ.</para>
- </section>
- <section id="examples.topic-selector-2">
- <title>Topic Selector 2</title>
- <para>The <literal>topic-selector-example2</literal> example shows you how to
- selectively consume messages using message selectors with topic consumers.</para>
- </section>
- <section id="examples.transaction-failover">
- <title>Transaction Failover</title>
- <para>The <literal>transaction-failover</literal> example demonstrates two servers coupled
- as a live-backup pair for high availability (HA), and a client using a transacted JMS
- session failing over from live to backup when the live server is
- crashed.</para>
- <para>ActiveMQ implements failover of client connections between
- live and backup servers. This is implemented by the sharing of a journal between the
- servers. When a live node crashes, the
- client connections can carry and continue to send and consume messages. When transacted
- sessions are used, once and only once message delivery is guaranteed.</para>
- </section>
- <section id="examples.no-transaction-failover">
- <title>Failover Without Transactions</title>
- <para>The <literal>stop-server-failover</literal> example demonstrates failover of the
- JMS connection from one node to another when the live server crashes using a JMS
- non-transacted session.</para>
- </section>
- <section id="examples.transactional-session">
- <title>Transactional Session</title>
- <para>The <literal>transactional</literal> example shows you how to use a transactional
- Session with ActiveMQ.</para>
- </section>
- <section>
- <title>XA Heuristic</title>
- <para>The <literal>xa-heuristic</literal> example shows you how to make an XA heuristic
- decision through ActiveMQ Management Interface. A heuristic decision is a unilateral
- decision to commit or rollback an XA transaction branch after it has been
- prepared.</para>
- </section>
- <section>
- <title>XA Receive</title>
- <para>The <literal>xa-receive</literal> example shows you how message receiving behaves
- in an XA transaction in ActiveMQ.</para>
- </section>
- <section>
- <title>XA Send</title>
- <para>The <literal>xa-send</literal> example shows you how message sending behaves in an
- XA transaction in ActiveMQ.</para>
- </section>
- <section>
- <title>XA with Transaction Manager</title>
- <para>The <literal>xa-with-jta</literal> example shows you how to use JTA interfaces to
- control transactions with ActiveMQ.</para>
- </section>
- </section>
- <section>
- <title>Core API Examples</title>
- <para>To run a core example, simply <literal>cd</literal> into the appropriate example
- directory and type <literal>ant</literal></para>
- <section id="examples.embedded">
- <title>Embedded</title>
- <para>The <literal>embedded</literal> example shows how to embed the ActiveMQ server
- within your own code.</para>
- </section>
- </section>
- <section>
- <title>Java EE Examples</title>
- <para>Most of the Java EE examples can be run the following way. Simply navigate into the
- appropriate example directory and type <literal>mvn verify</literal>. This will use Arquillian to run the Application
- Server and deploy the application. Note that you must have WildFly installed and the JBOSS_HOME environment
- variable set. Please refer to the examples documentation for further instructions.</para>
- <note>
- <para>When running the Java EE examples you may see warning messages in the WildFly log about incompatible client and
- server versions. This is normal if a newer version of the ActiveMQ project is being used with a version of WildFly that
- ships an older version of ActiveMQ. These examples should still complete without any functional errors.</para>
- </note>
- <section>
- <title>EJB/JMS Transaction</title>
- <para>An example that shows using an EJB and JMS together within a transaction.</para>
- </section>
- <section>
- <title>Resource Adapter Configuration</title>
- <para>This example demonstrates how to configure several properties on the ActiveMQ JCA
- resource adaptor.</para>
- </section>
- <section>
- <title>Resource Adapter Remote Server Configuration</title>
- <para>This example demonstrates how to configure the ActiveMQ resource adapter to talk to a remote ActiveMQ server</para>
- </section>
- <section id="examples.javaee.jms-bridge">
- <title>JMS Bridge</title>
- <para>An example demonstrating the use of the ActiveMQ JMS bridge.</para>
- </section>
- <section>
- <title>MDB (Message Driven Bean)</title>
- <para>A simple set of examples of message driven beans, including failover examples.</para>
- </section>
- <section>
- <title>Servlet Transport</title>
- <para>An example of how to use the ActiveMQ servlet transport.</para>
- </section>
- <section>
- <title>Servlet SSL Transport</title>
- <para>An example of how to use the ActiveMQ servlet transport over SSL.</para>
- </section>
- <section id="xa-recovery-example">
- <title>XA Recovery</title>
- <para>An example of how XA recovery works within the JBoss Application server using
- ActiveMQ.</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/filter-expressions.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/filter-expressions.md b/docs/user-manual/en/filter-expressions.md
new file mode 100644
index 0000000..c1dfca5
--- /dev/null
+++ b/docs/user-manual/en/filter-expressions.md
@@ -0,0 +1,52 @@
+Filter Expressions
+==================
+
+ActiveMQ provides a powerful filter language based on a subset of the
+SQL 92 expression syntax.
+
+It is the same as the syntax used for JMS selectors, but the predefined
+identifiers are different. For documentation on JMS selector syntax
+please the JMS javadoc for
+[javax.jms.Message](http://docs.oracle.com/javaee/6/api/javax/jms/Message.html).
+
+Filter expressions are used in several places in ActiveMQ
+
+- Predefined Queues. When pre-defining a queue, either in
+ `activemq-configuration.xml` or `activemq-jms.xml` a filter
+ expression can be defined for a queue. Only messages that match the
+ filter expression will enter the queue.
+
+- Core bridges can be defined with an optional filter expression, only
+ matching messages will be bridged (see ?).
+
+- Diverts can be defined with an optional filter expression, only
+ matching messages will be diverted (see ?).
+
+- Filter are also used programmatically when creating consumers,
+ queues and in several places as described in ?.
+
+There are some differences between JMS selector expressions and ActiveMQ
+core filter expressions. Whereas JMS selector expressions operate on a
+JMS message, ActiveMQ core filter expressions operate on a core message.
+
+The following identifiers can be used in a core filter expressions to
+refer to attributes of the core message in an expression:
+
+- `HQPriority`. To refer to the priority of a message. Message
+ priorities are integers with valid values from `0 - 9`. `0` is the
+ lowest priority and `9` is the highest. E.g.
+ `HQPriority = 3 AND animal = 'aardvark'`
+
+- `HQExpiration`. To refer to the expiration time of a message. The
+ value is a long integer.
+
+- `HQDurable`. To refer to whether a message is durable or not. The
+ value is a string with valid values: `DURABLE` or `NON_DURABLE`.
+
+- `HQTimestamp`. The timestamp of when the message was created. The
+ value is a long integer.
+
+- `HQSize`. The size of a message in bytes. The value is an integer.
+
+Any other identifiers used in core filter expressions will be assumed to
+be properties of the message.