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: RemoteJmsServerSessionIfc.java,v 1.18 2003/08/07 13:33:10 tanderson Exp $
44 *
45 * Date Author Changes
46 * 04/07/2000 jima Created
47 * 05/09/2000 jima Changed acknowledgeMessage signature to take
48 * destination name instead of client identity
49 */
50 package org.exolab.jms.server.rmi;
51
52 import java.rmi.Remote;
53 import java.rmi.RemoteException;
54 import java.util.Vector;
55
56 import javax.jms.JMSException;
57 import javax.jms.Message;
58 import javax.jms.MessageListener;
59 import javax.transaction.xa.XAException;
60 import javax.transaction.xa.XAResource;
61 import javax.transaction.xa.Xid;
62
63 import org.exolab.jms.client.JmsQueue;
64 import org.exolab.jms.client.JmsTopic;
65 import org.exolab.jms.client.rmi.RemoteJmsMessageListenerIfc;
66
67
68 /***
69 * This is an RMI wrapper for the JmsServerSession object. It allows remote
70 * access to this object.
71 * <p>
72 * For more semantic information on this object refer to org.exolab.jms.server.
73 * JmsServerSession.
74 * <p>
75 * All the methods throw RemoteException which is used to indicate an RMI
76 * specific error.
77 *
78 * @version $Revision: 1.18 $ $Date: 2003/08/07 13:33:10 $
79 * @author <a href="mailto:jima@exoffice.com">Jim Alateras</a>
80 * @see org.exolab.jms.server.JmsServerSession
81 * @see org.exolab.jms.server.rmi.RemoteJmsServerConnectionIfc
82 **/
83 public interface RemoteJmsServerSessionIfc
84 extends Remote {
85
86 /***
87 * Return a reference to the client id.
88 *
89 * @return String client id
90 * @exception RemoteException
91 */
92 public String getClientId()
93 throws RemoteException;
94
95 /***
96 * Return a reference to the session id
97 *
98 * @return String session id
99 * @exception RemoteException
100 */
101 public String getSessionId()
102 throws JMSException, RemoteException;
103
104 /***
105 * Close and release any resource allocated to this session. Throw the
106 * JMSException exception is a problem is encountered
107 *
108 * @exception JMSException
109 * @exception RemoteException
110 */
111 public void close()
112 throws JMSException, RemoteException;
113
114 /***
115 * Acknowledge that the message with the following id has been processed
116 *
117 * @param clientId the client identity
118 * @param messageId id of message to ack
119 * @exception JMSException if method does not complete
120 * @exception RemoteException
121 */
122 public void acknowledgeMessage(long clientId, String messageId)
123 throws JMSException, RemoteException;
124
125 /***
126 * Send the specified message to the server. If there is any problem
127 * then throw the JMSException exception
128 *
129 * @param message message to send
130 * @exception JMSException
131 * @exception RemoteException
132 */
133 public void sendMessage(Message message)
134 throws JMSException, RemoteException;
135
136 /***
137 * Send the specified messages to the server. If there is any problem
138 * then throw the JMSException exception
139 *
140 * @param messages messages to send
141 * @exception JMSException
142 * @exception RemoteException
143 */
144 public void sendMessages(Vector messages)
145 throws JMSException, RemoteException;
146
147 /***
148 * Return the next message for the specified client. The <code>wait</code>
149 * parameter indicates how long many milliseconds to wait for a message
150 * before returning. If <code>wait</code> is 0 then do not wait at all. If
151 * <code>wait</code> is -1 then wait indefinitely for the next message
152 *
153 * @param clientId the client identity
154 * @param wait number of ms to wait
155 * @return Message the next message or null
156 * @exception JMSException if there is an app level problem
157 * @exception RemoteException if there is a RMI based exception.
158 */
159 public Message receiveMessage(long clientId, long wait)
160 throws JMSException, RemoteException;
161
162 /***
163 * Return upto count messages from the endpoint with the specified client
164 * identity.
165 *
166 * @param clientId the client identity
167 * @param count max number of messages to receive
168 * @return Message the next message or null
169 * @exception JMSException if there is an app level problem
170 * @exception RemoteException if there is a RMI based exception.
171 */
172 public Vector receiveMessages(long clientId, int count)
173 throws JMSException, RemoteException;
174
175 /***
176 * Create a queue with the specified name. If the queue already exists
177 * then simply return a reference to it. If the queue does not exist
178 * then create it. If it cannot create the queue then throw the
179 * JMSException exception
180 *
181 * @param queue queue to create
182 * @exception JMSException
183 * @exception RemoteException
184 */
185 public void createQueue(JmsQueue queue)
186 throws JMSException, RemoteException;
187
188 /***
189 * Create a topic with the specified name. If the topic already exists
190 * then simply return a reference to it. If the topic does not exist
191 * then create it. If it cannot create the topic then throw the
192 * JMSException exception
193 *
194 * @param topic topic to create
195 * @exception JMSException
196 * @exception RemoteException
197 */
198 public void createTopic(JmsTopic topic)
199 throws JMSException, RemoteException;
200
201 /***
202 * Create a receiver endpoint for this session. A reciever is a message
203 * consumer specific to the queue message model. The receiver is
204 * associated with a queue.
205 * <p>
206 * You cannot create more than one receiver for the same destination
207 *
208 * @param queue receiver destination
209 * @param clientId the session allocated identifier of
210 * this consumer
211 * @param selector the selector to filter messages.
212 * This may be null.
213 * @exception JMSException.
214 * @exception RemoteException
215 */
216 public void createReceiver(JmsQueue queue, long clientId, String selector)
217 throws JMSException, RemoteException;
218
219 /***
220 * Create a sender endpoint for this session. A sender is a message
221 * publisher specific to the queue message model. The sender is associated
222 * with a queue.
223 * <p>
224 *
225 * You cannot create more than one receiver for the same destination
226 *
227 * @param queue receiver destination
228 * @exception JMSException.
229 * @exception RemoteException
230 */
231 public void createSender(JmsQueue queue)
232 throws JMSException, RemoteException;
233
234 /***
235 * Delete the receiver with the specified identity. If the receiver does
236 * not exist or cannot be deleted throw JMSException
237 *
238 * @param queue
239 * @exception JMSException.
240 * @exception RemoteException
241 */
242
243 /***
244 * Create a queue browser for this session. This allows clients to browse
245 * a queue without removing any messages.
246 * <p>
247 *
248 * You cannot create more than one queue browser for the same queue
249 * in a single session.
250 *
251 * @param queue queue to browse
252 * @param clientId identity of the client
253 * @param selector message selector. This may be null
254 * @exception JMSException
255 * @exception RemoteException
256 */
257 public void createBrowser(JmsQueue queue, long clientId, String selector)
258 throws JMSException, RemoteException;
259
260 /***
261 * Delete the specified receiver
262 *
263 * @param clientId the identity of the receiver
264 * @exception JMSException.
265 * @exception RemoteException
266 */
267 public void deleteReceiver(long clientId)
268 throws JMSException, RemoteException;
269
270 /***
271 * Delete the sender for the specified queue. If the sender does not
272 * exist or the sender cannot be deleted then throw JMSException
273 *
274 * @param clientId the unique client identity
275 * @exception JMSException.
276 * @exception RemoteException
277 */
278 public void deleteSender(long clientId)
279 throws JMSException, RemoteException;
280
281 /***
282 * Delete the queue browser associated with the specified queue from
283 * the session.
284 * If the corresponding queue does not exist or it cannot be deleted,
285 * then throw a JMSException.
286 *
287 * @param clientId - the client identity
288 * @exception JMSException
289 * @exception RemoteException
290 */
291 public void deleteBrowser(long clientId)
292 throws JMSException, RemoteException;
293
294 /***
295 * Create a subscriber endpoint for this session. A subscriber is a message
296 * consumer specific to the topic message model. The subscriber is
297 * associated with a topic. The consumer name is used to identify an
298 * endpoint for persistent delivery. If we are using non-persistent
299 * delivery then this can be set to null
300 * <p>
301 * You cannot create more than one subscriber for the same destination
302 *
303 * @param topic subscriber destination
304 * @param name consumer name
305 * @param clientId the session allocated identifier of
306 * this consumer
307 * @param selector the selector to filter messages.
308 * This may be null.
309 * @param noLocal inhibit consuming messages on same
310 * connection.
311 * @exception JMSException.
312 * @exception RemoteException
313 */
314 public void createSubscriber(JmsTopic topic, String name, long clientId,
315 String selector, boolean noLocal)
316 throws JMSException, RemoteException;
317
318 /***
319 * Create a publisher endpoint for this session. A publisher is a message
320 * publisher specific to the topic message model. The publisher is
321 * associated with a topic. Return the unique identity of the publisher
322 * <p>
323 * You cannot create more than one publisher for the same destination
324 *
325 * @param topic receiver destination
326 * @exception JMSException.
327 * @exception RemoteException
328 */
329 public void createPublisher(JmsTopic topic)
330 throws JMSException, RemoteException;
331
332 /***
333 * Delete the subscriber for the specified topic. If this subscriber
334 * does not exist or the cannot be deleted then throw JMSException.
335 *
336 * @param clientId the client identity
337 * @exception JMSException.
338 */
339 public void deleteSubscriber(long clientId)
340 throws JMSException, RemoteException;
341
342 /***
343 * Delete the publisher for the specified topic. If the publisher does
344 * not exist or cannot be deleted then throw JMSException
345 *
346 * @param topic topic name
347 * @exception JMSException.
348 * @exception RemoteException.
349 */
350 public void deletePublisher(JmsTopic topic)
351 throws JMSException, RemoteException;
352
353 /***
354 * Unsubscribe a durable subscription
355 *
356 * @param name the name used to identify the
357 * subscription
358 * @exception JMSException if the subscription cannot be removed
359 * @exception RemoteException
360 */
361 public void unsubscribe(String name)
362 throws JMSException, RemoteException;
363
364 /***
365 * Stop message delivery to this session. If there are any problems
366 * completing the request then throw the JMSException exception
367 *
368 * @exception JMSException
369 * @exception RemoteException.
370 */
371 public void stopMessageDelivery()
372 throws JMSException, RemoteException;
373
374 /***
375 * Start message delivery to this session. If there are any problems
376 * completing this request then throw the JMSException exception
377 *
378 * @exception JMSException
379 * @exception RemoteException.
380 */
381 public void startMessageDelivery()
382 throws JMSException, RemoteException;
383
384 /***
385 * Recover the session. If there are any problems completing the request
386 * then throw the JMSException exception
387 *
388 * @exception JMSException
389 * @exception RemoteException.
390 */
391 public void recover()
392 throws JMSException, RemoteException;
393
394 /***
395 * Commit the session. If there are any problems completing the request
396 * then throw the JMSException exception
397 *
398 * @exception JMSException
399 * @exception RemoteException.
400 */
401 public void commit()
402 throws JMSException, RemoteException;
403
404 /***
405 * Rollback the session. If there are any problems completing the request
406 * then throw the JMSException exception
407 *
408 * @exception JMSException
409 * @exception RemoteException.
410 */
411 public void rollback()
412 throws JMSException, RemoteException;
413
414 /***
415 * Commits an XA transaction that is in progress.
416 *
417 * @param xid - the xa transaction identity
418 * @param onePhase - treu if it is a one phase commit
419 * @throws XAException - if there is a problem completing the call
420 * @throws RemoteException - communication related error
421 */
422 public void commit(Xid xid, boolean onePhase)
423 throws XAException, RemoteException;
424
425 /***
426 * Ends the work performed on behalf of a transaction branch. The resource
427 * manager disassociates the XA resource from the transaction branch
428 * specified and let the transaction be completedCommits an XA transaction
429 * that is in progress.
430 *
431 * @param xid - the xa transaction identity
432 * @param flags - one of TMSUCCESS, TMFAIL, or TMSUSPEND
433 * @throws XAException - if there is a problem completing the call
434 * @throws RemoteException - communication related error
435 */
436 public void end(Xid xid, int flags)
437 throws XAException, RemoteException;
438
439 /***
440 * Tell the resource manager to forget about a heuristically completed
441 * transaction branch.
442 *
443 * @param xid - the xa transaction identity
444 * @throws XAException - if there is a problem completing the call
445 * @throws RemoteException - communication related error
446 */
447 public void forget(Xid xid)
448 throws XAException, RemoteException;
449
450 /***
451 * Return the transaction timeout for this instance of the resource
452 * manager.
453 *
454 * @return int - the timeout in seconds
455 * @throws XAException - if there is a problem completing the call
456 * @throws RemoteException - communication related error
457 */
458 public int getTransactionTimeout()
459 throws XAException, RemoteException;
460
461 /***
462 * Ask the resource manager to prepare for a transaction commit of the
463 * transaction specified in xid
464 *
465 * @param xid - the xa transaction identity
466 * @return int - XA_RDONLY or XA_OK
467 * @throws XAException - if there is a problem completing the call
468 * @throws RemoteException - communication related error
469 */
470 public int prepare(Xid xid)
471 throws XAException, RemoteException;
472
473 /***
474 * Obtain a list of prepared transaction branches from a resource manager.
475 * The transaction manager calls this method during recovery to obtain the
476 * list of transaction branches that are currently in prepared or
477 * heuristically completed states.
478 *
479 * @param flag - One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS
480 * @param Xid[] - the set of Xids to recover
481 * @throws XAException - if there is a problem completing the call
482 * @throws RemoteException - communication related error
483 */
484 public Xid[] recover(int flag)
485 throws XAException, RemoteException;
486
487 /***
488 * Inform the resource manager to roll back work done on behalf of a
489 * transaction branch
490 *
491 * @param xid - the xa transaction identity
492 * @throws XAException - if there is a problem completing the call
493 * @throws RemoteException - communication related error
494 */
495 public void rollback(Xid xid)
496 throws XAException, RemoteException;
497
498 /***
499 * Set the current transaction timeout value for this XAResource instance.
500 *
501 * @param seconds - timeout in seconds
502 * @return boolean - true if the new transaction timeout was accepted
503 * @throws XAException - if there is a problem completing the call
504 * @throws RemoteException - communication related error
505 */
506 public boolean setTransactionTimeout(int seconds)
507 throws XAException, RemoteException;
508
509 /***
510 * Start work on behalf of a transaction branch specified in xid If TMJOIN
511 * is specified, the start is for joining a transaction previously seen by
512 * the resource manager
513 *
514 * @param xid - the xa transaction identity
515 * @param flags - One of TMNOFLAGS, TMJOIN, or TMRESUME
516 * @throws XAException - if there is a problem completing the call
517 * @throws RemoteException - communication related error
518 */
519 public void start(Xid xid, int flags)
520 throws XAException, RemoteException;
521
522 /***
523 * Return the resource manager identity
524 *
525 * @return the resource manager identity
526 * @throws XAException - if there is a problem completing the call
527 * @throws RemoteException - communication related error
528 */
529 public String getResourceManagerId() throws XAException, RemoteException;
530
531 /***
532 * All server side sessions register with the consumer manager for
533 * message consumption (i.e push-model). When a message arrives this
534 * server-side instance will send it down to the client side stub for
535 * further processing.
536 * <p>
537 * If the listener is null then throw JMSException
538 *
539 * @param listener listener to delivery messages too.
540 * @exception JMSException
541 * @exception RemoteException.
542 */
543 public void setMessageListener(RemoteJmsMessageListenerIfc listener)
544 throws JMSException, RemoteException;
545
546 /***
547 * Enable or disable asynchronous message delivery for a particular
548 * consumer
549 *
550 * @param clientId - the id of the client to check
551 * @param id - the last message asynchronously delivered
552 * @param enable - true to enable; false to disable
553 */
554 public void enableAsynchronousDelivery(long clientId, String id,
555 boolean enable)
556 throws JMSException, RemoteException;
557 }