1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2000-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License ("CDDL") (collectively, the "License"). You may
9 * not use this file except in compliance with the License. You can obtain
10 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
11 * or mq/legal/LICENSE.txt. See the License for the specific language
12 * governing permissions and limitations under the License.
13 *
14 * When distributing the software, include this License Header Notice in each
15 * file and include the License file at mq/legal/LICENSE.txt. Sun designates
16 * this particular file as subject to the "Classpath" exception as provided by
17 * Sun in the GPL Version 2 section of the License file that accompanied this
18 * code. If applicable, add the following below the License Header, with the
19 * fields enclosed by brackets [] replaced by your own identifying information:
20 * "Portions Copyrighted [year] [name of copyright owner]"
21 *
22 * Contributor(s):
23 *
24 * If you wish your version of this file to be governed by only the CDDL or
25 * only the GPL Version 2, indicate your decision by adding "[Contributor]
26 * elects to include this software in this distribution under the [CDDL or GPL
27 * Version 2] license." If you don't indicate a single choice of license, a
28 * recipient has the option to distribute your version of this file under
29 * either the CDDL, the GPL Version 2 or to extend the choice of license to
30 * its licensees as provided above. However, if you add GPL Version 2 code
31 * and therefore, elected the GPL Version 2 license, then the option applies
32 * only if the new code is made subject to such option by the copyright holder.
33 */
34
35 /*
36 * @(#)Message.java 1.62 07/02/07
37 */
38
39 package javax.jms;
40
41 import java.util.Enumeration;
42 import java.util.Properties;
43
44 /** The <CODE>Message</CODE> interface is the root interface of all JMS
45 * messages. It defines the message header and the <CODE>acknowledge</CODE>
46 * method used for all messages.
47 *
48 * <P>Most message-oriented middleware (MOM) products treat messages as
49 * lightweight entities that consist
50 * of a header and a payload. The header contains fields used for message
51 * routing and identification; the payload contains the application data
52 * being sent.
53 *
54 * <P>Within this general form, the definition of a message varies
55 * significantly across products. It would be quite difficult for the JMS API
56 * to support all of these message models.
57 *
58 * <P>With this in mind, the JMS message model has the following goals:
59 * <UL>
60 * <LI>Provide a single, unified message API
61 * <LI>Provide an API suitable for creating messages that match the
62 * format used by provider-native messaging applications
63 * <LI>Support the development of heterogeneous applications that span
64 * operating systems, machine architectures, and computer languages
65 * <LI>Support messages containing objects in the Java programming language
66 * ("Java objects")
67 * <LI>Support messages containing Extensible Markup Language (XML) pages
68 * </UL>
69 *
70 * <P>JMS messages are composed of the following parts:
71 * <UL>
72 * <LI>Header - All messages support the same set of header fields.
73 * Header fields contain values used by both clients and providers to
74 * identify and route messages.
75 * <LI>Properties - Each message contains a built-in facility for supporting
76 * application-defined property values. Properties provide an efficient
77 * mechanism for supporting application-defined message filtering.
78 * <LI>Body - The JMS API defines several types of message body, which cover
79 * the majority of messaging styles currently in use.
80 * </UL>
81 *
82 * <H4>Message Bodies</H4>
83 *
84 * <P>The JMS API defines five types of message body:
85 * <UL>
86 * <LI>Stream - A <CODE>StreamMessage</CODE> object's message body contains
87 * a stream of primitive values in the Java programming
88 * language ("Java primitives"). It is filled and read sequentially.
89 * <LI>Map - A <CODE>MapMessage</CODE> object's message body contains a set
90 * of name-value pairs, where names are <CODE>String</CODE>
91 * objects, and values are Java primitives. The entries can be accessed
92 * sequentially or randomly by name. The order of the entries is
93 * undefined.
94 * <LI>Text - A <CODE>TextMessage</CODE> object's message body contains a
95 * <CODE>java.lang.String</CODE> object. This message type can be used
96 * to transport plain-text messages, and XML messages.
97 * <LI>Object - An <CODE>ObjectMessage</CODE> object's message body contains
98 * a <CODE>Serializable</CODE> Java object.
99 * <LI>Bytes - A <CODE>BytesMessage</CODE> object's message body contains a
100 * stream of uninterpreted bytes. This message type is for
101 * literally encoding a body to match an existing message format. In
102 * many cases, it is possible to use one of the other body types,
103 * which are easier to use. Although the JMS API allows the use of
104 * message properties with byte messages, they are typically not used,
105 * since the inclusion of properties may affect the format.
106 * </UL>
107 *
108 * <H4>Message Headers</H4>
109 *
110 * <P>The <CODE>JMSCorrelationID</CODE> header field is used for linking one
111 * message with
112 * another. It typically links a reply message with its requesting message.
113 *
114 * <P><CODE>JMSCorrelationID</CODE> can hold a provider-specific message ID,
115 * an application-specific <CODE>String</CODE> object, or a provider-native
116 * <CODE>byte[]</CODE> value.
117 *
118 * <H4>Message Properties</H4>
119 *
120 * <P>A <CODE>Message</CODE> object contains a built-in facility for supporting
121 * application-defined property values. In effect, this provides a mechanism
122 * for adding application-specific header fields to a message.
123 *
124 * <P>Properties allow an application, via message selectors, to have a JMS
125 * provider select, or filter, messages on its behalf using
126 * application-specific criteria.
127 *
128 * <P>Property names must obey the rules for a message selector identifier.
129 * Property names must not be null, and must not be empty strings. If a property
130 * name is set and it is either null or an empty string, an
131 * <CODE>IllegalArgumentException</CODE> must be thrown.
132 *
133 * <P>Property values can be <CODE>boolean</CODE>, <CODE>byte</CODE>,
134 * <CODE>short</CODE>, <CODE>int</CODE>, <CODE>long</CODE>, <CODE>float</CODE>,
135 * <CODE>double</CODE>, and <CODE>String</CODE>.
136 *
137 * <P>Property values are set prior to sending a message. When a client
138 * receives a message, its properties are in read-only mode. If a
139 * client attempts to set properties at this point, a
140 * <CODE>MessageNotWriteableException</CODE> is thrown. If
141 * <CODE>clearProperties</CODE> is called, the properties can now be both
142 * read from and written to. Note that header fields are distinct from
143 * properties. Header fields are never in read-only mode.
144 *
145 * <P>A property value may duplicate a value in a message's body, or it may
146 * not. Although JMS does not define a policy for what should or should not
147 * be made a property, application developers should note that JMS providers
148 * will likely handle data in a message's body more efficiently than data in
149 * a message's properties. For best performance, applications should use
150 * message properties only when they need to customize a message's header.
151 * The primary reason for doing this is to support customized message
152 * selection.
153 *
154 * <P>Message properties support the following conversion table. The marked
155 * cases must be supported. The unmarked cases must throw a
156 * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions
157 * may throw a runtime exception if the
158 * primitive's <CODE>valueOf</CODE> method does not accept the
159 * <CODE>String</CODE> as a valid representation of the primitive.
160 *
161 * <P>A value written as the row type can be read as the column type.
162 *
163 * <PRE>
164 * | | boolean byte short int long float double String
165 * |----------------------------------------------------------
166 * |boolean | X X
167 * |byte | X X X X X
168 * |short | X X X X
169 * |int | X X X
170 * |long | X X
171 * |float | X X X
172 * |double | X X
173 * |String | X X X X X X X X
174 * |----------------------------------------------------------
175 * </PRE>
176 *
177 * <P>In addition to the type-specific set/get methods for properties, JMS
178 * provides the <CODE>setObjectProperty</CODE> and
179 * <CODE>getObjectProperty</CODE> methods. These support the same set of
180 * property types using the objectified primitive values. Their purpose is
181 * to allow the decision of property type to made at execution time rather
182 * than at compile time. They support the same property value conversions.
183 *
184 * <P>The <CODE>setObjectProperty</CODE> method accepts values of class
185 * <CODE>Boolean</CODE>, <CODE>Byte</CODE>, <CODE>Short</CODE>,
186 * <CODE>Integer</CODE>, <CODE>Long</CODE>, <CODE>Float</CODE>,
187 * <CODE>Double</CODE>, and <CODE>String</CODE>. An attempt
188 * to use any other class must throw a <CODE>JMSException</CODE>.
189 *
190 * <P>The <CODE>getObjectProperty</CODE> method only returns values of class
191 * <CODE>Boolean</CODE>, <CODE>Byte</CODE>, <CODE>Short</CODE>,
192 * <CODE>Integer</CODE>, <CODE>Long</CODE>, <CODE>Float</CODE>,
193 * <CODE>Double</CODE>, and <CODE>String</CODE>.
194 *
195 * <P>The order of property values is not defined. To iterate through a
196 * message's property values, use <CODE>getPropertyNames</CODE> to retrieve
197 * a property name enumeration and then use the various property get methods
198 * to retrieve their values.
199 *
200 * <P>A message's properties are deleted by the <CODE>clearProperties</CODE>
201 * method. This leaves the message with an empty set of properties.
202 *
203 * <P>Getting a property value for a name which has not been set returns a
204 * null value. Only the <CODE>getStringProperty</CODE> and
205 * <CODE>getObjectProperty</CODE> methods can return a null value.
206 * Attempting to read a null value as a primitive type must be treated as
207 * calling the primitive's corresponding <CODE>valueOf(String)</CODE>
208 * conversion method with a null value.
209 *
210 * <P>The JMS API reserves the <CODE>JMSX</CODE> property name prefix for JMS
211 * defined properties.
212 * The full set of these properties is defined in the Java Message Service
213 * specification. New JMS defined properties may be added in later versions
214 * of the JMS API. Support for these properties is optional. The
215 * <CODE>String[] ConnectionMetaData.getJMSXPropertyNames</CODE> method
216 * returns the names of the JMSX properties supported by a connection.
217 *
218 * <P>JMSX properties may be referenced in message selectors whether or not
219 * they are supported by a connection. If they are not present in a
220 * message, they are treated like any other absent property.
221 *
222 * <P>JMSX properties defined in the specification as "set by provider on
223 * send" are available to both the producer and the consumers of the message.
224 * JMSX properties defined in the specification as "set by provider on
225 * receive" are available only to the consumers.
226 *
227 * <P><CODE>JMSXGroupID</CODE> and <CODE>JMSXGroupSeq</CODE> are standard
228 * properties that clients
229 * should use if they want to group messages. All providers must support them.
230 * Unless specifically noted, the values and semantics of the JMSX properties
231 * are undefined.
232 *
233 * <P>The JMS API reserves the <CODE>JMS_<I>vendor_name</I></CODE> property
234 * name prefix for provider-specific properties. Each provider defines its own
235 * value for <CODE><I>vendor_name</I></CODE>. This is the mechanism a JMS
236 * provider uses to make its special per-message services available to a JMS
237 * client.
238 *
239 * <P>The purpose of provider-specific properties is to provide special
240 * features needed to integrate JMS clients with provider-native clients in a
241 * single JMS application. They should not be used for messaging between JMS
242 * clients.
243 *
244 * <H4>Provider Implementations of JMS Message Interfaces</H4>
245 *
246 * <P>The JMS API provides a set of message interfaces that define the JMS
247 * message
248 * model. It does not provide implementations of these interfaces.
249 *
250 * <P>Each JMS provider supplies a set of message factories with its
251 * <CODE>Session</CODE> object for creating instances of messages. This allows
252 * a provider to use message implementations tailored to its specific needs.
253 *
254 * <P>A provider must be prepared to accept message implementations that are
255 * not its own. They may not be handled as efficiently as its own
256 * implementation; however, they must be handled.
257 *
258 * <P>Note the following exception case when a provider is handling a foreign
259 * message implementation. If the foreign message implementation contains a
260 * <CODE>JMSReplyTo</CODE> header field that is set to a foreign destination
261 * implementation, the provider is not required to handle or preserve the
262 * value of this header field.
263 *
264 * <H4>Message Selectors</H4>
265 *
266 * <P>A JMS message selector allows a client to specify, by
267 * header field references and property references, the
268 * messages it is interested in. Only messages whose header
269 * and property values
270 * match the
271 * selector are delivered. What it means for a message not to be delivered
272 * depends on the <CODE>MessageConsumer</CODE> being used (see
273 * {@link javax.jms.QueueReceiver QueueReceiver} and
274 * {@link javax.jms.TopicSubscriber TopicSubscriber}).
275 *
276 * <P>Message selectors cannot reference message body values.
277 *
278 * <P>A message selector matches a message if the selector evaluates to
279 * true when the message's header field values and property values are
280 * substituted for their corresponding identifiers in the selector.
281 *
282 * <P>A message selector is a <CODE>String</CODE> whose syntax is based on a
283 * subset of
284 * the SQL92 conditional expression syntax. If the value of a message selector
285 * is an empty string, the value is treated as a null and indicates that there
286 * is no message selector for the message consumer.
287 *
288 * <P>The order of evaluation of a message selector is from left to right
289 * within precedence level. Parentheses can be used to change this order.
290 *
291 * <P>Predefined selector literals and operator names are shown here in
292 * uppercase; however, they are case insensitive.
293 *
294 * <P>A selector can contain:
295 *
296 * <UL>
297 * <LI>Literals:
298 * <UL>
299 * <LI>A string literal is enclosed in single quotes, with a single quote
300 * represented by doubled single quote; for example,
301 * <CODE>'literal'</CODE> and <CODE>'literal''s'</CODE>. Like
302 * string literals in the Java programming language, these use the
303 * Unicode character encoding.
304 * <LI>An exact numeric literal is a numeric value without a decimal
305 * point, such as <CODE>57</CODE>, <CODE>-957</CODE>, and
306 * <CODE>+62</CODE>; numbers in the range of <CODE>long</CODE> are
307 * supported. Exact numeric literals use the integer literal
308 * syntax of the Java programming language.
309 * <LI>An approximate numeric literal is a numeric value in scientific
310 * notation, such as <CODE>7E3</CODE> and <CODE>-57.9E2</CODE>, or a
311 * numeric value with a decimal, such as <CODE>7.</CODE>,
312 * <CODE>-95.7</CODE>, and <CODE>+6.2</CODE>; numbers in the range of
313 * <CODE>double</CODE> are supported. Approximate literals use the
314 * floating-point literal syntax of the Java programming language.
315 * <LI>The boolean literals <CODE>TRUE</CODE> and <CODE>FALSE</CODE>.
316 * </UL>
317 * <LI>Identifiers:
318 * <UL>
319 * <LI>An identifier is an unlimited-length sequence of letters
320 * and digits, the first of which must be a letter. A letter is any
321 * character for which the method <CODE>Character.isJavaLetter</CODE>
322 * returns true. This includes <CODE>'_'</CODE> and <CODE>'$'</CODE>.
323 * A letter or digit is any character for which the method
324 * <CODE>Character.isJavaLetterOrDigit</CODE> returns true.
325 * <LI>Identifiers cannot be the names <CODE>NULL</CODE>,
326 * <CODE>TRUE</CODE>, and <CODE>FALSE</CODE>.
327 * <LI>Identifiers cannot be <CODE>NOT</CODE>, <CODE>AND</CODE>,
328 * <CODE>OR</CODE>, <CODE>BETWEEN</CODE>, <CODE>LIKE</CODE>,
329 * <CODE>IN</CODE>, <CODE>IS</CODE>, or <CODE>ESCAPE</CODE>.
330 * <LI>Identifiers are either header field references or property
331 * references. The type of a property value in a message selector
332 * corresponds to the type used to set the property. If a property
333 * that does not exist in a message is referenced, its value is
334 * <CODE>NULL</CODE>.
335 * <LI>The conversions that apply to the get methods for properties do not
336 * apply when a property is used in a message selector expression.
337 * For example, suppose you set a property as a string value, as in the
338 * following:
339 * <PRE>myMessage.setStringProperty("NumberOfOrders", "2");</PRE>
340 * The following expression in a message selector would evaluate to
341 * false, because a string cannot be used in an arithmetic expression:
342 * <PRE>"NumberOfOrders > 1"</PRE>
343 * <LI>Identifiers are case-sensitive.
344 * <LI>Message header field references are restricted to
345 * <CODE>JMSDeliveryMode</CODE>, <CODE>JMSPriority</CODE>,
346 * <CODE>JMSMessageID</CODE>, <CODE>JMSTimestamp</CODE>,
347 * <CODE>JMSCorrelationID</CODE>, and <CODE>JMSType</CODE>.
348 * <CODE>JMSMessageID</CODE>, <CODE>JMSCorrelationID</CODE>, and
349 * <CODE>JMSType</CODE> values may be null and if so are treated as a
350 * <CODE>NULL</CODE> value.
351 * <LI>Any name beginning with <CODE>'JMSX'</CODE> is a JMS defined
352 * property name.
353 * <LI>Any name beginning with <CODE>'JMS_'</CODE> is a provider-specific
354 * property name.
355 * <LI>Any name that does not begin with <CODE>'JMS'</CODE> is an
356 * application-specific property name.
357 * </UL>
358 * <LI>White space is the same as that defined for the Java programming
359 * language: space, horizontal tab, form feed, and line terminator.
360 * <LI>Expressions:
361 * <UL>
362 * <LI>A selector is a conditional expression; a selector that evaluates
363 * to <CODE>true</CODE> matches; a selector that evaluates to
364 * <CODE>false</CODE> or unknown does not match.
365 * <LI>Arithmetic expressions are composed of themselves, arithmetic
366 * operations, identifiers (whose value is treated as a numeric
367 * literal), and numeric literals.
368 * <LI>Conditional expressions are composed of themselves, comparison
369 * operations, and logical operations.
370 * </UL>
371 * <LI>Standard bracketing <CODE>()</CODE> for ordering expression evaluation
372 * is supported.
373 * <LI>Logical operators in precedence order: <CODE>NOT</CODE>,
374 * <CODE>AND</CODE>, <CODE>OR</CODE>
375 * <LI>Comparison operators: <CODE>=</CODE>, <CODE>></CODE>, <CODE>>=</CODE>,
376 * <CODE><</CODE>, <CODE><=</CODE>, <CODE><></CODE> (not equal)
377 * <UL>
378 * <LI>Only like type values can be compared. One exception is that it
379 * is valid to compare exact numeric values and approximate numeric
380 * values; the type conversion required is defined by the rules of
381 * numeric promotion in the Java programming language. If the
382 * comparison of non-like type values is attempted, the value of the
383 * operation is false. If either of the type values evaluates to
384 * <CODE>NULL</CODE>, the value of the expression is unknown.
385 * <LI>String and boolean comparison is restricted to <CODE>=</CODE> and
386 * <CODE><></CODE>. Two strings are equal
387 * if and only if they contain the same sequence of characters.
388 * </UL>
389 * <LI>Arithmetic operators in precedence order:
390 * <UL>
391 * <LI><CODE>+</CODE>, <CODE>-</CODE> (unary)
392 * <LI><CODE>*</CODE>, <CODE>/</CODE> (multiplication and division)
393 * <LI><CODE>+</CODE>, <CODE>-</CODE> (addition and subtraction)
394 * <LI>Arithmetic operations must use numeric promotion in the Java
395 * programming language.
396 * </UL>
397 * <LI><CODE><I>arithmetic-expr1</I> [NOT] BETWEEN <I>arithmetic-expr2</I>
398 * AND <I>arithmetic-expr3</I></CODE> (comparison operator)
399 * <UL>
400 * <LI><CODE>"age BETWEEN 15 AND 19"</CODE> is
401 * equivalent to
402 * <CODE>"age >= 15 AND age <= 19"</CODE>
403 * <LI><CODE>"age NOT BETWEEN 15 AND 19"</CODE>
404 * is equivalent to
405 * <CODE>"age < 15 OR age > 19"</CODE>
406 * </UL>
407 * <LI><CODE><I>identifier</I> [NOT] IN (<I>string-literal1</I>,
408 * <I>string-literal2</I>,...)</CODE> (comparison operator where
409 * <CODE><I>identifier</I></CODE> has a <CODE>String</CODE> or
410 * <CODE>NULL</CODE> value)
411 * <UL>
412 * <LI><CODE>"Country IN (' UK', 'US', 'France')"</CODE>
413 * is true for
414 * <CODE>'UK'</CODE> and false for <CODE>'Peru'</CODE>; it is
415 * equivalent to the expression
416 * <CODE>"(Country = ' UK') OR (Country = ' US') OR (Country = ' France')"</CODE>
417 * <LI><CODE>"Country NOT IN (' UK', 'US', 'France')"</CODE>
418 * is false for <CODE>'UK'</CODE> and true for <CODE>'Peru'</CODE>; it
419 * is equivalent to the expression
420 * <CODE>"NOT ((Country = ' UK') OR (Country = ' US') OR (Country = ' France'))"</CODE>
421 * <LI>If identifier of an <CODE>IN</CODE> or <CODE>NOT IN</CODE>
422 * operation is <CODE>NULL</CODE>, the value of the operation is
423 * unknown.
424 * </UL>
425 * <LI><CODE><I>identifier</I> [NOT] LIKE <I>pattern-value</I> [ESCAPE
426 * <I>escape-character</I>]</CODE> (comparison operator, where
427 * <CODE><I>identifier</I></CODE> has a <CODE>String</CODE> value;
428 * <CODE><I>pattern-value</I></CODE> is a string literal where
429 * <CODE>'_'</CODE> stands for any single character; <CODE>'%'</CODE>
430 * stands for any sequence of characters, including the empty sequence;
431 * and all other characters stand for themselves. The optional
432 * <CODE><I>escape-character</I></CODE> is a single-character string
433 * literal whose character is used to escape the special meaning of the
434 * <CODE>'_'</CODE> and <CODE>'%'</CODE> in
435 * <CODE><I>pattern-value</I></CODE>.)
436 * <UL>
437 * <LI><CODE>"phone LIKE '12%3'"</CODE> is true for
438 * <CODE>'123'</CODE> or <CODE>'12993'</CODE> and false for
439 * <CODE>'1234'</CODE>
440 * <LI><CODE>"word LIKE 'l_se'"</CODE> is true for
441 * <CODE>'lose'</CODE> and false for <CODE>'loose'</CODE>
442 * <LI><CODE>"underscored LIKE '\_%' ESCAPE '\'"</CODE>
443 * is true for <CODE>'_foo'</CODE> and false for <CODE>'bar'</CODE>
444 * <LI><CODE>"phone NOT LIKE '12%3'"</CODE> is false for
445 * <CODE>'123'</CODE> or <CODE>'12993'</CODE> and true for
446 * <CODE>'1234'</CODE>
447 * <LI>If <CODE><I>identifier</I></CODE> of a <CODE>LIKE</CODE> or
448 * <CODE>NOT LIKE</CODE> operation is <CODE>NULL</CODE>, the value
449 * of the operation is unknown.
450 * </UL>
451 * <LI><CODE><I>identifier</I> IS NULL</CODE> (comparison operator that tests
452 * for a null header field value or a missing property value)
453 * <UL>
454 * <LI><CODE>"prop_name IS NULL"</CODE>
455 * </UL>
456 * <LI><CODE><I>identifier</I> IS NOT NULL</CODE> (comparison operator that
457 * tests for the existence of a non-null header field value or a property
458 * value)
459 * <UL>
460 * <LI><CODE>"prop_name IS NOT NULL"</CODE>
461 * </UL>
462 *
463 * <P>JMS providers are required to verify the syntactic correctness of a
464 * message selector at the time it is presented. A method that provides a
465 * syntactically incorrect selector must result in a <CODE>JMSException</CODE>.
466 * JMS providers may also optionally provide some semantic checking at the time
467 * the selector is presented. Not all semantic checking can be performed at
468 * the time a message selector is presented, because property types are not known.
469 *
470 * <P>The following message selector selects messages with a message type
471 * of car and color of blue and weight greater than 2500 pounds:
472 *
473 * <PRE>"JMSType = 'car' AND color = 'blue' AND weight > 2500"</PRE>
474 *
475 * <H4>Null Values</H4>
476 *
477 * <P>As noted above, property values may be <CODE>NULL</CODE>. The evaluation
478 * of selector expressions containing <CODE>NULL</CODE> values is defined by
479 * SQL92 <CODE>NULL</CODE> semantics. A brief description of these semantics
480 * is provided here.
481 *
482 * <P>SQL treats a <CODE>NULL</CODE> value as unknown. Comparison or arithmetic
483 * with an unknown value always yields an unknown value.
484 *
485 * <P>The <CODE>IS NULL</CODE> and <CODE>IS NOT NULL</CODE> operators convert
486 * an unknown value into the respective <CODE>TRUE</CODE> and
487 * <CODE>FALSE</CODE> values.
488 *
489 * <P>The boolean operators use three-valued logic as defined by the
490 * following tables:
491 *
492 * <P><B>The definition of the <CODE>AND</CODE> operator</B>
493 *
494 * <PRE>
495 * | AND | T | F | U
496 * +------+-------+-------+-------
497 * | T | T | F | U
498 * | F | F | F | F
499 * | U | U | F | U
500 * +------+-------+-------+-------
501 * </PRE>
502 *
503 * <P><B>The definition of the <CODE>OR</CODE> operator</B>
504 *
505 * <PRE>
506 * | OR | T | F | U
507 * +------+-------+-------+--------
508 * | T | T | T | T
509 * | F | T | F | U
510 * | U | T | U | U
511 * +------+-------+-------+-------
512 * </PRE>
513 *
514 * <P><B>The definition of the <CODE>NOT</CODE> operator</B>
515 *
516 * <PRE>
517 * | NOT
518 * +------+------
519 * | T | F
520 * | F | T
521 * | U | U
522 * +------+-------
523 * </PRE>
524 *
525 * <H4>Special Notes</H4>
526 *
527 * <P>When used in a message selector, the <CODE>JMSDeliveryMode</CODE> header
528 * field is treated as having the values <CODE>'PERSISTENT'</CODE> and
529 * <CODE>'NON_PERSISTENT'</CODE>.
530 *
531 * <P>Date and time values should use the standard <CODE>long</CODE>
532 * millisecond value. When a date or time literal is included in a message
533 * selector, it should be an integer literal for a millisecond value. The
534 * standard way to produce millisecond values is to use
535 * <CODE>java.util.Calendar</CODE>.
536 *
537 * <P>Although SQL supports fixed decimal comparison and arithmetic, JMS
538 * message selectors do not. This is the reason for restricting exact
539 * numeric literals to those without a decimal (and the addition of
540 * numerics with a decimal as an alternate representation for
541 * approximate numeric values).
542 *
543 * <P>SQL comments are not supported.
544 *
545 * @see javax.jms.MessageConsumer#receive()
546 * @see javax.jms.MessageConsumer#receive(long)
547 * @see javax.jms.MessageConsumer#receiveNoWait()
548 * @see javax.jms.MessageListener#onMessage(Message)
549 * @see javax.jms.BytesMessage
550 * @see javax.jms.MapMessage
551 * @see javax.jms.ObjectMessage
552 * @see javax.jms.StreamMessage
553 * @see javax.jms.TextMessage
554 */
555
556 public interface Message {
557
558 /** The message producer's default delivery mode is <CODE>PERSISTENT</CODE>.
559 *
560 * @see DeliveryMode#PERSISTENT
561 */
562 static final int DEFAULT_DELIVERY_MODE = DeliveryMode.PERSISTENT;
563
564 /** The message producer's default priority is 4.
565 */
566 static final int DEFAULT_PRIORITY = 4;
567
568 /** The message producer's default time to live is unlimited; the message
569 * never expires.
570 */
571 static final long DEFAULT_TIME_TO_LIVE = 0;
572
573
574 /** Gets the message ID.
575 *
576 * <P>The <CODE>JMSMessageID</CODE> header field contains a value that
577 * uniquely identifies each message sent by a provider.
578 *
579 * <P>When a message is sent, <CODE>JMSMessageID</CODE> can be ignored.
580 * When the <CODE>send</CODE> or <CODE>publish</CODE> method returns, it
581 * contains a provider-assigned value.
582 *
583 * <P>A <CODE>JMSMessageID</CODE> is a <CODE>String</CODE> value that
584 * should function as a
585 * unique key for identifying messages in a historical repository.
586 * The exact scope of uniqueness is provider-defined. It should at
587 * least cover all messages for a specific installation of a
588 * provider, where an installation is some connected set of message
589 * routers.
590 *
591 * <P>All <CODE>JMSMessageID</CODE> values must start with the prefix
592 * <CODE>'ID:'</CODE>.
593 * Uniqueness of message ID values across different providers is
594 * not required.
595 *
596 * <P>Since message IDs take some effort to create and increase a
597 * message's size, some JMS providers may be able to optimize message
598 * overhead if they are given a hint that the message ID is not used by
599 * an application. By calling the
600 * <CODE>MessageProducer.setDisableMessageID</CODE> method, a JMS client
601 * enables this potential optimization for all messages sent by that
602 * message producer. If the JMS provider accepts this
603 * hint, these messages must have the message ID set to null; if the
604 * provider ignores the hint, the message ID must be set to its normal
605 * unique value.
606 *
607 * @return the message ID
608 *
609 * @exception JMSException if the JMS provider fails to get the message ID
610 * due to some internal error.
611 * @see javax.jms.Message#setJMSMessageID(String)
612 * @see javax.jms.MessageProducer#setDisableMessageID(boolean)
613 */
614
615 String
616 getJMSMessageID() throws JMSException;
617
618
619 /** Sets the message ID.
620 *
621 * <P>JMS providers set this field when a message is sent. This method
622 * can be used to change the value for a message that has been received.
623 *
624 * @param id the ID of the message
625 *
626 * @exception JMSException if the JMS provider fails to set the message ID
627 * due to some internal error.
628 *
629 * @see javax.jms.Message#getJMSMessageID()
630 */
631
632 void
633 setJMSMessageID(String id) throws JMSException;
634
635
636 /** Gets the message timestamp.
637 *
638 * <P>The <CODE>JMSTimestamp</CODE> header field contains the time a
639 * message was
640 * handed off to a provider to be sent. It is not the time the
641 * message was actually transmitted, because the actual send may occur
642 * later due to transactions or other client-side queueing of messages.
643 *
644 * <P>When a message is sent, <CODE>JMSTimestamp</CODE> is ignored. When
645 * the <CODE>send</CODE> or <CODE>publish</CODE>
646 * method returns, it contains a time value somewhere in the interval
647 * between the call and the return. The value is in the format of a normal
648 * millis time value in the Java programming language.
649 *
650 * <P>Since timestamps take some effort to create and increase a
651 * message's size, some JMS providers may be able to optimize message
652 * overhead if they are given a hint that the timestamp is not used by an
653 * application. By calling the
654 * <CODE>MessageProducer.setDisableMessageTimestamp</CODE> method, a JMS
655 * client enables this potential optimization for all messages sent by
656 * that message producer. If the JMS provider accepts this
657 * hint, these messages must have the timestamp set to zero; if the
658 * provider ignores the hint, the timestamp must be set to its normal
659 * value.
660 *
661 * @return the message timestamp
662 *
663 * @exception JMSException if the JMS provider fails to get the timestamp
664 * due to some internal error.
665 *
666 * @see javax.jms.Message#setJMSTimestamp(long)
667 * @see javax.jms.MessageProducer#setDisableMessageTimestamp(boolean)
668 */
669
670 long
671 getJMSTimestamp() throws JMSException;
672
673
674 /** Sets the message timestamp.
675 *
676 * <P>JMS providers set this field when a message is sent. This method
677 * can be used to change the value for a message that has been received.
678 *
679 * @param timestamp the timestamp for this message
680 *
681 * @exception JMSException if the JMS provider fails to set the timestamp
682 * due to some internal error.
683 *
684 * @see javax.jms.Message#getJMSTimestamp()
685 */
686
687 void
688 setJMSTimestamp(long timestamp) throws JMSException;
689
690
691 /** Gets the correlation ID as an array of bytes for the message.
692 *
693 * <P>The use of a <CODE>byte[]</CODE> value for
694 * <CODE>JMSCorrelationID</CODE> is non-portable.
695 *
696 * @return the correlation ID of a message as an array of bytes
697 *
698 * @exception JMSException if the JMS provider fails to get the correlation
699 * ID due to some internal error.
700 *
701 * @see javax.jms.Message#setJMSCorrelationID(String)
702 * @see javax.jms.Message#getJMSCorrelationID()
703 * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
704 */
705
706 byte []
707 getJMSCorrelationIDAsBytes() throws JMSException;
708
709
710 /** Sets the correlation ID as an array of bytes for the message.
711 *
712 * <P>The array is copied before the method returns, so
713 * future modifications to the array will not alter this message header.
714 *
715 * <P>If a provider supports the native concept of correlation ID, a
716 * JMS client may need to assign specific <CODE>JMSCorrelationID</CODE>
717 * values to match those expected by native messaging clients.
718 * JMS providers without native correlation ID values are not required to
719 * support this method and its corresponding get method; their
720 * implementation may throw a
721 * <CODE>java.lang.UnsupportedOperationException</CODE>.
722 *
723 * <P>The use of a <CODE>byte[]</CODE> value for
724 * <CODE>JMSCorrelationID</CODE> is non-portable.
725 *
726 * @param correlationID the correlation ID value as an array of bytes
727 *
728 * @exception JMSException if the JMS provider fails to set the correlation
729 * ID due to some internal error.
730 *
731 * @see javax.jms.Message#setJMSCorrelationID(String)
732 * @see javax.jms.Message#getJMSCorrelationID()
733 * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
734 */
735
736 void
737 setJMSCorrelationIDAsBytes(byte[] correlationID) throws JMSException;
738
739
740 /** Sets the correlation ID for the message.
741 *
742 * <P>A client can use the <CODE>JMSCorrelationID</CODE> header field to
743 * link one message with another. A typical use is to link a response
744 * message with its request message.
745 *
746 * <P><CODE>JMSCorrelationID</CODE> can hold one of the following:
747 * <UL>
748 * <LI>A provider-specific message ID
749 * <LI>An application-specific <CODE>String</CODE>
750 * <LI>A provider-native <CODE>byte[]</CODE> value
751 * </UL>
752 *
753 * <P>Since each message sent by a JMS provider is assigned a message ID
754 * value, it is convenient to link messages via message ID. All message ID
755 * values must start with the <CODE>'ID:'</CODE> prefix.
756 *
757 * <P>In some cases, an application (made up of several clients) needs to
758 * use an application-specific value for linking messages. For instance,
759 * an application may use <CODE>JMSCorrelationID</CODE> to hold a value
760 * referencing some external information. Application-specified values
761 * must not start with the <CODE>'ID:'</CODE> prefix; this is reserved for
762 * provider-generated message ID values.
763 *
764 * <P>If a provider supports the native concept of correlation ID, a JMS
765 * client may need to assign specific <CODE>JMSCorrelationID</CODE> values
766 * to match those expected by clients that do not use the JMS API. A
767 * <CODE>byte[]</CODE> value is used for this
768 * purpose. JMS providers without native correlation ID values are not
769 * required to support <CODE>byte[]</CODE> values. The use of a
770 * <CODE>byte[]</CODE> value for <CODE>JMSCorrelationID</CODE> is
771 * non-portable.
772 *
773 * @param correlationID the message ID of a message being referred to
774 *
775 * @exception JMSException if the JMS provider fails to set the correlation
776 * ID due to some internal error.
777 *
778 * @see javax.jms.Message#getJMSCorrelationID()
779 * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
780 * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
781 */
782
783 void
784 setJMSCorrelationID(String correlationID) throws JMSException;
785
786
787 /** Gets the correlation ID for the message.
788 *
789 * <P>This method is used to return correlation ID values that are
790 * either provider-specific message IDs or application-specific
791 * <CODE>String</CODE> values.
792 *
793 * @return the correlation ID of a message as a <CODE>String</CODE>
794 *
795 * @exception JMSException if the JMS provider fails to get the correlation
796 * ID due to some internal error.
797 *
798 * @see javax.jms.Message#setJMSCorrelationID(String)
799 * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
800 * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
801 */
802
803 String
804 getJMSCorrelationID() throws JMSException;
805
806
807 /** Gets the <CODE>Destination</CODE> object to which a reply to this
808 * message should be sent.
809 *
810 * @return <CODE>Destination</CODE> to which to send a response to this
811 * message
812 *
813 * @exception JMSException if the JMS provider fails to get the
814 * <CODE>JMSReplyTo</CODE> destination due to some
815 * internal error.
816 *
817 * @see javax.jms.Message#setJMSReplyTo(Destination)
818 */
819
820 Destination
821 getJMSReplyTo() throws JMSException;
822
823
824 /** Sets the <CODE>Destination</CODE> object to which a reply to this
825 * message should be sent.
826 *
827 * <P>The <CODE>JMSReplyTo</CODE> header field contains the destination
828 * where a reply
829 * to the current message should be sent. If it is null, no reply is
830 * expected. The destination may be either a <CODE>Queue</CODE> object or
831 * a <CODE>Topic</CODE> object.
832 *
833 * <P>Messages sent with a null <CODE>JMSReplyTo</CODE> value may be a
834 * notification of some event, or they may just be some data the sender
835 * thinks is of interest.
836 *
837 * <P>Messages with a <CODE>JMSReplyTo</CODE> value typically expect a
838 * response. A response is optional; it is up to the client to decide.
839 * These messages are called requests. A message sent in response to a
840 * request is called a reply.
841 *
842 * <P>In some cases a client may wish to match a request it sent earlier
843 * with a reply it has just received. The client can use the
844 * <CODE>JMSCorrelationID</CODE> header field for this purpose.
845 *
846 * @param replyTo <CODE>Destination</CODE> to which to send a response to
847 * this message
848 *
849 * @exception JMSException if the JMS provider fails to set the
850 * <CODE>JMSReplyTo</CODE> destination due to some
851 * internal error.
852 *
853 * @see javax.jms.Message#getJMSReplyTo()
854 */
855
856 void
857 setJMSReplyTo(Destination replyTo) throws JMSException;
858
859
860 /** Gets the <CODE>Destination</CODE> object for this message.
861 *
862 * <P>The <CODE>JMSDestination</CODE> header field contains the
863 * destination to which the message is being sent.
864 *
865 * <P>When a message is sent, this field is ignored. After completion
866 * of the <CODE>send</CODE> or <CODE>publish</CODE> method, the field
867 * holds the destination specified by the method.
868 *
869 * <P>When a message is received, its <CODE>JMSDestination</CODE> value
870 * must be equivalent to the value assigned when it was sent.
871 *
872 * @return the destination of this message
873 *
874 * @exception JMSException if the JMS provider fails to get the destination
875 * due to some internal error.
876 *
877 * @see javax.jms.Message#setJMSDestination(Destination)
878 */
879
880 Destination
881 getJMSDestination() throws JMSException;
882
883
884 /** Sets the <CODE>Destination</CODE> object for this message.
885 *
886 * <P>JMS providers set this field when a message is sent. This method
887 * can be used to change the value for a message that has been received.
888 *
889 * @param destination the destination for this message
890 *
891 * @exception JMSException if the JMS provider fails to set the destination
892 * due to some internal error.
893 *
894 * @see javax.jms.Message#getJMSDestination()
895 */
896
897 void
898 setJMSDestination(Destination destination) throws JMSException;
899
900
901 /** Gets the <CODE>DeliveryMode</CODE> value specified for this message.
902 *
903 * @return the delivery mode for this message
904 *
905 * @exception JMSException if the JMS provider fails to get the
906 * delivery mode due to some internal error.
907 *
908 * @see javax.jms.Message#setJMSDeliveryMode(int)
909 * @see javax.jms.DeliveryMode
910 */
911
912 int
913 getJMSDeliveryMode() throws JMSException;
914
915
916 /** Sets the <CODE>DeliveryMode</CODE> value for this message.
917 *
918 * <P>JMS providers set this field when a message is sent. This method
919 * can be used to change the value for a message that has been received.
920 *
921 * @param deliveryMode the delivery mode for this message
922 *
923 * @exception JMSException if the JMS provider fails to set the
924 * delivery mode due to some internal error.
925 *
926 * @see javax.jms.Message#getJMSDeliveryMode()
927 * @see javax.jms.DeliveryMode
928 */
929
930 void
931 setJMSDeliveryMode(int deliveryMode) throws JMSException;
932
933
934 /** Gets an indication of whether this message is being redelivered.
935 *
936 * <P>If a client receives a message with the <CODE>JMSRedelivered</CODE>
937 * field set,
938 * it is likely, but not guaranteed, that this message was delivered
939 * earlier but that its receipt was not acknowledged
940 * at that time.
941 *
942 * @return true if this message is being redelivered
943 *
944 * @exception JMSException if the JMS provider fails to get the redelivered
945 * state due to some internal error.
946 *
947 * @see javax.jms.Message#setJMSRedelivered(boolean)
948 */
949
950 boolean
951 getJMSRedelivered() throws JMSException;
952
953
954 /** Specifies whether this message is being redelivered.
955 *
956 * <P>This field is set at the time the message is delivered. This
957 * method can be used to change the value for a message that has
958 * been received.
959 *
960 * @param redelivered an indication of whether this message is being
961 * redelivered
962 *
963 * @exception JMSException if the JMS provider fails to set the redelivered
964 * state due to some internal error.
965 *
966 * @see javax.jms.Message#getJMSRedelivered()
967 */
968
969 void
970 setJMSRedelivered(boolean redelivered) throws JMSException;
971
972
973 /** Gets the message type identifier supplied by the client when the
974 * message was sent.
975 *
976 * @return the message type
977 *
978 * @exception JMSException if the JMS provider fails to get the message
979 * type due to some internal error.
980 *
981 * @see javax.jms.Message#setJMSType(String)
982 */
983
984 String
985 getJMSType() throws JMSException;
986
987
988 /** Sets the message type.
989 *
990 * <P>Some JMS providers use a message repository that contains the
991 * definitions of messages sent by applications. The <CODE>JMSType</CODE>
992 * header field may reference a message's definition in the provider's
993 * repository.
994 *
995 * <P>The JMS API does not define a standard message definition repository,
996 * nor does it define a naming policy for the definitions it contains.
997 *
998 * <P>Some messaging systems require that a message type definition for
999 * each application message be created and that each message specify its
1000 * type. In order to work with such JMS providers, JMS clients should
1001 * assign a value to <CODE>JMSType</CODE>, whether the application makes
1002 * use of it or not. This ensures that the field is properly set for those
1003 * providers that require it.
1004 *
1005 * <P>To ensure portability, JMS clients should use symbolic values for
1006 * <CODE>JMSType</CODE> that can be configured at installation time to the
1007 * values defined in the current provider's message repository. If string
1008 * literals are used, they may not be valid type names for some JMS
1009 * providers.
1010 *
1011 * @param type the message type
1012 *
1013 * @exception JMSException if the JMS provider fails to set the message
1014 * type due to some internal error.
1015 *
1016 * @see javax.jms.Message#getJMSType()
1017 */
1018
1019 void
1020 setJMSType(String type) throws JMSException;
1021
1022
1023 /** Gets the message's expiration value.
1024 *
1025 * <P>When a message is sent, the <CODE>JMSExpiration</CODE> header field
1026 * is left unassigned. After completion of the <CODE>send</CODE> or
1027 * <CODE>publish</CODE> method, it holds the expiration time of the
1028 * message. This is the sum of the time-to-live value specified by the
1029 * client and the GMT at the time of the <CODE>send</CODE> or
1030 * <CODE>publish</CODE>.
1031 *
1032 * <P>If the time-to-live is specified as zero, <CODE>JMSExpiration</CODE>
1033 * is set to zero to indicate that the message does not expire.
1034 *
1035 * <P>When a message's expiration time is reached, a provider should
1036 * discard it. The JMS API does not define any form of notification of
1037 * message expiration.
1038 *
1039 * <P>Clients should not receive messages that have expired; however,
1040 * the JMS API does not guarantee that this will not happen.
1041 *
1042 * @return the time the message expires, which is the sum of the
1043 * time-to-live value specified by the client and the GMT at the
1044 * time of the send
1045 *
1046 * @exception JMSException if the JMS provider fails to get the message
1047 * expiration due to some internal error.
1048 *
1049 * @see javax.jms.Message#setJMSExpiration(long)
1050 */
1051
1052 long
1053 getJMSExpiration() throws JMSException;
1054
1055
1056 /** Sets the message's expiration value.
1057 *
1058 * <P>JMS providers set this field when a message is sent. This method
1059 * can be used to change the value for a message that has been received.
1060 *
1061 * @param expiration the message's expiration time
1062 *
1063 * @exception JMSException if the JMS provider fails to set the message
1064 * expiration due to some internal error.
1065 *
1066 * @see javax.jms.Message#getJMSExpiration()
1067 */
1068
1069 void
1070 setJMSExpiration(long expiration) throws JMSException;
1071
1072
1073 /** Gets the message priority level.
1074 *
1075 * <P>The JMS API defines ten levels of priority value, with 0 as the
1076 * lowest
1077 * priority and 9 as the highest. In addition, clients should consider
1078 * priorities 0-4 as gradations of normal priority and priorities 5-9
1079 * as gradations of expedited priority.
1080 *
1081 * <P>The JMS API does not require that a provider strictly implement
1082 * priority
1083 * ordering of messages; however, it should do its best to deliver
1084 * expedited messages ahead of normal messages.
1085 *
1086 * @return the default message priority
1087 *
1088 * @exception JMSException if the JMS provider fails to get the message
1089 * priority due to some internal error.
1090 *
1091 * @see javax.jms.Message#setJMSPriority(int)
1092 */
1093
1094 int
1095 getJMSPriority() throws JMSException;
1096
1097
1098 /** Sets the priority level for this message.
1099 *
1100 * <P>JMS providers set this field when a message is sent. This method
1101 * can be used to change the value for a message that has been received.
1102 *
1103 * @param priority the priority of this message
1104 *
1105 * @exception JMSException if the JMS provider fails to set the message
1106 * priority due to some internal error.
1107 *
1108 * @see javax.jms.Message#getJMSPriority()
1109 */
1110
1111 void
1112 setJMSPriority(int priority) throws JMSException;
1113
1114
1115 /** Clears a message's properties.
1116 *
1117 * <P>The message's header fields and body are not cleared.
1118 *
1119 * @exception JMSException if the JMS provider fails to clear the message
1120 * properties due to some internal error.
1121 */
1122
1123 void
1124 clearProperties() throws JMSException;
1125
1126
1127 /** Indicates whether a property value exists.
1128 *
1129 * @param name the name of the property to test
1130 *
1131 * @return true if the property exists
1132 *
1133 * @exception JMSException if the JMS provider fails to determine if the
1134 * property exists due to some internal error.
1135 */
1136
1137 boolean
1138 propertyExists(String name) throws JMSException;
1139
1140
1141 /** Returns the value of the <CODE>boolean</CODE> property with the
1142 * specified name.
1143 *
1144 * @param name the name of the <CODE>boolean</CODE> property
1145 *
1146 * @return the <CODE>boolean</CODE> property value for the specified name
1147 *
1148 * @exception JMSException if the JMS provider fails to get the property
1149 * value due to some internal error.
1150 * @exception MessageFormatException if this type conversion is invalid.
1151 */
1152
1153 boolean
1154 getBooleanProperty(String name) throws JMSException;
1155
1156
1157 /** Returns the value of the <CODE>byte</CODE> property with the specified
1158 * name.
1159 *
1160 * @param name the name of the <CODE>byte</CODE> property
1161 *
1162 * @return the <CODE>byte</CODE> property value for the specified name
1163 *
1164 * @exception JMSException if the JMS provider fails to get the property
1165 * value due to some internal error.
1166 * @exception MessageFormatException if this type conversion is invalid.
1167 */
1168
1169 byte
1170 getByteProperty(String name) throws JMSException;
1171
1172
1173 /** Returns the value of the <CODE>short</CODE> property with the specified
1174 * name.
1175 *
1176 * @param name the name of the <CODE>short</CODE> property
1177 *
1178 * @return the <CODE>short</CODE> property value for the specified name
1179 *
1180 * @exception JMSException if the JMS provider fails to get the property
1181 * value due to some internal error.
1182 * @exception MessageFormatException if this type conversion is invalid.
1183 */
1184
1185 short
1186 getShortProperty(String name) throws JMSException;
1187
1188
1189 /** Returns the value of the <CODE>int</CODE> property with the specified
1190 * name.
1191 *
1192 * @param name the name of the <CODE>int</CODE> property
1193 *
1194 * @return the <CODE>int</CODE> property value for the specified name
1195 *
1196 * @exception JMSException if the JMS provider fails to get the property
1197 * value due to some internal error.
1198 * @exception MessageFormatException if this type conversion is invalid.
1199 */
1200
1201 int
1202 getIntProperty(String name) throws JMSException;
1203
1204
1205 /** Returns the value of the <CODE>long</CODE> property with the specified
1206 * name.
1207 *
1208 * @param name the name of the <CODE>long</CODE> property
1209 *
1210 * @return the <CODE>long</CODE> property value for the specified name
1211 *
1212 * @exception JMSException if the JMS provider fails to get the property
1213 * value due to some internal error.
1214 * @exception MessageFormatException if this type conversion is invalid.
1215 */
1216
1217 long
1218 getLongProperty(String name) throws JMSException;
1219
1220
1221 /** Returns the value of the <CODE>float</CODE> property with the specified
1222 * name.
1223 *
1224 * @param name the name of the <CODE>float</CODE> property
1225 *
1226 * @return the <CODE>float</CODE> property value for the specified name
1227 *
1228 * @exception JMSException if the JMS provider fails to get the property
1229 * value due to some internal error.
1230 * @exception MessageFormatException if this type conversion is invalid.
1231 */
1232
1233 float
1234 getFloatProperty(String name) throws JMSException;
1235
1236
1237 /** Returns the value of the <CODE>double</CODE> property with the specified
1238 * name.
1239 *
1240 * @param name the name of the <CODE>double</CODE> property
1241 *
1242 * @return the <CODE>double</CODE> property value for the specified name
1243 *
1244 * @exception JMSException if the JMS provider fails to get the property
1245 * value due to some internal error.
1246 * @exception MessageFormatException if this type conversion is invalid.
1247 */
1248
1249 double
1250 getDoubleProperty(String name) throws JMSException;
1251
1252
1253 /** Returns the value of the <CODE>String</CODE> property with the specified
1254 * name.
1255 *
1256 * @param name the name of the <CODE>String</CODE> property
1257 *
1258 * @return the <CODE>String</CODE> property value for the specified name;
1259 * if there is no property by this name, a null value is returned
1260 *
1261 * @exception JMSException if the JMS provider fails to get the property
1262 * value due to some internal error.
1263 * @exception MessageFormatException if this type conversion is invalid.
1264 */
1265
1266 String
1267 getStringProperty(String name) throws JMSException;
1268
1269
1270 /** Returns the value of the Java object property with the specified name.
1271 *
1272 * <P>This method can be used to return, in objectified format,
1273 * an object that has been stored as a property in the message with the
1274 * equivalent <CODE>setObjectProperty</CODE> method call, or its equivalent
1275 * primitive <CODE>set<I>type</I>Property</CODE> method.
1276 *
1277 * @param name the name of the Java object property
1278 *
1279 * @return the Java object property value with the specified name, in
1280 * objectified format (for example, if the property was set as an
1281 * <CODE>int</CODE>, an <CODE>Integer</CODE> is
1282 * returned); if there is no property by this name, a null value
1283 * is returned
1284 *
1285 * @exception JMSException if the JMS provider fails to get the property
1286 * value due to some internal error.
1287 */
1288
1289 Object
1290 getObjectProperty(String name) throws JMSException;
1291
1292
1293 /** Returns an <CODE>Enumeration</CODE> of all the property names.
1294 *
1295 * <P>Note that JMS standard header fields are not considered
1296 * properties and are not returned in this enumeration.
1297 *
1298 * @return an enumeration of all the names of property values
1299 *
1300 * @exception JMSException if the JMS provider fails to get the property
1301 * names due to some internal error.
1302 */
1303
1304 Enumeration
1305 getPropertyNames() throws JMSException;
1306
1307
1308 /** Sets a <CODE>boolean</CODE> property value with the specified name into
1309 * the message.
1310 *
1311 * @param name the name of the <CODE>boolean</CODE> property
1312 * @param value the <CODE>boolean</CODE> property value to set
1313 *
1314 * @exception JMSException if the JMS provider fails to set the property
1315 * due to some internal error.
1316 * @exception IllegalArgumentException if the name is null or if the name is
1317 * an empty string.
1318 * @exception MessageNotWriteableException if properties are read-only
1319 */
1320
1321 void
1322 setBooleanProperty(String name, boolean value)
1323 throws JMSException;
1324
1325
1326 /** Sets a <CODE>byte</CODE> property value with the specified name into
1327 * the message.
1328 *
1329 * @param name the name of the <CODE>byte</CODE> property
1330 * @param value the <CODE>byte</CODE> property value to set
1331 *
1332 * @exception JMSException if the JMS provider fails to set the property
1333 * due to some internal error.
1334 * @exception IllegalArgumentException if the name is null or if the name is
1335 * an empty string.
1336 * @exception MessageNotWriteableException if properties are read-only
1337 */
1338
1339 void
1340 setByteProperty(String name, byte value)
1341 throws JMSException;
1342
1343
1344 /** Sets a <CODE>short</CODE> property value with the specified name into
1345 * the message.
1346 *
1347 * @param name the name of the <CODE>short</CODE> property
1348 * @param value the <CODE>short</CODE> property value to set
1349 *
1350 * @exception JMSException if the JMS provider fails to set the property
1351 * due to some internal error.
1352 * @exception IllegalArgumentException if the name is null or if the name is
1353 * an empty string.
1354 * @exception MessageNotWriteableException if properties are read-only
1355 */
1356
1357 void
1358 setShortProperty(String name, short value)
1359 throws JMSException;
1360
1361
1362 /** Sets an <CODE>int</CODE> property value with the specified name into
1363 * the message.
1364 *
1365 * @param name the name of the <CODE>int</CODE> property
1366 * @param value the <CODE>int</CODE> property value to set
1367 *
1368 * @exception JMSException if the JMS provider fails to set the property
1369 * due to some internal error.
1370 * @exception IllegalArgumentException if the name is null or if the name is
1371 * an empty string.
1372 * @exception MessageNotWriteableException if properties are read-only
1373 */
1374
1375 void
1376 setIntProperty(String name, int value)
1377 throws JMSException;
1378
1379
1380 /** Sets a <CODE>long</CODE> property value with the specified name into
1381 * the message.
1382 *
1383 * @param name the name of the <CODE>long</CODE> property
1384 * @param value the <CODE>long</CODE> property value to set
1385 *
1386 * @exception JMSException if the JMS provider fails to set the property
1387 * due to some internal error.
1388 * @exception IllegalArgumentException if the name is null or if the name is
1389 * an empty string.
1390 * @exception MessageNotWriteableException if properties are read-only
1391 */
1392
1393 void
1394 setLongProperty(String name, long value)
1395 throws JMSException;
1396
1397
1398 /** Sets a <CODE>float</CODE> property value with the specified name into
1399 * the message.
1400 *
1401 * @param name the name of the <CODE>float</CODE> property
1402 * @param value the <CODE>float</CODE> property value to set
1403 *
1404 * @exception JMSException if the JMS provider fails to set the property
1405 * due to some internal error.
1406 * @exception IllegalArgumentException if the name is null or if the name is
1407 * an empty string.
1408 * @exception MessageNotWriteableException if properties are read-only
1409 */
1410
1411 void
1412 setFloatProperty(String name, float value)
1413 throws JMSException;
1414
1415
1416 /** Sets a <CODE>double</CODE> property value with the specified name into
1417 * the message.
1418 *
1419 * @param name the name of the <CODE>double</CODE> property
1420 * @param value the <CODE>double</CODE> property value to set
1421 *
1422 * @exception JMSException if the JMS provider fails to set the property
1423 * due to some internal error.
1424 * @exception IllegalArgumentException if the name is null or if the name is
1425 * an empty string.
1426 * @exception MessageNotWriteableException if properties are read-only
1427 */
1428
1429 void
1430 setDoubleProperty(String name, double value)
1431 throws JMSException;
1432
1433
1434 /** Sets a <CODE>String</CODE> property value with the specified name into
1435 * the message.
1436 *
1437 * @param name the name of the <CODE>String</CODE> property
1438 * @param value the <CODE>String</CODE> property value to set
1439 *
1440 * @exception JMSException if the JMS provider fails to set the property
1441 * due to some internal error.
1442 * @exception IllegalArgumentException if the name is null or if the name is
1443 * an empty string.
1444 * @exception MessageNotWriteableException if properties are read-only
1445 */
1446
1447 void
1448 setStringProperty(String name, String value)
1449 throws JMSException;
1450
1451
1452 /** Sets a Java object property value with the specified name into the
1453 * message.
1454 *
1455 * <P>Note that this method works only for the objectified primitive
1456 * object types (<CODE>Integer</CODE>, <CODE>Double</CODE>,
1457 * <CODE>Long</CODE> ...) and <CODE>String</CODE> objects.
1458 *
1459 * @param name the name of the Java object property
1460 * @param value the Java object property value to set
1461 *
1462 * @exception JMSException if the JMS provider fails to set the property
1463 * due to some internal error.
1464 * @exception IllegalArgumentException if the name is null or if the name is
1465 * an empty string.
1466 * @exception MessageFormatException if the object is invalid
1467 * @exception MessageNotWriteableException if properties are read-only
1468 */
1469
1470 void
1471 setObjectProperty(String name, Object value)
1472 throws JMSException;
1473
1474
1475 /** Acknowledges all consumed messages of the session of this consumed
1476 * message.
1477 *
1478 * <P>All consumed JMS messages support the <CODE>acknowledge</CODE>
1479 * method for use when a client has specified that its JMS session's
1480 * consumed messages are to be explicitly acknowledged. By invoking
1481 * <CODE>acknowledge</CODE> on a consumed message, a client acknowledges
1482 * all messages consumed by the session that the message was delivered to.
1483 *
1484 * <P>Calls to <CODE>acknowledge</CODE> are ignored for both transacted
1485 * sessions and sessions specified to use implicit acknowledgement modes.
1486 *
1487 * <P>A client may individually acknowledge each message as it is consumed,
1488 * or it may choose to acknowledge messages as an application-defined group
1489 * (which is done by calling acknowledge on the last received message of the group,
1490 * thereby acknowledging all messages consumed by the session.)
1491 *
1492 * <P>Messages that have been received but not acknowledged may be
1493 * redelivered.
1494 *
1495 * @exception JMSException if the JMS provider fails to acknowledge the
1496 * messages due to some internal error.
1497 * @exception IllegalStateException if this method is called on a closed
1498 * session.
1499 *
1500 * @see javax.jms.Session#CLIENT_ACKNOWLEDGE
1501 */
1502
1503 void
1504 acknowledge() throws JMSException;
1505
1506
1507 /** Clears out the message body. Clearing a message's body does not clear
1508 * its header values or property entries.
1509 *
1510 * <P>If this message body was read-only, calling this method leaves
1511 * the message body in the same state as an empty body in a newly
1512 * created message.
1513 *
1514 * @exception JMSException if the JMS provider fails to clear the message
1515 * body due to some internal error.
1516 */
1517
1518 void
1519 clearBody() throws JMSException;
1520 }
Save This Page