progress.message.jclient.mp
Interface Session

All Superinterfaces:

java.lang.Runnable, Session

All Known Subinterfaces:

QueueSession, TopicSession

public interface Session
extends Session

Title: SonicMQ Adaptive Pacing (Managed Client Session)

Description: This is an implementaiton of a Managed Client Session. If this session was created with Adaptive Pacing enabled, it must follow the rules and restrictions below. Standard sessions may be created without any restrictions, but may not make use of the Adaptive Pacing capabilities. In general, sessions are single threaded. Adaptive Pacing preserves this model by safeguarding against concurrent state modifications at the session level. Synchronization occurs at the session level and acts as an additional protection mechanism against concurrent state modifications by multi-threaded applications. Note that on Adaptive Paced sessions each consumer or producer will have a dedicated pacer thread that manages an acknowledgement timer. Further details on this implementation may be found in the documentation on PacerThread. General information regarding the Adaptive Pacing feature are covered in the Connection section. The following restrictions apply to paced sessions:

• Explicit usage of Commit/Rollback is not supported. The method calls will return without doing anything.
• Explicit creation of Transacted Sessions is not supported. Attempting this will throw a JMSException.
• Mixed mode Sessions, that is sessions that define both Producers and Consumers, are not supported. Attempts to create such sessions will result in a JMSException. A given Paced session may only be defined for a Producer or a Consumer. Sessions may not be reused for Mixed Mode purposes. Once created they remain dedicated.
• getTransacted() returns false.
• Since Adaptive Pacing is a Session level setting it is not possible to mix paced and non-paced producers and consumers on the same Session. Furthermore, if using Connection Factory settings obtained from an external Managed JMS Object definition each new Session will automatically inherit these settings from the progress.message.jclient.mp.Connection object. Users that wish to disable Adaptive Pacing for specific Sessions may use the setAdaptivePacing() method prior to session creation to force standard Session creation (ie. conn.setAdaptivePacing(false); ).
• By default, Adaptive Pacing extends to Message Producers and all their derrivatives (ie. Publishers, Senders) as well as Message Consumers (ie. Listeners, Receivers, Durable Subscribers). Batch Size and Timer interval are inherited by each Connection and Session unless overriden prior to object creation.
• Adaptive Pacing does not extend to Connection level methods that utiize Server Session Pools. J2EE Applications wishing to take advantage of Application Server pool are prohibited from participating in Adaptive Pacing. Such applications would have to utilize dedicated sessions in order to take advantage of Adaptive Pacing.

Copyright: Copyright (c) 2006

Company: Progress Software

Version:

2.2

Author:

Dmitry Lelchuk

Field Summary

Fields inherited from interface progress.message.jclient.Session

SINGLE_MESSAGE_ACKNOWLEDGE

Fields inherited from interface javax.jms.Session

AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED

Method Summary

void	close() Closes the session and frees up all the associate structures.
MessageConsumer	createConsumer(Destination destination) Creates a Managed Client message consumer cast to a standard javax.jms.MessageConsumer.
MessageConsumer	createConsumer(Destination destination, java.lang.String messageSelector) Creates a Managed Client message consumer cast to a standard javax.jms.MessageConsumer.
MessageConsumer	createConsumer(Destination destination, java.lang.String messageSelector, boolean NoLocal) Creates a Managed Client message consumer cast to a standard javax.jms.MessageConsumer.
TopicSubscriber	createDurableSubscriber(Topic topic, java.lang.String name) Creates a durable subscriber to the specified topic.
TopicSubscriber	createDurableSubscriber(Topic topic, java.lang.String name, long timeToLive) Creates a DurableSubscriber with the added ability to specify the timeToLive parameter describer as described below.
TopicSubscriber	createDurableSubscriber(Topic topic, java.lang.String name, java.lang.String messageSelector, boolean noLocal) Creates a durable subscriber to the specified topic.
TopicSubscriber	createDurableSubscriber(Topic topic, java.lang.String name, java.lang.String messageSelector, boolean noLocal, long timeToLive) Creates a DurableSubscriber with all relevant options.
MessageProducer	createProducer(Destination destination) Creates a Managed Client message Producer.
boolean	getAdaptivePacing() Indicates wether this session will use Adaptive Pacing.
int	getAdaptivePacingBatchSize() Returns the size of the message batch used by Adaptive Pacing Producers and Consumers.
int	getAdaptivePacingTimer() Returns the interval of Timer for Adaptive Pacing Sessions.
java.lang.String	getSessionID() For Managed Sessions returns a valid unique ID that identifies this Session.
void	setAdaptivePacingBatchSize(int adaptivePacingBatchSize) Sets the size of the Adaptive Pacing Batch for both Producers and Consumers.
void	setAdaptivePacingTimer(int adaptivePacingTimer) Sets the interval of Timer for Adaptive Pacing Sessions for both Producers and Consumers.

