Apache
/
activemq-artemis
mirror of https://github.com/apache/activemq-artemis.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
activemq-artemis/docs/user-manual/en/using-jms.md

17 KiB
Raw Blame History

Using JMS

Although ActiveMQ provides a JMS agnostic messaging API, many users will be more comfortable using JMS.

JMS is a very popular API standard for messaging, and most messaging systems provide a JMS API. If you are completely new to JMS we suggest you follow theSun JMS tutorial - a full JMS tutorial is out of scope for this guide.

ActiveMQ also ships with a wide range of examples, many of which demonstrate JMS API usage. A good place to start would be to play around with the simple JMS Queue and Topic example, but we also provide examples for many other parts of the JMS API. A full description of the examples is available in Examples.

In this section we'll go through the main steps in configuring the server for JMS and creating a simple JMS program. We'll also show how to configure and use JNDI, and also how to use JMS with ActiveMQ without using any JNDI.

A simple ordering system

For this chapter we're going to use a very simple ordering system as our example. It is a somewhat contrived example because of its extreme simplicity, but it serves to demonstrate the very basics of setting up and using JMS.

We will have a single JMS Queue called OrderQueue, and we will have a single MessageProducer sending an order message to the queue and a single MessageConsumer consuming the order message from the queue.

The queue will be a durable queue, i.e. it will survive a server restart or crash. We also want to pre-deploy the queue, i.e. specify the queue in the server JMS configuration so it is created automatically without us having to explicitly create it from the client.

JNDI Configuration

The JMS specification establishes the convention that administered objects (i.e. JMS queue, topic and connection factory instances) are made available via the JNDI API. Brokers are free to implement JNDI as they see fit assuming the implementation fits the API. ActiveMQ does not have a JNDI server. Rather, it uses a client-side JNDI implementation that relies on special properties set in the environment to construct the appropriate JMS objects. In other words, no objects are stored in JNDI on the ActiveMQ server. There are simply instantiated on the client based on the provided configuration. Let's look at the different kinds of administered objects and how to configure them.

Note

The following configuration properties are strictly required when ActiveMQ is running in stand-alone mode. When ActiveMQ is integrated to an application server (e.g. Wildfly) the application server itself will almost certainly provide a JNDI client with its own properties.

ConnectionFactory JNDI

A JMS connection factory is used by the client to make connections to the server. It knows the location of the server it is connecting to, as well as many other configuration parameters.

By default, a javax.naming.Context instance created using the org.apache.activemq.jndi.ActiveMQInitialContextFactory will automatically have the following connection factories available for lookup:

  • ConnectionFactory

  • XAConnectionFactory

  • QueueConnectionFactory

  • TopicConnectionFactory

Here's a simple example of the JNDI context environment for a client looking up a connection factory to access an embedded instance of ActiveMQ:

java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory

It's really as simple as that. As noted previously, any JNDI context created with the ActiveMQInitialContextFactory will have a set of default connection factories available. Therefore, only the java.naming.factory.initial property is required to access an embedded broker.

In certain situations there could be multiple server instances running within a particular JVM. In that situation each server would typically have an InVM acceptor with a unique server-ID. A client using JMS and JNDI can account for this by specifying a javax.naming.Context.PROVIDER_URL (String value of "java.naming.provider.url") in the JNDI environment like vm://2 where 2 is the server-ID for acceptor.

Here is a list of all the supported URL schemes:

  • vm

  • tcp

  • udp

  • jgroups

Most clients won't be connecting to an embedded broker. Clients will most commonly connect across a network a remote broker. In that case the client can use the javax.naming.Context.PROVIDER_URL (String value of "java.naming.provider.url") in the JNDI environment to specify where to connect. Here's a simple example of a client configuring a connection factory to connect to a remote broker running on myhost:5445:

java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
java.naming.provider.url=tcp://myhost:5445

