Skip navigation links

weblogic.jms.extensions
Interface WLJMSContext

All Superinterfaces:

AutoCloseable, JMSContext

public interface WLJMSContext

extends JMSContext

A WLJMSContext provides fields and methods that are not supported by javax.jms.JMSContext. WLJMSContext provides the same extension features as WLConnection WLJMSContext also provides the same extension features as WLSession. These include:

• Creating XMLMessages
• Defining a Session exception listener
• Setting or displaying the maximum number of messages allowed
• Setting or displaying the multicast session overrun policy that is applied when the message maximum is reached

WLSession also supports NO_ACKNOWLEDGE and MULTICAST_NO_ACKNOWLEDGE acknowledge modes.

See Also:

JMSContext

RECONNECT_POLICY_NONE

static final String RECONNECT_POLICY_NONE

See Also:

WLJMSContext.setReconnectPolicy(java.lang.String), WLJMSContext.getReconnectPolicy()

RECONNECT_POLICY_PRODUCER

static final String RECONNECT_POLICY_PRODUCER

See Also:

WLJMSContext.setReconnectPolicy(java.lang.String), WLJMSContext.getReconnectPolicy()

RECONNECT_POLICY_ALL

static final String RECONNECT_POLICY_ALL

See Also:

WLJMSContext.setReconnectPolicy(java.lang.String), WLJMSContext.getReconnectPolicy()

CLIENT_ID_POLICY_RESTRICTED

static final String CLIENT_ID_POLICY_RESTRICTED

Only one connection that uses this policy exists in a cluster at any given time for a particular ClientID.

See Also:

WLJMSContext.getClientIDPolicy(), WLJMSContext.setClientID(String,String)

CLIENT_ID_POLICY_UNRESTRICTED

static final String CLIENT_ID_POLICY_UNRESTRICTED

Connections created using this policy can specify any ClientID , even when other restricted or unrestricted connections already use the same ClientID.

See Also:

WLJMSContext.getClientIDPolicy(), WLJMSContext.setClientID(String,String)

SUBSCRIPTION_EXCLUSIVE

static final String SUBSCRIPTION_EXCLUSIVE

All subscribers created using this connection do not share subscriptions with any other subscribers.

See Also:

WLJMSContext.getSubscriptionSharingPolicy(), WLJMSContext.setSubscriptionSharingPolicy(java.lang.String)

SUBSCRIPTION_SHARABLE

static final String SUBSCRIPTION_SHARABLE

Subscribers created using this connection factory can share their subscriptions with other subscribers, regardless of whether those subscribers are created using the same connection factory or a different connection factory.

See Also:

WLJMSContext.getSubscriptionSharingPolicy(), WLJMSContext.setSubscriptionSharingPolicy(java.lang.String)

NO_ACKNOWLEDGE

static final int NO_ACKNOWLEDGE

No acknowledge is required.

Messages sent to a NO_ACKNOWLEDGE session are immediately deleted from the server. Messages received in this mode are not recovered, and as a result messages may be lost and/or a duplicate message may be delivered if an initial attempt to deliver a message fails.

This mode is supported for applications that do not require the quality of service provided by session acknowledge, and that do not want to incur the associated overhead.

You should avoid using this mode if your application cannot handle duplicate messages.

See Also:

Constant Field Values

MULTICAST_NO_ACKNOWLEDGE

static final int MULTICAST_NO_ACKNOWLEDGE

Multicast mode with no acknowledge required.

Messages sent to a MULTICAST_NO_ACKNOWLEDGE session share the same characteristics as NO_ACKNOWLEDGE mode.

This mode is supported for applications that want to support multicasting, and that do not require the quality of service provided by session acknowledge.

You should avoid using this mode if your application is unable to handle duplicate messages, which can occur if a message fails to be delivered during the first attempt.

See Also:

Constant Field Values

KEEP_OLD

static final int KEEP_OLD

Multicast overrun policy specifying that the oldest messages should be saved and the most recent ones discarded, as needed, so as not to exceed the message maximum.

See Also:

Constant Field Values

KEEP_NEW

static final int KEEP_NEW

Multicast overrun policy specifying that the most recent messages should be saved and the oldest ones discarded, as needed, so as not to exceed the message maximum.

See Also:

Constant Field Values

setReconnectPolicy

void setReconnectPolicy(String reconnectPolicy)
                        throws IllegalArgumentException

Sets the JMS client reconnection policy after a lost network connection with a server or upon a server reboot.

