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 2001-2005 (C) Exoffice Technologies Inc. All Rights Reserved.
42 *
43 * $Id: MessageHandle.java,v 1.2 2005/08/30 07:26:49 tanderson Exp $
44 */
45 package org.exolab.jms.messagemgr;
46
47 import javax.jms.JMSException;
48 import javax.jms.MessageConsumer;
49
50 import org.exolab.jms.client.JmsDestination;
51 import org.exolab.jms.message.MessageImpl;
52
53
54 /***
55 * A message handle is used to indirectly reference a message.
56 *
57 * @author <a href="mailto:jima@comware.com.au">Jim Alateras</a>
58 * @author <a href="mailto:tma@netspace.net.au">Tim Anderson</a>
59 * @version $Revision: 1.2 $ $Date: 2005/08/30 07:26:49 $
60 * @see MessageHandleComparator
61 */
62 public interface MessageHandle {
63
64 /***
65 * Returns the message identifier.
66 *
67 * @return the message identifier
68 */
69 String getMessageId();
70
71 /***
72 * Indicates if a message has been delivered to a {@link MessageConsumer},
73 * but not acknowledged.
74 *
75 * @param delivered if <code>true</code> indicates that an attempt has been
76 * made to deliver the message
77 */
78 void setDelivered(boolean delivered);
79
80 /***
81 * Returns if an attempt has already been made to deliver the message.
82 *
83 * @return <code>true</code> if delivery has been attempted
84 */
85 boolean getDelivered();
86
87 /***
88 * Returns the priority of the message.
89 *
90 * @return the message priority
91 */
92 int getPriority();
93
94 /***
95 * Returns the time that the corresponding message was accepted, in
96 * milliseconds.
97 *
98 * @return the time that the corresponding message was accepted
99 */
100 long getAcceptedTime();
101
102 /***
103 * Returns the time that the message expires, in milliseconds.
104 *
105 * @return the expiry time
106 */
107 long getExpiryTime();
108
109 /***
110 * Determines if the message has expired.
111 *
112 * @return <code>true</code> if the message has expired, otherwise
113 * <code>false</code>
114 */
115 boolean hasExpired();
116
117 /***
118 * Returns the handle's sequence number.
119 *
120 * @return the sequence number
121 */
122 long getSequenceNumber();
123
124 /***
125 * Returns the message destination.
126 *
127 * @return the message destination
128 */
129 JmsDestination getDestination();
130
131 /***
132 * Returns the consumer identity associated with the message.
133 *
134 * @return the consumer identity associated with the message, or *
135 * <code>-1</code> if the message isn't associated with a consumer
136 */
137 long getConsumerId();
138
139 /***
140 * Returns the connection identity associated with the message.
141 *
142 * @return the connection identity associated with the message, or
143 * <code>-1</code> if the message isn't associated with a
144 * connection
145 */
146 long getConnectionId();
147
148 /***
149 * Returns the persistent identity of the the consumer endpoint that owns
150 * this handle. If it is set, then a consumer owns it exclusively, otherwise
151 * the handle may be shared across a number of consumers.
152 *
153 * @return the consumer's persistent identity, or <code>null</code>
154 */
155 String getConsumerPersistentId();
156
157 /***
158 * Determines if the handle is persistent.
159 *
160 * @return <code>true</code> if the handle is persistent; otherwise
161 * <code>false</code>
162 */
163 boolean isPersistent();
164
165 /***
166 * Returns the message associated with this handle.
167 *
168 * @return the associated message, or <code>null</code> if the handle is no
169 * longer valid
170 * @throws JMSException for any error
171 */
172 MessageImpl getMessage() throws JMSException;
173
174 /***
175 * Make the handle persistent.
176 *
177 * @throws JMSException for any persistence error
178 */
179 void add() throws JMSException;
180
181 /***
182 * Update the persistent handle.
183 *
184 * @throws JMSException for any persistence error
185 */
186 void update() throws JMSException;
187
188 /***
189 * Destroy this handle. If this is the last handle to reference the message,
190 * also destroys the message.
191 *
192 * @throws JMSException for any error
193 */
194 void destroy() throws JMSException;
195
196 /***
197 * Release the message handle back to the cache, to recover an unsent or
198 * unacknowledged message.
199 *
200 * @throws JMSException for any error
201 */
202 void release() throws JMSException;
203
204 /***
205 * Returns the message reference.
206 *
207 * @return the message reference, or <code>null</code> if none has been set
208 */
209 MessageRef getMessageRef();
210
211
212 }
213