com.solacesystems.jcsmp

Interface JCSMPSession

All Superinterfaces:

Session

@ProviderType
public interface JCSMPSession
extends Session

JCSMPSession

JCSMPSession provides these major functions:

• Subscriber control, such as updating subscriptions / subscription filters, etc.
• Publish messages to an appliance.
• Receive messages from an appliance.

A client application uses JCSMPFactory to acquire a JCSMPSession instance by providing JCSMPProperties.

Note: All methods defined in JCSMPSession are thread-safe.

Connecting a Session

Once a Session is created, it must be connected. A JCSMPSession can be connected as a side effect of requesting a producer or consumer, or it can be explicitly connected by using the JCSMPSession.connect() method. As best practice, it is recommended to always use explicit connect.

Subscriber control

To perform Subscriber control operations, the application uses the methods defined in JCSMPSession.

Refer to Subscription and Topic for detailed information on subscriptions and subscription filters.

Publishing

To publish a message, an application acquires an XMLMessageProducer from the JCSMPSession. The application can publish documents in either synchronous publishing mode or asynchronous publishing mode (also called streaming publishing). In synchronous publishing mode, the application is blocked on send operations until an acknowledgement is received from the appliance. In streaming publishing mode, send operations do not block and wait for a reply. The application gets a response (when applicable) through a callback mechanism. To use streaming publishing mode, an application needs to provide a JCSMPStreamingPublishEventHandler instance to the XMLMessageProducer when acquiring it.

Refer to XMLMessageProducer for information on how to publish in synchronous or asynchronous modes, and on the use of producer-independent messages.

Receiving

To receive messages, an application acquires an XMLMessageConsumer instance from the JCSMPSession. The application can select to receive XML documents in either synchronous delivery or asynchronous delivery mode. In synchronous delivery mode, the application is blocked on the receive operation until a message is available. In asynchronous delivery mode, messages (and errors) are delivered to the application asynchronously. To work in asynchronous mode, an application must provide an XMLMessageListener instance to XMLMessageConsumer when acquiring it.

Field Summary

Fields

Modifier and Type	Field and Description
static int	FLAG_IGNORE_ALREADY_EXISTS
static int	FLAG_IGNORE_DOES_NOT_EXIST
static int	WAIT_FOR_CONFIRM If set, operations wait for a confirmation from the appliance before returning to the application.

Method Summary

Modifier and Type	Method and Description
void	addSubscription(Endpoint endpoint, Subscription subscription, int subscribeFlags) Adds a subscription to an Endpoint on the appliance.
void	addSubscription(Endpoint endpoint, Subscription subscription, JCSMPResponseListener handler, Object key) Adds a subscription asynchronously to an Endpoint on the appliance.
void	addSubscription(Subscription subscription) Adds a subscription to the appliance.
void	addSubscription(Subscription subscription, boolean waitForConfirm) Adds a subscription to an appliance.
void	addSubscription(Subscription subscription, JCSMPResponseListener handler, Object key) Adds a subscription asynchronously to the appliance.
void	applySubscriptions(Set<Subscription> subscriptions) Uses the subscription refresh feature to override the subscriptions and subscription filters associated with a subscriber on the appliance with a given list of subscriptions.
void	connect() Connect to the appliance.
Browser	createBrowser(BrowserProperties properties) Creates a Browser, which can be used for browsing the contents of a Queue.
Browser	createBrowser(BrowserProperties properties, FlowEventHandler flowEventHandler) Creates a Browser, which can be used for browsing the contents of a Queue.
CacheSession	createCacheSession(CacheSessionProperties properties) Creates a CacheSession using the provided CacheSession properties.
FlowReceiver	createFlow(Endpoint endpoint, Subscription newSubscription, XMLMessageListener listener) Get an instance of FlowReceiver bound to a appliance Endpoint, such as a Queue or TopicEndpoint.
FlowReceiver	createFlow(XMLMessageListener listener, ConsumerFlowProperties flowProps) Get an instance of FlowReceiver bound to an appliance Endpoint, such as a Queue or TopicEndpoint.
FlowReceiver	createFlow(XMLMessageListener listener, ConsumerFlowProperties flowProps, EndpointProperties endpointProps) Get an instance of FlowReceiver bound to an appliance Endpoint, such as a Queue or TopicEndpoint.
FlowReceiver	createFlow(XMLMessageListener listener, ConsumerFlowProperties flowProps, EndpointProperties endpointProps, FlowEventHandler flowEventHandler) Get an instance of FlowReceiver bound to an appliance Endpoint, such as a Queue or TopicEndpoint.
TopicEndpoint	createNonDurableTopicEndpoint() Creates a non-durable Topic Endpoint.
TopicEndpoint	createNonDurableTopicEndpoint(String name) Creates a non-durable Topic Endpoint based on the given name.
Requestor	createRequestor() Creates a new Requestor for this Session.
Queue	createTemporaryQueue() Creates a temporary Queue for this Session.
Queue	createTemporaryQueue(String name) Creates a temporary Queue with the given name.
Topic	createTemporaryTopic() Creates a temporary Topic for this Session.
TransactedSession	createTransactedSession() Creates a new TransactedSession with the connected appliance.
void	deprovision(Endpoint endpoint, long deprovisionFlags) Deprovisions an Endpoint on the appliance.
Object	getCapability(CapabilityType type) Gets the value of a capability for the currently connected Session.
XMLMessageConsumer	getMessageConsumer() Deprecated. Please see JCSMPSession.getMessageConsumer(XMLMessageListener).
XMLMessageConsumer	getMessageConsumer(JCSMPReconnectEventHandler reconnectHandler) Deprecated. Please see JCSMPSession.getMessageConsumer(JCSMPReconnectEventHandler, XMLMessageListener).
XMLMessageConsumer	getMessageConsumer(JCSMPReconnectEventHandler reconnectHandler, XMLMessageListener listener) Get a default XMLMessageConsumer with a reconnect event handler.
XMLMessageConsumer	getMessageConsumer(SubscriptionStateProvider subscriptionStateProvider) Deprecated. Please see JCSMPSession.getMessageConsumer(SubscriptionStateProvider, XMLMessageListener).
XMLMessageConsumer	getMessageConsumer(SubscriptionStateProvider subscriptionStateProvider, JCSMPReconnectEventHandler reconnectHandler) Deprecated. Please see JCSMPSession.getMessageConsumer(SubscriptionStateProvider, JCSMPReconnectEventHandler, XMLMessageListener).
XMLMessageConsumer	getMessageConsumer(SubscriptionStateProvider subscriptionStateProvider, JCSMPReconnectEventHandler reconnectHandler, XMLMessageListener listener) Deprecated. Subscriptions out-of-sync checking is no longer supported. This method will be removed in a future version.
XMLMessageConsumer	getMessageConsumer(SubscriptionStateProvider subscriptionStateProvider, XMLMessageListener listener) Deprecated. Subscriptions out-of-sync checking is no longer supported. This method will be removed in a future version.
XMLMessageConsumer	getMessageConsumer(XMLMessageListener listener) Get a default XMLMessageConsumer.
XMLMessageProducer	getMessageProducer() Deprecated. Please see JCSMPSession.getMessageProducer(JCSMPStreamingPublishEventHandler). Note that using this deprecated method can introduce a performance penalty during a streaming publishing Session because it forces the appliance to transmit acknowledgements to every message. Using the recommended JCSMPSession.getMessageProducer(JCSMPStreamingPublishEventHandler) form eliminates this problem.
XMLMessageProducer	getMessageProducer(JCSMPStreamingPublishEventHandler callback) Get an instance of XMLMessageProducer.
XMLMessageProducer	getMessageProducer(JCSMPStreamingPublishEventHandler streamCallback, JCSMPProducerEventHandler eventCallback) Get an instance of XMLMessageProducer.
Object	getProperty(String property) Gets a Session property.
Set<Subscription>	getSubscriptionCache() Gets an unmodifiable view of the Session's subscription cache.
boolean	isCapable(CapabilityType ctype) Checks if the specified capability is set on the currently connected Session.
void	logFlowInfo(JCSMPLogLevel level) Outputs a log at the specified log level that contains the flow state information for flows in this Session.
void	provision(Endpoint endpoint, EndpointProperties props, long provisionFlags) Provisions an Endpoint on the appliance.
void	removeSubscription(Endpoint endpoint, Subscription subscription, int unsubscribeFlags) Removes a subscription from an Endpoint on the appliance.
void	removeSubscription(Endpoint endpoint, Subscription subscription, JCSMPResponseListener handler, Object key) Removes a subscription asynchronously from an Endpoint on the appliance.
void	removeSubscription(Subscription subscription) Removes a subscription from the appliance.
void	removeSubscription(Subscription subscription, boolean waitForConfirm) Removes a subscription from the appliance.
void	removeSubscription(Subscription subscription, JCSMPResponseListener handler, Object key) Removes a subscription asynchronously from the appliance.
void	setProperty(String property, Object value) Sets a modifiable Session property once the Session has been constructed.
void	unsubscribeDurableTopicEndpoint(DurableTopicEndpoint endpoint) Unsubscribe from the durable Topic Endpoint.

Methods inherited from interface com.solacesystems.jcsmp.Session

addSubscriber, clearSubscriber, closeSession, getSessionName, getSessionStats, logSessionStats, removeSubscriber

Field Detail

FLAG_IGNORE_ALREADY_EXISTS

static final int FLAG_IGNORE_ALREADY_EXISTS

See Also:

Constant Field Values

FLAG_IGNORE_DOES_NOT_EXIST

static final int FLAG_IGNORE_DOES_NOT_EXIST

See Also:

Constant Field Values

WAIT_FOR_CONFIRM

static final int WAIT_FOR_CONFIRM

If set, operations wait for a confirmation from the appliance before returning to the application. If not set, errors are reported through the Session event handler.

See Also:

Constant Field Values

Method Detail

addSubscription

void addSubscription(Subscription subscription)
              throws JCSMPException

Adds a subscription to the appliance. This method blocks until the subscription operation has been confirmed. It is equivaelent to passing TRUE as the second argument to: JCSMPSession.addSubscription(Subscription, boolean)

Parameters:

subscription - The subscription to add.

Throws:

IllegalArgumentException - if a provided destination is invalid in the current Session mode.

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_INVALID
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_ALREADY_PRESENT
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_TOO_MANY
• JCSMPErrorResponseSubcodeEx.OUT_OF_RESOURCES
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_ACL_DENIED

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.

addSubscription

void addSubscription(Subscription subscription,
                     boolean waitForConfirm)
              throws JCSMPException

Adds a subscription to an appliance. This method allows applications to add subscriptions choosing whether or not to wait for a confirmation.

This method is used to add a subscription in either a blocking or non-blocking mode. Setting waitForConfirm to false prevents the API from waiting for a response before returning. In this mode, a response is only sent by the appliance if the subscription is rejected, and such a response is delivered to the session event handler. It is invalid to set waitForConfirm to false on a Session where no Session event handler is set, and such an operation throws OperationNotSupportedException. NOTE: When waitForConfirm is false the application will never receive a positive confirmation, only errors are sent by callback. When waitForConfirm is true, this method does not return until the appliance has responded to the subscription operation, it throws on error and otherwise returns to indicate the subscription operation was successful. Note:There is a useful interaction between JCSMPSession.WAIT_FOR_CONFIRM and JCSMPProperties.REAPPLY_SUBSCRIPTIONS. If the application chooses to wait for confirmation, if the subscription operation is unsuccessful then the subscription is removed from the cache of subscriptions to reapply and will therefore not be attempted again on a session reconnect. If the applications chooses not to wait for confirmation, even if the subscription operation fails, the subscription remains in the cache of subscriptions to reapply and may be successfully reapplied on a session reconnect.

Parameters:

subscription - The subscription to add.

waitForConfirm - Whether to request, and wait for, a response from the appliance before returning.

