com.solacesystems.jcsmp

Interface JCSMPDestinationSession

All Superinterfaces:

Session

All Known Implementing Classes:

JCSMPBasicSession

public interface JCSMPDestinationSession
extends Session

JCSMPDestinationSession

JCSMPDestinationSession provides the following major functions:

• Subscriber control, such as creating/updating destination subscriptions
• Publish messages to a Solace appliance
• Receive messages from a Solace appliance

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

The application is able to refresh its view of subscriber destination subscriptions onto the appliance using JCSMPDestinationSession by implementing the interface DestinationSubscriptionStateProvider. Refer to getMessageConsumer(DestinationSubscriptionStateProvider, DestinationListener), getMessageConsumer(DestinationSubscriptionStateProvider, JCSMPReconnectEventHandler, DestinationListener) and #applySubscriptions(List) for more information.

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

A Destination object encapsulates an address that identifies a Topic (publish/subscribe) or a Queue (point-to-point). In this version, only Topics are supported.

Topic
In the publish/subscribe messaging system currently supported by the Solace appliance, producers address messages to a Topic using a Destination object. In this system, the producer is known as a publisher, and the consumer is known as a subscriber. Many publishers can publish to the same Topic, and a message from a single publisher can be received by many subscribers. Subscribers subscribe to Topics, and all messages published to the Topic are received by all subscribers to each Topic.

Queue
Point-to-point messaging has one producer and one consumer for each message. This messaging system uses a Queue to store messages sent from producers until they are received and acknowledged by consumers.

A client application using a JCSMPDestinationSession uses Destination objects when publishing or subscribing to Topics. The API syntax is the same whether the Destination being used is a Topic or Queue.

Subscriber control

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

To use subscriber control functions, the application must provide JCSMPProperties.CONTROL_CHANNEL_PROPERTIES when acquiring the JCSMPDestinationSession. For subscriber control, the JCSMPChannelProperties.SUPPORTED_PROTOCOL_STACK_SMF_TCP protocol stack is supported.

Note: subscriber control channels do not use keep-alives to detect connection state, and only establish a TCP connection when a subscriber control operation is attempted. If operating a control channel for which the supplied JCSMPProperties.CONTROL_CHANNEL_PROPERTIES have disabled automatic reconnection attempts, the following operations will throw a JCSMPTransportException if the connection has failed since the last control operation:

• JCSMPDestinationSession#addSubscriptions(List)
• JCSMPDestinationSession#applySubscriptions(List)
• JCSMPDestinationSession#removeSubscriptions(List)

An application should re-attempt the control operation if a JCSMPTransportException is raised under such conditions.

Publishing

To publish a message, an application acquires an DestinationProducer from the JCSMPDestinationSession. The application can publish messages in either synchronous publishing mode or asynchronous (or streaming) publishing mode. 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 DestinationProducer when acquiring it.

To use publishing functions, an application must provide JCSMPProperties.PUBLISHER_DATA_CHANNEL_PROPERTIES when acquiring the JCSMPDestinationSession. See "Message Types" section in Session for additional notes on supported message types for each publishing mode. Refer to DestinationProducer for information on how to publish in synchronous or asynchronous modes.

The following protocol stacks are defined for publisher channels:

• JCSMPChannelProperties.SUPPORTED_PROTOCOL_STACK_SMF_TCP
• JCSMPChannelProperties.SUPPORTED_PROTOCOL_STACK_SMFS_TCP [*]

*: Not supported in this version.

Receiving

To receive messages, an application acquires an DestinationConsumer instance from the JCSMPDestinationSession. The application can select to receive messages 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 operate in asynchronous mode, an application must provide an DestinationListener instance to DestinationConsumer when acquiring it.

To use receiving functions, an application must provide JCSMPProperties.SUBSCRIBER_DATA_CHANNEL_PROPERTIES when acquiring the JCSMPDestinationSession.

The following protocol stacks are defined for subscriber channels:

• JCSMPChannelProperties.SUPPORTED_PROTOCOL_STACK_SMF_TCP
• JCSMPChannelProperties.SUPPORTED_PROTOCOL_STACK_SMFS_TCP [*]

*: Not supported in this version.

Method Summary

