Java > Open Source Codes > javax > jms > Message


1 /*
2  * The contents of this file are subject to the terms
3  * of the Common Development and Distribution License
4  * (the License). You may not use this file except in
5  * compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9  * glassfish/bootstrap/legal/CDDLv1.0.txt.
10  * See the License for the specific language governing
11  * permissions and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL
14  * Header Notice in each file and include the License file
15  * at glassfish/bootstrap/legal/CDDLv1.0.txt.
16  * If applicable, add the following below the CDDL Header,
17  * with the fields enclosed by brackets [] replaced by
18  * you own identifying information:
19  * "Portions Copyrighted [year] [name of copyright owner]"
20  *
21  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22  */
23
24
25 package javax.jms;
26
27 import java.util.Enumeration ;
28 import java.util.Properties ;
29
30 /** The <CODE>Message</CODE> interface is the root interface of all JMS
31   * messages. It defines the message header and the <CODE>acknowledge</CODE>
32   * method used for all messages.
33   *
34   * <P>Most message-oriented middleware (MOM) products treat messages as
35   * lightweight entities that consist
36   * of a header and a payload. The header contains fields used for message
37   * routing and identification; the payload contains the application data
38   * being sent.
39   *
40   * <P>Within this general form, the definition of a message varies
41   * significantly across products. It would be quite difficult for the JMS API
42   * to support all of these message models.
43   *
44   * <P>With this in mind, the JMS message model has the following goals:
45   * <UL>
46   * <LI>Provide a single, unified message API
47   * <LI>Provide an API suitable for creating messages that match the
48   * format used by provider-native messaging applications
49   * <LI>Support the development of heterogeneous applications that span
50   * operating systems, machine architectures, and computer languages
51   * <LI>Support messages containing objects in the Java programming language
52   * ("Java objects")
53   * <LI>Support messages containing Extensible Markup Language (XML) pages
54   * </UL>
55   *
56   * <P>JMS messages are composed of the following parts:
57   * <UL>
58   * <LI>Header - All messages support the same set of header fields.
59   * Header fields contain values used by both clients and providers to
60   * identify and route messages.
61   * <LI>Properties - Each message contains a built-in facility for supporting
62   * application-defined property values. Properties provide an efficient
63   * mechanism for supporting application-defined message filtering.
64   * <LI>Body - The JMS API defines several types of message body, which cover
65   * the majority of messaging styles currently in use.
66   * </UL>
67   *
68   * <H4>Message Bodies</H4>
69   *
70   * <P>The JMS API defines five types of message body:
71   * <UL>
72   * <LI>Stream - A <CODE>StreamMessage</CODE> object's message body contains
73   * a stream of primitive values in the Java programming
74   * language ("Java primitives"). It is filled and read sequentially.
75   * <LI>Map - A <CODE>MapMessage</CODE> object's message body contains a set
76   * of name-value pairs, where names are <CODE>String</CODE>
77   * objects, and values are Java primitives. The entries can be accessed
78   * sequentially or randomly by name. The order of the entries is
79   * undefined.
80   * <LI>Text - A <CODE>TextMessage</CODE> object's message body contains a
81   * <CODE>java.lang.String</CODE> object. This message type can be used
82   * to transport plain-text messages, and XML messages.
83   * <LI>Object - An <CODE>ObjectMessage</CODE> object's message body contains
84   * a <CODE>Serializable</CODE> Java object.
85   * <LI>Bytes - A <CODE>BytesMessage</CODE> object's message body contains a
86   * stream of uninterpreted bytes. This message type is for
87   * literally encoding a body to match an existing message format. In
88   * many cases, it is possible to use one of the other body types,
89   * which are easier to use. Although the JMS API allows the use of
90   * message properties with byte messages, they are typically not used,
91   * since the inclusion of properties may affect the format.
92   * </UL>
93   *
94   * <H4>Message Headers</H4>
95   *
96   * <P>The <CODE>JMSCorrelationID</CODE> header field is used for linking one
97   * message with
98   * another. It typically links a reply message with its requesting message.
99   *
100   * <P><CODE>JMSCorrelationID</CODE> can hold a provider-specific message ID,
101   * an application-specific <CODE>String</CODE> object, or a provider-native
102   * <CODE>byte[]</CODE> value.
103   *
104   * <H4>Message Properties</H4>
105   *
106   * <P>A <CODE>Message</CODE> object contains a built-in facility for supporting
107   * application-defined property values. In effect, this provides a mechanism
108   * for adding application-specific header fields to a message.
109   *
110   * <P>Properties allow an application, via message selectors, to have a JMS
111   * provider select, or filter, messages on its behalf using
112   * application-specific criteria.
113   *
114   * <P>Property names must obey the rules for a message selector identifier.
115   * Property names must not be null, and must not be empty strings. If a property
116   * name is set and it is either null or an empty string, an
117   * <CODE>IllegalArgumentException</CODE> must be thrown.
118   *
119   * <P>Property values can be <CODE>boolean</CODE>, <CODE>byte</CODE>,
120   * <CODE>short</CODE>, <CODE>int</CODE>, <CODE>long</CODE>, <CODE>float</CODE>,
121   * <CODE>double</CODE>, and <CODE>String</CODE>.
122   *
123   * <P>Property values are set prior to sending a message. When a client
124   * receives a message, its properties are in read-only mode. If a
125   * client attempts to set properties at this point, a
126   * <CODE>MessageNotWriteableException</CODE> is thrown. If
127   * <CODE>clearProperties</CODE> is called, the properties can now be both
128   * read from and written to. Note that header fields are distinct from
129   * properties. Header fields are never in read-only mode.
130   *
131   * <P>A property value may duplicate a value in a message's body, or it may
132   * not. Although JMS does not define a policy for what should or should not
133   * be made a property, application developers should note that JMS providers
134   * will likely handle data in a message's body more efficiently than data in
135   * a message's properties. For best performance, applications should use
136   * message properties only when they need to customize a message's header.
137   * The primary reason for doing this is to support customized message
138   * selection.
139   *
140   * <P>Message properties support the following conversion table. The marked
141   * cases must be supported. The unmarked cases must throw a
142   * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions
143   * may throw a runtime exception if the
144   * primitive's <CODE>valueOf</CODE> method does not accept the
145   * <CODE>String</CODE> as a valid representation of the primitive.
146   *
147   * <P>A value written as the row type can be read as the column type.
148   *
149   * <PRE>
150   * | | boolean byte short int long float double String
151   * |----------------------------------------------------------
152   * |boolean | X X
153   * |byte | X X X X X
154   * |short | X X X X
155   * |int | X X X
156   * |long | X X
157   * |float | X X X
158   * |double | X X
159   * |String | X X X X X X X X
160   * |----------------------------------------------------------
161   * </PRE>
162   *
163   * <P>In addition to the type-specific set/get methods for properties, JMS
164   * provides the <CODE>setObjectProperty</CODE> and
165   * <CODE>getObjectProperty</CODE> methods. These support the same set of
166   * property types using the objectified primitive values. Their purpose is
167   * to allow the decision of property type to made at execution time rather
168   * than at compile time. They support the same property value conversions.
169   *
170   * <P>The <CODE>setObjectProperty</CODE> method accepts values of class
171   * <CODE>Boolean</CODE>, <CODE>Byte</CODE>, <CODE>Short</CODE>,
172   * <CODE>Integer</CODE>, <CODE>Long</CODE>, <CODE>Float</CODE>,
173   * <CODE>Double</CODE>, and <CODE>String</CODE>. An attempt
174   * to use any other class must throw a <CODE>JMSException</CODE>.
175   *
176   * <P>The <CODE>getObjectProperty</CODE> method only returns values of class
177   * <CODE>Boolean</CODE>, <CODE>Byte</CODE>, <CODE>Short</CODE>,
178   * <CODE>Integer</CODE>, <CODE>Long</CODE>, <CODE>Float</CODE>,
179   * <CODE>Double</CODE>, and <CODE>String</CODE>.
180   *
181   * <P>The order of property values is not defined. To iterate through a
182   * message's property values, use <CODE>getPropertyNames</CODE> to retrieve
183   * a property name enumeration and then use the various property get methods
184   * to retrieve their values.
185   *
186   * <P>A message's properties are deleted by the <CODE>clearProperties</CODE>
187   * method. This leaves the message with an empty set of properties.
188   *
189   * <P>Getting a property value for a name which has not been set returns a
190   * null value. Only the <CODE>getStringProperty</CODE> and
191   * <CODE>getObjectProperty</CODE> methods can return a null value.
192   * Attempting to read a null value as a primitive type must be treated as
193   * calling the primitive's corresponding <CODE>valueOf(String)</CODE>
194   * conversion method with a null value.
195   *
196   * <P>The JMS API reserves the <CODE>JMSX</CODE> property name prefix for JMS
197   * defined properties.
198   * The full set of these properties is defined in the Java Message Service
199   * specification. New JMS defined properties may be added in later versions
200   * of the JMS API. Support for these properties is optional. The
201   * <CODE>String[] ConnectionMetaData.getJMSXPropertyNames</CODE> method
202   * returns the names of the JMSX properties supported by a connection.
203   *
204   * <P>JMSX properties may be referenced in message selectors whether or not
205   * they are supported by a connection. If they are not present in a
206   * message, they are treated like any other absent property.
207   *
208   * <P>JMSX properties defined in the specification as "set by provider on
209   * send" are available to both the producer and the consumers of the message.
210   * JMSX properties defined in the specification as "set by provider on
211   * receive" are available only to the consumers.
212   *
213   * <P><CODE>JMSXGroupID</CODE> and <CODE>JMSXGroupSeq</CODE> are standard
214   * properties that clients
215   * should use if they want to group messages. All providers must support them.
216   * Unless specifically noted, the values and semantics of the JMSX properties
217   * are undefined.
218   *
219   * <P>The JMS API reserves the <CODE>JMS_<I>vendor_name</I></CODE> property
220   * name prefix for provider-specific properties. Each provider defines its own
221   * value for <CODE><I>vendor_name</I></CODE>. This is the mechanism a JMS
222   * provider uses to make its special per-message services available to a JMS
223   * client.
224   *
225   * <P>The purpose of provider-specific properties is to provide special
226   * features needed to integrate JMS clients with provider-native clients in a
227   * single JMS application. They should not be used for messaging between JMS
228   * clients.
229   *
230   * <H4>Provider Implementations of JMS Message Interfaces</H4>
231   *
232   * <P>The JMS API provides a set of message interfaces that define the JMS
233   * message
234   * model. It does not provide implementations of these interfaces.
235   *
236   * <P>Each JMS provider supplies a set of message factories with its
237   * <CODE>Session</CODE> object for creating instances of messages. This allows
238   * a provider to use message implementations tailored to its specific needs.
239   *
240   * <P>A provider must be prepared to accept message implementations that are
241   * not its own. They may not be handled as efficiently as its own
242   * implementation; however, they must be handled.
243   *
244   * <P>Note the following exception case when a provider is handling a foreign
245   * message implementation. If the foreign message implementation contains a
246   * <CODE>JMSReplyTo</CODE> header field that is set to a foreign destination
247   * implementation, the provider is not required to handle or preserve the
248   * value of this header field.
249   *
250   * <H4>Message Selectors</H4>
251   *
252   * <P>A JMS message selector allows a client to specify, by
253   * header field references and property references, the
254   * messages it is interested in. Only messages whose header
255   * and property values
256   * match the
257   * selector are delivered. What it means for a message not to be delivered
258   * depends on the <CODE>MessageConsumer</CODE> being used (see
259   * {@link javax.jms.QueueReceiver QueueReceiver} and
260   * {@link javax.jms.TopicSubscriber TopicSubscriber}).
261   *
262   * <P>Message selectors cannot reference message body values.
263   *
264   * <P>A message selector matches a message if the selector evaluates to
265   * true when the message's header field values and property values are
266   * substituted for their corresponding identifiers in the selector.
267   *
268   * <P>A message selector is a <CODE>String</CODE> whose syntax is based on a
269   * subset of
270   * the SQL92 conditional expression syntax. If the value of a message selector
271   * is an empty string, the value is treated as a null and indicates that there
272   * is no message selector for the message consumer.
273   *
274   * <P>The order of evaluation of a message selector is from left to right
275   * within precedence level. Parentheses can be used to change this order.
276   *
277   * <P>Predefined selector literals and operator names are shown here in
278   * uppercase; however, they are case insensitive.
279   *
280   * <P>A selector can contain:
281   *
282   * <UL>
283   * <LI>Literals:
284   * <UL>
285   * <LI>A string literal is enclosed in single quotes, with a single quote
286   * represented by doubled single quote; for example,
287   * <CODE>'literal'</CODE> and <CODE>'literal''s'</CODE>. Like
288   * string literals in the Java programming language, these use the
289   * Unicode character encoding.
290   * <LI>An exact numeric literal is a numeric value without a decimal
291   * point, such as <CODE>57</CODE>, <CODE>-957</CODE>, and
292   * <CODE>+62</CODE>; numbers in the range of <CODE>long</CODE> are
293   * supported. Exact numeric literals use the integer literal
294   * syntax of the Java programming language.
295   * <LI>An approximate numeric literal is a numeric value in scientific
296   * notation, such as <CODE>7E3</CODE> and <CODE>-57.9E2</CODE>, or a
297   * numeric value with a decimal, such as <CODE>7.</CODE>,
298   * <CODE>-95.7</CODE>, and <CODE>+6.2</CODE>; numbers in the range of
299   * <CODE>double</CODE> are supported. Approximate literals use the
300   * floating-point literal syntax of the Java programming language.
301   * <LI>The boolean literals <CODE>TRUE</CODE> and <CODE>FALSE</CODE>.
302   * </UL>
303   * <LI>Identifiers:
304   * <UL>
305   * <LI>An identifier is an unlimited-length sequence of letters
306   * and digits, the first of which must be a letter. A letter is any
307   * character for which the method <CODE>Character.isJavaLetter</CODE>
308   * returns true. This includes <CODE>'_'</CODE> and <CODE>'$'</CODE>.
309   * A letter or digit is any character for which the method
310   * <CODE>Character.isJavaLetterOrDigit</CODE> returns true.
311   * <LI>Identifiers cannot be the names <CODE>NULL</CODE>,
312   * <CODE>TRUE</CODE>, and <CODE>FALSE</CODE>.
313   * <LI>Identifiers cannot be <CODE>NOT</CODE>, <CODE>AND</CODE>,
314   * <CODE>OR</CODE>, <CODE>BETWEEN</CODE>, <CODE>LIKE</CODE>,
315   * <CODE>IN</CODE>, <CODE>IS</CODE>, or <CODE>ESCAPE</CODE>.
316   * <LI>Identifiers are either header field references or property
317   * references. The type of a property value in a message selector
318   * corresponds to the type used to set the property. If a property
319   * that does not exist in a message is referenced, its value is
320   * <CODE>NULL</CODE>.
321   * <LI>The conversions that apply to the get methods for properties do not
322   * apply when a property is used in a message selector expression.
323   * For example, suppose you set a property as a string value, as in the
324   * following:
325   * <PRE>myMessage.setStringProperty("NumberOfOrders", "2");</PRE>
326   * The following expression in a message selector would evaluate to
327   * false, because a string cannot be used in an arithmetic expression:
328   * <PRE>"NumberOfOrders > 1"</PRE>
329   * <LI>Identifiers are case-sensitive.
330   * <LI>Message header field references are restricted to
331   * <CODE>JMSDeliveryMode</CODE>, <CODE>JMSPriority</CODE>,
332   * <CODE>JMSMessageID</CODE>, <CODE>JMSTimestamp</CODE>,
333   * <CODE>JMSCorrelationID</CODE>, and <CODE>JMSType</CODE>.
334   * <CODE>JMSMessageID</CODE>, <CODE>JMSCorrelationID</CODE>, and
335   * <CODE>JMSType</CODE> values may be null and if so are treated as a
336   * <CODE>NULL</CODE> value.
337   * <LI>Any name beginning with <CODE>'JMSX'</CODE> is a JMS defined
338   * property name.
339   * <LI>Any name beginning with <CODE>'JMS_'</CODE> is a provider-specific
340   * property name.
341   * <LI>Any name that does not begin with <CODE>'JMS'</CODE> is an
342   * application-specific property name.
343   * </UL>
344   * <LI>White space is the same as that defined for the Java programming
345   * language: space, horizontal tab, form feed, and line terminator.
346   * <LI>Expressions:
347   * <UL>
348   * <LI>A selector is a conditional expression; a selector that evaluates
349   * to <CODE>true</CODE> matches; a selector that evaluates to
350   * <CODE>false</CODE> or unknown does not match.
351   * <LI>Arithmetic expressions are composed of themselves, arithmetic
352   * operations, identifiers (whose value is treated as a numeric
353   * literal), and numeric literals.
354   * <LI>Conditional expressions are composed of themselves, comparison
355   * operations, and logical operations.
356   * </UL>
357   * <LI>Standard bracketing <CODE>()</CODE> for ordering expression evaluation
358   * is supported.
359   * <LI>Logical operators in precedence order: <CODE>NOT</CODE>,
360   * <CODE>AND</CODE>, <CODE>OR</CODE>
361   * <LI>Comparison operators: <CODE>=</CODE>, <CODE>></CODE>, <CODE>>=</CODE>,
362   * <CODE><</CODE>, <CODE><=</CODE>, <CODE><></CODE> (not equal)
363   * <UL>
364   * <LI>Only like type values can be compared. One exception is that it
365   * is valid to compare exact numeric values and approximate numeric
366   * values; the type conversion required is defined by the rules of
367   * numeric promotion in the Java programming language. If the
368   * comparison of non-like type values is attempted, the value of the
369   * operation is false. If either of the type values evaluates to
370   * <CODE>NULL</CODE>, the value of the expression is unknown.
371   * <LI>String and boolean comparison is restricted to <CODE>=</CODE> and
372   * <CODE><></CODE>. Two strings are equal
373   * if and only if they contain the same sequence of characters.
374   * </UL>
375   * <LI>Arithmetic operators in precedence order:
376   * <UL>
377   * <LI><CODE>+</CODE>, <CODE>-</CODE> (unary)
378   * <LI><CODE>*</CODE>, <CODE>/</CODE> (multiplication and division)
379   * <LI><CODE>+</CODE>, <CODE>-</CODE> (addition and subtraction)
380   * <LI>Arithmetic operations must use numeric promotion in the Java
381   * programming language.
382   * </UL>
383   * <LI><CODE><I>arithmetic-expr1</I> [NOT] BETWEEN <I>arithmetic-expr2</I>
384   * AND <I>arithmetic-expr3</I></CODE> (comparison operator)
385   * <UL>
386   * <LI><CODE>"age&nbsp;BETWEEN&nbsp;15&nbsp;AND&nbsp;19"</CODE> is
387   * equivalent to
388   * <CODE>"age&nbsp;>=&nbsp;15&nbsp;AND&nbsp;age&nbsp;<=&nbsp;19"</CODE>
389   * <LI><CODE>"age&nbsp;NOT&nbsp;BETWEEN&nbsp;15&nbsp;AND&nbsp;19"</CODE>
390   * is equivalent to
391   * <CODE>"age&nbsp;<&nbsp;15&nbsp;OR&nbsp;age&nbsp;>&nbsp;19"</CODE>
392   * </UL>
393   * <LI><CODE><I>identifier</I> [NOT] IN (<I>string-literal1</I>,
394   * <I>string-literal2</I>,...)</CODE> (comparison operator where
395   * <CODE><I>identifier</I></CODE> has a <CODE>String</CODE> or
396   * <CODE>NULL</CODE> value)
397   * <UL>
398   * <LI><CODE>"Country&nbsp;IN&nbsp;('&nbsp;UK',&nbsp;'US',&nbsp;'France')"</CODE>
399   * is true for
400   * <CODE>'UK'</CODE> and false for <CODE>'Peru'</CODE>; it is
401   * equivalent to the expression
402   * <CODE>"(Country&nbsp;=&nbsp;'&nbsp;UK')&nbsp;OR&nbsp;(Country&nbsp;=&nbsp;'&nbsp;US')&nbsp;OR&nbsp;(Country&nbsp;=&nbsp;'&nbsp;France')"</CODE>
403   * <LI><CODE>"Country&nbsp;NOT&nbsp;IN&nbsp;('&nbsp;UK',&nbsp;'US',&nbsp;'France')"</CODE>
404   * is false for <CODE>'UK'</CODE> and true for <CODE>'Peru'</CODE>; it
405   * is equivalent to the expression
406   * <CODE>"NOT&nbsp;((Country&nbsp;=&nbsp;'&nbsp;UK')&nbsp;OR&nbsp;(Country&nbsp;=&nbsp;'&nbsp;US')&nbsp;OR&nbsp;(Country&nbsp;=&nbsp;'&nbsp;France'))"</CODE>
407   * <LI>If identifier of an <CODE>IN</CODE> or <CODE>NOT IN</CODE>
408   * operation is <CODE>NULL</CODE>, the value of the operation is
409   * unknown.
410   * </UL>
411   * <LI><CODE><I>identifier</I> [NOT] LIKE <I>pattern-value</I> [ESCAPE
412   * <I>escape-character</I>]</CODE> (comparison operator, where
413   * <CODE><I>identifier</I></CODE> has a <CODE>String</CODE> value;
414   * <CODE><I>pattern-value</I></CODE> is a string literal where
415   * <CODE>'_'</CODE> stands for any single character; <CODE>'%'</CODE>
416   * stands for any sequence of characters, including the empty sequence;
417   * and all other characters stand for themselves. The optional
418   * <CODE><I>escape-character</I></CODE> is a single-character string
419   * literal whose character is used to escape the special meaning of the
420   * <CODE>'_'</CODE> and <CODE>'%'</CODE> in
421   * <CODE><I>pattern-value</I></CODE>.)
422   * <UL>
423   * <LI><CODE>"phone&nbsp;LIKE&nbsp;'12%3'"</CODE> is true for
424   * <CODE>'123'</CODE> or <CODE>'12993'</CODE> and false for
425   * <CODE>'1234'</CODE>
426   * <LI><CODE>"word&nbsp;LIKE&nbsp;'l_se'"</CODE> is true for
427   * <CODE>'lose'</CODE> and false for <CODE>'loose'</CODE>
428   * <LI><CODE>"underscored&nbsp;LIKE&nbsp;'\_%'&nbsp;ESCAPE&nbsp;'\'"</CODE>
429   * is true for <CODE>'_foo'</CODE> and false for <CODE>'bar'</CODE>
430   * <LI><CODE>"phone&nbsp;NOT&nbsp;LIKE&nbsp;'12%3'"</CODE> is false for
431   * <CODE>'123'</CODE> or <CODE>'12993'</CODE> and true for
432   * <CODE>'1234'</CODE>
433   * <LI>If <CODE><I>identifier</I></CODE> of a <CODE>LIKE</CODE> or
434   * <CODE>NOT LIKE</CODE> operation is <CODE>NULL</CODE>, the value
435   * of the operation is unknown.
436   * </UL>
437   * <LI><CODE><I>identifier</I> IS NULL</CODE> (comparison operator that tests
438   * for a null header field value or a missing property value)
439   * <UL>
440   * <LI><CODE>"prop_name&nbsp;IS&nbsp;NULL"</CODE>
441   * </UL>
442   * <LI><CODE><I>identifier</I> IS NOT NULL</CODE> (comparison operator that
443   * tests for the existence of a non-null header field value or a property
444   * value)
445   * <UL>
446   * <LI><CODE>"prop_name&nbsp;IS&nbsp;NOT&nbsp;NULL"</CODE>
447   * </UL>
448   *
449   * <P>JMS providers are required to verify the syntactic correctness of a
450   * message selector at the time it is presented. A method that provides a
451   * syntactically incorrect selector must result in a <CODE>JMSException</CODE>.
452   * JMS providers may also optionally provide some semantic checking at the time
453   * the selector is presented. Not all semantic checking can be performed at
454   * the time a message selector is presented, because property types are not known.
455   *
456   * <P>The following message selector selects messages with a message type
457   * of car and color of blue and weight greater than 2500 pounds:
458   *
459   * <PRE>"JMSType&nbsp;=&nbsp;'car'&nbsp;AND&nbsp;color&nbsp;=&nbsp;'blue'&nbsp;AND&nbsp;weight&nbsp;>&nbsp;2500"</PRE>
460   *
461   * <H4>Null Values</H4>
462   *
463   * <P>As noted above, property values may be <CODE>NULL</CODE>. The evaluation
464   * of selector expressions containing <CODE>NULL</CODE> values is defined by
465   * SQL92 <CODE>NULL</CODE> semantics. A brief description of these semantics
466   * is provided here.
467   *
468   * <P>SQL treats a <CODE>NULL</CODE> value as unknown. Comparison or arithmetic
469   * with an unknown value always yields an unknown value.
470   *
471   * <P>The <CODE>IS NULL</CODE> and <CODE>IS NOT NULL</CODE> operators convert
472   * an unknown value into the respective <CODE>TRUE</CODE> and
473   * <CODE>FALSE</CODE> values.
474   *
475   * <P>The boolean operators use three-valued logic as defined by the
476   * following tables:
477   *
478   * <P><B>The definition of the <CODE>AND</CODE> operator</B>
479   *
480   * <PRE>
481   * | AND | T | F | U
482   * +------+-------+-------+-------
483   * | T | T | F | U
484   * | F | F | F | F
485   * | U | U | F | U
486   * +------+-------+-------+-------
487   * </PRE>
488   *
489   * <P><B>The definition of the <CODE>OR</CODE> operator</B>
490   *
491   * <PRE>
492   * | OR | T | F | U
493   * +------+-------+-------+--------
494   * | T | T | T | T
495   * | F | T | F | U
496   * | U | T | U | U
497   * +------+-------+-------+-------
498   * </PRE>
499   *
500   * <P><B>The definition of the <CODE>NOT</CODE> operator</B>
501   *
502   * <PRE>
503   * | NOT
504   * +------+------
505   * | T | F
506   * | F | T
507   * | U | U
508   * +------+-------
509   * </PRE>
510   *
511   * <H4>Special Notes</H4>
512   *
513   * <P>When used in a message selector, the <CODE>JMSDeliveryMode</CODE> header
514   * field is treated as having the values <CODE>'PERSISTENT'</CODE> and
515   * <CODE>'NON_PERSISTENT'</CODE>.
516   *
517   * <P>Date and time values should use the standard <CODE>long</CODE>
518   * millisecond value. When a date or time literal is included in a message
519   * selector, it should be an integer literal for a millisecond value. The
520   * standard way to produce millisecond values is to use
521   * <CODE>java.util.Calendar</CODE>.
522   *
523   * <P>Although SQL supports fixed decimal comparison and arithmetic, JMS
524   * message selectors do not. This is the reason for restricting exact
525   * numeric literals to those without a decimal (and the addition of
526   * numerics with a decimal as an alternate representation for
527   * approximate numeric values).
528   *
529   * <P>SQL comments are not supported.
530   *
531   * @version 1.1 April 2, 2002
532   * @author Mark Hapner
533   * @author Rich Burridge
534   * @author Kate Stout
535   *
536   * @see javax.jms.MessageConsumer#receive()
537   * @see javax.jms.MessageConsumer#receive(long)
538   * @see javax.jms.MessageConsumer#receiveNoWait()
539   * @see javax.jms.MessageListener#onMessage(Message)
540   * @see javax.jms.BytesMessage
541   * @see javax.jms.MapMessage
542   * @see javax.jms.ObjectMessage
543   * @see javax.jms.StreamMessage
544   * @see javax.jms.TextMessage
545   */
546
547 public interface Message {
548
549     /** The message producer's default delivery mode is <CODE>PERSISTENT</CODE>.
550      *
551      * @see DeliveryMode#PERSISTENT
552      */
553     static final int DEFAULT_DELIVERY_MODE = DeliveryMode.PERSISTENT;
554
555     /** The message producer's default priority is 4.
556      */
557     static final int DEFAULT_PRIORITY = 4;
558
559     /** The message producer's default time to live is unlimited; the message
560      * never expires.
561      */
562     static final long DEFAULT_TIME_TO_LIVE = 0;
563
564
565     /** Gets the message ID.
566       *
567       * <P>The <CODE>JMSMessageID</CODE> header field contains a value that
568       * uniquely identifies each message sent by a provider.
569       *
570       * <P>When a message is sent, <CODE>JMSMessageID</CODE> can be ignored.
571       * When the <CODE>send</CODE> or <CODE>publish</CODE> method returns, it
572       * contains a provider-assigned value.
573       *
574       * <P>A <CODE>JMSMessageID</CODE> is a <CODE>String</CODE> value that
575       * should function as a
576       * unique key for identifying messages in a historical repository.
577       * The exact scope of uniqueness is provider-defined. It should at
578       * least cover all messages for a specific installation of a
579       * provider, where an installation is some connected set of message
580       * routers.
581       *
582       * <P>All <CODE>JMSMessageID</CODE> values must start with the prefix
583       * <CODE>'ID:'</CODE>.
584       * Uniqueness of message ID values across different providers is
585       * not required.
586       *
587       * <P>Since message IDs take some effort to create and increase a
588       * message's size, some JMS providers may be able to optimize message
589       * overhead if they are given a hint that the message ID is not used by
590       * an application. By calling the
591       * <CODE>MessageProducer.setDisableMessageID</CODE> method, a JMS client
592       * enables this potential optimization for all messages sent by that
593       * message producer. If the JMS provider accepts this
594       * hint, these messages must have the message ID set to null; if the
595       * provider ignores the hint, the message ID must be set to its normal
596       * unique value.
597       *
598       * @return the message ID
599       *
600       * @exception JMSException if the JMS provider fails to get the message ID
601       * due to some internal error.
602       * @see javax.jms.Message#setJMSMessageID(String)
603       * @see javax.jms.MessageProducer#setDisableMessageID(boolean)
604       */
605  
606     String
607     getJMSMessageID() throws JMSException ;
608
609
610     /** Sets the message ID.
611       *
612       * <P>JMS providers set this field when a message is sent. This method
613       * can be used to change the value for a message that has been received.
614       *
615       * @param id the ID of the message
616       *
617       * @exception JMSException if the JMS provider fails to set the message ID
618       * due to some internal error.
619       *
620       * @see javax.jms.Message#getJMSMessageID()
621       */
622
623     void
624     setJMSMessageID(String id) throws JMSException ;
625
626
627     /** Gets the message timestamp.
628       *
629       * <P>The <CODE>JMSTimestamp</CODE> header field contains the time a
630       * message was
631       * handed off to a provider to be sent. It is not the time the
632       * message was actually transmitted, because the actual send may occur
633       * later due to transactions or other client-side queueing of messages.
634       *
635       * <P>When a message is sent, <CODE>JMSTimestamp</CODE> is ignored. When
636       * the <CODE>send</CODE> or <CODE>publish</CODE>
637       * method returns, it contains a time value somewhere in the interval
638       * between the call and the return. The value is in the format of a normal
639       * millis time value in the Java programming language.
640       *
641       * <P>Since timestamps take some effort to create and increase a
642       * message's size, some JMS providers may be able to optimize message
643       * overhead if they are given a hint that the timestamp is not used by an
644       * application. By calling the
645       * <CODE>MessageProducer.setDisableMessageTimestamp</CODE> method, a JMS
646       * client enables this potential optimization for all messages sent by
647       * that message producer. If the JMS provider accepts this
648       * hint, these messages must have the timestamp set to zero; if the
649       * provider ignores the hint, the timestamp must be set to its normal
650       * value.
651       *
652       * @return the message timestamp
653       *
654       * @exception JMSException if the JMS provider fails to get the timestamp
655       * due to some internal error.
656       *
657       * @see javax.jms.Message#setJMSTimestamp(long)
658       * @see javax.jms.MessageProducer#setDisableMessageTimestamp(boolean)
659       */
660
661     long
662     getJMSTimestamp() throws JMSException ;
663
664
665     /** Sets the message timestamp.
666       *
667       * <P>JMS providers set this field when a message is sent. This method
668       * can be used to change the value for a message that has been received.
669       *
670       * @param timestamp the timestamp for this message
671       *
672       * @exception JMSException if the JMS provider fails to set the timestamp
673       * due to some internal error.
674       *
675       * @see javax.jms.Message#getJMSTimestamp()
676       */
677
678     void
679     setJMSTimestamp(long timestamp) throws JMSException ;
680
681
682     /** Gets the correlation ID as an array of bytes for the message.
683       *
684       * <P>The use of a <CODE>byte[]</CODE> value for
685       * <CODE>JMSCorrelationID</CODE> is non-portable.
686       *
687       * @return the correlation ID of a message as an array of bytes
688       *
689       * @exception JMSException if the JMS provider fails to get the correlation
690       * ID due to some internal error.
691       *
692       * @see javax.jms.Message#setJMSCorrelationID(String)
693       * @see javax.jms.Message#getJMSCorrelationID()
694       * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
695       */
696
697     byte []
698     getJMSCorrelationIDAsBytes() throws JMSException ;
699
700
701     /** Sets the correlation ID as an array of bytes for the message.
702       *
703       * <P>The array is copied before the method returns, so
704       * future modifications to the array will not alter this message header.
705       *
706       * <P>If a provider supports the native concept of correlation ID, a
707       * JMS client may need to assign specific <CODE>JMSCorrelationID</CODE>
708       * values to match those expected by native messaging clients.
709       * JMS providers without native correlation ID values are not required to
710       * support this method and its corresponding get method; their
711       * implementation may throw a
712       * <CODE>java.lang.UnsupportedOperationException</CODE>.
713       *
714       * <P>The use of a <CODE>byte[]</CODE> value for
715       * <CODE>JMSCorrelationID</CODE> is non-portable.
716       *
717       * @param correlationID the correlation ID value as an array of bytes
718       *
719       * @exception JMSException if the JMS provider fails to set the correlation
720       * ID due to some internal error.
721       *
722       * @see javax.jms.Message#setJMSCorrelationID(String)
723       * @see javax.jms.Message#getJMSCorrelationID()
724       * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
725       */
726
727     void
728     setJMSCorrelationIDAsBytes(byte[] correlationID) throws JMSException ;
729
730
731     /** Sets the correlation ID for the message.
732       *
733       * <P>A client can use the <CODE>JMSCorrelationID</CODE> header field to
734       * link one message with another. A typical use is to link a response
735       * message with its request message.
736       *
737       * <P><CODE>JMSCorrelationID</CODE> can hold one of the following:
738       * <UL>
739       * <LI>A provider-specific message ID
740       * <LI>An application-specific <CODE>String</CODE>
741       * <LI>A provider-native <CODE>byte[]</CODE> value
742       * </UL>
743       *
744       * <P>Since each message sent by a JMS provider is assigned a message ID
745       * value, it is convenient to link messages via message ID. All message ID
746       * values must start with the <CODE>'ID:'</CODE> prefix.
747       *
748       * <P>In some cases, an application (made up of several clients) needs to
749       * use an application-specific value for linking messages. For instance,
750       * an application may use <CODE>JMSCorrelationID</CODE> to hold a value
751       * referencing some external information. Application-specified values
752       * must not start with the <CODE>'ID:'</CODE> prefix; this is reserved for
753       * provider-generated message ID values.
754       *
755       * <P>If a provider supports the native concept of correlation ID, a JMS
756       * client may need to assign specific <CODE>JMSCorrelationID</CODE> values
757       * to match those expected by clients that do not use the JMS API. A
758       * <CODE>byte[]</CODE> value is used for this
759       * purpose. JMS providers without native correlation ID values are not
760       * required to support <CODE>byte[]</CODE> values. The use of a
761       * <CODE>byte[]</CODE> value for <CODE>JMSCorrelationID</CODE> is
762       * non-portable.
763       *
764       * @param correlationID the message ID of a message being referred to
765       *
766       * @exception JMSException if the JMS provider fails to set the correlation
767       * ID due to some internal error.
768       *
769       * @see javax.jms.Message#getJMSCorrelationID()
770       * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
771       * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
772       */
773
774     void
775     setJMSCorrelationID(String correlationID) throws JMSException ;
776
777
778     /** Gets the correlation ID for the message.
779       *
780       * <P>This method is used to return correlation ID values that are
781       * either provider-specific message IDs or application-specific
782       * <CODE>String</CODE> values.
783       *
784       * @return the correlation ID of a message as a <CODE>String</CODE>
785       *
786       * @exception JMSException if the JMS provider fails to get the correlation
787       * ID due to some internal error.
788       *
789       * @see javax.jms.Message#setJMSCorrelationID(String)
790       * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
791       * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
792       */
793  
794     String
795     getJMSCorrelationID() throws JMSException ;
796
797
798     /** Gets the <CODE>Destination</CODE> object to which a reply to this
799       * message should be sent.
800       *
801       * @return <CODE>Destination</CODE> to which to send a response to this
802       * message
803       *
804       * @exception JMSException if the JMS provider fails to get the
805       * <CODE>JMSReplyTo</CODE> destination due to some
806       * internal error.
807       *
808       * @see javax.jms.Message#setJMSReplyTo(Destination)
809       */
810  
811     Destination
812     getJMSReplyTo() throws JMSException ;
813
814
815     /** Sets the <CODE>Destination</CODE> object to which a reply to this
816       * message should be sent.
817       *
818       * <P>The <CODE>JMSReplyTo</CODE> header field contains the destination
819       * where a reply
820       * to the current message should be sent. If it is null, no reply is
821       * expected. The destination may be either a <CODE>Queue</CODE> object or
822       * a <CODE>Topic</CODE> object.
823       *
824       * <P>Messages sent with a null <CODE>JMSReplyTo</CODE> value may be a
825       * notification of some event, or they may just be some data the sender
826       * thinks is of interest.
827       *
828       * <P>Messages with a <CODE>JMSReplyTo</CODE> value typically expect a
829       * response. A response is optional; it is up to the client to decide.
830       * These messages are called requests. A message sent in response to a
831       * request is called a reply.
832       *
833       * <P>In some cases a client may wish to match a request it sent earlier
834       * with a reply it has just received. The client can use the
835       * <CODE>JMSCorrelationID</CODE> header field for this purpose.
836       *
837       * @param replyTo <CODE>Destination</CODE> to which to send a response to
838       * this message
839       *
840       * @exception JMSException if the JMS provider fails to set the
841       * <CODE>JMSReplyTo</CODE> destination due to some
842       * internal error.
843       *
844       * @see javax.jms.Message#getJMSReplyTo()
845       */
846
847     void
848     setJMSReplyTo(Destination replyTo) throws JMSException ;
849
850
851     /** Gets the <CODE>Destination</CODE> object for this message.
852       *
853       * <P>The <CODE>JMSDestination</CODE> header field contains the
854       * destination to which the message is being sent.
855       *
856       * <P>When a message is sent, this field is ignored. After completion
857       * of the <CODE>send</CODE> or <CODE>publish</CODE> method, the field
858       * holds the destination specified by the method.
859       *
860       * <P>When a message is received, its <CODE>JMSDestination</CODE> value
861       * must be equivalent to the value assigned when it was sent.
862       *
863       * @return the destination of this message
864       *
865       * @exception JMSException if the JMS provider fails to get the destination
866       * due to some internal error.
867       *
868       * @see javax.jms.Message#setJMSDestination(Destination)
869       */
870
871     Destination
872     getJMSDestination() throws JMSException ;
873
874
875     /** Sets the <CODE>Destination</CODE> object for this message.
876       *
877       * <P>JMS providers set this field when a message is sent. This method
878       * can be used to change the value for a message that has been received.
879       *
880       * @param destination the destination for this message
881       *
882       * @exception JMSException if the JMS provider fails to set the destination
883       * due to some internal error.
884       *
885       * @see javax.jms.Message#getJMSDestination()
886       */
887
888     void
889     setJMSDestination(Destination destination) throws JMSException ;
890
891
892     /** Gets the <CODE>DeliveryMode</CODE> value specified for this message.
893       *
894       * @return the delivery mode for this message
895       *
896       * @exception JMSException if the JMS provider fails to get the
897       * delivery mode due to some internal error.
898       *
899       * @see javax.jms.Message#setJMSDeliveryMode(int)
900       * @see javax.jms.DeliveryMode
901       */
902  
903     int
904     getJMSDeliveryMode() throws JMSException ;
905  
906  
907     /** Sets the <CODE>DeliveryMode</CODE> value for this message.
908       *
909       * <P>JMS providers set this field when a message is sent. This method
910       * can be used to change the value for a message that has been received.
911       *
912       * @param deliveryMode the delivery mode for this message
913       *
914       * @exception JMSException if the JMS provider fails to set the
915       * delivery mode due to some internal error.
916       *
917       * @see javax.jms.Message#getJMSDeliveryMode()
918       * @see javax.jms.DeliveryMode
919       */
920  
921     void
922     setJMSDeliveryMode(int deliveryMode) throws JMSException ;
923
924
925     /** Gets an indication of whether this message is being redelivered.
926       *
927       * <P>If a client receives a message with the <CODE>JMSRedelivered</CODE>
928       * field set,
929       * it is likely, but not guaranteed, that this message was delivered
930       * earlier but that its receipt was not acknowledged
931       * at that time.
932       *
933       * @return true if this message is being redelivered
934       *
935       * @exception JMSException if the JMS provider fails to get the redelivered
936       * state due to some internal error.
937       *
938       * @see javax.jms.Message#setJMSRedelivered(boolean)
939       */
940  
941     boolean
942     getJMSRedelivered() throws JMSException ;
943  
944  
945     /** Specifies whether this message is being redelivered.
946       *
947       * <P>This field is set at the time the message is delivered. This
948       * method can be used to change the value for a message that has
949       * been received.
950       *
951       * @param redelivered an indication of whether this message is being
952       * redelivered
953       *
954       * @exception JMSException if the JMS provider fails to set the redelivered
955       * state due to some internal error.
956       *
957       * @see javax.jms.Message#getJMSRedelivered()
958       */
959  
960     void
961     setJMSRedelivered(boolean redelivered) throws JMSException ;
962
963
964     /** Gets the message type identifier supplied by the client when the
965       * message was sent.
966       *
967       * @return the message type
968       *
969       * @exception JMSException if the JMS provider fails to get the message
970       * type due to some internal error.
971       *
972       * @see javax.jms.Message#setJMSType(String)
973       */
974        
975     String
976     getJMSType() throws JMSException ;
977
978
979     /** Sets the message type.
980       *
981       * <P>Some JMS providers use a message repository that contains the
982       * definitions of messages sent by applications. The <CODE>JMSType</CODE>
983       * header field may reference a message's definition in the provider's
984       * repository.
985       *
986       * <P>The JMS API does not define a standard message definition repository,
987       * nor does it define a naming policy for the definitions it contains.
988       *
989       * <P>Some messaging systems require that a message type definition for
990       * each application message be created and that each message specify its
991       * type. In order to work with such JMS providers, JMS clients should
992       * assign a value to <CODE>JMSType</CODE>, whether the application makes
993       * use of it or not. This ensures that the field is properly set for those
994       * providers that require it.
995       *
996       * <P>To ensure portability, JMS clients should use symbolic values for
997       * <CODE>JMSType</CODE> that can be configured at installation time to the
998       * values defined in the current provider's message repository. If string
999       * literals are used, they may not be valid type names for some JMS
1000      * providers.
1001      *
1002      * @param type the message type
1003      *
1004      * @exception JMSException if the JMS provider fails to set the message
1005      * type due to some internal error.
1006      *
1007      * @see javax.jms.Message#getJMSType()
1008      */
1009
1010    void
1011    setJMSType(String type) throws JMSException ;
1012
1013
1014    /** Gets the message's expiration value.
1015      *
1016      * <P>When a message is sent, the <CODE>JMSExpiration</CODE> header field
1017      * is left unassigned. After completion of the <CODE>send</CODE> or
1018      * <CODE>publish</CODE> method, it holds the expiration time of the
1019      * message. This is the sum of the time-to-live value specified by the
1020      * client and the GMT at the time of the <CODE>send</CODE> or
1021      * <CODE>publish</CODE>.
1022      *
1023      * <P>If the time-to-live is specified as zero, <CODE>JMSExpiration</CODE>
1024      * is set to zero to indicate that the message does not expire.
1025      *
1026      * <P>When a message's expiration time is reached, a provider should
1027      * discard it. The JMS API does not define any form of notification of
1028      * message expiration.
1029      *
1030      * <P>Clients should not receive messages that have expired; however,
1031      * the JMS API does not guarantee that this will not happen.
1032      *
1033      * @return the time the message expires, which is the sum of the
1034      * time-to-live value specified by the client and the GMT at the
1035      * time of the send
1036      *
1037      * @exception JMSException if the JMS provider fails to get the message
1038      * expiration due to some internal error.
1039      *
1040      * @see javax.jms.Message#setJMSExpiration(long)
1041      */
1042 
1043    long
1044    getJMSExpiration() throws JMSException ;
1045 
1046 
1047    /** Sets the message's expiration value.
1048      *
1049      * <P>JMS providers set this field when a message is sent. This method
1050      * can be used to change the value for a message that has been received.
1051      *
1052      * @param expiration the message's expiration time
1053      *
1054      * @exception JMSException if the JMS provider fails to set the message
1055      * expiration due to some internal error.
1056      *
1057      * @see javax.jms.Message#getJMSExpiration()
1058      */
1059 
1060    void