Throws:

IllegalArgumentException - If a provided destination is invalid in the current Session mode.

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_INVALID
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_ALREADY_PRESENT
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_TOO_MANY
• JCSMPErrorResponseSubcodeEx.OUT_OF_RESOURCES
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_ACL_DENIED

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.

removeSubscription

void removeSubscription(Subscription subscription)
                 throws JCSMPException

Removes a subscription from the appliance.

Parameters:

subscription - The subscription to remove.

Throws:

IllegalArgumentException - If a provided subscription is invalid in the current Session mode.

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_INVALID
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_NOT_FOUND

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.

removeSubscription

void removeSubscription(Subscription subscription,
                        boolean waitForConfirm)
                 throws JCSMPException

Removes a subscription from the appliance.

Setting waitForConfirm to false prevents the API from waiting for a response before returning. In this mode, the appliance only sends a response if the subscription is rejected, and such a response is delivered to the session event handler. It is invalid to set waitForConfirm to false on a Session where no Session event handler is set; such an operation throws OperationNotSupportedException.

Parameters:

subscription - The subscription to remove.

waitForConfirm - Whether to request, and wait for, a response from the appliance before returning.

Throws:

IllegalArgumentException - If a provided subscription is invalid in the current Session mode.

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_INVALID
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_NOT_FOUND

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.

addSubscription

void addSubscription(Endpoint endpoint,
                     Subscription subscription,
                     int subscribeFlags)
              throws JCSMPException

Adds a subscription to an Endpoint on the appliance. The Endpoint targeted can be either a Queue or a ClientName.

Adding subscriptions to Queues

Guaranteed messages are published to a Queue when it is set as the destination of the message. However, you can also add one or more topic subscriptions to a durable or temporary queue so that Guaranteed messages published to those topics are also delivered to the Queue.

• Only a Queue Endpoint can be used.
• Only a Topic subscription can be used.
• Must have modify-topic permissions on the Endpoint.

Adding subscriptions to remote clients

A subscription manager client may add subscriptions on behalf of other clients. These topic subscriptions are not retained in the subscription cache and will not be reapplied upon reconnection.

• Only a ClientName Endpoint can be used.
• Only a Topic subscription can be used.
• Must have subscription-manager permissions on the client username.

General notes

If subscribe Flag JCSMPSession.WAIT_FOR_CONFIRM is specified, the API waits for a response before returning, otherwise the API returns immediately after sending the update to the appliance. If JCSMPSession.WAIT_FOR_CONFIRM is not specified, negative responses are delivered to the session event handler. On a Session where no Session event handler is set, an OperationNotSupportedException is thrown if JCSMPSession.WAIT_FOR_CONFIRM is not specified.

JCSMPProperties.REAPPLY_SUBSCRIPTIONS will only apply direct topic subscriptions unpon a Session reconnect. It will not reapply topic subscriptions on durable and non-durable endpoints.

Parameters:

endpoint - The Endpoint to add the subscription on. If null, behaves like JCSMPSession.addSubscription(Subscription, boolean).

subscription - The subscription to add.

subscribeFlags - The valid flag is JCSMPSession.WAIT_FOR_CONFIRM

Throws:

IllegalArgumentException - If the provided Endpoint or subscription is invalid.

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_INVALID
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_ALREADY_PRESENT
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_TOO_MANY
• JCSMPErrorResponseSubcodeEx.OUT_OF_RESOURCES
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_ACL_DENIED
• JCSMPErrorResponseSubcodeEx.UNKNOWN_QUEUE_NAME
• JCSMPErrorResponseSubcodeEx.UNKNOWN_CLIENT_NAME
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_MANAGER_DENIED

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.

removeSubscription

void removeSubscription(Endpoint endpoint,
                        Subscription subscription,
                        int unsubscribeFlags)
                 throws JCSMPException

Removes a subscription from an Endpoint on the appliance. Used to remove subscriptions added by the JCSMPSession.addSubscription(Endpoint, Subscription, int) method. Refer to that method's documentation for operational parameters. This method cannot remove subscriptions added through the CLI.

Parameters:

endpoint - The Endpoint to remove the subscription from. If null, behaves like JCSMPSession.removeSubscription(Subscription, boolean).

subscription - The subscription to remove.

unsubscribeFlags - Valid flag is JCSMPSession.WAIT_FOR_CONFIRM

Throws:

IllegalArgumentException - If the provided Endpoint or subscription is invalid.

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_INVALID
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_NOT_FOUND
• JCSMPErrorResponseSubcodeEx.UNKNOWN_QUEUE_NAME
• JCSMPErrorResponseSubcodeEx.UNKNOWN_CLIENT_NAME
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_MANAGER_DENIED

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.

applySubscriptions

void applySubscriptions(Set<Subscription> subscriptions)
                 throws JCSMPException

Uses the subscription refresh feature to override the subscriptions and subscription filters associated with a subscriber on the appliance with a given list of subscriptions.

The application can call this method at any time to initiate a subscription refresh. Only valid if the Session is operating in non-client mode.

Parameters:

subscriptions - A Set<Subscription> of Subscription objects.

Throws:

IllegalArgumentException - If a destination is invalid in the current Session mode.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.

getMessageProducer

XMLMessageProducer getMessageProducer(JCSMPStreamingPublishEventHandler callback)
                               throws JCSMPException

Get an instance of XMLMessageProducer.

NOTE: For a given JCSMPSession, this method returns a new XMLMessageProducer object on each call, closing the existing producer if it exists.

NOTE: To monitor transport events in publish only applications it is necessary to create an empty XMLMessageConsumer. see JCSMPSession.getMessageConsumer(JCSMPReconnectEventHandler, XMLMessageListener).

Parameters:

callback - A mandatory callback handler to set. By setting a callback handler, any send returns immediately without confirming the successful delivery of the message. Applications receive a response (when applicable) to the send asynchronously through the callback.

Returns:

The message producer.

Throws:

JCSMPException - If acquiring the message producer failed.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPErrorResponseException - If the operation fails with an error response, see JCSMPErrorResponseSubcodeEx for login failures.

IllegalArgumentException - If callback is not provided and the Session is operating in client mode.

getMessageProducer

XMLMessageProducer getMessageProducer(JCSMPStreamingPublishEventHandler streamCallback,
                                      JCSMPProducerEventHandler eventCallback)
                               throws JCSMPException

Get an instance of XMLMessageProducer.

NOTE: For a given JCSMPSession, this method returns a new XMLMessageProducer object on each call, closing the existing producer if it exists.

NOTE: To monitor transport events in publish only applications it is necessary to create an empty XMLMessageConsumer. see JCSMPSession.getMessageConsumer(JCSMPReconnectEventHandler, XMLMessageListener).

Parameters:

streamCallback - A mandatory stream callback handler to set. By setting a callback handler, any send returns immediately without confirming the successful delivery of the message. Applications receive a response (when applicable) to the send asynchronously through the callback.

eventCallback - A producer event handler.

Returns:

The message producer.

Throws:

JCSMPException - If acquiring the message producer failed.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPErrorResponseException - If the operation fails with an error response, see JCSMPErrorResponseSubcodeEx for login failures.

IllegalArgumentException - If callback is not provided and the Session is operating in client mode.

Since:

7.1.2

getMessageProducer

XMLMessageProducer getMessageProducer()
                               throws JCSMPException

Deprecated. Please see JCSMPSession.getMessageProducer(JCSMPStreamingPublishEventHandler). Note that using this deprecated method can introduce a performance penalty during a streaming publishing Session because it forces the appliance to transmit acknowledgements to every message. Using the recommended JCSMPSession.getMessageProducer(JCSMPStreamingPublishEventHandler) form eliminates this problem.

Throws:

JCSMPException

getMessageConsumer

XMLMessageConsumer getMessageConsumer(XMLMessageListener listener)
                               throws JCSMPException

Get a default XMLMessageConsumer. The default XMLMessageConsumer is used to receive direct messages.

NOTE: For a given JCSMPSession, this method returns a new XMLMessageConsumer object on each call, closing the existing consumer if it exists.

Parameters:

listener - Sets the message consumer's message listener. By setting a message listener, the message consumer works in asynchronous mode. Setting the message listener to ((XMLMessageListener)null) puts the message consumer in synchronous delivery mode.

Returns:

The message consumer.

Throws:

JCSMPException - If acquiring the message consumer failed.

JCSMPErrorResponseException - If the operation fails with an error response, see JCSMPErrorResponseSubcodeEx for login failures.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

getMessageConsumer

XMLMessageConsumer getMessageConsumer()
                               throws JCSMPException

Deprecated. Please see JCSMPSession.getMessageConsumer(XMLMessageListener).

Throws:

JCSMPException

getMessageConsumer

XMLMessageConsumer getMessageConsumer(JCSMPReconnectEventHandler reconnectHandler,
                                      XMLMessageListener listener)
                               throws JCSMPException

Get a default XMLMessageConsumer with a reconnect event handler. The default XMLMessageConsumer is used to receive direct messages.

If auto-reconnect is enabled through the subscriber data channel's reconnectRetries in JCSMPChannelProperties, upon detecting the loss of the connection, JCSMPReconnectEventHandler.preReconnect() is called before JCSMP attempts to reestablish the connection with the appliance. If the method call returns the value false, the auto-reconnect process aborts. If the method call returns the value true, auto-reconnect process starts. When the connection is established successfully, JCSMPReconnectEventHandler.postReconnect() is called. To detect a permanent loss of a connection (when retries are exhausted) the method XMLMessageListener.onException(JCSMPException) will be called.

NOTE: For a given JCSMPSession, this method returns a new XMLMessageConsumer object on each call, closing the existing consumer if it exists.

Parameters:

reconnectHandler - An implementation of JCSMPReconnectEventHandler. This is strongly recommended when operating in client mode, since topic subscriptions do not persist between connections on the appliance.

listener - Sets the message consumer's message listener. By setting a message listener, the message consumer works in asynchronous mode. Setting the message listener to null puts the message consumer in synchronous delivery mode.

Returns:

The message consumer.

Throws:

JCSMPException - If acquiring the message consumer failed.

JCSMPErrorResponseException - If the operation fails with an error response, see JCSMPErrorResponseSubcodeEx for login failures.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

getMessageConsumer

XMLMessageConsumer getMessageConsumer(JCSMPReconnectEventHandler reconnectHandler)
                               throws JCSMPException

Deprecated. Please see JCSMPSession.getMessageConsumer(JCSMPReconnectEventHandler, XMLMessageListener).

Throws:

JCSMPException

getMessageConsumer

@Deprecated
XMLMessageConsumer getMessageConsumer(SubscriptionStateProvider subscriptionStateProvider,
                                                  XMLMessageListener listener)
                                           throws JCSMPException

Deprecated. Subscriptions out-of-sync checking is no longer supported. This method will be removed in a future version.

Get an instance of XMLMessageConsumer with subscriptions out-of-sync checking.

If the subscriptions on the appliance are not in sync with the SubscriptionState returned from SubscriptionStateProvider, SubscriptionsOutOfSynchException is raised.

NOTE: For a given JCSMPSession, this method returns a new XMLMessageConsumer object on each call, closing the existing consumer, if applicable.

Parameters:

subscriptionStateProvider - An implementation of SubscriptionStateProvider.

listener - Sets the message consumer's message listener. By setting a message listener, the message consumer works in asynchronous mode. Setting the message listener to null puts the message consumer in synchronous delivery mode.

Returns:

The message consumer.

Throws:

JCSMPException - If acquiring the message consumer failed.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

getMessageConsumer

XMLMessageConsumer getMessageConsumer(SubscriptionStateProvider subscriptionStateProvider)
                               throws JCSMPException

Deprecated. Please see JCSMPSession.getMessageConsumer(SubscriptionStateProvider, XMLMessageListener).

Throws:

JCSMPException

