com.j_spaces.jms
Class GSTopicSessionImpl

java.lang.Object
  com.j_spaces.jms.GSSessionImpl
      com.j_spaces.jms.GSTopicSessionImpl

All Implemented Interfaces:

Runnable, Session, TopicSession

public class GSTopicSessionImpl
extends GSSessionImpl
implements TopicSession

GigaSpaces implementation of the javax.jms.TopicSession interface. A TopicSession object provides methods for creating TopicPublisher,TopicSubscriber( and TemporaryTopic) objects. It also provides a method for deleting its client's durable subscribers.

A TopicSession is used for creating Pub/Sub specific objects. In general, use the Session object, and use TopicSession only to support existing code. Using the Session object simplifies the programming model, and allows transactions to be used across the two messaging domains.

A TopicSession cannot be used to create objects specific to the point-to-point domain. The following methods inherit from Session , but must throw an IllegalStateException if used from TopicSession:

• createBrowser
• createQueue
• createTemporaryQueue

Field Summary

Fields inherited from class com.j_spaces.jms.GSSessionImpl

ackLeaseTime, invalidSelectorIdentifiers, JMSX_CLIENT_NAMES, m_sessionID, reservedSelectorIdentifiers, txLeaseTime

Fields inherited from interface javax.jms.Session

AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED

Constructor Summary

GSTopicSessionImpl(com.j_spaces.jms.GSConnectionImpl connection, boolean transacted, int acknowledgeMode, Transaction transaction)
Constructs a topic session.

Method Summary

QueueBrowser	createBrowser(Queue arg0)
QueueBrowser	createBrowser(Queue arg0, String arg1)
TopicSubscriber	createDurableSubscriber(Topic topic, String name) API Method.
TopicSubscriber	createDurableSubscriber(Topic topic, String name, String messageSelector, boolean noLocal) Not An API method but a GS usage for createDurableSubscriber().
TopicPublisher	createPublisher(Topic topic) API method Creates a publisher for the specified topic.
Queue	createQueue(String arg0)
TopicSubscriber	createSubscriber(Topic topic) API method.
TopicSubscriber	createSubscriber(Topic topic, String messageSelector, boolean noLocal) API method.
TemporaryQueue	createTemporaryQueue()
TemporaryTopic	createTemporaryTopic() Creates a TemporaryTopic object.
Topic	createTopic(String topicName)
void	unsubscribe(String subscriptionName) Unsubscribes a durable subscription that has been created by a client.

Methods inherited from class com.j_spaces.jms.GSSessionImpl

acknowledge, cancel, close, commit, createBytesMessage, createBytesMessage, createConsumer, createConsumer, createConsumer, createMapMessage, createMapMessage, createMessage, createObjectMessage, createObjectMessage, createProducer, createStreamMessage, createTextMessage, createTextMessage, getAcknowledgeMode, getConsumersC, getJMSProviderName, getMessageListener, getMessagesC, getNumOfConsumedMsg, getNumOfProducedMsg, getProducersC, getSessionID, getTransacted, isLocalConsumer, isLocalProducer, recover, removeExternalEntryFromSpace, removeJMSAckDataEntryFromSpace, rollback, run, setConsumersC, setMessageListener, setMessagesC, setProducersC, setSessionID, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface javax.jms.Session

close, commit, createBytesMessage, createConsumer, createConsumer, createConsumer, createMapMessage, createMessage, createObjectMessage, createObjectMessage, createProducer, createStreamMessage, createTextMessage, createTextMessage, getAcknowledgeMode, getMessageListener, getTransacted, recover, rollback, run, setMessageListener

Constructor Detail

GSTopicSessionImpl

public GSTopicSessionImpl(com.j_spaces.jms.GSConnectionImpl connection,
                          boolean transacted,
                          int acknowledgeMode,
                          Transaction transaction)
                   throws JMSException

Constructs a topic session.

Parameters:

connection - The connection the session belongs to.

transacted - true for a transacted session.

acknowledgeMode - 1 (auto), 2 (client) or 3 (dups ok).

transaction -

Throws:

JMSException - In case of an invalid acknowledge mode.

Method Detail

createSubscriber

public TopicSubscriber createSubscriber(Topic topic)
                                 throws JMSException

API method. Creates a nondurable subscriber to the specified topic.

A client uses a TopicSubscriber object to receive messages that have been published to a topic.

Regular TopicSubscriber objects are not durable. They receive only messages that are published while they are active.

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:

createSubscriber in interface TopicSession

Parameters:

topic - the Topic to subscribe to

Returns:

topic subscriber according to the provided topic

Throws:

JMSException - if the session fails to create a subscriber due to some internal error.

InvalidDestinationException - if an invalid topic is specified.

IllegalStateException - If the session is closed or if the connection is broken.

createSubscriber

public TopicSubscriber createSubscriber(Topic topic,
                                        String messageSelector,
                                        boolean noLocal)
                                 throws JMSException

API method.

Specified by:

createSubscriber in interface TopicSession

Parameters:

topic -

messageSelector -

noLocal -

Throws:

IllegalStateException - If the session is closed or if the connection is broken.

JMSException - If the creation fails for any other reason.

See Also:

TopicSession.createSubscriber(Topic, String, boolean)