In the example above the client is using the tcp scheme for the provider URL. A client may also specify multiple comma-delimited host:port combinations in the URL (e.g. tcp://remote-host1:5445,remote-host2:5445). Whether there is one or many host:port combinations in the URL they are treated as the initial connector(s) for the underlying connection.

The udp scheme is also supported which should use an host:port combination that matches the group-address and group-port from the corresponding broadcast-group configured on the ActiveMQ server(s).

Each scheme has a specific set of properties which can be set using the traditional URL query string format (e.g. scheme://host:port?key1=value1&key2=value2) to customize the underlying transport mechanism. For example, if a client wanted to connect to a remote server using TCP and SSL it would use a Context.PROVIDER_URL of tcp://remote-host:5445?ssl-enabled=true.

All the properties available for the tcp scheme are described in the documentation regarding the Netty transport.

The udp scheme supports 4 properties:

  • local-address - If you are running with multiple network interfaces on the same machine, you may want to specify that the discovery group listens only only a specific interface. To do this you can specify the interface address with this parameter.

  • local-port - If you want to specify a local port to which the datagram socket is bound you can specify it here. Normally you would just use the default value of -1 which signifies that an anonymous port should be used. This parameter is always specified in conjunction with local-address.

  • refresh-timeout - This is the period the discovery group waits after receiving the last broadcast from a particular server before removing that servers connector pair entry from its list. You would normally set this to a value significantly higher than the broadcast-period on the broadcast group otherwise servers might intermittently disappear from the list even though they are still broadcasting due to slight differences in timing. This parameter is optional, the default value is 10000 milliseconds (10 seconds).

  • discovery-initial-wait-timeout - If the connection factory is used immediately after creation then it may not have had enough time to received broadcasts from all the nodes in the cluster. On first usage, the connection factory will make sure it waits this long since creation before creating the first connection. The default value for this parameter is 10000 milliseconds.

Lastly, the jgroups scheme is supported which provides an alternative to the udp scheme for server discovery. The URL pattern is as follows jgroups://<jgroups-xml-conf-filename> where <jgroups-xml-conf-filename> refers to an XML file on the classpath that contains the JGroups configuration.

The refresh-timeout and discovery-initial-wait-timeout properties are supported just like with udp.

Although a javax.naming.Context instance created using the org.apache.activemq.jndi.ActiveMQInitialContextFactory will automatically have some connection factories present, it is possible for a client to specify its own connection factories. This is done using the org.apache.activemq.jndi.ActiveMQInitialContextFactory.CONNECTION_FACTORY_NAMES property (String value of "connectionFactoryNames"). The value for this property is a comma delimited String of all the connection factories the client wishes to create. For example:

java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
java.naming.provider.url=tcp://localhost:5445
connectionFactoryNames=myConnectionFactory

In this example, the client is creating a connection factory named "myConnectionFactory." This replaces all the default connection factories so that only the "myConnectionFactory" connection factory is available to the client.

Aside from the underlying transport, the underlying connection factory implementation can also be configured using special properties. To configure a particular connection factory the client would follow this pattern for the property name to set in the environment: connection.<connection-factory-name>.<property-name>. For example, if the client wanted to customize the default connection factory "ConnectionFactory" to support high-availability then it would do this:

java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
java.naming.provider.url=tcp://myhost:5445
connection.ConnectionFactory.ha=true

Any property available on the underlying org.apache.activemq.jms.client.ActiveMQConnectionFactory can be set this way in addition to the ha (boolean) and type (String) properties. Here are the different options for the type:

Configuration for Connection Factory Types

type interface
CF (default) javax.jms.ConnectionFactory
XA_CF javax.jms.XAConnectionFactory
QUEUE_CF javax.jms.QueueConnectionFactory
QUEUE_XA_CF javax.jms.XAQueueConnectionFactory
TOPIC_CF javax.jms.TopicConnectionFactory
TOPIC_XA_CF javax.jms.XATopicConnectionFactory

Destination JNDI

JMS destinations are also typically looked up via JNDI. As with connection factories, destinations can be configured using special properties in the JNDI context environment. The property name should follow the pattern: queue.<jndi-binding> or topic.<jndi-binding>. The property value should be the name of the queue hosted by the ActiveMQ server. For example, if the server had a JMS queue configured like so:

<queue name="OrderQueue"/>

And if the client wanted to bind this queue to "queues/OrderQueue" then the JNDI properties would be configured like so:

java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
java.naming.provider.url=tcp://myhost:5445
queue.queues/OrderQueue=OrderQueue

It is also possible to look-up JMS destinations which haven't been configured explicitly in the JNDI context environment. This is possible using dynamicQueues/ or dynamicTopics/ in the look-up string. For example, if the client wanted to look-up the aforementioned "OrderQueue" it could do so simply by using the string "dynamicQueues/OrderQueue". Note, the text that follows dynamicQueues/ or dynamicTopics/ must correspond exactly to the name of the destination on the server.

The code

Here's the code for the example:

First we'll create a JNDI initial context from which to lookup our JMS objects. If the above properties are set in jndi.properties and it is on the classpath then any new, empty InitialContext will be initialized using those properties:

InitialContext ic = new InitialContext();

//Now we'll look up the connection factory from which we can create
//connections to myhost:5445:

ConnectionFactory cf = (ConnectionFactory)ic.lookup("ConnectionFactory");

//And look up the Queue:

Queue orderQueue = (Queue)ic.lookup("queues/OrderQueue");

//Next we create a JMS connection using the connection factory:

Connection connection = cf.createConnection();

//And we create a non transacted JMS Session, with AUTO\_ACKNOWLEDGE
//acknowledge mode:

Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);

//We create a MessageProducer that will send orders to the queue:

MessageProducer producer = session.createProducer(orderQueue);

//And we create a MessageConsumer which will consume orders from the
//queue:

MessageConsumer consumer = session.createConsumer(orderQueue);

//We make sure we start the connection, or delivery won't occur on it:

connection.start();

//We create a simple TextMessage and send it:

TextMessage message = session.createTextMessage("This is an order");
producer.send(message);

//And we consume the message:

TextMessage receivedMessage = (TextMessage)consumer.receive();
System.out.println("Got order: " + receivedMessage.getText());

It is as simple as that. For a wide range of working JMS examples please see the examples directory in the distribution.

Warning

Please note that JMS connections, sessions, producers and consumers are designed to be re-used.

It is an anti-pattern to create new connections, sessions, producers and consumers for each message you produce or consume. If you do this, your application will perform very poorly. This is discussed further in the section on performance tuning Performance Tuning.

Directly instantiating JMS Resources without using JNDI

Although it is a very common JMS usage pattern to lookup JMS Administered Objects (that's JMS Queue, Topic and ConnectionFactory instances) from JNDI, in some cases you just think "Why do I need JNDI? Why can't I just instantiate these objects directly?"

With ActiveMQ you can do exactly that. ActiveMQ supports the direct instantiation of JMS Queue, Topic and ConnectionFactory instances, so you don't have to use JNDI at all.

For a full working example of direct instantiation please see the JMS examples in ?.

Here's our simple example, rewritten to not use JNDI at all:

We create the JMS ConnectionFactory object via the ActiveMQJMSClient Utility class, note we need to provide connection parameters and specify which transport we are using, for more information on connectors please see Configuring the Transport.

TransportConfiguration transportConfiguration = new TransportConfiguration(NettyConnectorFactory.class.getName());

ConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);

//We also create the JMS Queue object via the ActiveMQJMSClient Utility
//class:

Queue orderQueue = ActiveMQJMSClient.createQueue("OrderQueue");

//Next we create a JMS connection using the connection factory:

Connection connection = cf.createConnection();

//And we create a non transacted JMS Session, with AUTO\_ACKNOWLEDGE
//acknowledge mode:

Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);

