Chapter 4. Configuration
This chapter describes the process for binding the AMQ Core Protocol JMS implementation to your JMS application and setting configuration options.
JMS uses the Java Naming Directory Interface (JNDI) to register and look up API implementations and other resources. This enables you to write code to the JMS API without tying it to a particular implementation.
Configuration options are exposed as query parameters on the connection URI.
4.1. Configuring the JNDI initial context
JMS applications use a JNDI
InitialContext object obtained from an
InitialContextFactory to look up JMS objects such as the connection factory. AMQ Core Protocol JMS provides an implementation of the
InitialContextFactory in the
InitialContextFactory implementation is discovered when the
InitialContext object is instantiated:
javax.naming.Context context = new javax.naming.InitialContext();
To find an implementation, JNDI must be configured in your environment. There are three ways of achieving this: using a
jndi.properties file, using a system property, or using the initial context API.
Using a jndi.properties file
Create a file named
jndi.properties and place it on the Java classpath. Add a property with the key
Example: Setting the JNDI initial context factory using a jndi.properties file
java.naming.factory.initial = org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
In Maven-based projects, the
jndi.properties file is placed in the
Using a system property
java.naming.factory.initial system property.
Example: Setting the JNDI initial context factory using a system property
$ java -Djava.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory ...
Using the initial context API
Use the JNDI initial context API to set properties programatically.
Example: Setting JNDI properties programatically
Hashtable<Object, Object> env = new Hashtable<>(); env.put("java.naming.factory.initial", "org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory"); InitialContext context = new InitialContext(env);
Note that you can use the same API to set the JNDI properties for connection factories, queues, and topics.
4.2. Configuring the connection factory
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.
The JNDI property format for connection factories
connectionFactory.<lookup-name> = <connection-uri>
For example, this is how you might configure a factory named
Example: Setting the connection factory in a jndi.properties file
connectionFactory.app1 = tcp://example.net:61616?clientID=backend
You can then use the JNDI context to look up your configured connection factory using the name
ConnectionFactory factory = (ConnectionFactory) context.lookup("app1");
4.3. Connection URIs
Connections are configured using a connection URI. The connection URI specifies the remote host, port, and a set of configuration options, which are set as query parameters. For more information about the available options, see Chapter 5, Configuration options.
The connection URI format
For example, the following is a connection URI that connects to host
example.net at port
61616 and sets the client ID to
Example: A connection URI
In addition to
tcp, AMQ Core Protocol JMS also supports the
jgroups schemes. These represent alternate transports and have corresponding acceptor configuration on the broker.
URIs can contain multiple target connection URIs. If the initial connection to one target fails, another is tried. They take the following form:
The failover URI format
Options outside of the parentheses are applied to all of the connection URIs.
4.4. Configuring queue and topic names
JMS provides the option of using JNDI to look up deployment-specific queue and topic resources.
To set queue and topic names in JNDI, create properties in the following format. Either place this configuration in a
jndi.properties file or set corresponding system properties.
The JNDI property format for queues and topics
queue.<lookup-name> = <queue-name> topic.<lookup-name> = <topic-name>
For example, the following properties define the names
notifications for two deployment-specific resources:
Example: Setting queue and topic names in a jndi.properties file
queue.jobs = app1/work-items topic.notifications = app1/updates
You can then look up the resources by their JNDI names:
Queue queue = (Queue) context.lookup("jobs"); Topic topic = (Topic) context.lookup("notifications");