docs/configuration.md - activemq-nms-amqp - Git at Google

 # Client configuration
 This file details various configuration options for the client, the syntax for its related configuration, and various uri options that can be set when defining a ConnectionFactory.

 ## Connection Uri
 The basic format of the clients Connection URI is as follows:

 ```
 amqp[s]://hostname:port[?option=value[&option2=value...]]
 ```

 Where the amqps and scheme is specified to use SSL/TLS.

 The client can be configured with a number of different settings using the uri while defining the ConnectionFactory, these are detailed in the following sections.

 ### NMS Configuration options
 The options apply to the behavior of the NMS objects such as Connection, Session, MessageConsumer and MessageProducer.

 - **nms.username** User name value used to authenticate the connection.
 - **nms.password** The password value used to authenticate the connection.
 - **nms.clientId** The ClientId value that is applied to the connection.
 - **nms.localMessageExpiry** Controls whether MessageConsumer instances will locally filter expired Messages or deliver them. By default this value is set to true and expired messages will be filtered.
 - **nms.sendTimeout** Timeout value that controls how long the client waits on completion of a synchronous message send before returning an error. By default the client will wait indefinitely for a send to complete.
 - **nms.requestTimeout** Timeout value that controls how long the client waits on completion of various synchronous interactions, such as opening a producer or consumer, before returning an error. Does not affect synchronous message sends. By default the client will wait indefinitely for a request to complete.
 - **nms.clientIdPrefix** Optional prefix value that is used for generated Client ID values when a new Connection is created for the JMS ConnectionFactory. The default prefix is 'ID:'.
 - **nms.connectionIdPrefix** Optional prefix value that is used for generated Connection ID values when a new Connection is created for the JMS ConnectionFactory. This connection ID is used when logging some information from the JMS Connection object so a configurable prefix can make breadcrumbing the logs easier. The default prefix is 'ID:'.
 - **nms.maxNewConnectionRatePerSec** Allowed approximated rate for how fast connection factory is allowed to create new connection. If there is more request, they will have to wait. Default value is -1 which means unlimited.
 - **nms.prefetchPolicy.all** Link credit value that will be assigned to new consumers from each category. It is pretty much the number of messages consumer can read without acknowledging. The default value is 1000.
 - **nms.prefetchPolicy.queuePrefetch** Link credit value that will be assigned to new consumers of queue. The default value is 1000.
 - **nms.prefetchPolicy.topicPrefetch** Link credit value that will be assigned to new consumers of topic. The default value is 1000.
 - **nms.prefetchPolicy.queueBrowserPrefetch** Link credit value that will be assigned to new queue browser. The default value is 1000..
 - **nms.prefetchPolicy.durableTopicPrefetch** Link credit value that will be assigned to new consumers of durable topic. The default value is 1000..

 ### AMQP Configuration options

 - **amqp.vhost** Optional, the name of the virtual host to which we are connecting. By default this value is derived from the URI. Can be used to determine the correct service if connecting to an AMQP proxy.

 ### TCP Transport Configuration options
 When connected to a remote using plain TCP these options configure the behaviour of the underlying socket. These options are appended to the connection URI along with the other configuration options, for example:

 ```
 amqp://localhost:5672?nms.clientId=foo&transport.receiveBufferSize=30000
 ```

 The complete set of TCP Transport options is listed below:

 - **transport.sendBufferSize** Specifies the ReceiveBufferSize option of the TCP socket.
 - **transport.receiveBufferSize** Specifies the SendBufferSize option of the TCP socket.
 - **transport.receiveTimeout** Specifies the ReceiveTimeout option of the TCP socket.
 - **transport.sendTimeout** Specifies the SendTimeout option of the TCP socket.
 - **transport.tcpKeepAliveTime** Specifies how often a keep-alive transmission is sent to an idle connection.
 - **transport.tcpKeepAliveInterval** Specifies how often a keep-alive transmission is sent when no response is received from previous keep-alive transmissions.
 - **transport.tcpNoDelay** Specifies the NoDelay option of the TCP socket.

 If *tcpKeepAliveTime* or *tcpKeepAliveInterval* it set, TCP Keep-Alive is enabled.

 ### Failover Configuration options
 With failover enabled the client can reconnect to another server automatically when connection to the current server is lost for some reason. The failover URI is always initiated with the failover prefix and a list of URIs for the server(s) is contained inside a set of parentheses. The "nms." options are applied to the overall failover URI, outside the parentheses, and affect the NMS Connection object for its lifetime.

 The URI for failover looks something like the following:

 ```
 failover:(amqp://host1:5672,amqp://host2:5672)?nms.clientId=foo&failover.maxReconnectAttempts=20
 ```

 The individual broker details within the parentheses can use the "transport." or "amqp." options defined earlier, with these being applied as each host is connected to:

 ```
 failover:(amqp://host1:5672?amqp.option=value,amqp://host2:5672?transport.option=value)?nms.clientId=foo
 ```

 The complete set of configuration options for failover is listed below:

 - **failover.initialReconnectDelay** The amount of time the client will wait before the first attempt to reconnect to a remote peer. The default value is zero, meaning the first attempt happens immediately.
 - **failover.reconnectDelay** Controls the delay between successive reconnection attempts, defaults to 10 milliseconds. If the backoff option is not enabled this value remains constant.
 - **failover.maxReconnectDelay** The maximum time that the client will wait before attempting a reconnect. This value is only used when the backoff feature is enabled to ensure that the delay doesn't not grow too large. Defaults to 30 seconds as the max time between connect attempts.
 - **failover.useReconnectBackOff** Controls whether the time between reconnection attempts should grow based on a configured multiplier. This option defaults to true.
 - **failover.reconnectBackOffMultiplier** The multiplier used to grow the reconnection delay value, defaults to 2.0d.
 - **failover.reconnectDelayRandomFactor** Reconnect backoff random factor. 0 means no randomisation. 0.5 would mean backoff time could be (pseudo)randomly between 0.5 and 1.5 of normal reconnect backoff time. 1 would mean backoff time could be between 0 and 2x normal reconnect backoff. 2 would mean backoff time between 0 and 3x normal backoff, and so on. Default value is 0.
 - **failover.maxReconnectAttempts** The number of reconnection attempts allowed before reporting the connection as failed to the client. The default is no limit or (-1).
 - **failover.startupMaxReconnectAttempts** For a client that has never connected to a remote peer before this option control how many attempts are made to connect before reporting the connection as failed. The default is to use the value of maxReconnectAttempts.
	# Client configuration
	This file details various configuration options for the client, the syntax for its related configuration, and various uri options that can be set when defining a ConnectionFactory.

	## Connection Uri
	The basic format of the clients Connection URI is as follows:

	```
	amqp[s]://hostname:port[?option=value[&option2=value...]]
	```

	Where the amqps and scheme is specified to use SSL/TLS.

	The client can be configured with a number of different settings using the uri while defining the ConnectionFactory, these are detailed in the following sections.

	### NMS Configuration options
	The options apply to the behavior of the NMS objects such as Connection, Session, MessageConsumer and MessageProducer.

	- nms.username User name value used to authenticate the connection.
	- nms.password The password value used to authenticate the connection.
	- nms.clientId The ClientId value that is applied to the connection.
	- nms.localMessageExpiry Controls whether MessageConsumer instances will locally filter expired Messages or deliver them. By default this value is set to true and expired messages will be filtered.
	- nms.sendTimeout Timeout value that controls how long the client waits on completion of a synchronous message send before returning an error. By default the client will wait indefinitely for a send to complete.
	- nms.requestTimeout Timeout value that controls how long the client waits on completion of various synchronous interactions, such as opening a producer or consumer, before returning an error. Does not affect synchronous message sends. By default the client will wait indefinitely for a request to complete.
	- nms.clientIdPrefix Optional prefix value that is used for generated Client ID values when a new Connection is created for the JMS ConnectionFactory. The default prefix is 'ID:'.
	- nms.connectionIdPrefix Optional prefix value that is used for generated Connection ID values when a new Connection is created for the JMS ConnectionFactory. This connection ID is used when logging some information from the JMS Connection object so a configurable prefix can make breadcrumbing the logs easier. The default prefix is 'ID:'.
	- nms.maxNewConnectionRatePerSec Allowed approximated rate for how fast connection factory is allowed to create new connection. If there is more request, they will have to wait. Default value is -1 which means unlimited.
	- nms.prefetchPolicy.all Link credit value that will be assigned to new consumers from each category. It is pretty much the number of messages consumer can read without acknowledging. The default value is 1000.
	- nms.prefetchPolicy.queuePrefetch Link credit value that will be assigned to new consumers of queue. The default value is 1000.
	- nms.prefetchPolicy.topicPrefetch Link credit value that will be assigned to new consumers of topic. The default value is 1000.
	- nms.prefetchPolicy.queueBrowserPrefetch Link credit value that will be assigned to new queue browser. The default value is 1000..
	- nms.prefetchPolicy.durableTopicPrefetch Link credit value that will be assigned to new consumers of durable topic. The default value is 1000..

	### AMQP Configuration options

	- amqp.vhost Optional, the name of the virtual host to which we are connecting. By default this value is derived from the URI. Can be used to determine the correct service if connecting to an AMQP proxy.

	### TCP Transport Configuration options
	When connected to a remote using plain TCP these options configure the behaviour of the underlying socket. These options are appended to the connection URI along with the other configuration options, for example:

	```
	amqp://localhost:5672?nms.clientId=foo&transport.receiveBufferSize=30000
	```

	The complete set of TCP Transport options is listed below:

	- transport.sendBufferSize Specifies the ReceiveBufferSize option of the TCP socket.
	- transport.receiveBufferSize Specifies the SendBufferSize option of the TCP socket.
	- transport.receiveTimeout Specifies the ReceiveTimeout option of the TCP socket.
	- transport.sendTimeout Specifies the SendTimeout option of the TCP socket.
	- transport.tcpKeepAliveTime Specifies how often a keep-alive transmission is sent to an idle connection.
	- transport.tcpKeepAliveInterval Specifies how often a keep-alive transmission is sent when no response is received from previous keep-alive transmissions.
	- transport.tcpNoDelay Specifies the NoDelay option of the TCP socket.

	If tcpKeepAliveTime or tcpKeepAliveInterval it set, TCP Keep-Alive is enabled.

	### Failover Configuration options
	With failover enabled the client can reconnect to another server automatically when connection to the current server is lost for some reason. The failover URI is always initiated with the failover prefix and a list of URIs for the server(s) is contained inside a set of parentheses. The "nms." options are applied to the overall failover URI, outside the parentheses, and affect the NMS Connection object for its lifetime.

	The URI for failover looks something like the following:

	```
	failover:(amqp://host1:5672,amqp://host2:5672)?nms.clientId=foo&failover.maxReconnectAttempts=20
	```

	The individual broker details within the parentheses can use the "transport." or "amqp." options defined earlier, with these being applied as each host is connected to:

	```
	failover:(amqp://host1:5672?amqp.option=value,amqp://host2:5672?transport.option=value)?nms.clientId=foo
	```

	The complete set of configuration options for failover is listed below:

	- failover.initialReconnectDelay The amount of time the client will wait before the first attempt to reconnect to a remote peer. The default value is zero, meaning the first attempt happens immediately.
	- failover.reconnectDelay Controls the delay between successive reconnection attempts, defaults to 10 milliseconds. If the backoff option is not enabled this value remains constant.
	- failover.maxReconnectDelay The maximum time that the client will wait before attempting a reconnect. This value is only used when the backoff feature is enabled to ensure that the delay doesn't not grow too large. Defaults to 30 seconds as the max time between connect attempts.
	- failover.useReconnectBackOff Controls whether the time between reconnection attempts should grow based on a configured multiplier. This option defaults to true.
	- failover.reconnectBackOffMultiplier The multiplier used to grow the reconnection delay value, defaults to 2.0d.
	- failover.reconnectDelayRandomFactor Reconnect backoff random factor. 0 means no randomisation. 0.5 would mean backoff time could be (pseudo)randomly between 0.5 and 1.5 of normal reconnect backoff time. 1 would mean backoff time could be between 0 and 2x normal reconnect backoff. 2 would mean backoff time between 0 and 3x normal backoff, and so on. Default value is 0.
	- failover.maxReconnectAttempts The number of reconnection attempts allowed before reporting the connection as failed to the client. The default is no limit or (-1).
	- failover.startupMaxReconnectAttempts For a client that has never connected to a remote peer before this option control how many attempts are made to connect before reporting the connection as failed. The default is to use the value of maxReconnectAttempts.