//We create a MessageProducer that will send orders to the queue:

MessageProducer producer = session.createProducer(orderQueue);

//And we create a MessageConsumer which will consume orders from the
//queue:

MessageConsumer consumer = session.createConsumer(orderQueue);

//We make sure we start the connection, or delivery won't occur on it:

connection.start();

//We create a simple TextMessage and send it:

TextMessage message = session.createTextMessage("This is an order");
producer.send(message);

//And we consume the message:

TextMessage receivedMessage = (TextMessage)consumer.receive();
System.out.println("Got order: " + receivedMessage.getText());

Setting The Client ID

This represents the client id for a JMS client and is needed for creating durable subscriptions. It is possible to configure this on the connection factory and can be set via the client-id element. Any connection created by this connection factory will have this set as its client id.

Setting The Batch Size for DUPS_OK

When the JMS acknowledge mode is set to DUPS_OK it is possible to configure the consumer so that it sends acknowledgements in batches rather that one at a time, saving valuable bandwidth. This can be configured via the connection factory via the dups-ok-batch-size element and is set in bytes. The default is 1024 * 1024 bytes = 1 MiB.

Setting The Transaction Batch Size

When receiving messages in a transaction it is possible to configure the consumer to send acknowledgements in batches rather than individually saving valuable bandwidth. This can be configured on the connection factory via the transaction-batch-size element and is set in bytes. The default is 1024 * 1024.