Methods inherited from interface progress.message.jclient.Session

commit, commit, createBrowser, createBrowser, createMultipartMessage, createMultiTopic, createQueue, createTemporaryQueue, createTemporaryQueue, createTemporaryTopic, createTopic, createXMLMessage, createXMLMessage, createXMLMessage, getAcknowledgeMode, getDurableMessageOrder, getFlowToDisk, getSessionName, getSplitMultiTopicDelivery, getTxnBatchSize, setAckBatchingEnabled, setDurableMessageOrder, setFlowControlDisabled, setFlowToDisk, setSplitMultiTopicDelivery, setTxnBatchSize, unsubscribe

Methods inherited from interface javax.jms.Session

commit, createBytesMessage, createMapMessage, createMessage, createObjectMessage, createObjectMessage, createStreamMessage, createTextMessage, createTextMessage, getMessageListener, getTransacted, recover, rollback, run, setMessageListener

Method Detail

createProducer

MessageProducer createProducer(Destination destination)
                               throws JMSException

Creates a Managed Client message Producer.

Specified by:

createProducer in interface Session

Parameters:

destination - Destinbation object that is either a Topic, Queue or MultiTopic.

Returns:

A standard message producer that may be cast to Managed Client message producer.

Throws:

JMSException - If anything goes wrong. Some exceptions may be wrapped as Managed Client.

createConsumer

MessageConsumer createConsumer(Destination destination)
                               throws JMSException

Creates a Managed Client message consumer cast to a standard javax.jms.MessageConsumer.

Specified by:

createConsumer in interface Session

Parameters:

destination - Destination for messages of the generic Destination type.

Returns:

A Managed Client Message Consumer.

Throws:

JMSException - If anything goes wrong. Some exceptions may be wrapped as Managed Client.

createConsumer

MessageConsumer createConsumer(Destination destination,
                               java.lang.String messageSelector)
                               throws JMSException

Creates a Managed Client message consumer cast to a standard javax.jms.MessageConsumer.

Specified by:

createConsumer in interface Session

Parameters:

destination - Destination for messages of the generic Destination type.

messageSelector - Message Selector for this consumer.

Returns:

A Managed Client Message Consumer.

Throws:

JMSException - If anything goes wrong. Some exceptions may be wrapped as Managed Client.

createConsumer

MessageConsumer createConsumer(Destination destination,
                               java.lang.String messageSelector,
                               boolean NoLocal)
                               throws JMSException

Creates a Managed Client message consumer cast to a standard javax.jms.MessageConsumer.

Specified by:

createConsumer in interface Session

Parameters:

destination - Destination for messages of the generic Destination type.

messageSelector - Message Selector for this consumer.

NoLocal - If set, inhibits the delivery of messages published by its own connection.

Returns:

A Managed Client Message Consumer.

Throws:

JMSException - If anything goes wrong. Some exceptions may be wrapped as Managed Client.

createDurableSubscriber

TopicSubscriber createDurableSubscriber(Topic topic,
                                        java.lang.String name)
                                        throws JMSException

Creates a durable subscriber to the specified topic.

If a client needs to receive all the messages published on a topic, including the ones published while the subscriber is inactive, it uses a durable TopicSubscriber. The JMS provider retains a record of this durable subscription and insures that all messages from the topic's publishers are retained until they are acknowledged by this durable subscriber or they have expired.

Sessions with durable subscribers must always provide the same client identifier. In addition, each client must specify a name that uniquely identifies (within client identifier) each durable subscription it creates. Only one session at a time can have a TopicSubscriber for a particular durable subscription.

A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and a new topic and/or message selector. Changing a durable subscriber is equivalent to unsubscribing (deleting) the old one and creating a new one.

In some cases, a connection may both publish and subscribe to a topic. The subscriber NoLocal attribute allows a subscriber to inhibit the delivery of messages published by its own connection. The default value for this attribute is false.

Specified by:

createDurableSubscriber in interface Session

Parameters:

