org.exolab.jms.server
Class JmsServerSession

java.lang.Object
  |
  +--org.exolab.jms.server.JmsServerSession

All Implemented Interfaces:

InternalMessageListener, javax.transaction.xa.XAResource

public class JmsServerSession

extends java.lang.Object

implements InternalMessageListener, javax.transaction.xa.XAResource

A session represents a server side endpoint to the JMSServer. A client can create producers, consumers and destinations through the session in addi- tion to other functions. A session has a unique identifer which is a comb- ination of clientId-connectionId-sessionId.

A session represents a single-threaded context which implies that it cannot be used with more than one thread concurrently. Threads registered with this session are synchronized.

Finally, instances of this object can only be created by classes within the same package.

Version:

$Revision: 1.89 $ $Date: 2003/08/17 01:32:26 $

Author:

Jim Alateras, Tim Anderson

See Also:

JmsServerConnection

Fields inherited from interface javax.transaction.xa.XAResource

TMENDRSCAN, TMFAIL, TMJOIN, TMNOFLAGS, TMONEPHASE, TMRESUME, TMSTARTRSCAN, TMSUCCESS, TMSUSPEND, XA_OK, XA_RDONLY

Method Summary

void	acknowledgeMessage(long clientId, java.lang.String id) Acknowledge that the message with the following id has been processed
void	close() Close and release any resource allocated to this session.
void	commit() Commit this session, which will acknowledge all sent messages for all consumers.
void	commit(javax.transaction.xa.Xid xid, boolean onePhase)
boolean	containsUnackedHandle(MessageHandle handle) Check if the specified message handle is in the session's list of unacked messages
void	createBrowser(JmsQueue queue, long clientId, java.lang.String selector) Create a queue browser for this session.
void	createPublisher(JmsTopic topic) This should be a no operation.
void	createQueue(JmsQueue queue) Create an amdinistered queue, through the message manager admin interface.
void	createReceiver(JmsQueue queue, long clientId, java.lang.String selector) Create a receiver endpoint for this session.
void	createSender(JmsQueue queue) This is a no-op
void	createSubscriber(JmsTopic topic, java.lang.String name, long clientId, java.lang.String selector, boolean noLocal) Create a subscriber endpoint for this session.
void	createTopic(JmsTopic topic) Create an administered topic, through the message manager admin interface.
void	deleteBrowser(long clientId) Delete the queue browser associated with the specified queue from the session.
void	deletePublisher(JmsTopic topic) Delete the publisher associated with the specified topic from the session.
void	deleteReceiver(long clientId) Delete the receiver with the specified identity and clean up all associated resources.
void	deleteSender(long clientId) Delete the sender associated with the specified queue from the session If the corresponding sender does not exist or it cannot delete it then throw the JMSException.
void	deleteSubscriber(long clientId) This function deletes a persistent subsrciber and its history from the database.
void	enableAsynchronousDelivery(long clientId, java.lang.String id, boolean enable) Check whether to enable asynchronous message delivery for a particular consumer
void	end(javax.transaction.xa.Xid xid, int flags)
void	forget(javax.transaction.xa.Xid xid)
int	getAckMode() Returns the message acknowledgement mode for the session
java.lang.String	getClientId() Return a reference to the client id
ConsumerEndpoint	getConsumerEndpoint(long clientId) Returns the consumer endpoint for the supplied client id
java.lang.String	getResourceManagerId() Return the identity of the ResourceManager.
java.lang.String	getSessionId() Return a reference to the session id
int	getTransactionTimeout()
javax.transaction.xa.Xid	getXid() Return the xid that is currently associated with this session or null if this session is currently not part of a global transactions
boolean	isClientEndpointActive() This will send a null message down the connection to the client to test whether the client endpoint is alive.
boolean	isSameRM(javax.transaction.xa.XAResource xares)
boolean	isTransacted() Determines if the session is transacted
void	onMessage(MessageHandle handle, boolean ignore) Send the specified message to the client.
void	onMessageAvailable(long clientId) Inform the session that there is a message available for the message consumer with the specified identity
void	onMessages(java.util.Vector handles) Send the specified collection of messages to the client
int	prepare(javax.transaction.xa.Xid xid)
javax.jms.Message	receiveMessage(long clientId, long wait) Return the next message for the specified client.
java.util.Vector	receiveMessages(long clientId, int count) Return up to count messages from the endpoint with the specified client identity.
void	recover() Call recover on all registered consumers.
javax.transaction.xa.Xid[]	recover(int flag)
void	rollback() Abort, will return all unacked messages to their respective endpoints, if they are still active.
void	rollback(javax.transaction.xa.Xid xid)
void	sendMessage(javax.jms.Message message) Send the specified message to the server
void	sendMessages(java.util.Vector messages) Send the specified messages to the server.
void	setMessageListener(JmsMessageListener listener) Set a message listener for the session.
boolean	setTransactionTimeout(int seconds)
void	start() Start the message delivery for the session.
void	start(javax.transaction.xa.Xid xid, int flags)
void	startMessageDelivery() Start message delivery to this session.
void	stop() Stop message delivery for the session
void	stopMessageDelivery() Stop message delivery to this session.
void	unsubscribe(java.lang.String name) Unsubscribe a durable subscription.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getClientId

