com.solacesystems.jcsmp

Interface Session

All Known Subinterfaces:

JCSMPSession

public interface Session

Session represents the main application interface.

Introduction

JCSMP is the Java implementation of the Solace Content Subscription Management Protocol (CSMP). It provides a programming interface for applications interacting with a Solace appliance. The following protocol stack is supported:

                             +---------------------------------------+
                             |                 JCSMP                 |
                             +---------------------------------------+
                             |                  CSMP                 |
                             +---------------------------------------+
                             |                  SMF                  |
                             +---------------------------------------+
                             |                TCP/IP                 |
                             +---------------------------------------+
                             
                              (SMF stands for Solace Message Format.)
 

Session

Session provides these major functions:

• Session lifecycle control, such as initializing and closing.
• Subscriber management
• Access to associated statistics.

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

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

Message Types

The following message delivery modes can be used for publishing:

Persistent and Non-Persistent

The appliance guarantees delivery to subscribers. These messages are always spooled in the Solace Messaging Platform and delivered in order. Refer to XMLMessage for more details.

Persistent and Non-Persistent messages can only be published over the JCSMPChannelProperties.SUPPORTED_PROTOCOL_STACK_SMF_TCP protocol stack.

Direct

Delivery of the document is not guaranteed (the Solace Message Platform uses a best-effort approach to delivery). Direct messages are never spooled to disk on the appliance, and they can be delivered out of order.

Direct messages can be published over the JCSMPChannelProperties.SUPPORTED_PROTOCOL_STACK_SMF_TCP protocol stack.

Message Acknowledgement Mode

Session supports two message acknowledgement modes: AUTO_ACK and CLIENT_ACK. With AUTO_ACK mode, when delivering each message to the application, the session acknowledges the message to the appliance automatically. With CLIENT_ACK, it is the application's responsibility to acknowledge by calling XMLMessage.ackMessage(). It is also the application's responsibility to have a policy in place to enforce in-time acknowledgement of all messages to avoid repeated delivery of Persistent and Non-Persistent messages.

Exceptions

There are three categories of exceptions defined in JCSMP:

• JCSMPOperationException
• JCSMPTransportException
• JCSMPStateException

Please refer to JCSMPException for details.

Method Summary

Modifier and Type	Method and Description
void	addSubscriber() Deprecated. It is no longer necessary to call this function. This function might be removed in a future version of JCSMP.
void	clearSubscriber() Deprecated. This method is no longer supported. The recommended way to delete subscriptions from the appliance is to perform an applySubscriptions() on the session with an empty subscription list.
void	closeSession() Closes the session.
String	getSessionName() If the session name is specified by JCSMPProperties.SESSION_NAME, this method returns the name specified.
JCSMPSessionStats	getSessionStats() Get this session's statistics.
void	logSessionStats(JCSMPLogLevel level) Outputs a log at the specified log level containing a textual representation of the session statistics.
void	removeSubscriber() Deprecated. Subscribers are now created and removed only through the appliance's management interface. This method has the same effect as Session.clearSubscriber()

Method Detail

getSessionName

String getSessionName()

If the session name is specified by JCSMPProperties.SESSION_NAME, this method returns the name specified. Otherwise, a default name is returned.

Returns:

The session name.

closeSession

void closeSession()

Closes the session. Once a session is closed it must not be used again, an application must instead acquire a new session.

Any XMLMessageProducer, XMLMessageConsumer, and channel connections associated with the session are also closed.

getSessionStats

JCSMPSessionStats getSessionStats()

Get this session's statistics.

Returns:

The session statistics.

logSessionStats

void logSessionStats(JCSMPLogLevel level)

Outputs a log at the specified log level containing a textual representation of the session statistics.

Parameters:

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

clearSubscriber

void clearSubscriber()
              throws JCSMPException

Deprecated. This method is no longer supported. The recommended way to delete subscriptions from the appliance is to perform an applySubscriptions() on the session with an empty subscription list.

Removes a subscriber's CSMP-created subscriptions from the appliance.

Note that if the subscriber has a large number of subscriptions, this operation can take a long time to return. If your application creates subscribers with several thousand subscriptions, it is advisable to increase the session's response timeout from the default, otherwise this operation could fail while waiting for the appliance to respond.

Throws:

JCSMPException - If there was an error clearing the subscriber.

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

addSubscriber

void addSubscriber()
            throws JCSMPException

Deprecated. It is no longer necessary to call this function. This function might be removed in a future version of JCSMP.

Adds a subscriber to the appliance using the user information associated with the Session.

If the user already exists on the appliance, this method still returns success.

Throws:

JCSMPException - If there was an error adding the subscriber.

removeSubscriber

void removeSubscriber()
               throws JCSMPException

Deprecated. Subscribers are now created and removed only through the appliance's management interface. This method has the same effect as Session.clearSubscriber()

Removes a subscriber from the appliance using the user information associated with the Session.

Throws:

JCSMPException - If there was an error removing the subscriber.