このコンテンツは選択した言語では利用できません。
Chapter 4. Configuration
This chapter details various configuration options for the client, such as how to configure and create a JNDI InitialContext
, the syntax for its related configuration, and the URI options that can be set when defining a ConnectionFactory
.
4.1. Configuring a JNDI InitialContext
JMS applications use a JNDI InitialContext
obtained from an InitialContextFactory
to look up JMS objects such as ConnectionFactory
. The client provides an implementation of the InitialContextFactory
in the org.apache.qpid.jms.jndi.JmsInitialContextFactory
class. You can configure it three different ways.
Configuring an InitialContext using a jndi.properties
file
If you include a file named jndi.properties
on the classpath and set the java.naming.factory.initial
property value to org.apache.qpid.jms.jndi.JmsInitialContextFactory
, the client InitialContextFactory
implementation is discovered when the InitialContext object
is instantiated.
javax.naming.Context ctx = new javax.naming.InitialContext();
The particular ConnectionFactory
, Queue
, and Topic
objects that you want the Context
to contain are configured as properties either directly within the jndi.properties
file or in a separate file whose path is referenced in jndi.properties
using the java.naming.provider.url
property. The syntax for these properties is detailed below.
Configuring an InitialContext using system properties
If you set the java.naming.factory.initial
system property to the value org.apache.qpid.jms.jndi.JmsInitialContextFactory
, the client InitialContextFactory
implementation is discovered when the InitialContext
object is instantiated.
javax.naming.Context ctx = new javax.naming.InitialContext();
The particular ConnectionFactory
, Queue
, and Topic
objects that you want the context to contain are configured as properties in a file, the path to which is passed using the java.naming.provider.url
system property. The syntax for these properties is detailed below.
Configuring an InitialContext programmatically
You can configure the InitialContext
directly by setting an environment variable on a Hashtable
environment object.
Hashtable<Object, Object> env = new Hashtable<Object, Object>(); env.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.qpid.jms.jndi.JmsInitialContextFactory"); javax.naming.Context context = new javax.naming.InitialContext(env);
The particular ConnectionFactory
, Queue
, and Topic
objects that you want the context to contain are configured as properties (the syntax for which is detailed below) either directly within the environment Hashtable
or in a separate file whose path is referenced using the java.naming.provider.url
property within the environment Hashtable
.
JNDI property syntax
The property syntax used in the properties file or environment Hashtable is as follows:
-
To define a
ConnectionFactory
, use formatconnectionfactory.<lookup-name> = <connection-uri>
. -
To define a
Queue
, use formatqueue.<lookup-name> = <queue-name>
. -
To define a
Topic
use formattopic.<lookup-name> = <topic-name>
.
For more details about the connection URI, see the next section.
As an example, consider the following properties that define a ConnectionFactory
, Queue
, and Topic
.
connectionfactory.myFactoryLookup = amqp://localhost:5672 queue.myQueueLookup = queueA topic.myTopicLookup = topicA
These objects could then be looked up from a Context
as follows.
ConnectionFactory factory = (ConnectionFactory) context.lookup("myFactoryLookup"); Queue queue = (Queue) context.lookup("myQueueLookup"); Topic topic = (Topic) context.lookup("myTopicLookup");
Variable expansion
The JNDI property values can contain variables of the form ${<variable-name>}
. The library searches for the value in order in the following locations:
- Java system properties
- OS environment variables
- The JNDI properties file or environment Hashtable
For example, on Linux ${HOME}
resolves to the HOME
environment variable, the current user’s home directory.
A default value can be supplied using the syntax ${<variable-name>:-<default-value>}
. If no value for <variable-name>
is found, the default value is used instead.
4.2. Connection URIs
A ConnectionFactory
is configured using a connection URI.
Connection URI format
amqp[s]://host:port[?option=value[&option2=value...]]
The available connection settings are detailed in the Section 4.3, “Connection URI options” section.
When failover is configured, the client can reconnect to another server automatically if the connection to the current server is lost. Failover URIs start with the prefix failover:
and contain a comma-separated list of server URIs inside parentheses. Additional options are specified at the end.
Failover URI format
failover:(amqp://host1:port[,amqp://host2:port...])[?option=value[&option2=value...]]
As with the connection URI example, the client can be configured with a number of different settings using the URI in a failover configuration. These settings are detailed below, with the Section 4.3.5, “Failover options” section being of particular interest.
When the amqps
scheme is used to specify an SSL/TLS connection, the hostname segment from the URI can be used by the JVM’s TLS SNI (Server Name Indication) extension to communicate the desired server hostname during a TLS handshake. The SNI extension is automatically included if a Fully Qualified Domain Name (for example, "myhost.mydomain") is specified, but not when an unqualified name (for example, "myhost") or a bare IP address is used.
4.3. Connection URI options
4.3.1. JMS options
These options control the behaviour of JMS objects such as Connection
, Session
, MessageConsumer
, and MessageProducer
.
- jms.username
- The user name used to authenticate the connection.
- jms.password
- The password used to authenticate the connection.
- jms.clientID
- The client ID that is applied to the connection.
- jms.forceAsyncSend
-
If enabled, all messages from a
MessageProducer
are sent asynchronously. Otherwise, only certain kinds, such as non-persistent messages or those inside a transaction, are sent asynchronously. It is disabled by default. - jms.forceSyncSend
-
If enabled, all messages from a
MessageProducer
are sent synchronously. It is disabled by default. - jms.forceAsyncAcks
- If enabled, all message acknowledgments are sent asynchronously. It is disabled by default.
- jms.localMessageExpiry
-
If enabled, any expired messages received by a
MessageConsumer
are filtered out and not delivered. It is enabled by default. - jms.localMessagePriority
- If enabled, prefetched messages are reordered locally based on their message priority value. It is disabled by default.
- jms.validatePropertyNames
- If enabled, message property names are required to be valid Java identifiers. It is enabled by default.
- jms.receiveLocalOnly
-
If enabled, calls to
receive
with a timeout argument will check a consumer’s local message buffer only. Otherwise, if the timeout expires, the remote peer is checked to ensure there are really no messages. It is disabled by default. - jms.receiveNoWaitLocalOnly
-
If enabled, calls to
receiveNoWait
will check a consumer’s local message buffer only. Otherwise, the remote peer is checked to ensure there are really no messages available. It is disabled by default. - jms.queuePrefix
-
An optional prefix value added to the name of any
Queue
created from aSession
. - jms.topicPrefix
-
An optional prefix value added to the name of any
Topic
created from aSession
. - jms.closeTimeout
- The time in milliseconds for which the client will wait for normal resource closure before returning. The default is 60000 (60 seconds).
- jms.connectTimeout
- The time in milliseconds for which the client will wait for connection establishment before returning with an error. The default is 15000 (15 seconds).
- jms.sendTimeout
- The time in milliseconds for which the client will wait for completion of a synchronous message send before returning an error. By default the client will wait indefinitely for a send to complete.
- jms.requestTimeout
- The time in milliseconds for which the client will wait for completion of various synchronous interactions like opening a producer or consumer (excluding send) with the remote peer before returning an error. By default the client will wait indefinitely for a request to complete.
- jms.clientIDPrefix
-
An optional prefix value used to generate client ID values when a new
Connection
is created by theConnectionFactory
. The default isID:
. - jms.connectionIDPrefix
-
An optional prefix value used to generate connection ID values when a new
Connection
is created by theConnectionFactory
. This connection ID is used when logging some information from theConnection
object, so a configurable prefix can make breadcrumbing the logs easier. The default isID:
. - jms.populateJMSXUserID
-
If enabled, populate the
JMSXUserID
property for each sent message using the authenticated user name from the connection. It is disabled by default. - jms.awaitClientID
- If enabled, a connection with no client ID configured in the URI will wait for a client ID to be set programmatically, or the connection being used otherwise to signal none can be set, before sending the AMQP connection "open". It is enabled by default.
- jms.useDaemonThread
- If enabled, a connection will use a daemon thread for its executor, rather than a non-daemon thread. It is disabled by default.
- jms.tracing
-
The name of a tracing provider. Supported values are
opentracing
andnoop
. The default isnoop
.
Prefetch policy options
Prefetch policy determines how many messages each MessageConsumer
will fetch from the remote peer and hold in a local "prefetch" buffer.
- jms.prefetchPolicy.queuePrefetch
- The default is 1000.
- jms.prefetchPolicy.topicPrefetch
- The default is 1000.
- jms.prefetchPolicy.queueBrowserPrefetch
- The default is 1000.
- jms.prefetchPolicy.durableTopicPrefetch
- The default is 1000.
- jms.prefetchPolicy.all
- This can be used to set all prefetch values at once.
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.
- jms.redeliveryPolicy.maxRedeliveries
- Controls when an incoming message is rejected based on the number of times it has been redelivered. A value of 0 indicates that no message redeliveries are accepted. A value of 5 allows a message to be redelivered five times, and so on. The default is -1, meaning no limit.
- jms.redeliveryPolicy.outcome
-
Controls the outcome applied to a message once it has exceeded the configured maxRedeliveries value. Supported values are:
ACCEPTED
,REJECTED
,RELEASED
,MODIFIED_FAILED
andMODIFIED_FAILED_UNDELIVERABLE
. The default value isMODIFIED_FAILED_UNDELIVERABLE
.
Message ID policy options
Message ID policy controls the data type of the message ID assigned to messages sent from the client.
- jms.messageIDPolicy.messageIDType
-
By default, a generated
String
value is used for the message ID on outgoing messages. Other available types areUUID
,UUID_STRING
, andPREFIXED_UUID_STRING
.
Presettle policy options
Presettle policy controls when a producer or consumer instance will be configured to use AMQP presettled messaging semantics.
- jms.presettlePolicy.presettleAll
- If enabled, all producers and non-transacted consumers created operate in presettled mode. It is disabled by default.
- jms.presettlePolicy.presettleProducers
- If enabled, all producers operate in presettled mode. It is disabled by default.
- jms.presettlePolicy.presettleTopicProducers
-
If enabled, any producer that is sending to a
Topic
orTemporaryTopic
destination will operate in presettled mode. It is disabled by default. - jms.presettlePolicy.presettleQueueProducers
-
If enabled, any producer that is sending to a
Queue
orTemporaryQueue
destination will operate in presettled mode. It is disabled by default. - jms.presettlePolicy.presettleTransactedProducers
-
If enabled, any producer that is created in a transacted
Session
will operate in presettled mode. It is disabled by default. - jms.presettlePolicy.presettleConsumers
- If enabled, all consumers operate in presettled mode. It is disabled by default.
- jms.presettlePolicy.presettleTopicConsumers
-
If enabled, any consumer that is receiving from a
Topic
orTemporaryTopic
destination will operate in presettled mode. It is disabled by default. - jms.presettlePolicy.presettleQueueConsumers
-
If enabled, any consumer that is receiving from a
Queue
orTemporaryQueue
destination will operate in presettled mode. It is disabled by default.
Deserialization policy options
Deserialization policy provides a means of controlling which Java types are trusted to be deserialized from the object stream while retrieving the body from an incoming ObjectMessage
composed of serialized Java Object
content. By default all types are trusted during an attempt to deserialize the body. The default deserialization policy provides URI options that allow specifying a whitelist and a blacklist of Java class or package names.
- jms.deserializationPolicy.whiteList
-
A comma-separated list of class and package names that should be allowed when deserializing the contents of an
ObjectMessage
, unless overridden byblackList
. The names in this list are not pattern values. The exact class or package name must be configured, as injava.util.Map
orjava.util
. Package matches include sub-packages. The default is to allow all. - jms.deserializationPolicy.blackList
-
A comma-separated list of class and package names that should be rejected when deserializing the contents of a
ObjectMessage
. The names in this list are not pattern values. The exact class or package name must be configured, as injava.util.Map
orjava.util
. Package matches include sub-packages. The default is to prevent none.
4.3.2. TCP transport options
When connected to a remote server using plain TCP, the following options specify the behavior of the underlying socket. These options are appended to the connection URI along with any other configuration options.
Example: A connection URI with transport options
amqp://localhost:5672?jms.clientID=foo&transport.connectTimeout=30000
The complete set of TCP transport options is listed below.
- transport.sendBufferSize
- The send buffer size in bytes. The default is 65536 (64 KB).
- transport.receiveBufferSize
- The receive buffer size in bytes. The default is 65536 (64 KB).
- transport.trafficClass
- The default is 0.
- transport.connectTimeout
- The default is 60 seconds.
- transport.soTimeout
- The default is -1.
- transport.soLinger
- The default is -1.
- transport.tcpKeepAlive
- The default is false.
- transport.tcpNoDelay
- The default is true.
- transport.useEpoll
- When available, use the native epoll IO layer instead of the NIO layer. This can improve performance. It is enabled by default.
4.3.3. SSL/TLS transport options
The SSL/TLS transport is enabled by using the amqps
URI scheme. Because the SSL/TLS transport extends the functionality of the TCP-based transport, all of the TCP transport options are valid on an SSL/TLS transport URI.
Example: A simple SSL/TLS connection URI
amqps://myhost.mydomain:5671
The complete set of SSL/TLS transport options is listed below.
- transport.keyStoreLocation
-
If unset, the value of the
javax.net.ssl.keyStore
system property is used. - transport.keyStorePassword
-
If unset, the value of the
javax.net.ssl.keyStorePassword
system property is used. - transport.trustStoreLocation
-
If unset, the value of the
javax.net.ssl.trustStore
system property is used. - transport.trustStorePassword
-
If unset, the value of the
javax.net.ssl.trustStorePassword
system property is used. - transport.keyStoreType
-
If unset, the value of the
javax.net.ssl.keyStoreType
system property is used. If the system property is unset, the default isJKS
. - transport.trustStoreType
-
If unset, the value of the
javax.net.ssl.trustStoreType
system property is used. If the system property is unset, the default isJKS
. - transport.storeType
-
Sets both
keyStoreType
andtrustStoreType
to the same value. If unset,keyStoreType
andtrustStoreType
default to the values specified above. - transport.contextProtocol
-
The protocol argument used when getting an SSLContext. The default is
TLS
, orTLSv1.2
if using OpenSSL. - transport.enabledCipherSuites
- A comma-separated list of cipher suites to enable. If unset, the context-default ciphers are used. Any disabled ciphers are removed from this list.
- transport.disabledCipherSuites
- A comma-separated list of cipher suites to disable. Ciphers listed here are removed from the enabled ciphers.
- transport.enabledProtocols
- A comma-separated list of protocols to enable. If unset, the context-default protocols are used. Any disabled protocols are removed from this list.
- transport.disabledProtocols
-
A comma-separated list of protocols to disable. Protocols listed here are removed from the enabled protocol list. The default is
SSLv2Hello,SSLv3
. - transport.trustAll
- If enabled, trust the provided server certificate implicitly, regardless of any configured trust store. It is disabled by default.
- transport.verifyHost
- If enabled, verify that the connection hostname matches the provided server certificate. It is enabled by default.
- transport.keyAlias
- The alias to use when selecting a key pair from the key store if required to send a client certificate to the server.
- transport.useOpenSSL
If enabled, use native OpenSSL libraries for SSL/TLS connections if available. It is disabled by default.
For more information, see Section 4.4.2, “Enabling OpenSSL support”.
4.3.4. AMQP options
The following options apply to aspects of behavior related to the AMQP wire protocol.
- amqp.idleTimeout
- The time in milliseconds after which the connection will be failed if the peer sends no AMQP frames. The default is 60000 (1 minute).
- amqp.vhost
- The virtual host to connect to. This is used to populate the SASL and AMQP hostname fields. The default is the main hostname from the connection URI.
- amqp.saslLayer
- If enabled, SASL is used when establishing connections. It is enabled by default.
- amqp.saslMechanisms
- A comma-separated list of SASL mechanisms the client should allow selection of, if offered by the server and usable with the configured credentials. The supported mechanisms are EXTERNAL, SCRAM-SHA-256, SCRAM-SHA-1, CRAM-MD5, PLAIN, ANONYMOUS, and GSSAPI for Kerberos. The default is to allow selection from all mechanisms except GSSAPI, which must be explicitly included here to enable.
- amqp.maxFrameSize
- The maximum AMQP frame size in bytes allowed by the client. This value will be advertised to the remote peer. The default is 1048576 (1 MiB).
- amqp.drainTimeout
- The time in milliseconds that the client will wait for a response from the remote peer when a consumer drain request is made. If no response is seen in the allotted timeout period, the link will be considered failed and the associated consumer will be closed. The default is 60000 (1 minute).
- amqp.allowNonSecureRedirects
- If enabled, allow AMQP redirects to alternative hosts when the existing connection is secure and the alternative connection is not. For example, if enabled this would permit redirecting an SSL/TLS connection to a raw TCP connection. It is disabled by default.
4.3.5. Failover options
Failover URIs start with the prefix failover:
and contain a comma-separated list of server URIs inside parentheses. Additional options are specified at the end. Options prefixed with jms.
are applied to the overall failover URI, outside of parentheses, and affect the Connection
object for its lifetime.
Example: A failover URI with failover options
failover:(amqp://host1:5672,amqp://host2:5672)?jms.clientID=foo&failover.maxReconnectAttempts=20
The individual broker details within the parentheses can use the transport.
or amqp.
options defined earlier. These are applied as each host is connected to.
Example: A failover URI with per-connection transport and AMQP options
failover:(amqp://host1:5672?amqp.option=value,amqp://host2:5672?transport.option=value)?jms.clientID=foo
All of the configuration options for failover are listed below.
- failover.initialReconnectDelay
- The time in milliseconds the client will wait before the first attempt to reconnect to a remote peer. The default is 0, meaning the first attempt happens immediately.
- failover.reconnectDelay
- The time in milliseconds between reconnection attempts. If the backoff option is not enabled, this value remains constant. The default is 10.
- failover.maxReconnectDelay
- The maximum time that the client will wait before attempting to reconnect. This value is only used when the backoff feature is enabled to ensure that the delay does not grow too large. The default is 30 seconds.
- failover.useReconnectBackOff
- If enabled, the time between reconnection attempts grows based on a configured multiplier. It is enabled by default.
- failover.reconnectBackOffMultiplier
- The multiplier used to grow the reconnection delay value. The default is 2.0.
- failover.maxReconnectAttempts
- The number of reconnection attempts allowed before reporting the connection as failed to the client. The default is -1, meaning no limit.
- failover.startupMaxReconnectAttempts
-
For a client that has never connected to a remote peer before, this option controls how many attempts are made to connect before reporting the connection as failed. If unset, the value of
maxReconnectAttempts
is used. - failover.warnAfterReconnectAttempts
- The number of failed reconnection attempts until a warning is logged. The default is 10.
- failover.randomize
- If enabled, the set of failover URIs is randomly shuffled before attempting to connect to one of them. This can help to distribute client connections more evenly across multiple remote peers. It is disabled by default.
- failover.amqpOpenServerListAction
-
Controls how the failover transport behaves when the connection "open" frame from the server provides a list of failover hosts to the client. Valid values are
REPLACE
,ADD
, orIGNORE
. IfREPLACE
is configured, all failover URIs other than the one for the current server are replaced with those provided by the server. IfADD
is configured, the URIs provided by the server are added to the existing set of failover URIs, with deduplication. IfIGNORE
is configured, any updates from the server are ignored and no changes are made to the set of failover URIs in use. The default isREPLACE
.
The failover URI also supports defining nested options as a means of specifying AMQP and transport option values applicable to all the individual nested broker URIs. This is accomplished using the same transport.
and amqp.
URI options outlined earlier for a non-failover broker URI but prefixed with failover.nested.
. For example, to apply the same value for the amqp.vhost
option to every broker connected to you might have a URI like the following:
Example: A failover URI with shared transport and AMQP options
failover:(amqp://host1:5672,amqp://host2:5672)?jms.clientID=foo&failover.nested.amqp.vhost=myhost
4.3.6. Discovery options
The client has an optional discovery module that provides a customized failover layer where the broker URIs to connect to are not given in the initial URI but instead are discovered by interacting with a discovery agent. There are currently two discovery agent implementations: a file watcher that loads URIs from a file and a multicast listener that works with ActiveMQ 5.x brokers that are configured to broadcast their broker addresses for listening clients.
The general set of failover-related options when using discovery are the same as those detailed earlier, with the main prefix changed from failover.
to discovery.
, and with the nested
prefix used to supply URI options common to all the discovered broker URIs. For example, without the agent URI details, a general discovery URI might look like the following:
Example: A discovery URI
discovery:(<agent-uri>)?discovery.maxReconnectAttempts=20&discovery.discovered.jms.clientID=foo
To use the file watcher discovery agent, create an agent URI like the following:
Example: A discovery URI using the file watcher agent
discovery:(file:///path/to/monitored-file?updateInterval=60000)
The URI options for the file watcher discovery agent are listed below.
- updateInterval
- The time in milliseconds between checks for file changes. The default is 30000 (30 seconds).
To use the multicast discovery agent with an ActiveMQ 5.x broker, create an agent URI like the following:
Example: A discovery URI using the multicast listener agent
discovery:(multicast://default?group=default)
Note that the use of default
as the host in the multicast agent URI above is a special value that is substituted by the agent with the default 239.255.2.3:6155
. You can change this to specify the actual IP address and port in use with your multicast configuration.
The URI option for the multicast discovery agent is listed below.
- group
-
The multicast group used to listen for updates. The default is
default
.
4.4. Security
AMQ JMS has a range of security-related configuration options that can be leveraged according to your application’s needs.
Basic user credentials such as username and password should be passed directly to the ConnectionFactory
when creating the Connection
within the application. However, if you are using the no-argument factory method, it is also possible to supply user credentials in the connection URI. For more information, see the Section 4.3.1, “JMS options” section.
Another common security consideration is use of SSL/TLS. The client connects to servers over an SSL/TLS transport when the amqps
URI scheme is specified in the connection URI, with various options available to configure behavior. For more information, see the Section 4.3.3, “SSL/TLS transport options” section.
In concert with the earlier items, it may be desirable to restrict the client to allow use of only particular SASL mechanisms from those that may be offered by a server, rather than selecting from all it supports. For more information, see the Section 4.3.4, “AMQP options” section.
Applications calling getObject()
on a received ObjectMessage
may wish to restrict the types created during deserialization. Note that message bodies composed using the AMQP type system do not use the ObjectInputStream
mechanism and therefore do not require this precaution. For more information, see the the section called “Deserialization policy options” section.
4.4.1. Authenticating using Kerberos
The client can be configured to authenticate using Kerberos when used with an appropriately configured server. To enable Kerberos, use the following steps.
Configure the client to use the
GSSAPI
mechanism for SASL authentication using theamqp.saslMechanisms
URI option.amqp://myhost:5672?amqp.saslMechanisms=GSSAPI failover:(amqp://myhost:5672?amqp.saslMechanisms=GSSAPI)
Set the
java.security.auth.login.config
system property to the path of a JAAS login configuration file containing appropriate configuration for a KerberosLoginModule
.-Djava.security.auth.login.config=<login-config-file>
The login configuration file might look like the following example:
amqp-jms-client { com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true; };
The precise configuration used will depend on how you wish the credentials to be established for the connection, and the particular LoginModule
in use. For details of the Oracle Krb5LoginModule
, see the Oracle Krb5LoginModule
class reference. For details of the IBM Java 8 Krb5LoginModule
, see the IBM Krb5LoginModule
class reference.
It is possible to configure a LoginModule
to establish the credentials to use for the Kerberos process, such as specifying a principal and whether to use an existing ticket cache or keytab. If, however, the LoginModule
configuration does not provide the means to establish all necessary credentials, it may then request and be passed the username and password values from the client Connection
object if they were either supplied when creating the Connection
using the ConnectionFactory
or previously configured via its URI options.
Note that Kerberos is supported only for authentication purposes. Use SSL/TLS connections for encryption.
The following connection URI options can be used to influence the Kerberos authentication process.
- sasl.options.configScope
-
The name of the login configuration entry used to authenticate. The default is
amqp-jms-client
. - sasl.options.protocol
-
The protocol value used during the GSSAPI SASL process. The default is
amqp
. - sasl.options.serverName
-
The
serverName
value used during the GSSAPI SASL process. The default is the server hostname from the connection URI.
Similar to the amqp.
and transport.
options detailed previously, these options must be specified on a per-host basis or as all-host nested options in a failover URI.
4.4.2. Enabling OpenSSL support
SSL/TLS connections can be configured to use a native OpenSSL implementation for improved performance. To use OpenSSL, the transport.useOpenSSL
option must be enabled, and an OpenSSL support library must be available on the classpath.
To use the system-installed OpenSSL libraries on Red Hat Enterprise Linux, install the openssl
and apr
RPM packages and add the following dependency to your POM file:
Example: Adding native OpenSSL support
<dependency> <groupId>io.netty</groupId> <artifactId>netty-tcnative</artifactId> <version>2.0.25.Final-redhat-00001</version> </dependency>
A list of OpenSSL library implementations is available from the Netty project.
4.5. Logging
The client uses the SLF4J API, enabling users to select a particular logging implementation based on their needs. For example, users can provide the slf4j-log4j binding to select the Log4J implementation. More details on SLF4J are available from its website.
The client uses Logger
names residing within the org.apache.qpid.jms
hierarchy, which you can use to configure a logging implementation based on your needs.
When debugging, it is sometimes useful to enable additional protocol trace logging from the Qpid Proton AMQP 1.0 library. There are two ways to achieve this.
-
Set the environment variable (not the Java system property)
PN_TRACE_FRM
to1
. This will cause Proton to emit frame logging to the console. -
Add the option
amqp.traceFrames=true
to your connection URI and configure theorg.apache.qpid.jms.provider.amqp.FRAMES
logger to log levelTRACE
. This will add a protocol tracer to Proton and include the output in your logs.
You can also configure the client to emit low-level tracing of input and output bytes. To enable this, add the option transport.traceBytes=true
to your connection URI and configure the org.apache.qpid.jms.transports.netty.NettyTcpTransport
logger to log level DEBUG
.
4.6. Tracing
The client offers distributed tracing based on the Jaeger implementation of the OpenTracing standard. Use the following steps to enable tracing in your application:
Add the Jaeger client dependency to your POM file.
<dependency> <groupId>io.jaegertracing</groupId> <artifactId>jaeger-client</artifactId> <version>${jaeger-version}</version> </dependency>
${jaeger-version}
must be 1.0.0 or later.Add the
jms.tracing
option to your connection URI. Set the value toopentracing
.Example: A connection URI with tracing enabled
amqps://example.net?jms.tracing=opentracing
Configure and register the global tracer.
Example: Global tracer configuration
import io.jaegertracing.Configuration; import io.opentracing.Tracer; import io.opentracing.util.GlobalTracer; public class Example { public static void main(String[] args) { System.setProperty("JAEGER_SERVICE_NAME", "<service-name>"); System.setProperty("JAEGER_SAMPLER_TYPE", "const"); System.setProperty("JAEGER_SAMPLER_PARAM", "1"); Tracer tracer = Configuration.fromEnv().getTracer(); GlobalTracer.registerIfAbsent(tracer); [...] } }
The configuration shown here is for demonstration purposes. For more information about Jaeger configuration, see Configuration via Environment and Jaeger Sampling.
To view the traces your application captures, use the Jaeger Getting Started to run the Jaeger infrastructure and console.
4.7. Extended session acknowledgment modes
The client supports two additional session acknowledgement modes beyond those defined in the JMS specification.
Individual acknowledge
In this mode, messages must be acknowledged individually by the application using the Message.acknowledge()
method used when the session is in CLIENT_ACKNOWLEDGE
mode. Unlike with CLIENT_ACKNOWLEDGE
mode, only the target message is acknowledged. All other delivered messages remain unacknowledged. The integer value used to activate this mode is 101.
connection.createSession(false, 101);
No acknowledge
In this mode, messages are accepted at the server before being dispatched to the client, and no acknowledgment is performed by the client. The client supports two integer values to activate this mode, 100 and 257.
connection.createSession(false, 100);