public java.lang.String getClientId()

Return a reference to the client id

Returns:

String client id

getSessionId

public java.lang.String getSessionId()

Return a reference to the session id

Returns:

String session id

start

public void start()

Start the message delivery for the session. If session delivery has already started then treat the operation as an no-op

stop

public void stop()

Stop message delivery for the session

close

public void close()
           throws javax.jms.JMSException

Close and release any resource allocated to this session. This method may be called by multiple threads.

Throws:

javax.jms.JMSException - if the session cannot be closed

acknowledgeMessage

public void acknowledgeMessage(long clientId,
                               java.lang.String id)
                        throws javax.jms.JMSException

Acknowledge that the message with the following id has been processed

Parameters:

clientId - the clientId that sent the message to the client

id - the message to ack

Throws:

javax.jms.JMSException - if message cannot be acknowledged

sendMessage

public void sendMessage(javax.jms.Message message)
                 throws javax.jms.JMSException

Send the specified message to the server

Parameters:

message - the message to send

Throws:

javax.jms.JMSException - if the message can't be sent

sendMessages

public void sendMessages(java.util.Vector messages)
                  throws javax.jms.JMSException

Send the specified messages to the server.

Parameters:

messages - the messages to send

Throws:

javax.jms.JMSException - if the messages can't be sent

receiveMessage

public javax.jms.Message receiveMessage(long clientId,
                                        long wait)
                                 throws javax.jms.JMSException

Return the next message for the specified client. The wait parameter indicates how long many milliseconds to wait for a message before returning. If wait is 0 then do not wait at all. If wait is -1 then wait indefinitely for the next message

Parameters:

clientId - the client identity

wait - number of ms to wait

Returns:

the next message or null if there is no message

Throws:

javax.jms.JMSException - if the message can't be received

receiveMessages

public java.util.Vector receiveMessages(long clientId,
                                        int count)
                                 throws javax.jms.JMSException

Return up to count messages from the endpoint with the specified client identity. The client must be a QueueBrowser.

Parameters:

clientId - the client identity

count - the maximum number of messages retrieve

Returns:

Message the next message or null

Throws:

javax.jms.JMSException - if the endpoint does not exist, or is not a QueueBrowserEndpoint

createQueue

public void createQueue(JmsQueue queue)
                 throws javax.jms.JMSException

Create an amdinistered queue, through the message manager admin interface.

Parameters:

queue - administered queue to create

Throws:

javax.jms.JMSException - if the queue can't be created

createTopic

public void createTopic(JmsTopic topic)
                 throws javax.jms.JMSException

Create an administered topic, through the message manager admin interface.

Parameters:

topic - administered topic to create

Throws:

javax.jms.JMSException - if the topic can't be created

createReceiver

public void createReceiver(JmsQueue queue,
                           long clientId,
                           java.lang.String selector)
                    throws javax.jms.JMSException

Create a receiver endpoint for this session. A receiver is a message consumer specific to the queue message model. The receiver is associated with a queue.

You cannot create more than one receiver for the same destination

Parameters:

queue - the receiver destination

consumerId - the client session allocated identifier of the consumer

selector - the selector to filter messages. May be null

Throws:

javax.jms.JMSException - if the receiver can't be created

createSender

public void createSender(JmsQueue queue)
                  throws javax.jms.JMSException

This is a no-op

createBrowser

public void createBrowser(JmsQueue queue,
                          long clientId,
                          java.lang.String selector)
                   throws javax.jms.JMSException

Create a queue browser for this session. This allows clients to browse a queue without removing any messages.

You cannot create more than one queue browser for the same queue in a single session.

Parameters:

queue - queue to browse

clientId - the client identity

selector - message selector. This may be null

Throws:

JMSException. -

deleteReceiver

public void deleteReceiver(long clientId)
                    throws javax.jms.JMSException

Delete the receiver with the specified identity and clean up all associated resources.

Parameters:

clientId - the identity of the receiver

Throws:

javax.jms.JMSException - if the receiver cannot be deleted

deleteSender

public void deleteSender(long clientId)
                  throws javax.jms.JMSException

Delete the sender associated with the specified queue from the session If the corresponding sender does not exist or it cannot delete it then throw the JMSException.

Parameters:

clientId - the identity of the sender

Throws:

javax.jms.JMSException - if the sender cannot be deleted

deleteBrowser

public void deleteBrowser(long clientId)
                   throws javax.jms.JMSException

Delete the queue browser associated with the specified queue from the session.

Parameters:

clientId - the identity of the browser

Throws:

javax.jms.JMSException - if the browser cannot be deleted

createSubscriber

public void createSubscriber(JmsTopic topic,
                             java.lang.String name,
                             long clientId,
                             java.lang.String selector,
                             boolean noLocal)
                      throws javax.jms.JMSException

Create a subscriber endpoint for this session. A subscriber is a message consumer specific to the topic message model. The subscriber is associated with a topic. Register the consumer with the message manager so that a queue can be set up for it. Finally add the consumer to the list of consumers managed by this session.

Note that the message manager manages consumers for all server sessions

You cannot create more than one subscriber for the same destination. Currently we don't check this

Parameters:

topic - subscriber destination

name - consumer name

clientId - the client session allocated identifier of the consumer

selector - the selector to filter messages. This may be null.

noLocal - true to inhibit consumption of messages published on this connection.

Throws:

JMSException. -

createPublisher

public void createPublisher(JmsTopic topic)
                     throws javax.jms.JMSException

This should be a no operation. Do we need to maintain state information that a publisher has been created.

Parameters:

topic - receiver destination

Throws:

JMSException. -

deleteSubscriber

public void deleteSubscriber(long clientId)
                      throws javax.jms.JMSException

This function deletes a persistent subsrciber and its history from the database. It his subscriber re-connects it get everything available for the queue topic. If the subscriber is reliable, this is a no op. See UnregisterSubscriber below for just unregistering the subscriber but leaving its persistent data in the db.

The data contains information necessary to delete the subscriber

Parameters:

clientId - the client identity

Throws:

JMSException. -

deletePublisher

public void deletePublisher(JmsTopic topic)
                     throws javax.jms.JMSException

Delete the publisher associated with the specified topic from the session. If the corresponding publisher does not exist or it cannot delete it then throw the JMSException.

Parameters:

topic - sender destination

Throws:

JMSException. -

unsubscribe

public void unsubscribe(java.lang.String name)
                 throws javax.jms.JMSException

Unsubscribe a durable subscription. This will delete the state of the durable subscriber maintained by the server. A durable subscriber is uniquely identifiable and the same subscriber cannot be associated with more than topic.

Parameters:

name - the name used to uniquely identify the subscription

Throws:

javax.jms.JMSException - if the subscription cannot be removed or any other problem.

stopMessageDelivery

public void stopMessageDelivery()
                         throws javax.jms.JMSException

Stop message delivery to this session. If there are any problems completing the request then throw the JMSException exception

Throws:

javax.jms.JMSException -

startMessageDelivery

public void startMessageDelivery()
                          throws javax.jms.JMSException

Start message delivery to this session. If there are any problems completing this request then throw the JMSException exception

Throws:

javax.jms.JMSException -

containsUnackedHandle

public boolean containsUnackedHandle(MessageHandle handle)

Check if the specified message handle is in the session's list of unacked messages

Parameters:

handle - - the handle to query

Returns:

boolean - true if it is and false otherwise

onMessage

public void onMessage(MessageHandle handle,
                      boolean ignore)
               throws java.lang.Exception

Description copied from interface: InternalMessageListener

Send the specified message to the client. If the ack paramter is set then comply to the acking policy of the session. If this parameter is not set then ignore the acking policy. The later mode is used by the queue browser, when it sends messages

Specified by:

onMessage in interface InternalMessageListener

Following copied from interface: org.exolab.jms.messagemgr.InternalMessageListener

Parameters:

message - - message handle

ack - - false ignores the acking policy

Throws:

java.lang.Exception - - propagate exceptions to client

onMessages

public void onMessages(java.util.Vector handles)
                throws java.lang.Exception

Description copied from interface: InternalMessageListener

Send the specified collection of messages to the client

Specified by:

onMessages in interface InternalMessageListener

Following copied from interface: org.exolab.jms.messagemgr.InternalMessageListener

Parameters:

messages - - collection of MessageHandle objects

Throws:

java.lang.Exception - - propagate exceptions to client

