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