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

This page was automatically generated by Maven