• weblogic.jms.extensions.WLJMSContext.RECONNECT_POLICY_NONE -- Prevents reconnection attempts.
• weblogic.jms.extensions.WLJMSContext.RECONNECT_POLICY_PRODUCER -- Explicitly refreshes Producer objects and implicitly refreshes any related Session and Connection objects. However, this value does not refresh Consumers, QueueBrowsers, and Connections with a configured ClientID for a durable subscriber.
• weblogic.jms.extensions.WLJMSContext.RECONNECT_POLICY_ALL -- Explicitly refreshes all Consumer and Producer objects and implicitly refreshes any related Session and Connection objects. However, this value does not refresh QueueBrowsers and Connections with a configured ClientID for a durable subscriber.

Parameters:

reconnectPolicy - reconnectPolicy is the new reconnect policy.

Throws:

IllegalArgumentException - when the argument is not: weblogic.jms.extensions.WLJMSContext.RECONNECT_POLICY_NONE weblogic.jms.extensions.WLJMSContext.RECONNECT_POLICY_PRODUCER weblogic.jms.extensions.WLJMSContext.RECONNECT_POLICY_ALL

See Also:

WLJMSContext.getReconnectPolicy(), WLJMSContext.RECONNECT_POLICY_NONE, WLJMSContext.RECONNECT_POLICY_PRODUCER, WLJMSContext.RECONNECT_POLICY_ALL, weblogic.jms.extensions.WLJMSContext#getJMSRedeliveryLimit()

getReconnectPolicy

String getReconnectPolicy()

The JMS client reconnection policy after a lost network connection with a server or upon a server reboot.

Returns:

The current reconnectPolicy.

See Also:

WLJMSContext.setReconnectPolicy(java.lang.String)

setReconnectBlockingMillis

void setReconnectBlockingMillis(long timeout)
                                throws IllegalArgumentException

Sets the maximum length of time that any synchronous JMS calls, such as a producer.send(), consumer.receive(), or session.createBrowser(), will block the calling thread before giving up on a JMS client reconnect in progress.

Parameters:

timeout - The number of milliseconds JMS operations will wait trying to reconnect to a disconnected server before throwing a JMSException.

When the timeout is zero, the reconnect starts but this call does not block waiting for the reconnected objects.

When the timeout is -1, the call blocks as long as reconnects are possible. For example, send() can block until close() is called, and send() will throw a JMSException.

Throws:

IllegalArgumentExcaption - is thrown when timeout is less than -1.

IllegalArgumentException

See Also:

WLJMSContext.getReconnectBlockingMillis()

getReconnectBlockingMillis

long getReconnectBlockingMillis()

The maximum length of time that any synchronous JMS calls block the calling thread before giving up on a JMS client reconnect in progress.

Returns:

The number of milliseconds JMS operations waits trying to reconnect to a disconnected server before throwing a JMSException.

See Also:

WLJMSContext.setReconnectBlockingMillis(long)

setTotalReconnectPeriodMillis

void setTotalReconnectPeriodMillis(long timeout)
                                   throws IllegalArgumentException

Sets the maximum length of time that JMS client operations continue to try to reconnect to the server after either the initial network disconnect or the last synchronous call attempt, whichever occurred most recently, before giving up retrying.

Parameters:

timeout - The number of milliseconds that JMS reconnect timers are permitted to reconnect a disconnected server.

When the timeout is -1, there is no limit. Reconnection timers are always scheduled until close() is called.

Throws:

IllegalArgumentExcaption - is thrown when timeout is less than -1.

IllegalArgumentException

See Also:

WLJMSContext.getTotalReconnectPeriodMillis()

getTotalReconnectPeriodMillis

long getTotalReconnectPeriodMillis()

The maximum length of time that JMS client operations continue to try to reconnect to the server.

Returns:

The number of milliseconds that JMS reconnect timers are permitted to reconnect a disconnected server.

See Also:

WLJMSContext.setTotalReconnectPeriodMillis(long)

setClientID

void setClientID(String clientID,
                 String clientIDPolicy)
                 throws IllegalArgumentException

Sets the ClientID and ClientIdPolicy on the connection.

The ClientID and ClientIdPolicy can be set administratively through the connection factory. If a client sets the ClientID explicitly, it must do so immediately after it creates the connection and before any other action on the connection is taken. After this point, setting the ClientID throws an IllegalStateException. If the ClientID is specified on the connection factory, an attempt to use this setter to change it throws IllegalStateException. If the ClientIdPolicy is specified on the connection factory without a ClientID, calling this setter with a ClientID and a different ClientIdPolicy overrides the policy as well as sets the ClientID.