getMessageConsumer

@Deprecated
XMLMessageConsumer getMessageConsumer(SubscriptionStateProvider subscriptionStateProvider,
                                                  JCSMPReconnectEventHandler reconnectHandler,
                                                  XMLMessageListener listener)
                                           throws JCSMPException

Deprecated. Subscriptions out-of-sync checking is no longer supported. This method will be removed in a future version.

Get an instance of XMLMessageConsumer with subscriptions out-of-sync checking and reconnect event handler.

If the subscriptions on the appliance are not in sync with the SubscriptionState returned from SubscriptionStateProvider, SubscriptionsOutOfSynchException is raised.

If auto-reconnect is enabled through the subscriber data channel's reconnectRetries in JCSMPChannelProperties, when detecting the loss of the connection, JCSMPReconnectEventHandler.preReconnect() is called before JCSMP attempts to re-establish the connection with the appliance. If the method call returns the value false, the auto-reconnect process aborts. If the method call returns the value true, the auto-reconnect process starts. When the connection is established successfully, JCSMPReconnectEventHandler.postReconnect() is called.

NOTE: For a given JCSMPSession, this method returns a new XMLMessageConsumer object on each call, closing the existing consumer, if applicable.

Parameters:

subscriptionStateProvider - An implementation of SubscriptionStateProvider.

listener - Sets the message consumer's message listener. By setting a message listener, the message consumer works in asynchronous mode. Setting the message listener to null puts the message consumer in synchronous delivery mode.

Returns:

The message consumer.

Throws:

JCSMPException - If acquiring the message consumer failed.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

getMessageConsumer

@Deprecated
XMLMessageConsumer getMessageConsumer(SubscriptionStateProvider subscriptionStateProvider,
                                                  JCSMPReconnectEventHandler reconnectHandler)
                                           throws JCSMPException

Deprecated. Please see JCSMPSession.getMessageConsumer(SubscriptionStateProvider, JCSMPReconnectEventHandler, XMLMessageListener).

Throws:

JCSMPException

createFlow

FlowReceiver createFlow(Endpoint endpoint,
                        Subscription newSubscription,
                        XMLMessageListener listener)
                 throws JCSMPException

Get an instance of FlowReceiver bound to a appliance Endpoint, such as a Queue or TopicEndpoint. Each time this method is called, it returns a new FlowReceiver object.

Parameters:

endpoint - The appliance Endpoint to bind to.

newSubscription - If binding to a TopicEndpoint the Topic to set/replace as a topic subscription on the endpoint. This must be specified for a TopicEndpoint, null otherwise.

listener - (optional) A callback listener to be used for asynchronous notification. If null, synchronous notification is used.

Returns:

A new FlowReceiver instance.

Throws:

OperationNotSupportedException - If the Session configuration does not allow the operation.

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.CANNOT_BIND_TO_QUEUE
• JCSMPErrorResponseSubcodeEx.ENDPOINT_ALREADY_EXISTS
• JCSMPErrorResponseSubcodeEx.PERMISSION_NOT_ALLOWED
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_QUEUE
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_TE
• JCSMPErrorResponseSubcodeEx.UNKNOWN_QUEUE_NAME
• JCSMPErrorResponseSubcodeEx.UNKNOWN_TE_NAME
• JCSMPErrorResponseSubcodeEx.QUEUE_SHUTDOWN
• JCSMPErrorResponseSubcodeEx.TE_SHUTDOWN
• JCSMPErrorResponseSubcodeEx.NO_MORE_NON_DURABLE_QUEUE_OR_TE
• JCSMPErrorResponseSubcodeEx.INVALID_TOPIC_NAME_FOR_TE

InvalidOperationException - If the peer capabilities do not support features requested in this operation.

JCSMPException - Other error cases.

createFlow

FlowReceiver createFlow(XMLMessageListener listener,
                        ConsumerFlowProperties flowProps)
                 throws JCSMPException

Get an instance of FlowReceiver bound to an appliance Endpoint, such as a Queue or TopicEndpoint. This method returns a new FlowReceiver object each time it is called.

Note: If the flow's message acknowledge mode is JCSMPProperties.SUPPORTED_MESSAGE_ACK_AUTO (the default behaviour), then the call to this method is ignored and a warning log is generated.

Parameters:

listener - (optional) A callback listener to be used for asynchronous notification. If null, synchronous notification is used.

flowProps - Consumer flow properties, like Guaranteed message window size, Endpoint to bind to, and so on.

Returns:

A new FlowReceiver instance.

Throws:

OperationNotSupportedException - If the Session configuration does not allow the operation.

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.CANNOT_BIND_TO_QUEUE
• JCSMPErrorResponseSubcodeEx.ENDPOINT_ALREADY_EXISTS
• JCSMPErrorResponseSubcodeEx.PERMISSION_NOT_ALLOWED
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_QUEUE
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_TE
• JCSMPErrorResponseSubcodeEx.UNKNOWN_QUEUE_NAME
• JCSMPErrorResponseSubcodeEx.UNKNOWN_TE_NAME
• JCSMPErrorResponseSubcodeEx.QUEUE_SHUTDOWN
• JCSMPErrorResponseSubcodeEx.TE_SHUTDOWN
• JCSMPErrorResponseSubcodeEx.NO_MORE_NON_DURABLE_QUEUE_OR_TE
• JCSMPErrorResponseSubcodeEx.INVALID_TOPIC_NAME_FOR_TE
• JCSMPErrorResponseSubcodeEx.SUBSCRIPTION_MATCH_ERROR
• JCSMPErrorResponseSubcodeEx.SELECTOR_MATCH_ERROR
• JCSMPErrorResponseSubcodeEx.SELECTOR_INVALID

InvalidOperationException - If the peer capabilities do not support features requested in this operation.

JCSMPException - Other error cases.

createFlow

FlowReceiver createFlow(XMLMessageListener listener,
                        ConsumerFlowProperties flowProps,
                        EndpointProperties endpointProps)
                 throws JCSMPException

