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.