Note: A durable subscription that is created using a Unrestricted client ID can only be unsubscribed using WLSession.unsubscribe(String name, Topic topic) method. An attempt of unsubscribing such a subscription using standard javax.jms.Session.unsubscribe(String name) will get an InvalidDestinationException.

Parameters:

clientID - the ClientID to be set

clientIDPolicy - the ClientIdPolicy to be set

Throws:

JMSException - if the JMS provider fails to set the client ID for this connection due to some internal error.

IllegalStateRuntimeException - if the JMS client attempts to set a connection's client ID at the wrong time or when it has been administratively configured.

InvalidClientIDRuntimeException - if the JMS client specifies an invalid or duplicate client ID using the RESTRICTED policy.

IllegalArgumentException - if the policy is not valid.

See Also:

WLJMSContext.getClientIDPolicy(), WLJMSContext.CLIENT_ID_POLICY_RESTRICTED, WLJMSContext.CLIENT_ID_POLICY_UNRESTRICTED

getClientIDPolicy

String getClientIDPolicy()

The ClientIdPolicy on this connection.

Returns:

the ClientIdPolicy on this connection.

See Also:

WLJMSContext.setClientID(String,String), WLJMSContext.CLIENT_ID_POLICY_RESTRICTED, WLJMSContext.CLIENT_ID_POLICY_UNRESTRICTED

getSubscriptionSharingPolicy

String getSubscriptionSharingPolicy()

The SubscriptionSharingPolicy on this connection.

Returns:

the SubscriptionSharingPolicy

See Also:

WLJMSContext.setSubscriptionSharingPolicy(java.lang.String), WLJMSContext.SUBSCRIPTION_EXCLUSIVE, WLJMSContext.SUBSCRIPTION_SHARABLE

setSubscriptionSharingPolicy

void setSubscriptionSharingPolicy(String subscriptionSharingPolicy)
                                  throws IllegalArgumentException

Sets the SubscriptionSharingPolicy on this connection. The SubscriptionSharingPolicy can be set administratively through the connection factory. Consumers can share a non-durable subscriptions only if they have the same Client ID and Client ID Policy; consumers can share a durable subscription only if they have the same Client ID, Client ID Policy, and Subscription Name.

Parameters:

subscriptionSharingPolicy - new subscription sharing policy to be set.

Throws:

JMSRuntimeException - if the JMS provider fails to set the Subsrciption Sharing Policy for this connection due to some internal error.

IllegalArgumentException - if the policy is not valid

See Also:

WLJMSContext.SUBSCRIPTION_EXCLUSIVE, WLJMSContext.SUBSCRIPTION_SHARABLE, WLJMSContext.getSubscriptionSharingPolicy()

createXMLMessage

XMLMessage createXMLMessage()

Create an XMLMessage. An XMLMessage is used to send a message containing XML content.

Throws:

JMSRuntimeException - if a JMS error occurs.

See Also:

WLJMSContext.createXMLMessage(String)

createXMLMessage

XMLMessage createXMLMessage(String xml)

Create an initialized XMLMessage from a String containing XML. An XMLMessage is used to send a message containing XML content.

Parameters:

xml - The XML content represented as a string

Throws:

JMSRuntimeException - if a JMS error occurs.

See Also:

WLJMSContext.createXMLMessage()

createXMLMessage

XMLMessage createXMLMessage(Document doc)

Create an initialized XMLMessage from a DOM Document containing XML. An XMLMessage is used to send a message containing XML content.

Parameters:

doc - The XML content represented as a DOM Document

Throws:

JMSRuntimeException - if a JMS error occurs.

See Also:

WLJMSContext.createXMLMessage()

setSessionExceptionListener

void setSessionExceptionListener(ExceptionListener exceptionListener)

Set an exception listener for this session.

If a JMS provider detects a serious problem with a session, it will inform the session's exception listener, if one has been registered. It informs the exception listener by calling the listener's onException() method and passing a JMSException describing the problem.

The exception listener allows a client to be asynchronously notified of a problem. Some sessions only consume messages, so they would have no other way to learn that the session has failed.

A session serializes execution of its exception listener.

A JMS provider should attempt to resolve session problems prior to notifying the client.

Parameters:

exceptionListener - The exception listener.

Throws:

JMSRuntimeException - general exception if JMS implementation fails to set the exception listener for this session.

getMessagesMaximum

int getMessagesMaximum()

The maximum number of messages that may exist for an asynchronous session, which have not yet been passed to the message listener.

A value of -1 indicates that there is no limit on the number of messages. In this case, however, the limit is set to the amount of remaining virtual memory.

Returns:

The message maximum set for this session.

Throws:

JMSRuntimeException - if a JMS error occurs.