onMessageAvailable

public void onMessageAvailable(long clientId)
                        throws java.lang.Exception

Description copied from interface: InternalMessageListener

Inform the session that there is a message available for the message consumer with the specified identity

Specified by:

onMessageAvailable in interface InternalMessageListener

Following copied from interface: org.exolab.jms.messagemgr.InternalMessageListener

Parameters:

clientId - - the identity of the client

isClientEndpointActive

public boolean isClientEndpointActive()

This will send a null message down the connection to the client to test whether the client endpoint is alive.

Returns:

true if it is active, otherwise false

setMessageListener

public void setMessageListener(JmsMessageListener listener)

Set a message listener for the session. This is the channel used to asynchronously deliver messages to consumers created on this session.

Parameters:

listener - the message listener

enableAsynchronousDelivery

public void enableAsynchronousDelivery(long clientId,
                                       java.lang.String id,
                                       boolean enable)
                                throws javax.jms.JMSException

Check whether to enable asynchronous message delivery for a particular consumer

Parameters:

clientId - the id of the client to check

id - the last processed message

enable - true to enable; false to disable

recover

public void recover()
             throws javax.jms.JMSException

Call recover on all registered consumers. This will cause all unacknowledged messages to be redelivered. Before we recover we need to stop messages delivery. We then need to start redelivery when the recovery has been completed

Throws:

javax.jms.JMSException - if the session can't be recovered

commit

public void commit()
            throws javax.jms.JMSException

Commit this session, which will acknowledge all sent messages for all consumers.

Throws:

javax.jms.JMSException - - if there are any problems

rollback

public void rollback()
              throws javax.jms.JMSException

Abort, will return all unacked messages to their respective endpoints, if they are still active.

Throws:

javax.jms.JMSException - - if there are any problems

commit

public void commit(javax.transaction.xa.Xid xid,
                   boolean onePhase)
            throws javax.transaction.xa.XAException

Specified by:

commit in interface javax.transaction.xa.XAResource

end

public void end(javax.transaction.xa.Xid xid,
                int flags)
         throws javax.transaction.xa.XAException

Specified by:

end in interface javax.transaction.xa.XAResource

forget

public void forget(javax.transaction.xa.Xid xid)
            throws javax.transaction.xa.XAException

Specified by:

forget in interface javax.transaction.xa.XAResource

getTransactionTimeout

public int getTransactionTimeout()
                          throws javax.transaction.xa.XAException

Specified by:

getTransactionTimeout in interface javax.transaction.xa.XAResource

isSameRM

public boolean isSameRM(javax.transaction.xa.XAResource xares)
                 throws javax.transaction.xa.XAException

Specified by:

isSameRM in interface javax.transaction.xa.XAResource

prepare

public int prepare(javax.transaction.xa.Xid xid)
            throws javax.transaction.xa.XAException

Specified by:

prepare in interface javax.transaction.xa.XAResource

recover

public javax.transaction.xa.Xid[] recover(int flag)
                                   throws javax.transaction.xa.XAException

Specified by:

recover in interface javax.transaction.xa.XAResource

rollback

public void rollback(javax.transaction.xa.Xid xid)
              throws javax.transaction.xa.XAException

Specified by:

rollback in interface javax.transaction.xa.XAResource

setTransactionTimeout

public boolean setTransactionTimeout(int seconds)
                              throws javax.transaction.xa.XAException

Specified by:

setTransactionTimeout in interface javax.transaction.xa.XAResource

start

public void start(javax.transaction.xa.Xid xid,
                  int flags)
           throws javax.transaction.xa.XAException

Specified by:

start in interface javax.transaction.xa.XAResource

getXid

public javax.transaction.xa.Xid getXid()

Return the xid that is currently associated with this session or null if this session is currently not part of a global transactions

Returns:

Xid

getResourceManagerId

public java.lang.String getResourceManagerId()
                                      throws javax.transaction.xa.XAException

Return the identity of the ResourceManager. The transaction manager should be the only one to initiating this call.

Returns:

the identity of the resource manager

Throws:

javax.transaction.xa.XAException - - if it cannot retrieve the rid.

isTransacted

public boolean isTransacted()

Determines if the session is transacted

Returns:

true if the session is transacted

getAckMode

public int getAckMode()

Returns the message acknowledgement mode for the session

getConsumerEndpoint

public ConsumerEndpoint getConsumerEndpoint(long clientId)

Returns the consumer endpoint for the supplied client id

Parameters:

clientId - the identity of the consumer endpoint

Returns:

the consumer endpoint corresponding to clientId, or null if none exists