0001: /*
0002: * The contents of this file are subject to the terms
0003: * of the Common Development and Distribution License
0004: * (the License). You may not use this file except in
0005: * compliance with the License.
0006: *
0007: * You can obtain a copy of the license at
0008: * https://glassfish.dev.java.net/public/CDDLv1.0.html or
0009: * glassfish/bootstrap/legal/CDDLv1.0.txt.
0010: * See the License for the specific language governing
0011: * permissions and limitations under the License.
0012: *
0013: * When distributing Covered Code, include this CDDL
0014: * Header Notice in each file and include the License file
0015: * at glassfish/bootstrap/legal/CDDLv1.0.txt.
0016: * If applicable, add the following below the CDDL Header,
0017: * with the fields enclosed by brackets [] replaced by
0018: * you own identifying information:
0019: * "Portions Copyrighted [year] [name of copyright owner]"
0020: *
0021: * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
0022: */
0023:
0024: package javax.jms;
0025:
0026: import java.util.Enumeration;
0027:
0028: /**
0029: * The <CODE>Message</CODE> interface is the root interface of all JMS
0030: * messages. It defines the message header and the <CODE>acknowledge</CODE>
0031: * method used for all messages.
0032: *
0033: * <P>
0034: * Most message-oriented middleware (MOM) products treat messages as lightweight
0035: * entities that consist of a header and a payload. The header contains fields
0036: * used for message routing and identification; the payload contains the
0037: * application data being sent.
0038: *
0039: * <P>
0040: * Within this general form, the definition of a message varies significantly
0041: * across products. It would be quite difficult for the JMS API to support all
0042: * of these message models.
0043: *
0044: * <P>
0045: * With this in mind, the JMS message model has the following goals:
0046: * <UL>
0047: * <LI>Provide a single, unified message API
0048: * <LI>Provide an API suitable for creating messages that match the format used
0049: * by provider-native messaging applications
0050: * <LI>Support the development of heterogeneous applications that span
0051: * operating systems, machine architectures, and computer languages
0052: * <LI>Support messages containing objects in the Java programming language
0053: * ("Java objects")
0054: * <LI>Support messages containing Extensible Markup Language (XML) pages
0055: * </UL>
0056: *
0057: * <P>
0058: * JMS messages are composed of the following parts:
0059: * <UL>
0060: * <LI>Header - All messages support the same set of header fields. Header
0061: * fields contain values used by both clients and providers to identify and
0062: * route messages.
0063: * <LI>Properties - Each message contains a built-in facility for supporting
0064: * application-defined property values. Properties provide an efficient
0065: * mechanism for supporting application-defined message filtering.
0066: * <LI>Body - The JMS API defines several types of message body, which cover
0067: * the majority of messaging styles currently in use.
0068: * </UL>
0069: *
0070: * <H4>Message Bodies</H4>
0071: *
0072: * <P>
0073: * The JMS API defines five types of message body:
0074: * <UL>
0075: * <LI>Stream - A <CODE>StreamMessage</CODE> object's message body contains a
0076: * stream of primitive values in the Java programming language ("Java
0077: * primitives"). It is filled and read sequentially.
0078: * <LI>Map - A <CODE>MapMessage</CODE> object's message body contains a set
0079: * of name-value pairs, where names are <CODE>String</CODE> objects, and
0080: * values are Java primitives. The entries can be accessed sequentially or
0081: * randomly by name. The order of the entries is undefined.
0082: * <LI>Text - A <CODE>TextMessage</CODE> object's message body contains a
0083: * <CODE>java.lang.String</CODE> object. This message type can be used to
0084: * transport plain-text messages, and XML messages.
0085: * <LI>Object - An <CODE>ObjectMessage</CODE> object's message body contains
0086: * a <CODE>Serializable</CODE> Java object.
0087: * <LI>Bytes - A <CODE>BytesMessage</CODE> object's message body contains a
0088: * stream of uninterpreted bytes. This message type is for literally encoding a
0089: * body to match an existing message format. In many cases, it is possible to
0090: * use one of the other body types, which are easier to use. Although the JMS
0091: * API allows the use of message properties with byte messages, they are
0092: * typically not used, since the inclusion of properties may affect the format.
0093: * </UL>
0094: *
0095: * <H4>Message Headers</H4>
0096: *
0097: * <P>
0098: * The <CODE>JMSCorrelationID</CODE> header field is used for linking one
0099: * message with another. It typically links a reply message with its requesting
0100: * message.
0101: *
0102: * <P>
0103: * <CODE>JMSCorrelationID</CODE> can hold a provider-specific message ID, an
0104: * application-specific <CODE>String</CODE> object, or a provider-native
0105: * <CODE>byte[]</CODE> value.
0106: *
0107: * <H4>Message Properties</H4>
0108: *
0109: * <P>
0110: * A <CODE>Message</CODE> object contains a built-in facility for supporting
0111: * application-defined property values. In effect, this provides a mechanism for
0112: * adding application-specific header fields to a message.
0113: *
0114: * <P>
0115: * Properties allow an application, via message selectors, to have a JMS
0116: * provider select, or filter, messages on its behalf using application-specific
0117: * criteria.
0118: *
0119: * <P>
0120: * Property names must obey the rules for a message selector identifier.
0121: * Property names must not be null, and must not be empty strings. If a property
0122: * name is set and it is either null or an empty string, an <CODE>IllegalArgumentException</CODE>
0123: * must be thrown.
0124: *
0125: * <P>
0126: * Property values can be <CODE>boolean</CODE>, <CODE>byte</CODE>, <CODE>short</CODE>,
0127: * <CODE>int</CODE>, <CODE>long</CODE>, <CODE>float</CODE>, <CODE>double</CODE>,
0128: * and <CODE>String</CODE>.
0129: *
0130: * <P>
0131: * Property values are set prior to sending a message. When a client receives a
0132: * message, its properties are in read-only mode. If a client attempts to set
0133: * properties at this point, a <CODE>MessageNotWriteableException</CODE> is
0134: * thrown. If <CODE>clearProperties</CODE> is called, the properties can now
0135: * be both read from and written to. Note that header fields are distinct from
0136: * properties. Header fields are never in read-only mode.
0137: *
0138: * <P>
0139: * A property value may duplicate a value in a message's body, or it may not.
0140: * Although JMS does not define a policy for what should or should not be made a
0141: * property, application developers should note that JMS providers will likely
0142: * handle data in a message's body more efficiently than data in a message's
0143: * properties. For best performance, applications should use message properties
0144: * only when they need to customize a message's header. The primary reason for
0145: * doing this is to support customized message selection.
0146: *
0147: * <P>
0148: * Message properties support the following conversion table. The marked cases
0149: * must be supported. The unmarked cases must throw a <CODE>JMSException</CODE>.
0150: * The <CODE>String</CODE>-to-primitive conversions may throw a runtime
0151: * exception if the primitive's <CODE>valueOf</CODE> method does not accept
0152: * the <CODE>String</CODE> as a valid representation of the primitive.
0153: *
0154: * <P>
0155: * A value written as the row type can be read as the column type.
0156: *
0157: * <PRE> | | boolean byte short int long float double String
0158: * |---------------------------------------------------------- |boolean | X X
0159: * |byte | X X X X X |short | X X X X |int | X X X |long | X X |float | X X X
0160: * |double | X X |String | X X X X X X X X
0161: * |----------------------------------------------------------
0162: *
0163: * </PRE>
0164: *
0165: * <P>
0166: * In addition to the type-specific set/get methods for properties, JMS provides
0167: * the <CODE>setObjectProperty</CODE> and <CODE>getObjectProperty</CODE>
0168: * methods. These support the same set of property types using the objectified
0169: * primitive values. Their purpose is to allow the decision of property type to
0170: * made at execution time rather than at compile time. They support the same
0171: * property value conversions.
0172: *
0173: * <P>
0174: * The <CODE>setObjectProperty</CODE> method accepts values of class <CODE>Boolean</CODE>,
0175: * <CODE>Byte</CODE>, <CODE>Short</CODE>, <CODE>Integer</CODE>, <CODE>Long</CODE>,
0176: * <CODE>Float</CODE>, <CODE>Double</CODE>, and <CODE>String</CODE>. An
0177: * attempt to use any other class must throw a <CODE>JMSException</CODE>.
0178: *
0179: * <P>
0180: * The <CODE>getObjectProperty</CODE> method only returns values of class
0181: * <CODE>Boolean</CODE>, <CODE>Byte</CODE>, <CODE>Short</CODE>, <CODE>Integer</CODE>,
0182: * <CODE>Long</CODE>, <CODE>Float</CODE>, <CODE>Double</CODE>, and
0183: * <CODE>String</CODE>.
0184: *
0185: * <P>
0186: * The order of property values is not defined. To iterate through a message's
0187: * property values, use <CODE>getPropertyNames</CODE> to retrieve a property
0188: * name enumeration and then use the various property get methods to retrieve
0189: * their values.
0190: *
0191: * <P>
0192: * A message's properties are deleted by the <CODE>clearProperties</CODE>
0193: * method. This leaves the message with an empty set of properties.
0194: *
0195: * <P>
0196: * Getting a property value for a name which has not been set returns a null
0197: * value. Only the <CODE>getStringProperty</CODE> and <CODE>getObjectProperty</CODE>
0198: * methods can return a null value. Attempting to read a null value as a
0199: * primitive type must be treated as calling the primitive's corresponding
0200: * <CODE>valueOf(String)</CODE> conversion method with a null value.
0201: *
0202: * <P>
0203: * The JMS API reserves the <CODE>JMSX</CODE> property name prefix for JMS
0204: * defined properties. The full set of these properties is defined in the Java
0205: * Message Service specification. New JMS defined properties may be added in
0206: * later versions of the JMS API. Support for these properties is optional. The
0207: * <CODE>String[] ConnectionMetaData.getJMSXPropertyNames</CODE> method
0208: * returns the names of the JMSX properties supported by a connection.
0209: *
0210: * <P>
0211: * JMSX properties may be referenced in message selectors whether or not they
0212: * are supported by a connection. If they are not present in a message, they are
0213: * treated like any other absent property.
0214: *
0215: * <P>
0216: * JMSX properties defined in the specification as "set by provider on send" are
0217: * available to both the producer and the consumers of the message. JMSX
0218: * properties defined in the specification as "set by provider on receive" are
0219: * available only to the consumers.
0220: *
0221: * <P>
0222: * <CODE>JMSXGroupID</CODE> and <CODE>JMSXGroupSeq</CODE> are standard
0223: * properties that clients should use if they want to group messages. All
0224: * providers must support them. Unless specifically noted, the values and
0225: * semantics of the JMSX properties are undefined.
0226: *
0227: * <P>
0228: * The JMS API reserves the <CODE>JMS_<I>vendor_name</I></CODE> property
0229: * name prefix for provider-specific properties. Each provider defines its own
0230: * value for <CODE><I>vendor_name</I></CODE>. This is the mechanism a JMS
0231: * provider uses to make its special per-message services available to a JMS
0232: * client.
0233: *
0234: * <P>
0235: * The purpose of provider-specific properties is to provide special features
0236: * needed to integrate JMS clients with provider-native clients in a single JMS
0237: * application. They should not be used for messaging between JMS clients.
0238: *
0239: * <H4>Provider Implementations of JMS Message Interfaces</H4>
0240: *
0241: * <P>
0242: * The JMS API provides a set of message interfaces that define the JMS message
0243: * model. It does not provide implementations of these interfaces.
0244: *
0245: * <P>
0246: * Each JMS provider supplies a set of message factories with its <CODE>Session</CODE>
0247: * object for creating instances of messages. This allows a provider to use
0248: * message implementations tailored to its specific needs.
0249: *
0250: * <P>
0251: * A provider must be prepared to accept message implementations that are not
0252: * its own. They may not be handled as efficiently as its own implementation;
0253: * however, they must be handled.
0254: *
0255: * <P>
0256: * Note the following exception case when a provider is handling a foreign
0257: * message implementation. If the foreign message implementation contains a
0258: * <CODE>JMSReplyTo</CODE> header field that is set to a foreign destination
0259: * implementation, the provider is not required to handle or preserve the value
0260: * of this header field.
0261: *
0262: * <H4>Message Selectors</H4>
0263: *
0264: * <P>
0265: * A JMS message selector allows a client to specify, by header field references
0266: * and property references, the messages it is interested in. Only messages
0267: * whose header and property values match the selector are delivered. What it
0268: * means for a message not to be delivered depends on the <CODE>MessageConsumer</CODE>
0269: * being used (see {@link javax.jms.QueueReceiver QueueReceiver} and
0270: * {@link javax.jms.TopicSubscriber TopicSubscriber}).
0271: *
0272: * <P>
0273: * Message selectors cannot reference message body values.
0274: *
0275: * <P>
0276: * A message selector matches a message if the selector evaluates to true when
0277: * the message's header field values and property values are substituted for
0278: * their corresponding identifiers in the selector.
0279: *
0280: * <P>
0281: * A message selector is a <CODE>String</CODE> whose syntax is based on a
0282: * subset of the SQL92 conditional expression syntax. If the value of a message
0283: * selector is an empty string, the value is treated as a null and indicates
0284: * that there is no message selector for the message consumer.
0285: *
0286: * <P>
0287: * The order of evaluation of a message selector is from left to right within
0288: * precedence level. Parentheses can be used to change this order.
0289: *
0290: * <P>
0291: * Predefined selector literals and operator names are shown here in uppercase;
0292: * however, they are case insensitive.
0293: *
0294: * <P>
0295: * A selector can contain:
0296: *
0297: * <UL>
0298: * <LI>Literals:
0299: * <UL>
0300: * <LI>A string literal is enclosed in single quotes, with a single quote
0301: * represented by doubled single quote; for example, <CODE>'literal'</CODE>
0302: * and <CODE>'literal''s'</CODE>. Like string literals in the Java
0303: * programming language, these use the Unicode character encoding.
0304: * <LI>An exact numeric literal is a numeric value without a decimal point,
0305: * such as <CODE>57</CODE>, <CODE>-957</CODE>, and <CODE>+62</CODE>;
0306: * numbers in the range of <CODE>long</CODE> are supported. Exact numeric
0307: * literals use the integer literal syntax of the Java programming language.
0308: * <LI>An approximate numeric literal is a numeric value in scientific
0309: * notation, such as <CODE>7E3</CODE> and <CODE>-57.9E2</CODE>, or a
0310: * numeric value with a decimal, such as <CODE>7.</CODE>, <CODE>-95.7</CODE>,
0311: * and <CODE>+6.2</CODE>; numbers in the range of <CODE>double</CODE> are
0312: * supported. Approximate literals use the floating-point literal syntax of the
0313: * Java programming language.
0314: * <LI>The boolean literals <CODE>TRUE</CODE> and <CODE>FALSE</CODE>.
0315: * </UL>
0316: * <LI>Identifiers:
0317: * <UL>
0318: * <LI>An identifier is an unlimited-length sequence of letters and digits, the
0319: * first of which must be a letter. A letter is any character for which the
0320: * method <CODE>Character.isJavaLetter</CODE> returns true. This includes
0321: * <CODE>'_'</CODE> and <CODE>'$'</CODE>. A letter or digit is any
0322: * character for which the method <CODE>Character.isJavaLetterOrDigit</CODE>
0323: * returns true.
0324: * <LI>Identifiers cannot be the names <CODE>NULL</CODE>, <CODE>TRUE</CODE>,
0325: * and <CODE>FALSE</CODE>.
0326: * <LI>Identifiers cannot be <CODE>NOT</CODE>, <CODE>AND</CODE>, <CODE>OR</CODE>,
0327: * <CODE>BETWEEN</CODE>, <CODE>LIKE</CODE>, <CODE>IN</CODE>, <CODE>IS</CODE>,
0328: * or <CODE>ESCAPE</CODE>.
0329: * <LI>Identifiers are either header field references or property references.
0330: * The type of a property value in a message selector corresponds to the type
0331: * used to set the property. If a property that does not exist in a message is
0332: * referenced, its value is <CODE>NULL</CODE>.
0333: * <LI>The conversions that apply to the get methods for properties do not
0334: * apply when a property is used in a message selector expression. For example,
0335: * suppose you set a property as a string value, as in the following:
0336: *
0337: * <PRE>
0338: *
0339: * myMessage.setStringProperty("NumberOfOrders", "2");
0340: *
0341: * </PRE>
0342: *
0343: * The following expression in a message selector would evaluate to false,
0344: * because a string cannot be used in an arithmetic expression:
0345: *
0346: * <PRE>
0347: *
0348: * "NumberOfOrders > 1"
0349: *
0350: * </PRE>
0351: *
0352: * <LI>Identifiers are case-sensitive.
0353: * <LI>Message header field references are restricted to <CODE>JMSDeliveryMode</CODE>,
0354: * <CODE>JMSPriority</CODE>, <CODE>JMSMessageID</CODE>, <CODE>JMSTimestamp</CODE>,
0355: * <CODE>JMSCorrelationID</CODE>, and <CODE>JMSType</CODE>. <CODE>JMSMessageID</CODE>,
0356: * <CODE>JMSCorrelationID</CODE>, and <CODE>JMSType</CODE> values may be
0357: * null and if so are treated as a <CODE>NULL</CODE> value.
0358: * <LI>Any name beginning with <CODE>'JMSX'</CODE> is a JMS defined property
0359: * name.
0360: * <LI>Any name beginning with <CODE>'JMS_'</CODE> is a provider-specific
0361: * property name.
0362: * <LI>Any name that does not begin with <CODE>'JMS'</CODE> is an
0363: * application-specific property name.
0364: * </UL>
0365: * <LI>White space is the same as that defined for the Java programming
0366: * language: space, horizontal tab, form feed, and line terminator.
0367: * <LI>Expressions:
0368: * <UL>
0369: * <LI>A selector is a conditional expression; a selector that evaluates to
0370: * <CODE>true</CODE> matches; a selector that evaluates to <CODE>false</CODE>
0371: * or unknown does not match.
0372: * <LI>Arithmetic expressions are composed of themselves, arithmetic
0373: * operations, identifiers (whose value is treated as a numeric literal), and
0374: * numeric literals.
0375: * <LI>Conditional expressions are composed of themselves, comparison
0376: * operations, and logical operations.
0377: * </UL>
0378: * <LI>Standard bracketing <CODE>()</CODE> for ordering expression evaluation
0379: * is supported.
0380: * <LI>Logical operators in precedence order: <CODE>NOT</CODE>, <CODE>AND</CODE>,
0381: * <CODE>OR</CODE>
0382: * <LI>Comparison operators: <CODE>=</CODE>, <CODE>></CODE>, <CODE>>=</CODE>,
0383: * <CODE><</CODE>, <CODE><=</CODE>, <CODE><></CODE> (not equal)
0384: * <UL>
0385: * <LI>Only like type values can be compared. One exception is that it is valid
0386: * to compare exact numeric values and approximate numeric values; the type
0387: * conversion required is defined by the rules of numeric promotion in the Java
0388: * programming language. If the comparison of non-like type values is attempted,
0389: * the value of the operation is false. If either of the type values evaluates
0390: * to <CODE>NULL</CODE>, the value of the expression is unknown.
0391: * <LI>String and boolean comparison is restricted to <CODE>=</CODE> and
0392: * <CODE><></CODE>. Two strings are equal if and only if they contain the
0393: * same sequence of characters.
0394: * </UL>
0395: * <LI>Arithmetic operators in precedence order:
0396: * <UL>
0397: * <LI><CODE>+</CODE>, <CODE>-</CODE> (unary)
0398: * <LI><CODE>*</CODE>, <CODE>/</CODE> (multiplication and division)
0399: * <LI><CODE>+</CODE>, <CODE>-</CODE> (addition and subtraction)
0400: * <LI>Arithmetic operations must use numeric promotion in the Java programming
0401: * language.
0402: * </UL>
0403: * <LI><CODE><I>arithmetic-expr1</I> [NOT] BETWEEN <I>arithmetic-expr2</I>
0404: * AND <I>arithmetic-expr3</I></CODE> (comparison operator)
0405: * <UL>
0406: * <LI><CODE>"age BETWEEN 15 AND 19"</CODE> is equivalent
0407: * to <CODE>"age >= 15 AND age <= 19"</CODE>
0408: * <LI><CODE>"age NOT BETWEEN 15 AND 19"</CODE> is
0409: * equivalent to <CODE>"age < 15 OR age > 19"</CODE>
0410: * </UL>
0411: * <LI><CODE><I>identifier</I> [NOT] IN (<I>string-literal1</I>,
0412: * <I>string-literal2</I>,...)</CODE> (comparison operator where <CODE><I>identifier</I></CODE>
0413: * has a <CODE>String</CODE> or <CODE>NULL</CODE> value)
0414: * <UL>
0415: * <LI><CODE>"Country IN (' UK', 'US', 'France')"</CODE>
0416: * is true for <CODE>'UK'</CODE> and false for <CODE>'Peru'</CODE>; it is
0417: * equivalent to the expression <CODE>"(Country = ' UK') OR (Country = ' US') OR (Country = ' France')"</CODE>
0418: * <LI><CODE>"Country NOT IN (' UK', 'US', 'France')"</CODE>
0419: * is false for <CODE>'UK'</CODE> and true for <CODE>'Peru'</CODE>; it is
0420: * equivalent to the expression <CODE>"NOT ((Country = ' UK') OR (Country = ' US') OR (Country = ' France'))"</CODE>
0421: * <LI>If identifier of an <CODE>IN</CODE> or <CODE>NOT IN</CODE> operation
0422: * is <CODE>NULL</CODE>, the value of the operation is unknown.
0423: * </UL>
0424: * <LI><CODE><I>identifier</I> [NOT] LIKE <I>pattern-value</I> [ESCAPE
0425: * <I>escape-character</I>]</CODE> (comparison operator, where <CODE><I>identifier</I></CODE>
0426: * has a <CODE>String</CODE> value; <CODE><I>pattern-value</I></CODE> is a
0427: * string literal where <CODE>'_'</CODE> stands for any single character;
0428: * <CODE>'%'</CODE> stands for any sequence of characters, including the empty
0429: * sequence; and all other characters stand for themselves. The optional <CODE><I>escape-character</I></CODE>
0430: * is a single-character string literal whose character is used to escape the
0431: * special meaning of the <CODE>'_'</CODE> and <CODE>'%'</CODE> in <CODE><I>pattern-value</I></CODE>.)
0432: * <UL>
0433: * <LI><CODE>"phone LIKE '12%3'"</CODE> is true for <CODE>'123'</CODE>
0434: * or <CODE>'12993'</CODE> and false for <CODE>'1234'</CODE>
0435: * <LI><CODE>"word LIKE 'l_se'"</CODE> is true for <CODE>'lose'</CODE>
0436: * and false for <CODE>'loose'</CODE>
0437: * <LI><CODE>"underscored LIKE '\_%' ESCAPE '\'"</CODE>
0438: * is true for <CODE>'_foo'</CODE> and false for <CODE>'bar'</CODE>
0439: * <LI><CODE>"phone NOT LIKE '12%3'"</CODE> is false for
0440: * <CODE>'123'</CODE> or <CODE>'12993'</CODE> and true for <CODE>'1234'</CODE>
0441: * <LI>If <CODE><I>identifier</I></CODE> of a <CODE>LIKE</CODE> or <CODE>NOT
0442: * LIKE</CODE> operation is <CODE>NULL</CODE>, the value of the operation is
0443: * unknown.
0444: * </UL>
0445: * <LI><CODE><I>identifier</I> IS NULL</CODE> (comparison operator that
0446: * tests for a null header field value or a missing property value)
0447: * <UL>
0448: * <LI><CODE>"prop_name IS NULL"</CODE>
0449: * </UL>
0450: * <LI><CODE><I>identifier</I> IS NOT NULL</CODE> (comparison operator that
0451: * tests for the existence of a non-null header field value or a property value)
0452: * <UL>
0453: * <LI><CODE>"prop_name IS NOT NULL"</CODE>
0454: * </UL>
0455: *
0456: * <P>
0457: * JMS providers are required to verify the syntactic correctness of a message
0458: * selector at the time it is presented. A method that provides a syntactically
0459: * incorrect selector must result in a <CODE>JMSException</CODE>. JMS
0460: * providers may also optionally provide some semantic checking at the time the
0461: * selector is presented. Not all semantic checking can be performed at the time
0462: * a message selector is presented, because property types are not known.
0463: *
0464: * <P>
0465: * The following message selector selects messages with a message type of car
0466: * and color of blue and weight greater than 2500 pounds:
0467: *
0468: * <PRE>
0469: *
0470: * "JMSType = 'car' AND color = 'blue' AND weight > 2500"
0471: *
0472: * </PRE>
0473: *
0474: * <H4>Null Values</H4>
0475: *
0476: * <P>
0477: * As noted above, property values may be <CODE>NULL</CODE>. The evaluation
0478: * of selector expressions containing <CODE>NULL</CODE> values is defined by
0479: * SQL92 <CODE>NULL</CODE> semantics. A brief description of these semantics
0480: * is provided here.
0481: *
0482: * <P>
0483: * SQL treats a <CODE>NULL</CODE> value as unknown. Comparison or arithmetic
0484: * with an unknown value always yields an unknown value.
0485: *
0486: * <P>
0487: * The <CODE>IS NULL</CODE> and <CODE>IS NOT NULL</CODE> operators convert
0488: * an unknown value into the respective <CODE>TRUE</CODE> and <CODE>FALSE</CODE>
0489: * values.
0490: *
0491: * <P>
0492: * The boolean operators use three-valued logic as defined by the following
0493: * tables:
0494: *
0495: * <P>
0496: * <B>The definition of the <CODE>AND</CODE> operator</B>
0497: *
0498: * <PRE> | AND | T | F | U +------+-------+-------+------- | T | T | F | U | F |
0499: * F | F | F | U | U | F | U +------+-------+-------+-------
0500: *
0501: * </PRE>
0502: *
0503: * <P>
0504: * <B>The definition of the <CODE>OR</CODE> operator</B>
0505: *
0506: * <PRE> | OR | T | F | U +------+-------+-------+-------- | T | T | T | T | F |
0507: * T | F | U | U | T | U | U +------+-------+-------+-------
0508: *
0509: * </PRE>
0510: *
0511: * <P>
0512: * <B>The definition of the <CODE>NOT</CODE> operator</B>
0513: *
0514: * <PRE> | NOT +------+------ | T | F | F | T | U | U +------+-------
0515: *
0516: * </PRE>
0517: *
0518: * <H4>Special Notes</H4>
0519: *
0520: * <P>
0521: * When used in a message selector, the <CODE>JMSDeliveryMode</CODE> header
0522: * field is treated as having the values <CODE>'PERSISTENT'</CODE> and <CODE>'NON_PERSISTENT'</CODE>.
0523: *
0524: * <P>
0525: * Date and time values should use the standard <CODE>long</CODE> millisecond
0526: * value. When a date or time literal is included in a message selector, it
0527: * should be an integer literal for a millisecond value. The standard way to
0528: * produce millisecond values is to use <CODE>java.util.Calendar</CODE>.
0529: *
0530: * <P>
0531: * Although SQL supports fixed decimal comparison and arithmetic, JMS message
0532: * selectors do not. This is the reason for restricting exact numeric literals
0533: * to those without a decimal (and the addition of numerics with a decimal as an
0534: * alternate representation for approximate numeric values).
0535: *
0536: * <P>
0537: * SQL comments are not supported.
0538: *
0539: * @version 1.1 April 2, 2002
0540: * @author Mark Hapner
0541: * @author Rich Burridge
0542: * @author Kate Stout
0543: *
0544: * @see javax.jms.MessageConsumer#receive()
0545: * @see javax.jms.MessageConsumer#receive(long)
0546: * @see javax.jms.MessageConsumer#receiveNoWait()
0547: * @see javax.jms.MessageListener#onMessage(Message)
0548: * @see javax.jms.BytesMessage
0549: * @see javax.jms.MapMessage
0550: * @see javax.jms.ObjectMessage
0551: * @see javax.jms.StreamMessage
0552: * @see javax.jms.TextMessage
0553: */
0554:
0555: public interface Message {
0556:
0557: /**
0558: * The message producer's default delivery mode is <CODE>PERSISTENT</CODE>.
0559: *
0560: * @see DeliveryMode#PERSISTENT
0561: */
0562: static final int DEFAULT_DELIVERY_MODE = DeliveryMode.PERSISTENT;
0563:
0564: /**
0565: * The message producer's default priority is 4.
0566: */
0567: static final int DEFAULT_PRIORITY = 4;
0568:
0569: /**
0570: * The message producer's default time to live is unlimited; the message
0571: * never expires.
0572: */
0573: static final long DEFAULT_TIME_TO_LIVE = 0;
0574:
0575: /**
0576: * Gets the message ID.
0577: *
0578: * <P>
0579: * The <CODE>JMSMessageID</CODE> header field contains a value that
0580: * uniquely identifies each message sent by a provider.
0581: *
0582: * <P>
0583: * When a message is sent, <CODE>JMSMessageID</CODE> can be ignored. When
0584: * the <CODE>send</CODE> or <CODE>publish</CODE> method returns, it
0585: * contains a provider-assigned value.
0586: *
0587: * <P>
0588: * A <CODE>JMSMessageID</CODE> is a <CODE>String</CODE> value that
0589: * should function as a unique key for identifying messages in a historical
0590: * repository. The exact scope of uniqueness is provider-defined. It should
0591: * at least cover all messages for a specific installation of a provider,
0592: * where an installation is some connected set of message routers.
0593: *
0594: * <P>
0595: * All <CODE>JMSMessageID</CODE> values must start with the prefix <CODE>'ID:'</CODE>.
0596: * Uniqueness of message ID values across different providers is not
0597: * required.
0598: *
0599: * <P>
0600: * Since message IDs take some effort to create and increase a message's
0601: * size, some JMS providers may be able to optimize message overhead if they
0602: * are given a hint that the message ID is not used by an application. By
0603: * calling the <CODE>MessageProducer.setDisableMessageID</CODE> method, a
0604: * JMS client enables this potential optimization for all messages sent by
0605: * that message producer. If the JMS provider accepts this hint, these
0606: * messages must have the message ID set to null; if the provider ignores
0607: * the hint, the message ID must be set to its normal unique value.
0608: *
0609: * @return the message ID
0610: *
0611: * @exception JMSException
0612: * if the JMS provider fails to get the message ID due to
0613: * some internal error.
0614: * @see javax.jms.Message#setJMSMessageID(String)
0615: * @see javax.jms.MessageProducer#setDisableMessageID(boolean)
0616: */
0617:
0618: String getJMSMessageID() throws JMSException;
0619:
0620: /**
0621: * Sets the message ID.
0622: *
0623: * <P>
0624: * JMS providers set this field when a message is sent. This method can be
0625: * used to change the value for a message that has been received.
0626: *
0627: * @param id
0628: * the ID of the message
0629: *
0630: * @exception JMSException
0631: * if the JMS provider fails to set the message ID due to
0632: * some internal error.
0633: *
0634: * @see javax.jms.Message#getJMSMessageID()
0635: */
0636:
0637: void setJMSMessageID(String id) throws JMSException;
0638:
0639: /**
0640: * Gets the message timestamp.
0641: *
0642: * <P>
0643: * The <CODE>JMSTimestamp</CODE> header field contains the time a message
0644: * was handed off to a provider to be sent. It is not the time the message
0645: * was actually transmitted, because the actual send may occur later due to
0646: * transactions or other client-side queueing of messages.
0647: *
0648: * <P>
0649: * When a message is sent, <CODE>JMSTimestamp</CODE> is ignored. When the
0650: * <CODE>send</CODE> or <CODE>publish</CODE> method returns, it contains
0651: * a time value somewhere in the interval between the call and the return.
0652: * The value is in the format of a normal millis time value in the Java
0653: * programming language.
0654: *
0655: * <P>
0656: * Since timestamps take some effort to create and increase a message's
0657: * size, some JMS providers may be able to optimize message overhead if they
0658: * are given a hint that the timestamp is not used by an application. By
0659: * calling the <CODE>MessageProducer.setDisableMessageTimestamp</CODE>
0660: * method, a JMS client enables this potential optimization for all messages
0661: * sent by that message producer. If the JMS provider accepts this hint,
0662: * these messages must have the timestamp set to zero; if the provider
0663: * ignores the hint, the timestamp must be set to its normal value.
0664: *
0665: * @return the message timestamp
0666: *
0667: * @exception JMSException
0668: * if the JMS provider fails to get the timestamp due to some
0669: * internal error.
0670: *
0671: * @see javax.jms.Message#setJMSTimestamp(long)
0672: * @see javax.jms.MessageProducer#setDisableMessageTimestamp(boolean)
0673: */
0674:
0675: long getJMSTimestamp() throws JMSException;
0676:
0677: /**
0678: * Sets the message timestamp.
0679: *
0680: * <P>
0681: * JMS providers set this field when a message is sent. This method can be
0682: * used to change the value for a message that has been received.
0683: *
0684: * @param timestamp
0685: * the timestamp for this message
0686: *
0687: * @exception JMSException
0688: * if the JMS provider fails to set the timestamp due to some
0689: * internal error.
0690: *
0691: * @see javax.jms.Message#getJMSTimestamp()
0692: */
0693:
0694: void setJMSTimestamp(long timestamp) throws JMSException;
0695:
0696: /**
0697: * Gets the correlation ID as an array of bytes for the message.
0698: *
0699: * <P>
0700: * The use of a <CODE>byte[]</CODE> value for <CODE>JMSCorrelationID</CODE>
0701: * is non-portable.
0702: *
0703: * @return the correlation ID of a message as an array of bytes
0704: *
0705: * @exception JMSException
0706: * if the JMS provider fails to get the correlation ID due to
0707: * some internal error.
0708: *
0709: * @see javax.jms.Message#setJMSCorrelationID(String)
0710: * @see javax.jms.Message#getJMSCorrelationID()
0711: * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
0712: */
0713:
0714: byte[] getJMSCorrelationIDAsBytes() throws JMSException;
0715:
0716: /**
0717: * Sets the correlation ID as an array of bytes for the message.
0718: *
0719: * <P>
0720: * The array is copied before the method returns, so future modifications to
0721: * the array will not alter this message header.
0722: *
0723: * <P>
0724: * If a provider supports the native concept of correlation ID, a JMS client
0725: * may need to assign specific <CODE>JMSCorrelationID</CODE> values to
0726: * match those expected by native messaging clients. JMS providers without
0727: * native correlation ID values are not required to support this method and
0728: * its corresponding get method; their implementation may throw a <CODE>java.lang.UnsupportedOperationException</CODE>.
0729: *
0730: * <P>
0731: * The use of a <CODE>byte[]</CODE> value for <CODE>JMSCorrelationID</CODE>
0732: * is non-portable.
0733: *
0734: * @param correlationID
0735: * the correlation ID value as an array of bytes
0736: *
0737: * @exception JMSException
0738: * if the JMS provider fails to set the correlation ID due to
0739: * some internal error.
0740: *
0741: * @see javax.jms.Message#setJMSCorrelationID(String)
0742: * @see javax.jms.Message#getJMSCorrelationID()
0743: * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
0744: */
0745:
0746: void setJMSCorrelationIDAsBytes(byte[] correlationID)
0747: throws JMSException;
0748:
0749: /**
0750: * Sets the correlation ID for the message.
0751: *
0752: * <P>
0753: * A client can use the <CODE>JMSCorrelationID</CODE> header field to link
0754: * one message with another. A typical use is to link a response message
0755: * with its request message.
0756: *
0757: * <P>
0758: * <CODE>JMSCorrelationID</CODE> can hold one of the following:
0759: * <UL>
0760: * <LI>A provider-specific message ID
0761: * <LI>An application-specific <CODE>String</CODE>
0762: * <LI>A provider-native <CODE>byte[]</CODE> value
0763: * </UL>
0764: *
0765: * <P>
0766: * Since each message sent by a JMS provider is assigned a message ID value,
0767: * it is convenient to link messages via message ID. All message ID values
0768: * must start with the <CODE>'ID:'</CODE> prefix.
0769: *
0770: * <P>
0771: * In some cases, an application (made up of several clients) needs to use
0772: * an application-specific value for linking messages. For instance, an
0773: * application may use <CODE>JMSCorrelationID</CODE> to hold a value
0774: * referencing some external information. Application-specified values must
0775: * not start with the <CODE>'ID:'</CODE> prefix; this is reserved for
0776: * provider-generated message ID values.
0777: *
0778: * <P>
0779: * If a provider supports the native concept of correlation ID, a JMS client
0780: * may need to assign specific <CODE>JMSCorrelationID</CODE> values to
0781: * match those expected by clients that do not use the JMS API. A <CODE>byte[]</CODE>
0782: * value is used for this purpose. JMS providers without native correlation
0783: * ID values are not required to support <CODE>byte[]</CODE> values. The
0784: * use of a <CODE>byte[]</CODE> value for <CODE>JMSCorrelationID</CODE>
0785: * is non-portable.
0786: *
0787: * @param correlationID
0788: * the message ID of a message being referred to
0789: *
0790: * @exception JMSException
0791: * if the JMS provider fails to set the correlation ID due to
0792: * some internal error.
0793: *
0794: * @see javax.jms.Message#getJMSCorrelationID()
0795: * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
0796: * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
0797: */
0798:
0799: void setJMSCorrelationID(String correlationID) throws JMSException;
0800:
0801: /**
0802: * Gets the correlation ID for the message.
0803: *
0804: * <P>
0805: * This method is used to return correlation ID values that are either
0806: * provider-specific message IDs or application-specific <CODE>String</CODE>
0807: * values.
0808: *
0809: * @return the correlation ID of a message as a <CODE>String</CODE>
0810: *
0811: * @exception JMSException
0812: * if the JMS provider fails to get the correlation ID due to
0813: * some internal error.
0814: *
0815: * @see javax.jms.Message#setJMSCorrelationID(String)
0816: * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
0817: * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
0818: */
0819:
0820: String getJMSCorrelationID() throws JMSException;
0821:
0822: /**
0823: * Gets the <CODE>Destination</CODE> object to which a reply to this
0824: * message should be sent.
0825: *
0826: * @return <CODE>Destination</CODE> to which to send a response to this
0827: * message
0828: *
0829: * @exception JMSException
0830: * if the JMS provider fails to get the <CODE>JMSReplyTo</CODE>
0831: * destination due to some internal error.
0832: *
0833: * @see javax.jms.Message#setJMSReplyTo(Destination)
0834: */
0835:
0836: Destination getJMSReplyTo() throws JMSException;
0837:
0838: /**
0839: * Sets the <CODE>Destination</CODE> object to which a reply to this
0840: * message should be sent.
0841: *
0842: * <P>
0843: * The <CODE>JMSReplyTo</CODE> header field contains the destination where
0844: * a reply to the current message should be sent. If it is null, no reply is
0845: * expected. The destination may be either a <CODE>Queue</CODE> object or
0846: * a <CODE>Topic</CODE> object.
0847: *
0848: * <P>
0849: * Messages sent with a null <CODE>JMSReplyTo</CODE> value may be a
0850: * notification of some event, or they may just be some data the sender
0851: * thinks is of interest.
0852: *
0853: * <P>
0854: * Messages with a <CODE>JMSReplyTo</CODE> value typically expect a
0855: * response. A response is optional; it is up to the client to decide. These
0856: * messages are called requests. A message sent in response to a request is
0857: * called a reply.
0858: *
0859: * <P>
0860: * In some cases a client may wish to match a request it sent earlier with a
0861: * reply it has just received. The client can use the <CODE>JMSCorrelationID</CODE>
0862: * header field for this purpose.
0863: *
0864: * @param replyTo
0865: * <CODE>Destination</CODE> to which to send a response to this
0866: * message
0867: *
0868: * @exception JMSException
0869: * if the JMS provider fails to set the <CODE>JMSReplyTo</CODE>
0870: * destination due to some internal error.
0871: *
0872: * @see javax.jms.Message#getJMSReplyTo()
0873: */
0874:
0875: void setJMSReplyTo(Destination replyTo) throws JMSException;
0876:
0877: /**
0878: * Gets the <CODE>Destination</CODE> object for this message.
0879: *
0880: * <P>
0881: * The <CODE>JMSDestination</CODE> header field contains the destination
0882: * to which the message is being sent.
0883: *
0884: * <P>
0885: * When a message is sent, this field is ignored. After completion of the
0886: * <CODE>send</CODE> or <CODE>publish</CODE> method, the field holds the
0887: * destination specified by the method.
0888: *
0889: * <P>
0890: * When a message is received, its <CODE>JMSDestination</CODE> value must
0891: * be equivalent to the value assigned when it was sent.
0892: *
0893: * @return the destination of this message
0894: *
0895: * @exception JMSException
0896: * if the JMS provider fails to get the destination due to
0897: * some internal error.
0898: *
0899: * @see javax.jms.Message#setJMSDestination(Destination)
0900: */
0901:
0902: Destination getJMSDestination() throws JMSException;
0903:
0904: /**
0905: * Sets the <CODE>Destination</CODE> object for this message.
0906: *
0907: * <P>
0908: * JMS providers set this field when a message is sent. This method can be
0909: * used to change the value for a message that has been received.
0910: *
0911: * @param destination
0912: * the destination for this message
0913: *
0914: * @exception JMSException
0915: * if the JMS provider fails to set the destination due to
0916: * some internal error.
0917: *
0918: * @see javax.jms.Message#getJMSDestination()
0919: */
0920:
0921: void setJMSDestination(Destination destination) throws JMSException;
0922:
0923: /**
0924: * Gets the <CODE>DeliveryMode</CODE> value specified for this message.
0925: *
0926: * @return the delivery mode for this message
0927: *
0928: * @exception JMSException
0929: * if the JMS provider fails to get the delivery mode due to
0930: * some internal error.
0931: *
0932: * @see javax.jms.Message#setJMSDeliveryMode(int)
0933: * @see javax.jms.DeliveryMode
0934: */
0935:
0936: int getJMSDeliveryMode() throws JMSException;
0937:
0938: /**
0939: * Sets the <CODE>DeliveryMode</CODE> value for this message.
0940: *
0941: * <P>
0942: * JMS providers set this field when a message is sent. This method can be
0943: * used to change the value for a message that has been received.
0944: *
0945: * @param deliveryMode
0946: * the delivery mode for this message
0947: *
0948: * @exception JMSException
0949: * if the JMS provider fails to set the delivery mode due to
0950: * some internal error.
0951: *
0952: * @see javax.jms.Message#getJMSDeliveryMode()
0953: * @see javax.jms.DeliveryMode
0954: */
0955:
0956: void setJMSDeliveryMode(int deliveryMode) throws JMSException;
0957:
0958: /**
0959: * Gets an indication of whether this message is being redelivered.
0960: *
0961: * <P>
0962: * If a client receives a message with the <CODE>JMSRedelivered</CODE>
0963: * field set, it is likely, but not guaranteed, that this message was
0964: * delivered earlier but that its receipt was not acknowledged at that time.
0965: *
0966: * @return true if this message is being redelivered
0967: *
0968: * @exception JMSException
0969: * if the JMS provider fails to get the redelivered state due
0970: * to some internal error.
0971: *
0972: * @see javax.jms.Message#setJMSRedelivered(boolean)
0973: */
0974:
0975: boolean getJMSRedelivered() throws JMSException;
0976:
0977: /**
0978: * Specifies whether this message is being redelivered.
0979: *
0980: * <P>
0981: * This field is set at the time the message is delivered. This method can
0982: * be used to change the value for a message that has been received.
0983: *
0984: * @param redelivered
0985: * an indication of whether this message is being redelivered
0986: *
0987: * @exception JMSException
0988: * if the JMS provider fails to set the redelivered state due
0989: * to some internal error.
0990: *
0991: * @see javax.jms.Message#getJMSRedelivered()
0992: */
0993:
0994: void setJMSRedelivered(boolean redelivered) throws JMSException;
0995:
0996: /**
0997: * Gets the message type identifier supplied by the client when the message
0998: * was sent.
0999: *
1000: * @return the message type
1001: *
1002: * @exception JMSException
1003: * if the JMS provider fails to get the message type due to
1004: * some internal error.
1005: *
1006: * @see javax.jms.Message#setJMSType(String)
1007: */
1008:
1009: String getJMSType() throws JMSException;
1010:
1011: /**
1012: * Sets the message type.
1013: *
1014: * <P>
1015: * Some JMS providers use a message repository that contains the definitions
1016: * of messages sent by applications. The <CODE>JMSType</CODE> header field
1017: * may reference a message's definition in the provider's repository.
1018: *
1019: * <P>
1020: * The JMS API does not define a standard message definition repository, nor
1021: * does it define a naming policy for the definitions it contains.
1022: *
1023: * <P>
1024: * Some messaging systems require that a message type definition for each
1025: * application message be created and that each message specify its type. In
1026: * order to work with such JMS providers, JMS clients should assign a value
1027: * to <CODE>JMSType</CODE>, whether the application makes use of it or
1028: * not. This ensures that the field is properly set for those providers that
1029: * require it.
1030: *
1031: * <P>
1032: * To ensure portability, JMS clients should use symbolic values for <CODE>JMSType</CODE>
1033: * that can be configured at installation time to the values defined in the
1034: * current provider's message repository. If string literals are used, they
1035: * may not be valid type names for some JMS providers.
1036: *
1037: * @param type
1038: * the message type
1039: *
1040: * @exception JMSException
1041: * if the JMS provider fails to set the message type due to
1042: * some internal error.
1043: *
1044: * @see javax.jms.Message#getJMSType()
1045: */
1046:
1047: void setJMSType(String type) throws JMSException;
1048:
1049: /**
1050: * Gets the message's expiration value.
1051: *
1052: * <P>
1053: * When a message is sent, the <CODE>JMSExpiration</CODE> header field is
1054: * left unassigned. After completion of the <CODE>send</CODE> or <CODE>publish</CODE>
1055: * method, it holds the expiration time of the message. This is the sum of
1056: * the time-to-live value specified by the client and the GMT at the time of
1057: * the <CODE>send</CODE> or <CODE>publish</CODE>.
1058: *
1059: * <P>
1060: * If the time-to-live is specified as zero, <CODE>JMSExpiration</CODE> is
1061: * set to zero to indicate that the message does not expire.
1062: *
1063: * <P>
1064: * When a message's expiration time is reached, a provider should discard
1065: * it. The JMS API does not define any form of notification of message
1066: * expiration.
1067: *
1068: * <P>
1069: * Clients should not receive messages that have expired; however, the JMS
1070: * API does not guarantee that this will not happen.
1071: *
1072: * @return the time the message expires, which is the sum of the
1073: * time-to-live value specified by the client and the GMT at the
1074: * time of the send
1075: *
1076: * @exception JMSException
1077: * if the JMS provider fails to get the message expiration
1078: * due to some internal error.
1079: *
1080: * @see javax.jms.Message#setJMSExpiration(long)
1081: */
1082:
1083: long getJMSExpiration() throws JMSException;
1084:
1085: /**
1086: * Sets the message's expiration value.
1087: *
1088: * <P>
1089: * JMS providers set this field when a message is sent. This method can be
1090: * used to change the value for a message that has been received.
1091: *
1092: * @param expiration
1093: * the message's expiration time
1094: *
1095: * @exception JMSException
1096: * if the JMS provider fails to set the message expiration
1097: * due to some internal error.
1098: *
1099: * @see javax.jms.Message#getJMSExpiration()
1100: */
1101:
1102: void setJMSExpiration(long expiration) throws JMSException;
1103:
1104: /**
1105: * Gets the message priority level.
1106: *
1107: * <P>
1108: * The JMS API defines ten levels of priority value, with 0 as the lowest
1109: * priority and 9 as the highest. In addition, clients should consider
1110: * priorities 0-4 as gradations of normal priority and priorities 5-9 as
1111: * gradations of expedited priority.
1112: *
1113: * <P>
1114: * The JMS API does not require that a provider strictly implement priority
1115: * ordering of messages; however, it should do its best to deliver expedited
1116: * messages ahead of normal messages.
1117: *
1118: * @return the default message priority
1119: *
1120: * @exception JMSException
1121: * if the JMS provider fails to get the message priority due
1122: * to some internal error.
1123: *
1124: * @see javax.jms.Message#setJMSPriority(int)
1125: */
1126:
1127: int getJMSPriority() throws JMSException;
1128:
1129: /**
1130: * Sets the priority level for this message.
1131: *
1132: * <P>
1133: * JMS providers set this field when a message is sent. This method can be
1134: * used to change the value for a message that has been received.
1135: *
1136: * @param priority
1137: * the priority of this message
1138: *
1139: * @exception JMSException
1140: * if the JMS provider fails to set the message priority due
1141: * to some internal error.
1142: *
1143: * @see javax.jms.Message#getJMSPriority()
1144: */
1145:
1146: void setJMSPriority(int priority) throws JMSException;
1147:
1148: /**
1149: * Clears a message's properties.
1150: *
1151: * <P>
1152: * The message's header fields and body are not cleared.
1153: *
1154: * @exception JMSException
1155: * if the JMS provider fails to clear the message properties
1156: * due to some internal error.
1157: */
1158:
1159: void clearProperties() throws JMSException;
1160:
1161: /**
1162: * Indicates whether a property value exists.
1163: *
1164: * @param name
1165: * the name of the property to test
1166: *
1167: * @return true if the property exists
1168: *
1169: * @exception JMSException
1170: * if the JMS provider fails to determine if the property
1171: * exists due to some internal error.
1172: */
1173:
1174: boolean propertyExists(String name) throws JMSException;
1175:
1176: /**
1177: * Returns the value of the <CODE>boolean</CODE> property with the
1178: * specified name.
1179: *
1180: * @param name
1181: * the name of the <CODE>boolean</CODE> property
1182: *
1183: * @return the <CODE>boolean</CODE> property value for the specified name
1184: *
1185: * @exception JMSException
1186: * if the JMS provider fails to get the property value due to
1187: * some internal error.
1188: * @exception MessageFormatException
1189: * if this type conversion is invalid.
1190: */
1191:
1192: boolean getBooleanProperty(String name) throws JMSException;
1193:
1194: /**
1195: * Returns the value of the <CODE>byte</CODE> property with the specified
1196: * name.
1197: *
1198: * @param name
1199: * the name of the <CODE>byte</CODE> property
1200: *
1201: * @return the <CODE>byte</CODE> property value for the specified name
1202: *
1203: * @exception JMSException
1204: * if the JMS provider fails to get the property value due to
1205: * some internal error.
1206: * @exception MessageFormatException
1207: * if this type conversion is invalid.
1208: */
1209:
1210: byte getByteProperty(String name) throws JMSException;
1211:
1212: /**
1213: * Returns the value of the <CODE>short</CODE> property with the specified
1214: * name.
1215: *
1216: * @param name
1217: * the name of the <CODE>short</CODE> property
1218: *
1219: * @return the <CODE>short</CODE> property value for the specified name
1220: *
1221: * @exception JMSException
1222: * if the JMS provider fails to get the property value due to
1223: * some internal error.
1224: * @exception MessageFormatException
1225: * if this type conversion is invalid.
1226: */
1227:
1228: short getShortProperty(String name) throws JMSException;
1229:
1230: /**
1231: * Returns the value of the <CODE>int</CODE> property with the specified
1232: * name.
1233: *
1234: * @param name
1235: * the name of the <CODE>int</CODE> property
1236: *
1237: * @return the <CODE>int</CODE> property value for the specified name
1238: *
1239: * @exception JMSException
1240: * if the JMS provider fails to get the property value due to
1241: * some internal error.
1242: * @exception MessageFormatException
1243: * if this type conversion is invalid.
1244: */
1245:
1246: int getIntProperty(String name) throws JMSException;
1247:
1248: /**
1249: * Returns the value of the <CODE>long</CODE> property with the specified
1250: * name.
1251: *
1252: * @param name
1253: * the name of the <CODE>long</CODE> property
1254: *
1255: * @return the <CODE>long</CODE> property value for the specified name
1256: *
1257: * @exception JMSException
1258: * if the JMS provider fails to get the property value due to
1259: * some internal error.
1260: * @exception MessageFormatException
1261: * if this type conversion is invalid.
1262: */
1263:
1264: long getLongProperty(String name) throws JMSException;
1265:
1266: /**
1267: * Returns the value of the <CODE>float</CODE> property with the specified
1268: * name.
1269: *
1270: * @param name
1271: * the name of the <CODE>float</CODE> property
1272: *
1273: * @return the <CODE>float</CODE> property value for the specified name
1274: *
1275: * @exception JMSException
1276: * if the JMS provider fails to get the property value due to
1277: * some internal error.
1278: * @exception MessageFormatException
1279: * if this type conversion is invalid.
1280: */
1281:
1282: float getFloatProperty(String name) throws JMSException;
1283:
1284: /**
1285: * Returns the value of the <CODE>double</CODE> property with the
1286: * specified name.
1287: *
1288: * @param name
1289: * the name of the <CODE>double</CODE> property
1290: *
1291: * @return the <CODE>double</CODE> property value for the specified name
1292: *
1293: * @exception JMSException
1294: * if the JMS provider fails to get the property value due to
1295: * some internal error.
1296: * @exception MessageFormatException
1297: * if this type conversion is invalid.
1298: */
1299:
1300: double getDoubleProperty(String name) throws JMSException;
1301:
1302: /**
1303: * Returns the value of the <CODE>String</CODE> property with the
1304: * specified name.
1305: *
1306: * @param name
1307: * the name of the <CODE>String</CODE> property
1308: *
1309: * @return the <CODE>String</CODE> property value for the specified name;
1310: * if there is no property by this name, a null value is returned
1311: *
1312: * @exception JMSException
1313: * if the JMS provider fails to get the property value due to
1314: * some internal error.
1315: * @exception MessageFormatException
1316: * if this type conversion is invalid.
1317: */
1318:
1319: String getStringProperty(String name) throws JMSException;
1320:
1321: /**
1322: * Returns the value of the Java object property with the specified name.
1323: *
1324: * <P>
1325: * This method can be used to return, in objectified format, an object that
1326: * has been stored as a property in the message with the equivalent <CODE>setObjectProperty</CODE>
1327: * method call, or its equivalent primitive <CODE>set<I>type</I>Property</CODE>
1328: * method.
1329: *
1330: * @param name
1331: * the name of the Java object property
1332: *
1333: * @return the Java object property value with the specified name, in
1334: * objectified format (for example, if the property was set as an
1335: * <CODE>int</CODE>, an <CODE>Integer</CODE> is returned); if
1336: * there is no property by this name, a null value is returned
1337: *
1338: * @exception JMSException
1339: * if the JMS provider fails to get the property value due to
1340: * some internal error.
1341: */
1342:
1343: Object getObjectProperty(String name) throws JMSException;
1344:
1345: /**
1346: * Returns an <CODE>Enumeration</CODE> of all the property names.
1347: *
1348: * <P>
1349: * Note that JMS standard header fields are not considered properties and
1350: * are not returned in this enumeration.
1351: *
1352: * @return an enumeration of all the names of property values
1353: *
1354: * @exception JMSException
1355: * if the JMS provider fails to get the property names due to
1356: * some internal error.
1357: */
1358:
1359: Enumeration getPropertyNames() throws JMSException;
1360:
1361: /**
1362: * Sets a <CODE>boolean</CODE> property value with the specified name into
1363: * the message.
1364: *
1365: * @param name
1366: * the name of the <CODE>boolean</CODE> property
1367: * @param value
1368: * the <CODE>boolean</CODE> property value to set
1369: *
1370: * @exception JMSException
1371: * if the JMS provider fails to set the property due to some
1372: * internal error.
1373: * @exception IllegalArgumentException
1374: * if the name is null or if the name is an empty string.
1375: * @exception MessageNotWriteableException
1376: * if properties are read-only
1377: */
1378:
1379: void setBooleanProperty(String name, boolean value)
1380: throws JMSException;
1381:
1382: /**
1383: * Sets a <CODE>byte</CODE> property value with the specified name into
1384: * the message.
1385: *
1386: * @param name
1387: * the name of the <CODE>byte</CODE> property
1388: * @param value
1389: * the <CODE>byte</CODE> property value to set
1390: *
1391: * @exception JMSException
1392: * if the JMS provider fails to set the property due to some
1393: * internal error.
1394: * @exception IllegalArgumentException
1395: * if the name is null or if the name is an empty string.
1396: * @exception MessageNotWriteableException
1397: * if properties are read-only
1398: */
1399:
1400: void setByteProperty(String name, byte value) throws JMSException;
1401:
1402: /**
1403: * Sets a <CODE>short</CODE> property value with the specified name into
1404: * the message.
1405: *
1406: * @param name
1407: * the name of the <CODE>short</CODE> property
1408: * @param value
1409: * the <CODE>short</CODE> property value to set
1410: *
1411: * @exception JMSException
1412: * if the JMS provider fails to set the property due to some
1413: * internal error.
1414: * @exception IllegalArgumentException
1415: * if the name is null or if the name is an empty string.
1416: * @exception MessageNotWriteableException
1417: * if properties are read-only
1418: */
1419:
1420: void setShortProperty(String name, short value) throws JMSException;
1421:
1422: /**
1423: * Sets an <CODE>int</CODE> property value with the specified name into
1424: * the message.
1425: *
1426: * @param name
1427: * the name of the <CODE>int</CODE> property
1428: * @param value
1429: * the <CODE>int</CODE> property value to set
1430: *
1431: * @exception JMSException
1432: * if the JMS provider fails to set the property due to some
1433: * internal error.
1434: * @exception IllegalArgumentException
1435: * if the name is null or if the name is an empty string.
1436: * @exception MessageNotWriteableException
1437: * if properties are read-only
1438: */
1439:
1440: void setIntProperty(String name, int value) throws JMSException;
1441:
1442: /**
1443: * Sets a <CODE>long</CODE> property value with the specified name into
1444: * the message.
1445: *
1446: * @param name
1447: * the name of the <CODE>long</CODE> property
1448: * @param value
1449: * the <CODE>long</CODE> property value to set
1450: *
1451: * @exception JMSException
1452: * if the JMS provider fails to set the property due to some
1453: * internal error.
1454: * @exception IllegalArgumentException
1455: * if the name is null or if the name is an empty string.
1456: * @exception MessageNotWriteableException
1457: * if properties are read-only
1458: */
1459:
1460: void setLongProperty(String name, long value) throws JMSException;
1461:
1462: /**
1463: * Sets a <CODE>float</CODE> property value with the specified name into
1464: * the message.
1465: *
1466: * @param name
1467: * the name of the <CODE>float</CODE> property
1468: * @param value
1469: * the <CODE>float</CODE> property value to set
1470: *
1471: * @exception JMSException
1472: * if the JMS provider fails to set the property due to some
1473: * internal error.
1474: * @exception IllegalArgumentException
1475: * if the name is null or if the name is an empty string.
1476: * @exception MessageNotWriteableException
1477: * if properties are read-only
1478: */
1479:
1480: void setFloatProperty(String name, float value) throws JMSException;
1481:
1482: /**
1483: * Sets a <CODE>double</CODE> property value with the specified name into
1484: * the message.
1485: *
1486: * @param name
1487: * the name of the <CODE>double</CODE> property
1488: * @param value
1489: * the <CODE>double</CODE> property value to set
1490: *
1491: * @exception JMSException
1492: * if the JMS provider fails to set the property due to some
1493: * internal error.
1494: * @exception IllegalArgumentException
1495: * if the name is null or if the name is an empty string.
1496: * @exception MessageNotWriteableException
1497: * if properties are read-only
1498: */
1499:
1500: void setDoubleProperty(String name, double value)
1501: throws JMSException;
1502:
1503: /**
1504: * Sets a <CODE>String</CODE> property value with the specified name into
1505: * the message.
1506: *
1507: * @param name
1508: * the name of the <CODE>String</CODE> property
1509: * @param value
1510: * the <CODE>String</CODE> property value to set
1511: *
1512: * @exception JMSException
1513: * if the JMS provider fails to set the property due to some
1514: * internal error.
1515: * @exception IllegalArgumentException
1516: * if the name is null or if the name is an empty string.
1517: * @exception MessageNotWriteableException
1518: * if properties are read-only
1519: */
1520:
1521: void setStringProperty(String name, String value)
1522: throws JMSException;
1523:
1524: /**
1525: * Sets a Java object property value with the specified name into the
1526: * message.
1527: *
1528: * <P>
1529: * Note that this method works only for the objectified primitive object
1530: * types (<CODE>Integer</CODE>, <CODE>Double</CODE>, <CODE>Long</CODE>
1531: * ...) and <CODE>String</CODE> objects.
1532: *
1533: * @param name
1534: * the name of the Java object property
1535: * @param value
1536: * the Java object property value to set
1537: *
1538: * @exception JMSException
1539: * if the JMS provider fails to set the property due to some
1540: * internal error.
1541: * @exception IllegalArgumentException
1542: * if the name is null or if the name is an empty string.
1543: * @exception MessageFormatException
1544: * if the object is invalid
1545: * @exception MessageNotWriteableException
1546: * if properties are read-only
1547: */
1548:
1549: void setObjectProperty(String name, Object value)
1550: throws JMSException;
1551:
1552: /**
1553: * Acknowledges all consumed messages of the session of this consumed
1554: * message.
1555: *
1556: * <P>
1557: * All consumed JMS messages support the <CODE>acknowledge</CODE> method
1558: * for use when a client has specified that its JMS session's consumed
1559: * messages are to be explicitly acknowledged. By invoking <CODE>acknowledge</CODE>
1560: * on a consumed message, a client acknowledges all messages consumed by the
1561: * session that the message was delivered to.
1562: *
1563: * <P>
1564: * Calls to <CODE>acknowledge</CODE> are ignored for both transacted
1565: * sessions and sessions specified to use implicit acknowledgement modes.
1566: *
1567: * <P>
1568: * A client may individually acknowledge each message as it is consumed, or
1569: * it may choose to acknowledge messages as an application-defined group
1570: * (which is done by calling acknowledge on the last received message of the
1571: * group, thereby acknowledging all messages consumed by the session.)
1572: *
1573: * <P>
1574: * Messages that have been received but not acknowledged may be redelivered.
1575: *
1576: * @exception JMSException
1577: * if the JMS provider fails to acknowledge the messages due
1578: * to some internal error.
1579: * @exception IllegalStateException
1580: * if this method is called on a closed session.
1581: *
1582: * @see javax.jms.Session#CLIENT_ACKNOWLEDGE
1583: */
1584:
1585: void acknowledge() throws JMSException;
1586:
1587: /**
1588: * Clears out the message body. Clearing a message's body does not clear its
1589: * header values or property entries.
1590: *
1591: * <P>
1592: * If this message body was read-only, calling this method leaves the
1593: * message body in the same state as an empty body in a newly created
1594: * message.
1595: *
1596: * @exception JMSException
1597: * if the JMS provider fails to clear the message body due to
1598: * some internal error.
1599: */
1600:
1601: void clearBody() throws JMSException;
1602: }
|