ServerSession


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.1 2005/03/18 04:07:02 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.1 $ $Date: 2005/03/18 04:07:02 $
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 message to the specified consumer.
103      * <p/>
104      * The <code>wait</code> parameter indicates how many milliseconds to wait
105      * for a message before returning. If <code>wait</code> is <code>0</code>
106      * then do not wait. If <code>wait</code> is <code>-1</code> then wait
107      * indefinitely for the next message.
108      *
109      * @param consumerId the consumer identifier
110      * @param wait       number of milliseconds to wait
111      * @return the next message or <code>null</code>
112      * @throws JMSException for any JMS error
113      */
114     MessageImpl receive(long consumerId, long wait) throws JMSException  ;
115 
116     /**
117      * Browse up to count messages
118      *
119      * @param consumerId the consumer identifier
120      * @param count      the maximum number of messages to receive
121      * @return a list of {@link MessageImpl} instances
122      * @throws JMSException for any JMS error
123      */
124     List   browse(long consumerId, int count) throws JMSException  ;
125 
126     /**
127      * Create a new message consumer
128      *
129      * @param destination the destination to consume messages from
130      * @param selector    the message selector. May be <code>null</code>
131      * @param noLocal     if true, and the destination is a topic, inhibits the
132      *                    delivery of messages published by its own connection.
133      *                    The behavior for <code>noLocal</code> is not specified
134      *                    if the destination is a queue.
135      * @return the identifty of the message consumer
136      * @throws JMSException for any JMS error
137      */
138     long createConsumer(JmsDestination destination, String   selector,
139                         boolean noLocal)
140             throws JMSException  ;
141 
142     /**
143      * Create a new durable consumer. Durable consumers may only consume from
144      * non-temporary <code>Topic</code> destinations.
145      *
146      * @param topic    the non-temporary <code>Topic</code> to subscribe to
147      * @param name     the name used to identify this subscription
148      * @param selector only messages with properties matching the message
149      *                 selector expression are delivered.  A value of null or an
150      *                 empty string indicates that there is no message selector
151      *                 for the message consumer.
152      * @param noLocal  if set, inhibits the delivery of messages published by
153      *                 its own connection
154      * @return the identity of the durable consumer
155      * @throws JMSException for any JMS error
156      */
157     long createDurableConsumer(JmsTopic topic, String   name, String   selector,
158                                  boolean noLocal)
159             throws JMSException  ;
160 
161     /**
162      * Create a queue browser for this session. This allows clients to browse a
163      * queue without removing any messages.
164      *
165      * @param queue    the queue to browse
166      * @param selector the message selector. May be <code>null</code>
167      * @return the identity of the queue browser
168      * @throws JMSException for any JMS error
169      */
170     long createBrowser(JmsQueue queue, String   selector) throws JMSException  ;
171 
172     /**
173      * Remove a message consumer
174      *
175      * @param consumerId the identity of the consumer to remove
176      * @throws JMSException for any JMS error
177      */
178     void removeConsumer(long consumerId) throws JMSException  ;
179 
180     /**
181      * Unsubscribe a durable subscription
182      *
183      * @param name the name used to identify the subscription
184      * @throws JMSException for any JMS error
185      */
186     void unsubscribe(String   name) throws JMSException  ;
187 
188     /**
189      * Start message delivery to this session
190      *
191      * @throws JMSException for any JMS error
192      */
193     void start() throws JMSException  ;
194 
195     /**
196      * Stop message delivery to this session
197      *
198      * @throws JMSException for any JMS error
199      */
200     void stop() throws JMSException  ;
201 
202     /**
203      * Set the listener for this session. The listener is an object that
204      * implements MessageListener and is called back whenever a message for the
205      * session is present
206      *
207      * @param listener the message listener
208      */
209     void setMessageListener(JmsMessageListener listener);
210 
211     /**
212      * Enable or disable asynchronous message delivery for a particular
213      * consumer
214      *
215      * @param consumerId the consumer identifier
216      * @param enable     true to enable; false to disable
217      * @throws JMSException for any JMS error
218      */
219     void enableAsynchronousDelivery(long consumerId, boolean enable)
220             throws JMSException  ;
221 
222     /**
223      * Recover the session. This means all unacknowledged messages are resent
224      * with the redelivery flag set
225      *
226      * @throws JMSException if the session cannot be recovered
227      */
228     void recover() throws JMSException  ;
229 
230     /**
231      * Commit the session which will send all the published messages and
232      * acknowledge all received messages
233      *
234      * @throws JMSException if the session cannot be committed
235      */
236     void commit() throws JMSException  ;
237 
238     /**
239      * Rollback the session, which will not acknowledge any of the sent
240      * messages
241      *
242      * @throws JMSException if the session cannot be rolled back
243      */
244     void rollback() throws JMSException  ;
245 
246     /**
247      * Start work on behalf of a transaction branch specified in xid If TMJOIN
248      * is specified, the start is for joining a transaction previously seen by
249      * the resource manager
250      *
251      * @param xid   the xa transaction identity
252      * @param flags One of TMNOFLAGS, TMJOIN, or TMRESUME
253      * @throws XAException if there is a problem completing the call
254      */
255     void start(Xid   xid, int flags) throws XAException  ;
256 
257     /**
258      * Ask the resource manager to prepare for a transaction commit of the
259      * transaction specified in xid
260      *
261      * @param xid the xa transaction identity
262      * @return XA_RDONLY or XA_OK
263      * @throws XAException if there is a problem completing the call
264      */
265     int prepare(Xid   xid) throws XAException  ;
266 
267     /**
268      * Commits an XA transaction that is in progress.
269      *
270      * @param xid      the xa transaction identity
271      * @param onePhase true if it is a one phase commit
272      * @throws XAException if there is a problem completing the call
273      */
274     void commit(Xid   xid, boolean onePhase) throws XAException  ;
275 
276     /**
277      * Ends the work performed on behalf of a transaction branch. The resource
278      * manager disassociates the XA resource from the transaction branch
279      * specified and let the transaction be completedCommits an XA transaction
280      * that is in progress.
281      *
282      * @param xid   the xa transaction identity
283      * @param flags one of TMSUCCESS, TMFAIL, or TMSUSPEND
284      * @throws XAException if there is a problem completing the call
285      */
286     void end(Xid   xid, int flags) throws XAException  ;
287 
288     /**
289      * Tell the resource manager to forget about a heuristically completed
290      * transaction branch.
291      *
292      * @param xid the xa transaction identity
293      * @throws XAException if there is a problem completing the call
294      */
295     void forget(Xid   xid) throws XAException  ;
296 
297     /**
298      * Obtain a list of prepared transaction branches from a resource manager.
299      * The transaction manager calls this method during recovery to obtain the
300      * list of transaction branches that are currently in prepared or
301      * heuristically completed states.
302      *
303      * @param flag One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS
304      * @return the set of Xids to recover
305      * @throws XAException - if there is a problem completing the call
306      */
307     Xid  [] recover(int flag) throws XAException  ;
308 
309     /**
310      * Inform the resource manager to roll back work done on behalf of a
311      * transaction branch
312      *
313      * @param xid the xa transaction identity
314      * @throws XAException if there is a problem completing the call
315      */
316     void rollback(Xid   xid) throws XAException  ;
317 
318     /**
319      * Return the transaction timeout for this instance of the resource
320      * manager.
321      *
322      * @return the timeout in seconds
323      * @throws XAException if there is a problem completing the call
324      */
325     int getTransactionTimeout() throws XAException  ;
326     /**
327      * Set the current transaction timeout value for this XAResource instance.
328      *
329      * @param seconds timeout in seconds
330      * @return if the new transaction timeout was accepted
331      * @throws XAException if there is a problem completing the call
332      */
333     boolean setTransactionTimeout(int seconds) throws XAException  ;
334 
335     /**
336      * Return the identity of the associated resource manager.
337      *
338      * @return the identity of the resource manager
339      * @throws XAException if there is a problem completing the call
340      */
341     String   getResourceManagerId() throws XAException  ;
342 
343 }
344
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags