Using the AMQ OpenWire JMS Client

AMQ OpenWire JMS supports the following industry-recognized standards and network protocols:

AMQ OpenWire JMS supports the OS and language versions listed below. For more information, see Red Hat AMQ 7 Supported Configurations.

AMQ OpenWire JMS is supported in combination with the following AMQ components and versions:

This section introduces the core API entities and describes how they operate together.

AMQ OpenWire JMS sends and receives messages. Messages are transferred between connected peers using message producers and consumers. Producers and consumers are established over sessions. Sessions are established over connections. Connections are created by connection factories.

A sending peer creates a producer to send messages. The producer has a destination that identifies a target queue or topic at the remote peer. A receiving peer creates a consumer to receive messages. Like the producer, the consumer has a destination that identifies a source queue or topic at the remote peer.

A destination is either a queue or a topic. In JMS, queues and topics are client-side representations of named broker entities that hold messages.

A queue implements point-to-point semantics. Each message is seen by only one consumer, and the message is removed from the queue after it is read. A topic implements publish-subscribe semantics. Each message is seen by multiple consumers, and the message remains available to other consumers after it is read.

See the JMS tutorial for more information.

The sudo command

In this document, sudo is used for any command that requires root privileges. Exercise caution when using sudo because any changes can affect the entire system. For more information about sudo, see Using the sudo command.

File paths

In this document, all file paths are valid for Linux, UNIX, and similar operating systems (for example, /home/andrea). On Microsoft Windows, you must use the equivalent Windows paths (for example, C:\Users\andrea).

Variable text

This document contains code blocks with variables that you must replace with values specific to your environment. Variable text is enclosed in arrow braces and styled as italic monospace. For example, in the following command, replace <project-dir> with the value for your environment:

cd <project-dir>

$ cd <project-dir>

Configure your Maven environment to download the client library from the Red Hat Maven repository.

The client is now available in your Maven project.

As an alternative to the online repository, AMQ OpenWire JMS can be installed to your local filesystem as a file-based Maven repository.

The example creates a consumer and producer for a queue named exampleQueue. It sends a text message and then receives it back, printing the received message to the console.

Running it on Linux results in the following output:

java -cp "target/classes:target/dependency/*" org.apache.activemq.artemis.jms.example.QueueExample

$ java -cp "target/classes:target/dependency/*" org.apache.activemq.artemis.jms.example.QueueExample
Sent message: This is a text message
Received message: This is a text message

The source code for the example is in the <install-dir>/examples/protocols/openwire/queue/src directory. Additional examples are available in the <install-dir>/examples/protocols/openwire directory.

JMS applications use a JNDI InitialContext object obtained from an InitialContextFactory to look up JMS objects such as the connection factory. AMQ OpenWire JMS provides an implementation of the InitialContextFactory in the org.apache.activemq.jndi.ActiveMQInitialContextFactory class.

The InitialContextFactory implementation is discovered when the InitialContext object is instantiated:

javax.naming.Context context = new javax.naming.InitialContext();

javax.naming.Context context = new javax.naming.InitialContext();

To find an implementation, JNDI must be configured in your environment. There are two main ways of achieving this, using a jndi.properties file or using a system property.

Using a jndi.properties file

Create a file named jndi.properties and place it on the Java classpath. Add a property with the key java.naming.factory.initial.

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

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

In Maven-based projects, the jndi.properties file is placed in the <project-dir>/src/main/resources directory.

Using a system property

Set the java.naming.factory.initial system property.

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

$ java -Djava.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory ...

The JMS connection factory is the entry point for creating connections. It uses a connection URI that encodes your application-specific configuration settings.

To set the factory name and connection URI, create a property in the format below. You can store this configuration in a jndi.properties file or set the corresponding system property.

connectionFactory.<factory-name> = <connection-uri>

connectionFactory.<factory-name> = <connection-uri>

For example, this is how you might configure a factory named app1:

connectionFactory.app1 = tcp://example.net:61616?jms.clientID=backend

connectionFactory.app1 = tcp://example.net:61616?jms.clientID=backend

You can then use the JNDI context to look up your configured connection factory using the name app1:

ConnectionFactory factory = (ConnectionFactory) context.lookup("app1");

ConnectionFactory factory = (ConnectionFactory) context.lookup("app1");

A connection factory is configured using a connection URI in the following format:

<scheme>://<host>:<port>[?<option>=<value>[&<option>=<value>...]]

<scheme>://<host>:<port>[?<option>=<value>[&<option>=<value>...]]

The scheme is tcp for unencrypted connections and ssl for SSL/TLS connections.

For example, the following is a connection URI that connects to host example.net at port 61616 and sets the client ID to backend:

tcp://example.net:61616?jms.clientID=backend

tcp://example.net:61616?jms.clientID=backend

Failover URIs take the following form:

failover:(<connection-uri>[,<connection-uri>])[?<option>=<value>[&<option>=<value>...]]

failover:(<connection-uri>[,<connection-uri>])[?<option>=<value>[&<option>=<value>...]]

Options prefixed with nested. are applied to each connection URI in the list.

The available connection options are described in the following sections.

Prefetch policy options

Prefetch policy determines how many messages each MessageConsumer will fetch from the remote peer and hold in a local "prefetch" buffer.

The value of prefetch can affect the distribution of messages to multiple consumers on a queue or shared subscription. A higher value can result in larger batches sent at once to each consumer. To achieve more even round-robin distribution, use a lower value.

Redelivery policy options

Redelivery policy controls how redelivered messages are handled on the client.

The client can enable large message support by setting a value for the property wireFormat.minLargeMessageSize. Any message larger than wireFormat.minLargeMessageSize is considered a large message.

To write to a large message, use the BytesMessage.writeBytes() method. The following example reads bytes from a file and writes them to a message:

BytesMessage message = session.createBytesMessage();
File inputFile = new File(inputFilePath);
InputStream inputStream = new FileInputStream(inputFile);

int numRead;
byte[] buffer = new byte[1024];

while ((numRead = inputStream.read(buffer, 0, buffer.length)) != -1) {
    message.writeBytes(buffer, 0, numRead);
}

BytesMessage message = session.createBytesMessage();
File inputFile = new File(inputFilePath);
InputStream inputStream = new FileInputStream(inputFile);

int numRead;
byte[] buffer = new byte[1024];

while ((numRead = inputStream.read(buffer, 0, buffer.length)) != -1) {
    message.writeBytes(buffer, 0, numRead);
}

To read from a large message, use the BytesMessage.readBytes() method. The following example reads bytes from a message and writes them to a file:

BytesMessage message = (BytesMessage) consumer.receive();
File outputFile = new File(outputFilePath);
OutputStream outputStream = new FileOutputStream(outputFile);

int numRead;
byte buffer[] = new byte[1024];

for (int pos = 0; pos < message.getBodyLength(); pos += buffer.length) {
    numRead = message.readBytes(buffer);
    outputStream.write(buffer, 0, numRead);
}

BytesMessage message = (BytesMessage) consumer.receive();
File outputFile = new File(outputFilePath);
OutputStream outputStream = new FileOutputStream(outputFile);

int numRead;
byte buffer[] = new byte[1024];

for (int pos = 0; pos < message.getBodyLength(); pos += buffer.length) {
    numRead = message.readBytes(buffer);
    outputStream.write(buffer, 0, numRead);
}