694 lines
43 KiB
XML
694 lines
43 KiB
XML
<?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>
|