14-6 Programming JMS for Oracle WebLogic Server
■
Pending Unacknowledged Messages – If a Session had unacknowledged messages prior to the Session refresh, then the first WLSession.acknowledge call after
a refresh throws a weblogic.jms.common.LostServerException. This indicates that the acknowledge call may not have removed messages from the
server. As a result, the refreshed Session may receive duplicate messages that were also delivered before the disconnect.
14.1.2.6 Reconnected MessageProducer Objects
As described in Section 14.1.2.4, Reconnected Connection Objects,
JMS MessageProducer objects are refreshed when their associated JMS connection gets
refreshed see Step 5 in Example 14–1
. If producers are non-anonymous, that is, they are specific to a Destination object standalone or distributed destination, then the
producers destination is also implicitly refreshed, as described in Section 14.1.2.3,
Re-usable Destination Objects. If a producer is anonymous, that is not specific to a
Destination object, then the possibly-stale Destination object specified on the producers send operation is implicitly refreshed.
14.1.2.6.1 Special Case for Distributed Destinations It is possible that a producer can send
a message at the same time that a distributed destination member becomes unavailable. If WebLogic JMS can determine that the distributed destination member
is not available, or was not available when the message was sent, the system will retry sending the message to another distributed member. If there is no way to determine if
the message made it through the connection all the way to the distributed member before it went down, the system will not attempt to resend the message because doing
so may create a duplicate message. In that case, WebLogic JMS will throw an exception. It is up to the application to catch that exception and decide whether or not
to resend the message.
14.1.3 Configuring Automatic Failover for JMS Consumers
JMS MessageConsumer objects that are part of a JMS Connection via a JMS Session can be refreshed during a JMS connection refresh see Step 5 in
Example 14–2 .
However, due to the stateful nature of JMS consumers, as well as their potential asynchronous nature, you must explicitly enable this capability using either the
weblogic.jms.extension.WLConnection API or the Administration Console.
Explicitly enabling automatic refresh of consumers also refreshes connections with a configured Client ID for a durable subscriber, as described in
Section 14.1.3.4.3, Consumer Connections with a ClientID for Durable Subscriptions.
However, refreshed consumers does not include QueueBrowser clients, which are never
refreshed, as described in Section 14.1.1, Automatic Reconnect Limitations.
14.1.3.1 Sample Consumer Client Code
When Message Consumer refresh is explicitly activated, in the event of a network failure, the WebLogic JMS client code for message consumption will attempt to
reconnect during Steps 3-8 in Example 14–2
.
Example 14–2 Sample JMS Client Code for Message Consumption
0. Context ctx = create WebLogic JNDI context with credentials etc. 1. ConnectionFactory cf = ctx.lookupJNDI name of connection factory
2. Destination dest = ctx.lookupJNDI name of destination the following operations recover from network failures
3. Connection con = cf.createConnection weblogic.jms.extensions.WLConnectioncon.setReconnectPolicyall
4. Session sess = con.createSessionno transactions, auto ack
Recovering from a Server Failure 14-7
5. MessageConsumer cons = sess.createConsumerdest, message selector - also for async consumers : cons.setMessageListeneronMessage impl
6. con.start 7. Loop over:
for sync consumers: Message msg = consumer.receive for async consumers in different thread: onMessage invoked
8. con.close, ctx.close
Note that the connection factory does not refresh MessageConsumer objects by default. For this to occur programmatically, your client application code must call the
WebLogic WLConnection extension, with the setReconnectPolicy set to all, as shown in Step 3 in
Example 14–2 .
14.1.3.2 Configuring Automatic Client Refresh Options
The JMS client reconnect API includes the following configuration parameters, which allow you to make some choices that affect the behavior of the reconnect feature for
consumers.
For instructions on configuring client parameters on a connection factory using the Administration Console, see Configure connection factory client parameters in the
Oracle WebLogic Server Administration Console Help. For more information about these parameters, see ClientParamsBean in the Oracle WebLogic Server MBean Reference.
14.1.3.3 Common Cases for Reconnected Consumers
This section describes the common scenarios when refreshing synchronous and asynchronous consumers.
14.1.3.3.1 Synchronous Consumers Synchronous consumers use
MessageConsumer.receive, MessageConsumer.receivetimeout, and MessageConsume.receiveNoWait methods to consume messages. The first two
methods are already expected to be potentially block the application code, while the third method is not expected to block the application code. To retain these semantics,
the following rules describe interaction of the reconnect feature with the synchronous consumer calls:
Table 14–1 Automatic JMS Client Reconnect Options
Console LabelMBean Attribute
Value Description
Reconnect Policy ReconnectPolicy
■
None
■
Producer default
■
All Determines which JMS client objects are implicitly refreshed
upon a network disconnect or server reboot. It only affects the implicit refresh of Connections, Sessions, Producers, and
Consumers derived from this Connection Factory. This attribute does not affect Destination or ConnectionFactory objects in the
JMS client, since those objects are always refreshed implicitly. Nor does it affect the QueueBrowser object in the JMS client,
since that object is never refreshed.
Reconnect Blocking Time ReconnectBlockingTimeMillis
6000 Determines how long any synchronous JMS calls, such as
producer.send, consumer.receive, and session.createBrowser will block the calling thread
before giving up on a JMS client reconnect in progress.
TotalReconnectPeriodMillis -1
Determines how long JMS clients should keep retrying to connect after either the initial network disconnect or the last synchronous
JMS call attempt whichever occurs most recently, before giving up retrying.
14-8 Programming JMS for Oracle WebLogic Server
■
MessageConsumer.receive– If there is a network disconnect during this call, this method can block for up to Reconnect Blocking Time property described
in the configuration section for a reconnect to go through before throwing an Exception.
■
MessageConsumer.receivetimeout – This call will block for the at-most timeout milliseconds specified by caller. If the Reconnect Blocking Time property
is less than timeout, the receive will still block up to the Reconnect Blocking Time setting; if the Reconnect Blocking Time value is more than timeout, the receive will
only block up to timeout.
■
MessageConsumer.receiveNoWait – This call will not block if the JMS Connection is in the process of reconnecting. The Reconnect Blocking Time value
will have no effect on this call.
If these methods eventually reach their respective timeoutwait periods, they all will throw the same Exceptions. as without reconnect. If a reconnect succeeds while these
methods are blockedcalled, these methods will continue returning messages, but with a potentially lowered quality-of-service and with generally similar semantics of
receiving messages like Redelivered messages, as after a recover. The application is notified of this possibility by a Connection ExceptionListener callback with
LostServerException. In addition, for non-AUTO_ACK acknowledge modes, the first acknowledge call after a refresh will throw a LostServerException to notify
the application of this possibility.
14.1.3.3.2 Asynchronous Consumers In the context of a reconnect, the behavior for
asynchronous consumers will be governed by the setting on the Total Reconnect Period property. The JMS Consumers registered message listeners onMessage
will continue to be invoked if the reconnect framework is able to successfully re-establish a connection within the Total Reconnect Period setting after a connection
failure. If the user explicitly calls a close on the JMS Connection or on the JMS Session corresponding to the asynchronous Consumer, then the reconnect framework
will not invoke any further onMessages for that Consumer. The onMessage should expect post-recover behavior like Redelivered messages if the Connection
ExceptionListeners onException is invoked with a LostServerException.
14.1.3.4 Special Cases for Reconnected Consumers