Modifier and Type	Method and Description
DestinationConsumer	getMessageConsumer(DestinationListener listener) Get the instance of DestinationConsumer.
DestinationConsumer	getMessageConsumer(DestinationSubscriptionStateProvider destinationSubscriptionStateProvider, DestinationListener listener) Get the instance of DestinationConsumer with subscriptions out-of-sync checking.
DestinationConsumer	getMessageConsumer(DestinationSubscriptionStateProvider destinationSubscriptionStateProvider, JCSMPReconnectEventHandler reconnectHandler, DestinationListener listener) Get the instance of DestinationConsumer with subscriptions out-of-sync checking and reconnect event handler.
DestinationConsumer	getMessageConsumer(JCSMPReconnectEventHandler reconnectHandler, DestinationListener listener) Get the instance of DestinationConsumer with a reconnect event handler.
DestinationProducer	getMessageProducer(JCSMPStreamingPublishEventHandler callback, Destination defaultDestination) Get the instance of DestinationProducer.

Methods inherited from interface com.solacesystems.jcsmp.Session

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

Method Detail

getMessageConsumer

DestinationConsumer getMessageConsumer(DestinationListener listener)
                                throws JCSMPException

Get the instance of DestinationConsumer.

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

Parameters:

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

Returns:

The destination consumer.

Throws:

JCSMPException - if acquiring the destination consumer failed.

OperationNotSupportedException - if performed on a closed session or a session not configured for this operation.

getMessageConsumer

DestinationConsumer getMessageConsumer(JCSMPReconnectEventHandler reconnectHandler,
                                       DestinationListener listener)
                                throws JCSMPException

Get the instance of DestinationConsumer with a reconnect event handler.

If auto-reconnect is enabled through the subscriber data channel's reconnectRetries in JCSMPChannelProperties, when connection loss is detected, 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 JCSMPDestinationSession, this method returns a new DestinationConsumer object on each call, closing the existing consumer (if it exists).

Parameters:

reconnectHandler - an instance of a JCSMPReconnectEventHandler

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

Returns:

the destination consumer.

Throws:

JCSMPException - if acquiring the destination consumer failed.

OperationNotSupportedException - if performed on a closed session, or a session not configured for this operation.

getMessageConsumer

DestinationConsumer getMessageConsumer(DestinationSubscriptionStateProvider destinationSubscriptionStateProvider,
                                       DestinationListener listener)
                                throws JCSMPException

Get the instance of DestinationConsumer with subscriptions out-of-sync checking.

If the destination subscriptions on the appliance are not in sync with the DestinationSubscriptionState returned from DestinationSubscriptionStateProvider, SubscriptionsOutOfSynchException is raised.

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

Parameters:

destinationSubscriptionStateProvider - An implementation of DestinationSubscriptionStateProvider.

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

Returns:

The destination consumer.

Throws:

JCSMPException - if acquiring the destination consumer failed.

OperationNotSupportedException - if performed on a closed session, or a session not configured for this operation.

getMessageConsumer

DestinationConsumer getMessageConsumer(DestinationSubscriptionStateProvider destinationSubscriptionStateProvider,
                                       JCSMPReconnectEventHandler reconnectHandler,
                                       DestinationListener listener)
                                throws JCSMPException

Get the instance of DestinationConsumer with subscriptions out-of-sync checking and reconnect event handler.

If the destination subscriptions on the appliance are not in sync with the DestinationSubscriptionState returned from DestinationSubscriptionStateProvider, 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 JCSMPDestinationSession, this method returns a new DestinationConsumer object on each call, closing the existing consumer (if it exists).

Parameters:

destinationSubscriptionStateProvider - An implementation of DestinationSubscriptionStateProvider.

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

Returns:

The destination consumer.

Throws:

JCSMPException - if acquiring the destination consumer failed.

OperationNotSupportedException - if performed on a closed session, or a session not configured for this operation.

getMessageProducer

DestinationProducer getMessageProducer(JCSMPStreamingPublishEventHandler callback,
                                       Destination defaultDestination)
                                throws JCSMPException

Get the instance of DestinationProducer.

NOTE: For a given JCSMPDestinationSession, this method returns a new DestinationProducer object on each call, closing the existing producer (if it exists).

Parameters:

callback - Callback handler to set. By setting a streaming callback handler, any send returns immediately without confirming the successful delivery of the message. Applications receive the response of the send asynchronously through the callback. Setting this to null puts the producer in blocking mode.

defaultDestination - the default Destination. If null, the default Destination is left unset.

Returns:

The destination producer.

Throws:

JCSMPException - if acquiring the destination producer failed.

OperationNotSupportedException - if performed on a closed session, or a session not configured for this operation.