org.exolab.jms.client
Interface JmsSessionStubIfc

All Known Implementing Classes:

HttpJmsSessionStub, IntravmJmsSessionStub, IpcJmsSessionStub, RmiJmsSessionStub

public interface JmsSessionStubIfc

This is the interface that session stubs must implement in order to support remote invocations. This level of indirection will enable us to support different ORB environments. The only restriction is that the stubs must support this interface and that it must have a default constructor.

Version:

$Revision: 1.20 $ $Date: 2003/08/17 01:32:21 $

Author:

Jim Alateras

Method Summary

void	acknowledgeMessage(long clientId, java.lang.String messageId) Acknowledge the following message If this method does not complete then throw JMSException.
void	beforeClose() This method is called before the call to close, so that the stub can do some local clean up
void	close() Close and release any resource allocated to this session.
void	commit() Commit the session which will send all the published messages and acknowledge all received messages
void	commit(javax.transaction.xa.Xid xid, boolean onePhase) Commits an XA transaction that is in progress.
void	createBrowser(JmsQueue queue, long clientId, java.lang.String selector) Create a queue browser for this session.
void	createPublisher(JmsTopic topic) Create a publisher endpoint for this session.
void	createQueue(JmsQueue queue) Create a queue with the specified name.
void	createReceiver(JmsQueue queue, long clientId, java.lang.String selector) Create a receiver endpoint for this session.
void	createSender(JmsQueue queue) Create a sender endpoint for this session.
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 a topic with the specified name.
void	deleteBrowser(long clientId) Delete the queue browser associated with the corresponding client id.
void	deleteReceiver(long clientId) Delete the receiver with the corresponding client id.
void	deleteSubscriber(long clientId) Delete the subscriber associated with the sepcified identity.
void	enableAsynchronousDelivery(long clientId, java.lang.String id, boolean enable) Enable or disable asynchronous message delivery for a particular 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	getClientId() Return the client id associated with this session.
java.lang.String	getResourceManagerId() Return the identity of the associated resource manager.
java.lang.String	getSessionId() Return the session identity.
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
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 a collection of messages from the specified client upto the nominated count.
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, which will not acknowledge any of the sent messages
void	rollback(javax.transaction.xa.Xid xid) Inform the resource manager to roll back work done on behalf of a transaction branch
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 the listener for this session.
boolean	setTransactionTimeout(int seconds) Set the current transaction timeout value for this XAResource instance.
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	startMessageDelivery() Start message delivery to this session
void	stopMessageDelivery() Stop message delivery to this session
void	unsubscribe(java.lang.String name) Unsubscribe a durable subscription

Method Detail

getClientId

public java.lang.String getClientId()
                             throws javax.jms.JMSException

Return the client id associated with this session.

Returns:

the client id associated with this session

Throws:

javax.jms.JMSException - for any JMS error

getSessionId

public java.lang.String getSessionId()
                              throws javax.jms.JMSException

Return the session identity. Session identities are unique within the context of a server.

Returns:

the session identity

Throws:

javax.jms.JMSException - for any JMS error

beforeClose

public void beforeClose()
                 throws javax.jms.JMSException

This method is called before the call to close, so that the stub can do some local clean up

Throws:

javax.jms.JMSException - for any JMS error

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 clientId,
                               java.lang.String messageId)
                        throws javax.jms.JMSException

Acknowledge the following message If this method does not complete then throw JMSException.

Parameters:

clientId - the identity ofthe client

messageId - the message identity to ack

Throws:

javax.jms.JMSException - for any JMS error

sendMessage

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

Send the specified message to the server. If there is any problem then throw the JMSException exception

Parameters:

message - the message to send

Throws:

javax.jms.JMSException - for any JMS error

sendMessages

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

Send the specified messages to the server. If there is any problem then throw the JMSException exception

Parameters:

messages - the messages to send

Throws:

javax.jms.JMSException - for any JMS error

receiveMessage

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

Return the next message for the specified client. The client id maps to a consumer on the server side. The caller can also specify how long to wait if no messages are currently available. If the caller specifies 0 then the call will return immediately if there are no messages available. If the caller specified -1 then the call will block until a message becomes available.

Parameters:

clientId - the client identity

wait - the number of ms to wait. -1 means wait indefinitely.

Returns:

the next message or null

Throws:

javax.jms.JMSException - for any JMS error

receiveMessages

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

Return a collection of messages from the specified client upto the nominated count. This method may return less than count messages but it will never return more than count messages

Parameters:

client - the client identity

count - max messages to return

Returns:

collection of MessageImpl objects

Throws:

javax.jms.JMSException - for any JMS error

createQueue

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

Create a queue with the specified name. If the queue already exists then simply return a reference to it. If the queue does not exist then create it.

Parameters:

queue - the queue to create

Throws:

javax.jms.JMSException - for any JMS error

createTopic

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

Create a topic with the specified name. If the topic already exists then simply return a reference to it. If the topic does not exist then create it.

Parameters:

topic - the topic to create

Throws:

javax.jms.JMSException - for any JMS error

createReceiver

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

Create a receiver endpoint for this session. A reciever 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

clientId - the session allocated identifier of this consumer

selector - the message selector. This may be null.

Returns:

the unique consumer identifier

Throws:

javax.jms.JMSException - for any JMS error

createSender

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

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

You cannot create more than one receiver for the same destination

Parameters:

queue - the receiver destination

Throws:

javax.jms.JMSException - for any JMS error

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 - the queue to browse

clientId - the client identity

selector - the message selector. This may be null

Throws:

javax.jms.JMSException - for any JMS error

deleteReceiver

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

Delete the receiver with the corresponding client id.

Parameters:

clientId - the identity of the receiver to delete

Throws:

javax.jms.JMSException - for any JMS error

deleteBrowser

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

Delete the queue browser associated with the corresponding client id.

Parameters:

clientId - the id of the browser

Throws:

javax.jms.JMSException - for any JMS error

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. The name is used to identify the consumer and can be set to null

You cannot create more than one subscriber for the same destination

Parameters:

topic - subscriber destination

name - name of the consumer associated with the subscriber. This may be null.

clientId - the session allocated identifier of this consumer

selector - message selector. This may be null.

noLocal - inhibit consuming messages on same connection.

Throws:

javax.jms.JMSException - for any JMS error

createPublisher

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

Create a publisher endpoint for this session. A publisher is a message publisher specific to the topic message model. The publisher is associated with a topic.

You cannot create more than one publisher for the same destination

Parameters:

topic - receiver destination

Throws:

javax.jms.JMSException - for any JMS error

deleteSubscriber

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

Delete the subscriber associated with the sepcified identity.

Parameters:

clientid - the client identity

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

stopMessageDelivery

public void stopMessageDelivery()
                         throws javax.jms.JMSException

Stop message delivery to this session

Throws:

javax.jms.JMSException - for any JMS error

startMessageDelivery

public void startMessageDelivery()
                          throws javax.jms.JMSException

Start 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 an object that implements MessageListener and is called back whenever a message for the session is present

Parameters:

listener - the message listener

enableAsynchronousDelivery

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

Enable or disable asynchronous message delivery for a particular consumer

Parameters:

clientId - the id of the client to check

id - the message id of the last delivered message

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. This means all unacknowledged messages are resent with the redelivery flag set

Throws:

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

commit

public void commit()
            throws javax.jms.JMSException

Commit the session which will send all the published messages and acknowledge all received messages

Throws:

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

rollback

public void rollback()
              throws javax.jms.JMSException

Rollback the session, which will not acknowledge any of the sent messages

Throws:

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

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

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

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

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

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

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

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