View Javadoc

1   /***
2    * Redistribution and use of this software and associated documentation
3    * ("Software"), with or without modification, are permitted provided
4    * that the following conditions are met:
5    *
6    * 1. Redistributions of source code must retain copyright
7    *    statements and notices.  Redistributions must also contain a
8    *    copy of this document.
9    *
10   * 2. Redistributions in binary form must reproduce the
11   *    above copyright notice, this list of conditions and the
12   *    following disclaimer in the documentation and/or other
13   *    materials provided with the distribution.
14   *
15   * 3. The name "Exolab" must not be used to endorse or promote
16   *    products derived from this Software without prior written
17   *    permission of Exoffice Technologies.  For written permission,
18   *    please contact info@exolab.org.
19   *
20   * 4. Products derived from this Software may not be called "Exolab"
21   *    nor may "Exolab" appear in their names without prior written
22   *    permission of Exoffice Technologies. Exolab is a registered
23   *    trademark of Exoffice Technologies.
24   *
25   * 5. Due credit should be given to the Exolab Project
26   *    (http://www.exolab.org/).
27   *
28   * THIS SOFTWARE IS PROVIDED BY EXOFFICE TECHNOLOGIES AND CONTRIBUTORS
29   * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
30   * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
31   * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
32   * EXOFFICE TECHNOLOGIES OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
33   * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
34   * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
35   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
36   * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
37   * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
38   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
39   * OF THE POSSIBILITY OF SUCH DAMAGE.
40   *
41   * Copyright 2005 (C) Exoffice Technologies Inc. All Rights Reserved.
42   *
43   * $Id: ServerSession.java,v 1.2 2005/08/30 05:23:16 tanderson Exp $
44   */
45  package org.exolab.jms.server;
46  
47  import java.util.List;
48  import javax.jms.JMSException;
49  import javax.transaction.xa.XAException;
50  import javax.transaction.xa.Xid;
51  
52  import org.exolab.jms.client.JmsDestination;
53  import org.exolab.jms.client.JmsMessageListener;
54  import org.exolab.jms.client.JmsQueue;
55  import org.exolab.jms.client.JmsTopic;
56  import org.exolab.jms.message.MessageImpl;
57  
58  
59  /***
60   * Indicates the methods clients can call on the server-side implementation of
61   * the {@link javax.jms.Session} interface
62   *
63   * @author <a href="mailto:tma@netspace.net.au">Tim Anderson</a>
64   * @version $Revision: 1.2 $ $Date: 2005/08/30 05:23:16 $
65   */
66  public interface ServerSession {
67  
68      /***
69       * Close and release any resource allocated to this session.
70       *
71       * @throws JMSException for any JMS error
72       */
73      void close() throws JMSException;
74  
75      /***
76       * Acknowledge that a message has been processed.
77       *
78       * @param consumerId the identity of the consumer performing the ack
79       * @param messageId  the message identifier
80       * @throws JMSException for any error
81       */
82      void acknowledgeMessage(long consumerId, String messageId)
83              throws JMSException;
84  
85      /***
86       * Send a message.
87       *
88       * @param message the message to send
89       * @throws JMSException for any error
90       */
91      void send(MessageImpl message) throws JMSException;
92  
93      /***
94       * Send a set of messages.
95       *
96       * @param messages a list of <code>MessageImpl</code> instances
97       * @throws JMSException for any JMS error
98       */
99      void send(List messages) throws JMSException;
100 
101     /***
102      * Return the next available mesage to the specified consumer.
103      * <p/>
104      * This method is non-blocking. If no messages are available, it will return
105      * immediately.
106      *
107      * @param consumerId the consumer identifier
108      * @return the next message or <code>null</code> if none is available
109      * @throws JMSException for any JMS error
110      */
111     MessageImpl receiveNoWait(long consumerId) throws JMSException;
112 
113     /***
114      * Return the next available message to the specified consumer.
115      * <p/>
116      * This method is non-blocking. However, clients can specify a
117      * <code>wait</code> interval to indicate how long they are prepared to wait
118      * for a message. If no message is available, and the client indicates that
119      * it will wait, it will be notified via the registered {@link
120      * JmsMessageListener} if one subsequently becomes available.
121      *
122      * @param consumerId the consumer identifier
123      * @param wait       number of milliseconds to wait. A value of <code>0
124      *                   </code> indicates to wait indefinitely
125      * @return the next message, or <code>null</code>
126      * @return the next message or <code>null</code> if none is available
127      * @throws JMSException for any JMS error
128      */
129     MessageImpl receive(long consumerId, long wait) throws JMSException;
130 
131     /***
132      * Browse up to count messages.
133      *
134      * @param consumerId the consumer identifier
135      * @param count      the maximum number of messages to receive
136      * @return a list of {@link MessageImpl} instances
137      * @throws JMSException for any JMS error
138      */
139     List browse(long consumerId, int count) throws JMSException;
140 
141     /***
142      * Create a new message consumer.
143      *
144      * @param destination the destination to consume messages from
145      * @param selector    the message selector. May be <code>null</code>
146      * @param noLocal     if true, and the destination is a topic, inhibits the
147      *                    delivery of messages published by its own connection.
148      *                    The behavior for <code>noLocal</code> is not specified
149      *                    if the destination is a queue.
150      * @return the identifty of the message consumer
151      * @throws JMSException for any JMS error
152      */
153     long createConsumer(JmsDestination destination, String selector,
154                         boolean noLocal)
155             throws JMSException;
156 
157     /***
158      * Create a new durable consumer. Durable consumers may only consume from
159      * non-temporary <code>Topic</code> destinations.
160      *
161      * @param topic    the non-temporary <code>Topic</code> to subscribe to
162      * @param name     the name used to identify this subscription
163      * @param selector only messages with properties matching the message
164      *                 selector expression are delivered.  A value of null or an
165      *                 empty string indicates that there is no message selector
166      *                 for the message consumer.
167      * @param noLocal  if set, inhibits the delivery of messages published by
168      *                 its own connection
169      * @return the identity of the durable consumer
170      * @throws JMSException for any JMS error
171      */
172     long createDurableConsumer(JmsTopic topic, String name, String selector,
173                                boolean noLocal)
174             throws JMSException;
175 
176     /***
177      * Create a queue browser for this session. This allows clients to browse a
178      * queue without removing any messages.
179      *
180      * @param queue    the queue to browse
181      * @param selector the message selector. May be <code>null</code>
182      * @return the identity of the queue browser
183      * @throws JMSException for any JMS error
184      */
185     long createBrowser(JmsQueue queue, String selector) throws JMSException;
186 
187     /***
188      * Close a message consumer.
189      *
190      * @param consumerId the identity of the consumer to close
191      * @throws JMSException for any JMS error
192      */
193     void closeConsumer(long consumerId) throws JMSException;
194 
195     /***
196      * Unsubscribe a durable subscription.
197      *
198      * @param name the name used to identify the subscription
199      * @throws JMSException for any JMS error
200      */
201     void unsubscribe(String name) throws JMSException;
202 
203     /***
204      * Start message delivery to this session.
205      *
206      * @throws JMSException for any JMS error
207      */
208     void start() throws JMSException;
209 
210     /***
211      * Stop message delivery to this session.
212      *
213      * @throws JMSException for any JMS error
214      */
215     void stop() throws JMSException;
216 
217     /***
218      * Set the listener for this session.
219      * <p/>
220      * The listener is notified whenever a message for the session is present.
221      *
222      * @param listener the message listener
223      */
224     void setMessageListener(JmsMessageListener listener);
225 
226     /***
227      * Enable or disable asynchronous message delivery for a particular
228      * consumer.
229      *
230      * @param consumerId the consumer identifier
231      * @param enable     true to enable; false to disable
232      * @throws JMSException for any JMS error
233      */
234     void setAsynchronous(long consumerId, boolean enable)
235             throws JMSException;
236 
237     /***
238      * Recover the session.
239      * <p/>
240      * All unacknowledged messages are re-delivered with the JMSRedelivered flag
241      * set.
242      *
243      * @throws JMSException if the session cannot be recovered
244      */
245     void recover() throws JMSException;
246 
247     /***
248      * Commit the session.
249      * <p/>
250      * This will acknowledge all delivered messages.
251      *
252      * @throws JMSException if the session cannot be committed
253      */
254     void commit() throws JMSException;
255 
256     /***
257      * Rollback the session.
258      * <p/>
259      * All messages delivered to the client will be redelivered with the
260      * JMSRedelivered flag set.
261      *
262      * @throws JMSException if the session cannot be rolled back
263      */
264     void rollback() throws JMSException;
265 
266     /***
267      * Start work on behalf of a transaction branch specified in xid If TMJOIN
268      * is specified, the start is for joining a transaction previously seen by
269      * the resource manager
270      *
271      * @param xid   the xa transaction identity
272      * @param flags One of TMNOFLAGS, TMJOIN, or TMRESUME
273      * @throws XAException if there is a problem completing the call
274      */
275     void start(Xid xid, int flags) throws XAException;
276 
277     /***
278      * Ask the resource manager to prepare for a transaction commit of the
279      * transaction specified in xid.
280      *
281      * @param xid the xa transaction identity
282      * @return XA_RDONLY or XA_OK
283      * @throws XAException if there is a problem completing the call
284      */
285     int prepare(Xid xid) throws XAException;
286 
287     /***
288      * Commits an XA transaction that is in progress.
289      *
290      * @param xid      the xa transaction identity
291      * @param onePhase true if it is a one phase commit
292      * @throws XAException if there is a problem completing the call
293      */
294     void commit(Xid xid, boolean onePhase) throws XAException;
295 
296     /***
297      * Ends the work performed on behalf of a transaction branch. The resource
298      * manager disassociates the XA resource from the transaction branch
299      * specified and let the transaction be completedCommits an XA transaction
300      * that is in progress.
301      *
302      * @param xid   the xa transaction identity
303      * @param flags one of TMSUCCESS, TMFAIL, or TMSUSPEND
304      * @throws XAException if there is a problem completing the call
305      */
306     void end(Xid xid, int flags) throws XAException;
307 
308     /***
309      * Tell the resource manager to forget about a heuristically completed
310      * transaction branch.
311      *
312      * @param xid the xa transaction identity
313      * @throws XAException if there is a problem completing the call
314      */
315     void forget(Xid xid) throws XAException;
316 
317     /***
318      * Obtain a list of prepared transaction branches from a resource manager.
319      * The transaction manager calls this method during recovery to obtain the
320      * list of transaction branches that are currently in prepared or
321      * heuristically completed states.
322      *
323      * @param flag One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS
324      * @return the set of Xids to recover
325      * @throws XAException if there is a problem completing the call
326      */
327     Xid[] recover(int flag) throws XAException;
328 
329     /***
330      * Inform the resource manager to roll back work done on behalf of a
331      * transaction branch.
332      *
333      * @param xid the xa transaction identity
334      * @throws XAException if there is a problem completing the call
335      */
336     void rollback(Xid xid) throws XAException;
337 
338     /***
339      * Return the transaction timeout for this instance of the resource
340      * manager.
341      *
342      * @return the timeout in seconds
343      * @throws XAException if there is a problem completing the call
344      */
345     int getTransactionTimeout() throws XAException;
346 
347     /***
348      * Set the current transaction timeout value for this XAResource instance.
349      *
350      * @param seconds timeout in seconds
351      * @return if the new transaction timeout was accepted
352      * @throws XAException if there is a problem completing the call
353      */
354     boolean setTransactionTimeout(int seconds) throws XAException;
355 
356     /***
357      * Return the identity of the associated resource manager.
358      *
359      * @return the identity of the resource manager
360      * @throws XAException if there is a problem completing the call
361      */
362     String getResourceManagerId() throws XAException;
363 
364 }