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 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 }

This page was automatically generated by Maven