topic - The non-temporary Topic to subscribe to.

name - The name used to identify this subscription.

Returns:

A Durable Topic Subscriber.

Throws:

JMSException - If anything goes wrong. Some exceptions may be wrapped as Managed Client.

createDurableSubscriber

TopicSubscriber createDurableSubscriber(Topic topic,
                                        java.lang.String name,
                                        java.lang.String messageSelector,
                                        boolean noLocal)
                                        throws JMSException

Creates a durable subscriber to the specified topic. Provides additional options for specifying message selector and disabling delivery of messages generated by this connection.

Specified by:

createDurableSubscriber in interface Session

Parameters:

topic - The non-temporary Topic to subscribe to.

name - The name used to identify this subscription.

messageSelector - Only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.

noLocal - If set, inhibits the delivery of messages published by its own connection.

Returns:

A Durable Topic Subscriber.

Throws:

JMSException - If anything goes wrong. Some exceptions may be wrapped as Managed Client.

createDurableSubscriber

TopicSubscriber createDurableSubscriber(Topic topic,
                                        java.lang.String name,
                                        long timeToLive)
                                        throws JMSException

Creates a DurableSubscriber with the added ability to specify the timeToLive parameter describer as described below.

Parameters:

topic - The non-temporary Topic to subscribe to.

name - The name used to identify this subscription.

timeToLive - Time in milliseconds that a DurableSubscriber will live for after it has disconnected. The maximum value for timeToLive is (315360000000L) 10 years

NOTE: A timeToLive value <= 0 will result in NOT setting a disconnected timeToLive.

Returns:

A Durable Topic Subscriber.

Throws:

JMSException - If anything goes wrong. Some exceptions may be wrapped as Managed Client.

createDurableSubscriber

TopicSubscriber createDurableSubscriber(Topic topic,
                                        java.lang.String name,
                                        java.lang.String messageSelector,
                                        boolean noLocal,
                                        long timeToLive)
                                        throws JMSException

Creates a DurableSubscriber with all relevant options.

Parameters:

topic - The non-temporary Topic to subscribe to.

name - The name used to identify this subscription.

messageSelector - Only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.

noLocal - If set, inhibits the delivery of messages published by its own connection.

timeToLive - Time in milliseconds that a DurableSubscriber will live for after it has disconnected. The maximum value for timeToLive is (315360000000L) 10 years

NOTE: A timeToLive value <= 0 will result in NOT setting a disconnected timeToLive.

Returns:

A Durable Topic Subscriber.

Throws:

JMSException - If anything goes wrong. Some exceptions may be wrapped as Managed Client.

close

void close()
           throws JMSException

Closes the session and frees up all the associate structures.

Specified by:

close in interface Session

Throws:

JMSException - If something goes wrong.

getSessionID

java.lang.String getSessionID()

For Managed Sessions returns a valid unique ID that identifies this Session.

Returns:

Session ID.

getAdaptivePacing

boolean getAdaptivePacing()

Indicates wether this session will use Adaptive Pacing. This property value is inherited from the Connection object.

Returns:

True if Adaptive Pacing was set on this Session by the Connection, False it was not.

setAdaptivePacingBatchSize

void setAdaptivePacingBatchSize(int adaptivePacingBatchSize)

Sets the size of the Adaptive Pacing Batch for both Producers and Consumers. May be overriden at the individual Producer or Consumer level once they are created.

Parameters:

adaptivePacingBatchSize - Size of message batch.

getAdaptivePacingBatchSize

int getAdaptivePacingBatchSize()

Returns the size of the message batch used by Adaptive Pacing Producers and Consumers. This value is inherited from the Connection object but may be set for a specific Session or individual Producers and Consumers once they are created.

Returns:

Size of message batch.

setAdaptivePacingTimer

void setAdaptivePacingTimer(int adaptivePacingTimer)

Sets the interval of Timer for Adaptive Pacing Sessions for both Producers and Consumers. May be overriden at the individual Producer or Consumer level once they are created.

Parameters:

adaptivePacingTimer - Message operation acknowledgement timer interval in milliseconds.

getAdaptivePacingTimer

int getAdaptivePacingTimer()

Returns the interval of Timer for Adaptive Pacing Sessions. Used by Producers and Consumers. This value is inherited from the Connection object but may be set for a specific Session or individual Producers and Consumers once they are created.

Returns:

Timer interval for Adaptive Pacing Timer Thread.