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 2000-2003 (C) Exoffice Technologies Inc. All Rights Reserved.
42 *
43 * $Id: JmsSessionStubIfc.java,v 1.20 2003/08/17 01:32:21 tanderson Exp $
44 *
45 * Date Author Changes
46 * 04/12/2000 jima Created
47 */
48 package org.exolab.jms.client;
49
50 import java.util.Vector;
51
52 import javax.jms.JMSException;
53 import javax.jms.Message;
54 import javax.transaction.xa.XAException;
55 import javax.transaction.xa.XAResource;
56 import javax.transaction.xa.Xid;
57
58
59 /***
60 * This is the interface that session stubs must implement in order to
61 * support remote invocations. This level of indirection will enable us to
62 * support different ORB environments. The only restriction is that the
63 * stubs must support this interface and that it must have a default
64 * constructor.
65 *
66 * @version $Revision: 1.20 $ $Date: 2003/08/17 01:32:21 $
67 * @author <a href="mailto:jima@exoffice.com">Jim Alateras</a>
68 */
69 public interface JmsSessionStubIfc {
70
71 /***
72 * Return the client id associated with this session.
73 *
74 * @return the client id associated with this session
75 * @throws JMSException for any JMS error
76 */
77 String getClientId() throws JMSException;
78
79 /***
80 * Return the session identity. Session identities are unique
81 * within the context of a server.
82 *
83 * @return the session identity
84 * @throws JMSException for any JMS error
85 */
86 String getSessionId() throws JMSException;
87
88 /***
89 * This method is called before the call to <code>close</code>, so that the
90 * stub can do some local clean up
91 *
92 * @throws JMSException for any JMS error
93 */
94 void beforeClose() throws JMSException;
95
96 /***
97 * Close and release any resource allocated to this session.
98 *
99 * @throws JMSException for any JMS error
100 */
101 void close() throws JMSException;
102
103 /***
104 * Acknowledge the following message If this method does not complete then
105 * throw JMSException.
106 *
107 * @param clientId the identity ofthe client
108 * @param messageId the message identity to ack
109 * @throws JMSException for any JMS error
110 */
111 void acknowledgeMessage(long clientId, String messageId)
112 throws JMSException;
113
114 /***
115 * Send the specified message to the server. If there is any problem
116 * then throw the JMSException exception
117 *
118 * @param message the message to send
119 * @throws JMSException for any JMS error
120 */
121 void sendMessage(Message message) throws JMSException;
122
123 /***
124 * Send the specified messages to the server. If there is any problem
125 * then throw the JMSException exception
126 *
127 * @param messages the messages to send
128 * @throws JMSException for any JMS error
129 */
130 void sendMessages(Vector messages) throws JMSException;
131
132 /***
133 * Return the next message for the specified client. The client id
134 * maps to a consumer on the server side. The caller can also specify
135 * how long to wait if no messages are currently available. If the caller
136 * specifies 0 then the call will return immediately if there are no
137 * messages available. If the caller specified -1 then the call will
138 * block until a message becomes available.
139 *
140 * @param clientId the client identity
141 * @param wait the number of ms to wait. -1 means wait indefinitely.
142 * @return the next message or null
143 * @throws JMSException for any JMS error
144 */
145 Message receiveMessage(long clientId, long wait) throws JMSException;
146
147 /***
148 * Return a collection of messages from the specified client upto the
149 * nominated count. This method may return less than count messages
150 * but it will never return more than count messages
151 *
152 * @param client the client identity
153 * @param count max messages to return
154 * @return collection of MessageImpl objects
155 * @throws JMSException for any JMS error
156 */
157 Vector receiveMessages(long clientId, int count) throws JMSException;
158
159 /***
160 * Create a queue with the specified name. If the queue already exists
161 * then simply return a reference to it. If the queue does not exist
162 * then create it.
163 *
164 * @param queue the queue to create
165 * @throws JMSException for any JMS error
166 */
167 void createQueue(JmsQueue queue) throws JMSException;
168
169 /***
170 * Create a topic with the specified name. If the topic already exists
171 * then simply return a reference to it. If the topic does not exist
172 * then create it.
173 *
174 * @param topic the topic to create
175 * @throws JMSException for any JMS error
176 */
177 void createTopic(JmsTopic topic) throws JMSException;
178
179 /***
180 * Create a receiver endpoint for this session. A reciever is a message
181 * consumer specific to the queue message model. The receiver is associated
182 * with a queue.
183 * <p>
184 * You cannot create more than one receiver for the same destination
185 *
186 * @param queue the receiver destination
187 * @param clientId the session allocated identifier of this consumer
188 * @param selector the message selector. This may be null.
189 * @return the unique consumer identifier
190 * @throws JMSException for any JMS error
191 */
192 void createReceiver(JmsQueue queue, long clientId, String selector)
193 throws JMSException;
194
195 /***
196 * Create a sender endpoint for this session. A sender is a message
197 * publisher specific to the queue message model. The sender is associated
198 * with a queue.
199 * <p>
200 * You cannot create more than one receiver for the same destination
201 *
202 * @param queue the receiver destination
203 * @throws JMSException for any JMS error
204 */
205 void createSender(JmsQueue queue) throws JMSException;
206
207 /***
208 * Create a queue browser for this session. This allows clients to browse
209 * a queue without removing any messages.
210 * <p>
211 *
212 * You cannot create more than one queue browser for the same queue
213 * in a single session.
214 *
215 * @param queue the queue to browse
216 * @param clientId the client identity
217 * @param selector the message selector. This may be null
218 * @throws JMSException for any JMS error
219 */
220 void createBrowser(JmsQueue queue, long clientId, String selector)
221 throws JMSException;
222
223 /***
224 * Delete the receiver with the corresponding client id.
225 *
226 * @param clientId the identity of the receiver to delete
227 * @throws JMSException for any JMS error
228 */
229 void deleteReceiver(long clientId) throws JMSException;
230
231 /***
232 * Delete the queue browser associated with the corresponding client id.
233 *
234 * @param clientId the id of the browser
235 * @throws JMSException for any JMS error
236 */
237 void deleteBrowser(long clientId) throws JMSException;
238
239 /***
240 * Create a subscriber endpoint for this session. A subscriber is a message
241 * consumer specific to the topic message model. The subscriber is
242 * associated with a topic. The name is used to identify the consumer and
243 * can be set to null
244 * <p>
245 * You cannot create more than one subscriber for the same destination
246 *
247 * @param topic subscriber destination
248 * @param name name of the consumer associated with the subscriber.
249 * This may be null.
250 * @param clientId the session allocated identifier of this consumer
251 * @param selector message selector. This may be null.
252 * @param noLocal inhibit consuming messages on same connection.
253 * @throws JMSException for any JMS error
254 */
255 void createSubscriber(JmsTopic topic, String name, long clientId,
256 String selector, boolean noLocal)
257 throws JMSException;
258
259 /***
260 * Create a publisher endpoint for this session. A publisher is a message
261 * publisher specific to the topic message model. The publisher is
262 * associated with a topic.
263 * <p>
264 * You cannot create more than one publisher for the same destination
265 *
266 * @param topic receiver destination
267 * @throws JMSException for any JMS error
268 */
269 void createPublisher(JmsTopic topic) throws JMSException;
270
271 /***
272 * Delete the subscriber associated with the sepcified identity.
273 *
274 * @param clientid the client identity
275 * @throws JMSException for any JMS error
276 */
277 void deleteSubscriber(long clientId) throws JMSException;
278
279 /***
280 * Unsubscribe a durable subscription
281 *
282 * @param name the name used to identify the subscription
283 * @throws JMSException for any JMS error
284 */
285 void unsubscribe(String name) throws JMSException;
286
287 /***
288 * Stop message delivery to this session
289 *
290 * @throws JMSException for any JMS error
291 */
292 void stopMessageDelivery() throws JMSException;
293
294 /***
295 * Start message delivery to this session
296 *
297 * @throws JMSException for any JMS error
298 */
299 void startMessageDelivery() throws JMSException;
300
301 /***
302 * Set the listener for this session. The listener is an object that
303 * implements MessageListener and is called back whenever a message
304 * for the session is present
305 *
306 * @param listener the message listener
307 */
308 void setMessageListener(JmsMessageListener listener);
309
310 /***
311 * Enable or disable asynchronous message delivery for a particular
312 * consumer
313 *
314 * @param clientId the id of the client to check
315 * @param id the message id of the last delivered message
316 * @param enable true to enable; false to disable
317 * @throws JMSException for any JMS error
318 */
319 void enableAsynchronousDelivery(long clientId, String id, boolean enable)
320 throws JMSException;
321
322 /***
323 * Recover the session. This means all unacknowledged messages are
324 * resent with the redelivery flag set
325 *
326 * @throws JMSException if the session cannot be recovered
327 */
328 void recover() throws JMSException;
329
330 /***
331 * Commit the session which will send all the published messages and
332 * acknowledge all received messages
333 *
334 * @throws JMSException if the session cannot be committed
335 */
336 void commit() throws JMSException;
337
338 /***
339 * Rollback the session, which will not acknowledge any of the sent
340 * messages
341 *
342 * @throws JMSException if the session cannot be rolled back
343 */
344 void rollback() throws JMSException;
345
346 /***
347 * Commits an XA transaction that is in progress.
348 *
349 * @param xid the xa transaction identity
350 * @param onePhase true if it is a one phase commit
351 * @throws XAException if there is a problem completing the call
352 */
353 void commit(Xid xid, boolean onePhase) throws XAException;
354
355 /***
356 * Ends the work performed on behalf of a transaction branch. The resource
357 * manager disassociates the XA resource from the transaction branch
358 * specified and let the transaction be completedCommits an XA transaction
359 * that is in progress.
360 *
361 * @param xid the xa transaction identity
362 * @param flags one of TMSUCCESS, TMFAIL, or TMSUSPEND
363 * @throws XAException if there is a problem completing the call
364 */
365 void end(Xid xid, int flags) throws XAException;
366
367 /***
368 * Tell the resource manager to forget about a heuristically completed
369 * transaction branch.
370 *
371 * @param xid the xa transaction identity
372 * @throws XAException if there is a problem completing the call
373 */
374 void forget(Xid xid) throws XAException;
375
376 /***
377 * Return the transaction timeout for this instance of the resource
378 * manager.
379 *
380 * @return the timeout in seconds
381 * @throws XAException if there is a problem completing the call
382 */
383 int getTransactionTimeout() throws XAException;
384
385 /***
386 * Ask the resource manager to prepare for a transaction commit of the
387 *transaction specified in xid
388 *
389 * @param xid the xa transaction identity
390 * @return XA_RDONLY or XA_OK
391 * @throws XAException if there is a problem completing the call
392 */
393 int prepare(Xid xid) throws XAException;
394
395 /***
396 * Obtain a list of prepared transaction branches from a resource manager.
397 * The transaction manager calls this method during recovery to obtain the
398 * list of transaction branches that are currently in prepared or
399 * heuristically completed states.
400 *
401 * @param flag One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS
402 * @return the set of Xids to recover
403 * @throws XAException - if there is a problem completing the call
404 */
405 Xid[] recover(int flag) throws XAException;
406
407 /***
408 * Inform the resource manager to roll back work done on behalf of a
409 * transaction branch
410 *
411 * @param xid the xa transaction identity
412 * @throws XAException if there is a problem completing the call
413 */
414 void rollback(Xid xid) throws XAException;
415
416 /***
417 * Set the current transaction timeout value for this XAResource instance.
418 *
419 * @param seconds timeout in seconds
420 * @return if the new transaction timeout was accepted
421 * @throws XAException if there is a problem completing the call
422 */
423 boolean setTransactionTimeout(int seconds) throws XAException;
424
425 /***
426 * Start work on behalf of a transaction branch specified in xid If TMJOIN
427 * is specified, the start is for joining a transaction previously seen by
428 * the resource manager
429 *
430 * @param xid the xa transaction identity
431 * @param flags One of TMNOFLAGS, TMJOIN, or TMRESUME
432 * @throws XAException if there is a problem completing the call
433 */
434 void start(Xid xid, int flags) throws XAException;
435
436 /***
437 * Return the identity of the associated resource manager.
438 *
439 * @return the identity of the resource manager
440 * @throws XAException if there is a problem completing the call
441 */
442 String getResourceManagerId() throws XAException;
443 }