org.exolab.jms.server
Interface ServerSession

All Known Implementing Classes:

JmsSessionStubImpl, RemoteServerSession

public interface ServerSession

Indicates the methods clients can call on the server-side implementation of the Session interface

Version:

$Revision: 1.2 $ $Date: 2005/08/30 05:23:16 $

Author:

Tim Anderson

Method Summary

void	acknowledgeMessage(long consumerId, java.lang.String messageId) Acknowledge that a message has been processed.
java.util.List	browse(long consumerId, int count) Browse up to count messages.
void	close() Close and release any resource allocated to this session.
void	closeConsumer(long consumerId) Close a message consumer.
void	commit() Commit the session.
void	commit(javax.transaction.xa.Xid xid, boolean onePhase) Commits an XA transaction that is in progress.
long	createBrowser(JmsQueue queue, java.lang.String selector) Create a queue browser for this session.
long	createConsumer(JmsDestination destination, java.lang.String selector, boolean noLocal) Create a new message consumer.
long	createDurableConsumer(JmsTopic topic, java.lang.String name, java.lang.String selector, boolean noLocal) Create a new durable consumer.
void	end(javax.transaction.xa.Xid xid, int flags) Ends the work performed on behalf of a transaction branch.
void	forget(javax.transaction.xa.Xid xid) Tell the resource manager to forget about a heuristically completed transaction branch.
java.lang.String	getResourceManagerId() Return the identity of the associated resource manager.
int	getTransactionTimeout() Return the transaction timeout for this instance of the resource manager.
int	prepare(javax.transaction.xa.Xid xid) Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.
MessageImpl	receive(long consumerId, long wait) Return the next available message to the specified consumer.
MessageImpl	receiveNoWait(long consumerId) Return the next available mesage to the specified consumer.
void	recover() Recover the session.
javax.transaction.xa.Xid[]	recover(int flag) Obtain a list of prepared transaction branches from a resource manager.
void	rollback() Rollback the session.
void	rollback(javax.transaction.xa.Xid xid) Inform the resource manager to roll back work done on behalf of a transaction branch.
void	send(java.util.List messages) Send a set of messages.
void	send(MessageImpl message) Send a message.
void	setAsynchronous(long consumerId, boolean enable) Enable or disable asynchronous message delivery for a particular consumer.
void	setMessageListener(JmsMessageListener listener) Set the listener for this session.
boolean	setTransactionTimeout(int seconds) Set the current transaction timeout value for this XAResource instance.
void	start() Start message delivery to this session.
void	start(javax.transaction.xa.Xid xid, int flags) Start work on behalf of a transaction branch specified in xid If TMJOIN is specified, the start is for joining a transaction previously seen by the resource manager
void	stop() Stop message delivery to this session.
void	unsubscribe(java.lang.String name) Unsubscribe a durable subscription.

Method Detail

close

public void close()
           throws javax.jms.JMSException

Close and release any resource allocated to this session.

Throws:

javax.jms.JMSException - for any JMS error

acknowledgeMessage

public void acknowledgeMessage(long consumerId,
                               java.lang.String messageId)
                        throws javax.jms.JMSException

Acknowledge that a message has been processed.

Parameters:

consumerId - the identity of the consumer performing the ack

messageId - the message identifier

Throws:

javax.jms.JMSException - for any error

send

public void send(MessageImpl message)
          throws javax.jms.JMSException

Send a message.

Parameters:

message - the message to send

Throws:

javax.jms.JMSException - for any error

send

public void send(java.util.List messages)
          throws javax.jms.JMSException

Send a set of messages.

Parameters:

messages - a list of MessageImpl instances

Throws:

javax.jms.JMSException - for any JMS error

receiveNoWait

public MessageImpl receiveNoWait(long consumerId)
                          throws javax.jms.JMSException

Return the next available mesage to the specified consumer.

This method is non-blocking. If no messages are available, it will return immediately.

Parameters:

consumerId - the consumer identifier

Returns:

the next message or null if none is available

Throws:

javax.jms.JMSException - for any JMS error

receive

public MessageImpl receive(long consumerId,
                           long wait)
                    throws javax.jms.JMSException

Return the next available message to the specified consumer.

This method is non-blocking. However, clients can specify a wait interval to indicate how long they are prepared to wait for a message. If no message is available, and the client indicates that it will wait, it will be notified via the registered JmsMessageListener if one subsequently becomes available.

Parameters:

consumerId - the consumer identifier

wait - number of milliseconds to wait. A value of 0 indicates to wait indefinitely

Returns:

the next message, or null

Throws:

javax.jms.JMSException - for any JMS error

browse

public java.util.List browse(long consumerId,
                             int count)
                      throws javax.jms.JMSException

Browse up to count messages.

Parameters:

consumerId - the consumer identifier

count - the maximum number of messages to receive

Returns:

a list of MessageImpl instances

Throws:

javax.jms.JMSException - for any JMS error

createConsumer

public long createConsumer(JmsDestination destination,
                           java.lang.String selector,
                           boolean noLocal)
                    throws javax.jms.JMSException

Create a new message consumer.

Parameters:

destination - the destination to consume messages from

selector - the message selector. May be null

noLocal - if true, and the destination is a topic, inhibits the delivery of messages published by its own connection. The behavior for noLocal is not specified if the destination is a queue.

Returns:

the identifty of the message consumer

Throws:

javax.jms.JMSException - for any JMS error

createDurableConsumer

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

Create a new durable consumer. Durable consumers may only consume from non-temporary Topic destinations.

Parameters:

topic - the non-temporary Topic to subscribe to

name - the name used to identify this subscription

selector - 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:

the identity of the durable consumer

Throws:

javax.jms.JMSException - for any JMS error

createBrowser

public long createBrowser(JmsQueue queue,
                          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.

Parameters:

queue - the queue to browse

selector - the message selector. May be null

Returns:

the identity of the queue browser

Throws:

javax.jms.JMSException - for any JMS error

closeConsumer

public void closeConsumer(long consumerId)
                   throws javax.jms.JMSException

Close a message consumer.

Parameters:

consumerId - the identity of the consumer to close

Throws:

javax.jms.JMSException - for any JMS error

unsubscribe

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

Unsubscribe a durable subscription.

Parameters:

name - the name used to identify the subscription

Throws:

javax.jms.JMSException - for any JMS error

start

public void start()
           throws javax.jms.JMSException

Start message delivery to this session.

Throws:

javax.jms.JMSException - for any JMS error

stop

public void stop()
          throws javax.jms.JMSException

Stop message delivery to this session.

Throws:

javax.jms.JMSException - for any JMS error

setMessageListener

public void setMessageListener(JmsMessageListener listener)

Set the listener for this session.

The listener is notified whenever a message for the session is present.

Parameters:

listener - the message listener

setAsynchronous

public void setAsynchronous(long consumerId,
                            boolean enable)
                     throws javax.jms.JMSException

Enable or disable asynchronous message delivery for a particular consumer.

Parameters:

consumerId - the consumer identifier

enable - true to enable; false to disable

Throws:

javax.jms.JMSException - for any JMS error

recover

public void recover()
             throws javax.jms.JMSException

Recover the session.

All unacknowledged messages are re-delivered with the JMSRedelivered flag set.

Throws:

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

commit

public void commit()
            throws javax.jms.JMSException

Commit the session.

This will acknowledge all delivered messages.

Throws:

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

rollback

public void rollback()
              throws javax.jms.JMSException

Rollback the session.

All messages delivered to the client will be redelivered with the JMSRedelivered flag set.

Throws:

javax.jms.JMSException - if the session cannot be rolled back

start

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

Start work on behalf of a transaction branch specified in xid If TMJOIN is specified, the start is for joining a transaction previously seen by the resource manager

Parameters:

xid - the xa transaction identity

flags - One of TMNOFLAGS, TMJOIN, or TMRESUME

Throws:

javax.transaction.xa.XAException - if there is a problem completing the call

prepare

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

Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.

Parameters:

xid - the xa transaction identity

Returns:

XA_RDONLY or XA_OK

Throws:

javax.transaction.xa.XAException - if there is a problem completing the call

commit

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

Commits an XA transaction that is in progress.

Parameters:

xid - the xa transaction identity

onePhase - true if it is a one phase commit

Throws:

javax.transaction.xa.XAException - if there is a problem completing the call

end

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

Ends the work performed on behalf of a transaction branch. The resource manager disassociates the XA resource from the transaction branch specified and let the transaction be completedCommits an XA transaction that is in progress.

Parameters:

xid - the xa transaction identity

flags - one of TMSUCCESS, TMFAIL, or TMSUSPEND

Throws:

javax.transaction.xa.XAException - if there is a problem completing the call

forget

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

Tell the resource manager to forget about a heuristically completed transaction branch.

Parameters:

xid - the xa transaction identity

Throws:

javax.transaction.xa.XAException - if there is a problem completing the call

recover

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

Obtain a list of prepared transaction branches from a resource manager. The transaction manager calls this method during recovery to obtain the list of transaction branches that are currently in prepared or heuristically completed states.

Parameters:

flag - One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS

Returns:

the set of Xids to recover

Throws:

javax.transaction.xa.XAException - if there is a problem completing the call

rollback

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

Inform the resource manager to roll back work done on behalf of a transaction branch.

Parameters:

xid - the xa transaction identity

Throws:

javax.transaction.xa.XAException - if there is a problem completing the call

getTransactionTimeout

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

Return the transaction timeout for this instance of the resource manager.

Returns:

the timeout in seconds

Throws:

javax.transaction.xa.XAException - if there is a problem completing the call

setTransactionTimeout

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

Set the current transaction timeout value for this XAResource instance.

Parameters:

seconds - timeout in seconds

Returns:

if the new transaction timeout was accepted

Throws:

javax.transaction.xa.XAException - if there is a problem completing the call

getResourceManagerId

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

Return the identity of the associated resource manager.

Returns:

the identity of the resource manager

Throws:

javax.transaction.xa.XAException - if there is a problem completing the call