Get an instance of FlowReceiver bound to an appliance Endpoint, such as a Queue or TopicEndpoint. This method returns a new FlowReceiver object each time it is called.

Parameters:

listener - (optional) A callback listener to be used for asynchronous notification. If null, synchronous notification is used.

flowProps - Consumer flow properties, like Guaranteed message window size, Endpoint to bind to, and so on.

endpointProps - (optional) Endpoint properties for the created temporary Endpoint (when binding to a temporary / non-durable Endpoint). If null, default Endpoint properties are applied by the appliance.

Returns:

A new FlowReceiver instance.

Throws:

OperationNotSupportedException - If the Session configuration does not allow the operation.

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.CANNOT_BIND_TO_QUEUE
• JCSMPErrorResponseSubcodeEx.ENDPOINT_ALREADY_EXISTS
• JCSMPErrorResponseSubcodeEx.PERMISSION_NOT_ALLOWED
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_QUEUE
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_TE
• JCSMPErrorResponseSubcodeEx.UNKNOWN_QUEUE_NAME
• JCSMPErrorResponseSubcodeEx.UNKNOWN_TE_NAME
• JCSMPErrorResponseSubcodeEx.QUEUE_SHUTDOWN
• JCSMPErrorResponseSubcodeEx.TE_SHUTDOWN
• JCSMPErrorResponseSubcodeEx.NO_MORE_NON_DURABLE_QUEUE_OR_TE
• JCSMPErrorResponseSubcodeEx.INVALID_TOPIC_NAME_FOR_TE

InvalidOperationException - If the peer capabilities do not support features requested in this operation.

JCSMPException - Other error cases.

createFlow

FlowReceiver createFlow(XMLMessageListener listener,
                        ConsumerFlowProperties flowProps,
                        EndpointProperties endpointProps,
                        FlowEventHandler flowEventHandler)
                 throws JCSMPException

Get an instance of FlowReceiver bound to an appliance Endpoint, such as a Queue or TopicEndpoint. This method returns a new FlowReceiver object each time it is called.

Parameters:

listener - (optional) A callback listener to be used for asynchronous notification. If null, synchronous notification is used.

flowProps - Consumer flow properties, like Guaranteed message window size, Endpoint to bind to, and so on.

endpointProps - (optional) Endpoint properties for the created temporary Endpoint (when binding to a temporary / non-durable Endpoint). If null, default Endpoint properties are applied by the appliance.

flowEventHandler - (optional) A callback listener registered to a flow to receive flow active or flow inactive event if active flow indication is set to true in the consumer flow properties. See ConsumerFlowProperties.setActiveFlowIndication(boolean).

Returns:

A new FlowReceiver instance.

Throws:

OperationNotSupportedException - If the Session configuration does not allow the operation.

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.CANNOT_BIND_TO_QUEUE
• JCSMPErrorResponseSubcodeEx.ENDPOINT_ALREADY_EXISTS
• JCSMPErrorResponseSubcodeEx.PERMISSION_NOT_ALLOWED
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_QUEUE
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_TE
• JCSMPErrorResponseSubcodeEx.UNKNOWN_QUEUE_NAME
• JCSMPErrorResponseSubcodeEx.UNKNOWN_TE_NAME
• JCSMPErrorResponseSubcodeEx.QUEUE_SHUTDOWN
• JCSMPErrorResponseSubcodeEx.TE_SHUTDOWN
• JCSMPErrorResponseSubcodeEx.NO_MORE_NON_DURABLE_QUEUE_OR_TE
• JCSMPErrorResponseSubcodeEx.INVALID_TOPIC_NAME_FOR_TE

InvalidOperationException - If the peer capabilities do not support features requested in this operation.

InvalidPropertiesException - If active flow indication is set to true in the consumer properties, but flow event handler parameter is set to null.

JCSMPException - Other error cases.

logFlowInfo

void logFlowInfo(JCSMPLogLevel level)

Outputs a log at the specified log level that contains the flow state information for flows in this Session.

Parameters:

level - The level (corresponding to org.apache.commons.logging levels) at which to output the log.

unsubscribeDurableTopicEndpoint

void unsubscribeDurableTopicEndpoint(DurableTopicEndpoint endpoint)
                              throws JCSMPException

Unsubscribe from the durable Topic Endpoint. This method can only be called if no clients are currently bound to the Endpoint. Unsubscribing from the durable Topic Endpoint causes any spooled messages on this Endpoint to be deleted.

This method is only valid if the Session is operating in non-client mode.

Parameters:

endpoint - The durable Topic Endpoint on the appliance to unsubscribe from.

Throws:

JCSMPErrorResponseException - If the unsubscribe command is rejected. With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.UNKNOWN_TE_NAME

JCSMPException - On any other error.

setProperty

void setProperty(String property,
                 Object value)
          throws JCSMPException

Sets a modifiable Session property once the Session has been constructed.

Modifiable properties include:

• APPLICATION_DESCRIPTION (in TBRM only)
• CLIENT_NAME (in TBRM only)
• JCSMPProperties.OAUTH2_ACCESS_TOKEN
• JCSMPProperties.OIDC_ID_TOKEN

Note: Modifying a Session property while the channel to the appliance is disconnected can cause it to connect and go through the authentication process. Modification of a Session property may or may not occur instantly or may occur during the next session reconnection. Modification of a Session property during ongoing session reconnection may apply to the next session reconnection attempt.

Parameters:

property - The name of the property to modify.

value - The new value of the property.

Throws:

IllegalArgumentException - If the specified property cannot be modified in the current Session mode, or the provided value is invalid.

JCSMPTransportException - If a transport error occurs.

JCSMPErrorResponseException - If the appliance rejects the modification.

JCSMPException - On other errors.

getProperty

Object getProperty(String property)

Gets a Session property.

Parameters:

property - The requested property name.

Returns:

The requested property, or null if it does not exist.

createCacheSession

CacheSession createCacheSession(CacheSessionProperties properties)
                         throws JCSMPException

Creates a CacheSession using the provided CacheSession properties.