See Also:

WLJMSContext.setMessagesMaximum(int)

setMessagesMaximum

void setMessagesMaximum(int messagesMaximum)

Set the maximum number of messages that may exist for an asynchronous session, which have not yet been passed to the message listener.

A value of -1 indicates that there is no limit on the number of messages. In this case, however, the limit is set to the amount of remaining virtual memory.

When the number of messages reaches the specified value, the following occurs:

• For multicast sessions, new messages are discarded according to the specified overrun policy, and a DataOverrunException is thrown.
• For non-multicast sessions, new messages are flow-controlled, or retained on the server until the application can accomodate the messages.

For multicast sessions, when a connection is stopped, messages will continue to be accumulated, but only until the specified maximum value is reached. Once this value is reached, messages will be discarded based on the overrun policy.

Parameters:

messagesMaximum - The maximum number of messages allowed, valid values are -1, and 1 through 2^63-1 (default is 10).

Throws:

JMSException - if a JMS error occurs.

See Also:

WLJMSContext.getMessagesMaximum()

getOverrunPolicy

int getOverrunPolicy()

Get overrun policy for multicast sessions.

Returns:

The overrun policy set for this session.

Throws:

JMSRuntimeException - general exception if the JMS implementation fails to set the exception listener for this session.

See Also:

WLJMSContext.setOverrunPolicy(int)

setOverrunPolicy

void setOverrunPolicy(int policy)

Set overrun policy for multicast sessions.

When the number of messages reaches the message maximum, messages are discarded based on the specified policy, as follows:

• If set to KeepNew, the most recent messages are given priority over the oldest messages, and the oldest messages are discarded, as needed.
• If set to KeepOld, the oldest messages are given priority over the most recent messages, and the most recent messages are discarded, as needed.

Message age is defined by the order of receipt, not by the JMSTimestamp value.

Parameters:

policy - The overrun policy.

Throws:

JMSRuntimeException - general exception if JMS implementation fails to set the exception listener for this session.

See Also:

WLJMSContext.getOverrunPolicy()

getRedeliveryDelay

long getRedeliveryDelay()

The redelivery delay for this session; this defines the delay in milliseconds before rolled back or recovered messages are redelivered. The default redelivery delay is obtained from the configuration of the connection factory used to create this consumer. If the time to deliver on the session is explicitly set to -1 via WLSession.setRedliveryDelay(), then this method will return the connection factory setting; if it is set to any other value, then this method will return that value.

Returns:

Redelivery delay for this session.

Throws:

JMSRuntimeException - if a JMS error occurs.

See Also:

WLJMSContext.setRedeliveryDelay(long)

setRedeliveryDelay

void setRedeliveryDelay(long redeliveryDelay)

Set the redelivery delay for this consumer; this defines the delay in milliseconds before rolled back or recovered messages are redelivered. The default redeliver delay is 0; this default may be changed by modifying the configuration of the connection factory used to create this consumer. Setting the redelivery delay to -1 forces the use of this default. Setting it to anything greater than or equal to 0 overrides this default. If this method is not called, then the connection factory setting is used.

Performance Note: If any consumers for remote destinations already exist on this session, calling this method results in a network call(s) in order to disseminate the changed delay value to them.

Parameters:

redeliveryDelay - Redelivery delay for this session.

Throws:

JMSRuntimeException - if a JMS error occurs.

See Also:

WLJMSContext.getRedeliveryDelay()

acknowledge

void acknowledge(Message message)

Acknowledge all the messages received by this session. This is similar to the method Message.acknowledge(), except it can be called from the session. This is for users who set their connection factory AcknowledgePolicy to "Previous" so they may acknowledge "All" messages received by this session. This method must not be used if the JMSContext is container-managed (injected). Doing so will cause a IllegalStateRuntimeException to be thrown.

Throws:

IllegalStateRuntimeException - if the JMSContext is container-managed (injected)

JMSRuntimeException - if a JMS error occurs

unsubscribe

void unsubscribe(Topic topic,
                 String name)

Unsubscribe a durable subscription on a particular topic or distributed topic member.

Although this API can be used for both Unrestricted and Restricted Client ID cases, if a subscription is created using an Unrestricted Client ID, it can only be unsubscribed using this method from a session that has the same Unrestricted Client ID.

Parameters:

topic - the topic or distributed topic member that the subscription is on

name - the name used to identify this subscription

Throws:

JMSRuntimeException - if the session fails to unsubscribe to the durable subscription due to some internal error.

InvalidDestinationRuntimeException - if an invalid subscription name, a null topic, or a distributed topic is specified.

Skip navigation links