createDurableSubscriber

public TopicSubscriber createDurableSubscriber(Topic topic,
                                               String name)
                                        throws JMSException

API Method.

Specified by:

createDurableSubscriber in interface Session

Specified by:

createDurableSubscriber in interface TopicSession

Overrides:

createDurableSubscriber in class GSSessionImpl

Throws:

JMSException

See Also:

Session.createDurableSubscriber(javax.jms.Topic, java.lang.String)

createDurableSubscriber

public TopicSubscriber createDurableSubscriber(Topic topic,
                                               String name,
                                               String messageSelector,
                                               boolean noLocal)
                                        throws JMSException

Not An API method but a GS usage for createDurableSubscriber(). Creates a durable subscriber to the specified topic, using a message selector or specifying whether messages published by its own connection should be delivered to it.

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 which 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. An inactive durable subscriber is one that exists but does not currently have a message consumer associated with it.

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.

Specified by:

createDurableSubscriber in interface Session

Specified by:

createDurableSubscriber in interface TopicSession

Overrides:

createDurableSubscriber in class GSSessionImpl

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

Throws:

JMSException - if the session fails to create a subscriber due to some internal error.

InvalidDestinationException - if an invalid topic is specified.

InvalidSelectorException - if the message selector is invalid.

createTemporaryTopic

public TemporaryTopic createTemporaryTopic()
                                    throws JMSException

Creates a TemporaryTopic object. Its lifetime will be that of the TopicConnection unless it is deleted earlier. We use the same space proxy we obtained in the session and we write another External Entry, which will have a class name of 'TempQueue_ < >. The only message m_consumers that can consume from a temporary destination are those created by the same connection that created the destination. Any message producer can send to the temporary destination. If you close the connection that a temporary destination belongs to, the destination is closed and its contents lost. You can use temporary destinations to implement a simple request/reply mechanism. If you create a temporary destination and specify it as the value of the JMSReplyTo message header field when you send a message, the consumer of the message can use the value of the JMSReplyTo field as the destination to which it sends a reply and can also reference the original request by setting the JMSCorrelationID header field of the reply message to the value of the JMSMessageID header field of the request.

Specified by:

createTemporaryTopic in interface Session

Specified by:

createTemporaryTopic in interface TopicSession

Overrides:

createTemporaryTopic in class GSSessionImpl

Throws:

JMSException

See Also:

Session.createTemporaryQueue()

createPublisher

public TopicPublisher createPublisher(Topic topic)
                               throws JMSException

API method Creates a publisher for the specified topic.

A client uses a TopicPublisher object to publish messages on a topic. Each time a client creates a TopicPublisher on a topic, it defines a new sequence of messages that have no ordering relationship with the messages it has previously sent.

Specified by:

createPublisher in interface TopicSession

Parameters:

topic - the Topic to publish to, or null if this is an unidentified producer

Throws:

JMSException - if the session fails to create a publisher due to some internal error.

InvalidDestinationException - if an invalid topic is specified.

IllegalStateException - If the session is closed or if the connection is broken.

See Also:

TopicSession.createPublisher(Topic topic)

unsubscribe

public void unsubscribe(String subscriptionName)
                 throws JMSException

Unsubscribes a durable subscription that has been created by a client. It basically doing the following: - Checks for matched subscriptionName in one of the session's m_consumers, if it found such, it removes the matched JMSDurableSubDataEntry from the JMSDurableSubService. - It uses the GSJMSAdmin to update the unsubscribe durable subscriber's details from the jms-config.xml file.

This method deletes the state being maintained on behalf of the subscriber by its provider.

It is erroneous for a client to delete a durable subscription while there is an active TopicSubscriber for the subscription, or while a consumed message is part of a pending transaction or has not been acknowledged in the session.

Specified by:

unsubscribe in interface Session

Specified by:

unsubscribe in interface TopicSession

Overrides:

unsubscribe in class GSSessionImpl

Parameters:

subscriptionName - the name used to identify this subscription

Throws:

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

InvalidDestinationException - if an invalid subscription name is specified.

createTopic

public Topic createTopic(String topicName)
                  throws JMSException

Specified by:

createTopic in interface Session

Specified by:

createTopic in interface TopicSession

Overrides:

createTopic in class GSSessionImpl

Throws:

JMSException

See Also:

Session.createTopic(java.lang.String)

createQueue

public Queue createQueue(String arg0)
                  throws JMSException

Specified by:

createQueue in interface Session

Overrides:

createQueue in class GSSessionImpl

Throws:

JMSException

createBrowser

public QueueBrowser createBrowser(Queue arg0)
                           throws JMSException

Specified by:

createBrowser in interface Session

Overrides:

createBrowser in class GSSessionImpl

Throws:

JMSException

createBrowser

public QueueBrowser createBrowser(Queue arg0,
                                  String arg1)
                           throws JMSException

Specified by:

createBrowser in interface Session

Overrides:

createBrowser in class GSSessionImpl

Throws:

JMSException

createTemporaryQueue

public TemporaryQueue createTemporaryQueue()
                                    throws JMSException

Specified by:

createTemporaryQueue in interface Session

Overrides:

createTemporaryQueue in class GSSessionImpl

Throws:

JMSException