Managing Sessions
A Session is a single‑threaded context through which a JMS client application can create producers and consumers. JMS applications can create one or more Session per connection. The Solace JMS API supports transacted and non‑transacted Sessions
For information on working with XA Sessions, see Using XA Transactions.
Creating Sessions
To create a Session, call connection.createSession(boolean transacted, int acknowledgeMode)
Where:
transacted indicates whether the Session is to be transacted. A local transacted Session can group a set of message sends and a set of message receives into an atomic unit of work. By default, this value is set to false, and the Session is not transacted. (For more information on transacted Sessions, see Using Transacted Sessions.)
acknowledgeMode is the message acknowledgment mode to use. For more information, see Acknowledgment Modes below.
For a transacted Session, the acknowledgment mode is ignored because messages in a transaction are only acknowledged when commit() is called for the transaction.
Acknowledgment Modes
For a non-transacted Session, four acknowledgment options are supported:
Session.AUTO_ACKNOWLEDGEThe Session automatically acknowledges a client’s receipt of a message either when the Session successfully returns from a call to receive or when the message listener the Session calls to process the message successfully returns.
Session.DUPS_OK_ACKNOWLEDGEThe Session may lazily acknowledge the delivery of each message by acknowledging them collectively as a windowed group. This acknowledgment option can reduce the amount of work the Session must perform to ensure that no duplicate messages are delivered, but in the event of a system failure, it can also result in the delivery of duplicate messages.
Session.CLIENT_ACKNOWLEDGEThe client explicitly calls the
acknowledge()method to acknowledge a consumed message. This automatically acknowledges the receipt of all messages that have been delivered by the Session.A single Session can hold multiple JMS consumers. Therefore, when
CLIENT_ACKNOWLEDGEis used, it is possible for one consumer to acknowledge another consumer’s messages. This could occur if the two consumers do not take the same amount of time to process their messages. In this case, the acknowledgments might not be returned in the order in which they were received.com.solacesystems.jms.SupportedProperty.SOL_CLIENT_ACKNOWLEDGEThis is a Solace-defined message acknowledgment mode. When there are multiple consumers on a single Session, this option allows each consumer to only acknowledge messages that it receives—a consumer cannot acknowledge messages that another consumer receives. When this mode is used, each call to
Message.acknowledge()only acknowledges the message received by the consumer.A Session and its message producers and consumers can only be accessed by one thread at a time. Their behavior is undefined if multiple threads access them simultaneously.
Configuring Connection Time-Outs and Retries
The following properties are used to configure a client’s JNDI and JMS connect and reconnect behavior.
When using high-availability (HA) redundant event broker pairs, a failover from one event broker to its mate will typically occur in under 30 seconds, however, applications should attempt to reconnect for at least five minutes. To allow for a reconnect duration of five minutes for HA redundant event brokers, set the following Session property values:
- connect retries—1
- reconnect retries—20
- reconnect retry wait—3000 ms
- connect retries per host—5
Connect Retries
The connect retries property specifies the maximum number of times to attempt to establish a connection after the first connect fails.
The valid range is an integer greater than or equal to –1. A value of –1 specifies an unlimited number of connect retires is allowed; a value of 0 specifies no automatic connection retries (that is, try once and give up).
If a host list is used, each connect retry will traverse the host list according to the value set for the Connect Retries property. For example, if a connect retry value of 2 is used, the API may successively attempt to establish a JNDI connection to each entry in the host list. If it is not successful, the second connect retry will begin again with the first host entry and successively attempt each host entry. If there is no success, no further connect retries are attempted. The number of times a connection attempt may be made for each entry as it traverses that list is determined by the connection retries per host property (see Connection Retries Per Host).
The connect retries value can be set through the Connect Retries property for the JNDI connection. For more information, see JNDI Connection Properties.
Connect Time-Out
The connect time-out property specifies the maximum amount of time (in milliseconds) that is allowed for establishing an initial connection.
When a host list is used, the amount of time set for the Connection Time-Out property is applied to each connection attempt to a host. For example, if there are four host entries, it is possible that an application would have to wait for the connection time-out to occur for each host entry—multiplied by the number of connect attempts—before receiving a notice of an established connection or a connection failure. This wait time is also extended by the Reconnect Retry Wait time that occurs after each unsuccessful attempt to connect to a host.
A connection attempt can terminate more quickly if a failure is detected by the socket layer.
The connection time-out value can be set through the Connect Timeout property for the JNDI or data connection. For more information, see JMS Properties Reference.
Reconnect Retries
The reconnect retries property specifies the number of times to try to reconnect to a host after a disconnect. If a host list is used, this property sets the number of times the API will traverse the host list in an attempt to reconnect to one of the hosts in the list.
The valid range is an integer greater than or equal to –1. A value of –1 specifies an unlimited number of reconnect retires is allowed; a value of 0 specifies no automatic reconnect retries (that is, try once and give up).
When a host list is used, if the API cannot connect to the first event broker on the list (that is, the preferred event broker), the API attempts to connect to the next listed event broker, and so on. The API attempts to connect to each host for the number of times set for the Connect Retries Per Host property before attempting to connect to the next host.
After each unsuccessful connection attempt, the API waits for the amount of time set by the Reconnect Retry Wait property before attempting to connect to the same host, the next listed host, or, after all of the listed hosts have been attempted, to the first host on the list again.
Multiple reconnects should be specified when using a host for which event broker redundancy has been enabled (that is, the IP address listed as a host is used by a pair of redundant event brokers). Disabling reconnect retries could affect activity switches that might occur when active/active redundancy is used and could cause service disruptions. For example, in a fail‑over scenario, if no reconnect retries are enabled, a connection attempt cannot be made to the redundant event broker.
An automatic reconnect frequency limit is used to prevent a client from reconnecting more than four times within ten seconds. If the replacement of duplicate client connections during authentication is permitted by the event broker, when multiple clients with the same client user name are used, they could enter a cycle where one client connects, and then is disconnected when another client connects. If these clients have a non-zero Reconnect Retries value, each time one disconnected client successfully reconnects, it disconnects another connected client. The automatic reconnect frequency limit ensures that this client connect/reconnect cycle does not occur indefinitely.
For information on how to enable the replacement of duplicate client connections during authentication, see Configuring the Connection Behavior for Duplicate Clients .
The reconnect retries value can be set through the Reconnect Retries property for the JNDI or data connection. For more information, see JMS Properties Reference.
Reconnect Retry Wait
The reconnect retry wait property sets the amount of time (in milliseconds) to wait after an unsuccessful attempt to reconnect to the same host that the client was connected to. After this time expires, another reconnect attempt can be made. Valid values are 1 or greater.
If the API works through all of the entries in the host list without establishing a connection, and a Connect Retry is permitted because the Connect Retry property is greater than 0, the API waits for the amount of time set for the Reconnect Retry Wait property before retrying to connect to the first host in the host list.
The reconnect retry wait value can be set through the Reconnect Retry Wait property for the JNDI or data connection. For more information, see JMS Properties Reference.
Connection Retries Per Host
When using a host list, the connection retries per host property sets how many times to try to connect or reconnect to one host before moving to the next host in the list. When traversing the list, each entry is attempted for the number of times set for the connection retries per host property + 1.
A value of 0 means do not attempt a single connection or reconnection attempt. A value of –1 means attempt an infinite number of connect or reconnect retries (in this case, the API only tries to connect or reconnect to the first host listed).
If a connect or reconnect attempt to a host is not successful, the API must wait for the amount of time set for the Reconnect Retry Wait property before making another connect or reconnect attempt.
If a client application gets disconnected, the API will attempt to reconnect to the event broker it was connected to, and if that fails it will attempt to reconnect to the next listed host, and so on. If the application had published Guaranteed messages prior to being reconnected to a new host, the new host will not have the required Guaranteed messaging publisher state to agree with the API on which messages were last received/acknowledged. Therefore, the API will reset the publisher flow state, renumber and resend any unacknowledged messages. Note that if the new host was configured as a Replication mate of the original host, resending messages may create duplicates because the original messages may have been successfully delivered to the mate even though from the API’s perspective they were unacknowledged. In this case, it is up to the receiving application to resolve this duplication in an appropriate manner.
Note that for API versions prior to 7.1.2, if a reconnect to a different host occurred after publishing Guaranteed messages, the API would close the newly created session and raise a session event—the application was responsible for reconnecting and resending any unacknowledged published messages. To use this legacy behavior, you must change the Guaranteed Delivery Reconnect Fail Action property to the appropriate non-default value. For more information, see the JMS Properties Reference.
The connect retries per host value can be set through the Connection Retries Per Host property for the JNDI or data connection. For more information, see JMS Properties Reference.
Handling JMS Connection Events
The Solace JMS implementation offers a callback listener (SolConnectionEventListener) for the JMS connection events (for example, SolReconnectedEventand SolReconnectingEvent).
For your JMS applications to receive asynchronous notifications when SolConnection events occur, you must implement the SolConnectionEventListener interface and register with a SolConnectionEventSource.
Event notifications can occur on the Connections I/O and event threads.
Closing Sessions
To close a Session, call Session.closeSession().
When this method is invoked, the producers and consumers created in that same Session are closed. That is, they do not have to be explicitly closed before Session.closeSession() is invoked.
The Session.closeSession() call blocks until a receive call or message listener in progress has completed. A blocked message consumer receive call returns null when this Session is closed.
Closing a transacted Session will roll back any transaction that is in progress.
This method is the only method for the Session interface that can be called concurrently.
If a provider has allocated resources for the Session outside the JVM, those resources should be closed before calling Session.closeSession() because relying on garbage collection to eventually reclaim those resources may not be timely enough.