Parameters:

properties - Properties for the CacheSession.

Returns:

The created CacheSession.

Throws:

JCSMPException - on error

createRequestor

Requestor createRequestor()
                   throws JCSMPException

Creates a new Requestor for this Session. Applications are responsible for having previously created an XMLMessageProducer and XMLMessageConsumer on this Session. The XMLMessageConsumer must be started before performing a request.

Returns:

A new Requestor instance.

Throws:

JCSMPException - on error

createNonDurableTopicEndpoint

TopicEndpoint createNonDurableTopicEndpoint()
                                     throws JCSMPException

Creates a non-durable Topic Endpoint. It must be bound to by a consumer on this Session. This operation requires that the Session be previously connected to the appliance, as appliance capabilities must be populated to create non-durable entities.

Returns:

A new non-durable Topic Endpoint.

Throws:

JCSMPException - on error

createNonDurableTopicEndpoint

TopicEndpoint createNonDurableTopicEndpoint(String name)
                                     throws JCSMPException

Creates a non-durable Topic Endpoint based on the given name. The Topic Endpoint should only be bound to by a consumer on this Session. This operation requires that the Session be previously connected to the appliance, as appliance capabilities must be populated to create non-durable entities.

Parameters:

name - The name of the non-durable Topic Endpoint.

Returns:

A new non-durable Topic Endpoint.

Throws:

JCSMPException - on error

createTemporaryQueue

Queue createTemporaryQueue()
                    throws JCSMPException

Creates a temporary Queue for this Session. This Queue should only be bound to by a consumer on this Session; although other Sessions can publish to it.

This operation requires that the Session be previously connected to the appliance, as appliance capabilities must be populated to create non-durable entities.

Returns:

A new non-durable Queue.

Throws:

JCSMPException - on error

createTemporaryQueue

Queue createTemporaryQueue(String name)
                    throws JCSMPException

Creates a temporary Queue with the given name. This Queue should only be bound to by a consumer on this Session; although other Sessions can publish to it. This operation requires that the Session be previously connected to the appliance, as appliance capabilities must be populated to create non-durable entities.

Parameters:

name - The name of the temporary Queue.

Returns:

A new non-durable Queue.

Throws:

JCSMPException - on error

createTemporaryTopic

Topic createTemporaryTopic()
                    throws JCSMPException

Creates a temporary Topic for this Session. This Topic should only be bound to by a consumer on this Session; although other Sessions can publish to it. This operation requires that the Session be previously connected to the appliance, as appliance capabilities must be populated to create non-durable entities. The temporary Topic's physical name is fully generated by JCSMP to provide uniqueness.

Returns:

A new temporary Topic.

Throws:

JCSMPException - on error

getCapability

Object getCapability(CapabilityType type)
              throws JCSMPException

Gets the value of a capability for the currently connected Session.

The returned value is an object of the type specified in CapabilityType.

This operation requires that the Session be previously connected to the appliance. If the Session is not connected, requesting a capability will throw InvalidOperationException. Otherwise, the last known value reported is returned.

Returns:

The value of the specified capability.

Throws:

JCSMPException

isCapable

boolean isCapable(CapabilityType ctype)

Checks if the specified capability is set on the currently connected Session. This is a convenience function to be used with Boolean capabilities. It throws IllegalArgumentException if the provided key does not allow conversion of the value to boolean.

If the Session has never been connected, requesting a capability returns false. Otherwise, the last known value is returned.

Parameters:

ctype - The capability to check.

Returns:

Whether this capability is set.

Throws:

IllegalArgumentException - If the specified key has a value that cannot be converted to boolean.

connect

void connect()
      throws JCSMPException

Connect to the appliance. This operation establishes channels for publishing and subscribing, and authenticates with the appliance. If the Session is already connected, this call has no effect. Although a JCSMPSession can be connected as a side effect of requesting a producer or consumer, as best practice it is recommended to always explicitly connect before.

After connect() returns, the Session is connected to the appliance. At this point, the appliance's information and capabilities are populated, and can be queried by JCSMPSession.getCapability(CapabilityType). Some Session operations require the Session to be connected before attempting them, such as:

• JCSMPSession.createNonDurableTopicEndpoint()
• JCSMPSession.createTemporaryQueue()
• JCSMPSession.createTemporaryTopic()
• JCSMPSession.getCapability(CapabilityType)

Throws:

JCSMPTransportException - If a connection exception occurs.

JCSMPException - On other failures.

getSubscriptionCache

Set<Subscription> getSubscriptionCache()

Gets an unmodifiable view of the Session's subscription cache. The set is empty if JCSMPProperties.REAPPLY_SUBSCRIPTIONS is disabled.

Returns:

An unmodifiable view of the Session's subscription cache.

provision

void provision(Endpoint endpoint,
               EndpointProperties props,
               long provisionFlags)
        throws JCSMPException

Provisions an Endpoint on the appliance. Provisioning operations are not retried upon failure or timeout, regardless of Session auto-reconnection settings.

Allowed flags for the provisioning operation include:

• JCSMPSession.FLAG_IGNORE_ALREADY_EXISTS

Parameters:

endpoint - Endpoint to provision.

props - Properties for the provisioned Endpoint.

provisionFlags - Provisioning flags.

Throws:

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.ENDPOINT_ALREADY_EXISTS
• JCSMPErrorResponseSubcodeEx.ENDPOINT_PROPERTY_MISMATCH
• JCSMPErrorResponseSubcodeEx.DELETE_IN_PROGRESS
• JCSMPErrorResponseSubcodeEx.OUT_OF_RESOURCES
• JCSMPErrorResponseSubcodeEx.NO_MORE_NON_DURABLE_QUEUE_OR_TE

JCSMPException - on error

deprovision

void deprovision(Endpoint endpoint,
                 long deprovisionFlags)
          throws JCSMPException

Deprovisions an Endpoint on the appliance. Provisioning operations are not retried upon failure or timeout, regardless of Session auto-reconnection settings.

Allowed flags for the deprovisioning operation include:

• JCSMPSession.FLAG_IGNORE_DOES_NOT_EXIST

Parameters:

endpoint - The Endpoint to deprovision.

deprovisionFlags - Deprovisioning flags.

Throws:

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.UNKNOWN_QUEUE_NAME
• JCSMPErrorResponseSubcodeEx.UNKNOWN_TE_NAME
• JCSMPErrorResponseSubcodeEx.PERMISSION_NOT_ALLOWED

JCSMPException - on error

createBrowser

Browser createBrowser(BrowserProperties properties)
               throws JCSMPException

Creates a Browser, which can be used for browsing the contents of a Queue.

Parameters:

properties - The Browser properties used for creation.

Throws:

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.CANNOT_BIND_TO_QUEUE
• JCSMPErrorResponseSubcodeEx.PERMISSION_NOT_ALLOWED
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_QUEUE
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_TE
• JCSMPErrorResponseSubcodeEx.UNKNOWN_QUEUE_NAME
• JCSMPErrorResponseSubcodeEx.UNKNOWN_TE_NAME
• JCSMPErrorResponseSubcodeEx.QUEUE_SHUTDOWN
• JCSMPErrorResponseSubcodeEx.TE_SHUTDOWN

JCSMPException - on other exceptions.

createBrowser

Browser createBrowser(BrowserProperties properties,
                      FlowEventHandler flowEventHandler)
               throws JCSMPException

Creates a Browser, which can be used for browsing the contents of a Queue.

Parameters:

properties - The Browser properties used for creation.

flowEventHandler - (optional) A callback listener registered to a flow to receive flow active or flow inactive event if active flow indication is set to true in the consumer flow properties. See ConsumerFlowProperties.setActiveFlowIndication(boolean).

Throws:

JCSMPErrorResponseException - With detailed error information on error responses from the appliance. Error response subcodes:

• JCSMPErrorResponseSubcodeEx.CANNOT_BIND_TO_QUEUE
• JCSMPErrorResponseSubcodeEx.PERMISSION_NOT_ALLOWED
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_QUEUE
• JCSMPErrorResponseSubcodeEx.MAX_CLIENTS_FOR_TE
• JCSMPErrorResponseSubcodeEx.UNKNOWN_QUEUE_NAME
• JCSMPErrorResponseSubcodeEx.UNKNOWN_TE_NAME
• JCSMPErrorResponseSubcodeEx.QUEUE_SHUTDOWN
• JCSMPErrorResponseSubcodeEx.TE_SHUTDOWN

JCSMPException - on other exceptions.

createTransactedSession

TransactedSession createTransactedSession()
                                   throws JCSMPException

Creates a new TransactedSession with the connected appliance. This call blocks until the TransactedSession is successfully created.

Returns:

A new TransactedSession.

Throws:

JCSMPException - on error

Since:

5.3

addSubscription

void addSubscription(Subscription subscription,
                     JCSMPResponseListener handler,
                     Object key)
              throws JCSMPException

Adds a subscription asynchronously to the appliance. The API returns immediately after sending an add subscription request to the appliance. A router confirmation will be delivered to the subscription event handler instead.

Parameters:

subscription - The subscription to add.

handler - The subscription event handler

key - The correlation key of the add subscription operation

Throws:

IllegalArgumentException - if a provided destination is invalid in the current Session mode.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.

addSubscription

void addSubscription(Endpoint endpoint,
                     Subscription subscription,
                     JCSMPResponseListener handler,
                     Object key)
              throws JCSMPException

Adds a subscription asynchronously to an Endpoint on the appliance. The Endpoint targeted can be either a Queue or a ClientName. Guaranteed messages are published to a Queue when it is set as the destination of the message. However, you can also add one or more topic subscriptions to a durable or temporary queue so that Guaranteed messages published to those topics are also delivered to the Queue.

• Only a Queue Endpoint can be used.
• Only a Topic subscription can be used.
• Must have modify-topic permissions on the Endpoint.

Adding subscriptions to remote clients

A subscription manager client may add subscriptions on behalf of other clients. These topic subscriptions are not retained in the subscription cache and will not be reapplied upon reconnection.

• Only a ClientName Endpoint can be used.
• Only a Topic subscription can be used.
• Must have subscription-manager permissions on the client username.

General notes

The API returns immediately after sending an add subscription request to the appliance. A router confirmation will be delivered to the subscription event handler instead.

JCSMPProperties.REAPPLY_SUBSCRIPTIONS will not reapply topic subscriptions on durable and non-durable endpoints.

Parameters:

endpoint - The Endpoint to add the subscription on.

subscription - The subscription to add.

handler - The subscription event handler

key - The correlation key of the add subscription operation

Throws:

IllegalArgumentException - If the provided Endpoint or subscription is invalid.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.

removeSubscription

void removeSubscription(Subscription subscription,
                        JCSMPResponseListener handler,
                        Object key)
                 throws JCSMPException

Removes a subscription asynchronously from the appliance. The API returns immediately after sending a remove subscription request to the appliance. A router confirmation will be delivered to the subscription event handler instead.

Parameters:

subscription - The subscription to remove.

handler - The subscription event handler

key - The correlation key of the remove subscription operation

Throws:

IllegalArgumentException - if a provided destination is invalid in the current Session mode.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.

removeSubscription

void removeSubscription(Endpoint endpoint,
                        Subscription subscription,
                        JCSMPResponseListener handler,
                        Object key)
                 throws JCSMPException

Removes a subscription asynchronously from an Endpoint on the appliance. The API returns immediately after sending a remove subscription request to the appliance. A router confirmation will be delivered to the subscription event handler instead.

Parameters:

endpoint - The Endpoint to remove the subscription from.

subscription - The subscription to remove.

handler - The subscription event handler

key - The correlation key of the remove subscription operation

Throws:

IllegalArgumentException - If the provided Endpoint or subscription is invalid.

OperationNotSupportedException - If performed on a closed Session or a Session not configured for this operation.

JCSMPException - On any other error condition.