message.java

JAVA 消息服务(JMS)定义了Java 中访问消息中间件的接口,里边有实现消息服务的基础源码,可以开发高级应用

  *     <LI>Identifiers cannot be <CODE>NOT</CODE>, <CODE>AND</CODE>, 
  *         <CODE>OR</CODE>, <CODE>BETWEEN</CODE>, <CODE>LIKE</CODE>, 
  *         <CODE>IN</CODE>, <CODE>IS</CODE>, or <CODE>ESCAPE</CODE>.
  *     <LI>Identifiers are either header field references or property 
  *         references.  The type of a property value in a message selector 
  *         corresponds to the type used to set the property. If a property 
  *         that does not exist in a message is referenced, its value is 
  *         <CODE>NULL</CODE>.
  *     <LI>The conversions that apply to the get methods for properties do not
  *         apply when a property is used in a message selector expression.
  *         For example, suppose you set a property as a string value, as in the
  *         following:
  *         <PRE>myMessage.setStringProperty("NumberOfOrders", "2");</PRE>
  *         The following expression in a message selector would evaluate to 
  *         false, because a string cannot be used in an arithmetic expression:
  *         <PRE>"NumberOfOrders > 1"</PRE>
  *     <LI>Identifiers are case-sensitive.
  *     <LI>Message header field references are restricted to 
  *         <CODE>JMSDeliveryMode</CODE>, <CODE>JMSPriority</CODE>, 
  *         <CODE>JMSMessageID</CODE>, <CODE>JMSTimestamp</CODE>, 
  *         <CODE>JMSCorrelationID</CODE>, and <CODE>JMSType</CODE>. 
  *         <CODE>JMSMessageID</CODE>, <CODE>JMSCorrelationID</CODE>, and 
  *         <CODE>JMSType</CODE> values may be null and if so are treated as a 
  *         <CODE>NULL</CODE> value.
  *     <LI>Any name beginning with <CODE>'JMSX'</CODE> is a JMS defined  
  *         property name.
  *     <LI>Any name beginning with <CODE>'JMS_'</CODE> is a provider-specific 
  *         property name.
  *     <LI>Any name that does not begin with <CODE>'JMS'</CODE> is an 
  *         application-specific property name.
  *   </UL>
  *   <LI>White space is the same as that defined for the Java programming
  *       language: space, horizontal tab, form feed, and line terminator.
  *   <LI>Expressions: 
  *   <UL>
  *     <LI>A selector is a conditional expression; a selector that evaluates 
  *         to <CODE>true</CODE> matches; a selector that evaluates to 
  *         <CODE>false</CODE> or unknown does not match.
  *     <LI>Arithmetic expressions are composed of themselves, arithmetic 
  *         operations, identifiers (whose value is treated as a numeric 
  *         literal), and numeric literals.
  *     <LI>Conditional expressions are composed of themselves, comparison 
  *         operations, and logical operations.
  *   </UL>
  *   <LI>Standard bracketing <CODE>()</CODE> for ordering expression evaluation
  *      is supported.
  *   <LI>Logical operators in precedence order: <CODE>NOT</CODE>, 
  *       <CODE>AND</CODE>, <CODE>OR</CODE>
  *   <LI>Comparison operators: <CODE>=</CODE>, <CODE>></CODE>, <CODE>>=</CODE>,
  *       <CODE><</CODE>, <CODE><=</CODE>, <CODE><></CODE> (not equal)
  *   <UL>
  *     <LI>Only like type values can be compared. One exception is that it 
  *         is valid to compare exact numeric values and approximate numeric 
  *         values; the type conversion required is defined by the rules of 
  *         numeric promotion in the Java programming language. If the 
  *         comparison of non-like type values is attempted, the value of the 
  *         operation is false. If either of the type values evaluates to 
  *         <CODE>NULL</CODE>, the value of the expression is unknown.   
  *     <LI>String and boolean comparison is restricted to <CODE>=</CODE> and 
  *         <CODE><></CODE>. Two strings are equal 
  *         if and only if they contain the same sequence of characters.
  *   </UL>
  *   <LI>Arithmetic operators in precedence order:
  *   <UL>
  *     <LI><CODE>+</CODE>, <CODE>-</CODE> (unary)
  *     <LI><CODE>*</CODE>, <CODE>/</CODE> (multiplication and division)
  *     <LI><CODE>+</CODE>, <CODE>-</CODE> (addition and subtraction)
  *     <LI>Arithmetic operations must use numeric promotion in the Java 
  *         programming language.
  *   </UL>
  *   <LI><CODE><I>arithmetic-expr1</I> [NOT] BETWEEN <I>arithmetic-expr2</I> 
  *       AND <I>arithmetic-expr3</I></CODE> (comparison operator)
  *   <UL>
  *     <LI><CODE>"age&nbsp;BETWEEN&nbsp;15&nbsp;AND&nbsp;19"</CODE> is 
  *         equivalent to 
  *         <CODE>"age&nbsp;>=&nbsp;15&nbsp;AND&nbsp;age&nbsp;<=&nbsp;19"</CODE>
  *     <LI><CODE>"age&nbsp;NOT&nbsp;BETWEEN&nbsp;15&nbsp;AND&nbsp;19"</CODE> 
  *         is equivalent to 
  *         <CODE>"age&nbsp;<&nbsp;15&nbsp;OR&nbsp;age&nbsp;>&nbsp;19"</CODE>
  *   </UL>
  *   <LI><CODE><I>identifier</I> [NOT] IN (<I>string-literal1</I>, 
  *       <I>string-literal2</I>,...)</CODE> (comparison operator where 
  *       <CODE><I>identifier</I></CODE> has a <CODE>String</CODE> or 
  *       <CODE>NULL</CODE> value)
  *   <UL>
  *     <LI><CODE>"Country&nbsp;IN&nbsp;('&nbsp;UK',&nbsp;'US',&nbsp;'France')"</CODE>
  *         is true for 
  *         <CODE>'UK'</CODE> and false for <CODE>'Peru'</CODE>; it is 
  *         equivalent to the expression 
  *         <CODE>"(Country&nbsp;=&nbsp;'&nbsp;UK')&nbsp;OR&nbsp;(Country&nbsp;=&nbsp;'&nbsp;US')&nbsp;OR&nbsp;(Country&nbsp;=&nbsp;'&nbsp;France')"</CODE>
  *     <LI><CODE>"Country&nbsp;NOT&nbsp;IN&nbsp;('&nbsp;UK',&nbsp;'US',&nbsp;'France')"</CODE> 
  *         is false for <CODE>'UK'</CODE> and true for <CODE>'Peru'</CODE>; it 
  *         is equivalent to the expression 
  *         <CODE>"NOT&nbsp;((Country&nbsp;=&nbsp;'&nbsp;UK')&nbsp;OR&nbsp;(Country&nbsp;=&nbsp;'&nbsp;US')&nbsp;OR&nbsp;(Country&nbsp;=&nbsp;'&nbsp;France'))"</CODE>
  *     <LI>If identifier of an <CODE>IN</CODE> or <CODE>NOT IN</CODE> 
  *         operation is <CODE>NULL</CODE>, the value of the operation is 
  *         unknown.
  *   </UL>
  *   <LI><CODE><I>identifier</I> [NOT] LIKE <I>pattern-value</I> [ESCAPE 
  *       <I>escape-character</I>]</CODE> (comparison operator, where 
  *       <CODE><I>identifier</I></CODE> has a <CODE>String</CODE> value; 
  *       <CODE><I>pattern-value</I></CODE> is a string literal where 
  *       <CODE>'_'</CODE> stands for any single character; <CODE>'%'</CODE> 
  *       stands for any sequence of characters, including the empty sequence; 
  *       and all other characters stand for themselves. The optional 
  *       <CODE><I>escape-character</I></CODE> is a single-character string 
  *       literal whose character is used to escape the special meaning of the 
  *       <CODE>'_'</CODE> and <CODE>'%'</CODE> in 
  *       <CODE><I>pattern-value</I></CODE>.)
  *   <UL>
  *     <LI><CODE>"phone&nbsp;LIKE&nbsp;'12%3'"</CODE> is true for 
  *         <CODE>'123'</CODE> or <CODE>'12993'</CODE> and false for 
  *         <CODE>'1234'</CODE>
  *     <LI><CODE>"word&nbsp;LIKE&nbsp;'l_se'"</CODE> is true for 
  *         <CODE>'lose'</CODE> and false for <CODE>'loose'</CODE>
  *     <LI><CODE>"underscored&nbsp;LIKE&nbsp;'\_%'&nbsp;ESCAPE&nbsp;'\'"</CODE>
  *          is true for <CODE>'_foo'</CODE> and false for <CODE>'bar'</CODE>
  *     <LI><CODE>"phone&nbsp;NOT&nbsp;LIKE&nbsp;'12%3'"</CODE> is false for 
  *         <CODE>'123'</CODE> or <CODE>'12993'</CODE> and true for 
  *         <CODE>'1234'</CODE>
  *     <LI>If <CODE><I>identifier</I></CODE> of a <CODE>LIKE</CODE> or 
  *         <CODE>NOT LIKE</CODE> operation is <CODE>NULL</CODE>, the value 
  *         of the operation is unknown.
  *   </UL>
  *   <LI><CODE><I>identifier</I> IS NULL</CODE> (comparison operator that tests
  *       for a null header field value or a missing property value)
  *   <UL>
  *     <LI><CODE>"prop_name&nbsp;IS&nbsp;NULL"</CODE>
  *   </UL>
  *   <LI><CODE><I>identifier</I> IS NOT NULL</CODE> (comparison operator that
  *       tests for the existence of a non-null header field value or a property
  *       value)
  *   <UL>
  *     <LI><CODE>"prop_name&nbsp;IS&nbsp;NOT&nbsp;NULL"</CODE>
  *   </UL>
  *
  * <P>JMS providers are required to verify the syntactic correctness of a 
  *    message selector at the time it is presented. A method that provides a 
  *  syntactically incorrect selector must result in a <CODE>JMSException</CODE>.
  * JMS providers may also optionally provide some semantic checking at the time
  * the selector is presented. Not all semantic checking can be performed at
  * the time a message selector is presented, because property types are not known.
  * 
  * <P>The following message selector selects messages with a message type 
  * of car and color of blue and weight greater than 2500 pounds:
  *
  * <PRE>"JMSType&nbsp;=&nbsp;'car'&nbsp;AND&nbsp;color&nbsp;=&nbsp;'blue'&nbsp;AND&nbsp;weight&nbsp;>&nbsp;2500"</PRE>
  *
  * <H4>Null Values</H4>
  *
  * <P>As noted above, property values may be <CODE>NULL</CODE>. The evaluation 
  * of selector expressions containing <CODE>NULL</CODE> values is defined by 
  * SQL92 <CODE>NULL</CODE> semantics. A brief description of these semantics 
  * is provided here.
  *
  * <P>SQL treats a <CODE>NULL</CODE> value as unknown. Comparison or arithmetic
  * with an unknown value always yields an unknown value.
  *
  * <P>The <CODE>IS NULL</CODE> and <CODE>IS NOT NULL</CODE> operators convert 
  * an unknown value into the respective <CODE>TRUE</CODE> and 
  * <CODE>FALSE</CODE> values.
  *
  * <P>The boolean operators use three-valued logic as defined by the 
  * following tables:
  *
  * <P><B>The definition of the <CODE>AND</CODE> operator</B>
  *
  * <PRE>
  * | AND  |   T   |   F   |   U
  * +------+-------+-------+-------
  * |  T   |   T   |   F   |   U
  * |  F   |   F   |   F   |   F
  * |  U   |   U   |   F   |   U
  * +------+-------+-------+-------
  * </PRE>
  *
  * <P><B>The definition of the <CODE>OR</CODE> operator</B>
  *
  * <PRE>
  * | OR   |   T   |   F   |   U
  * +------+-------+-------+--------
  * |  T   |   T   |   T   |   T
  * |  F   |   T   |   F   |   U
  * |  U   |   T   |   U   |   U
  * +------+-------+-------+------- 
  * </PRE> 
  *
  * <P><B>The definition of the <CODE>NOT</CODE> operator</B>
  *
  * <PRE>
  * | NOT
  * +------+------
  * |  T   |   F
  * |  F   |   T
  * |  U   |   U
  * +------+-------
  * </PRE>
  *
  * <H4>Special Notes</H4>
  *
  * <P>When used in a message selector, the <CODE>JMSDeliveryMode</CODE> header 
  *    field is treated as having the values <CODE>'PERSISTENT'</CODE> and 
  *    <CODE>'NON_PERSISTENT'</CODE>.
  *
  * <P>Date and time values should use the standard <CODE>long</CODE> 
  *    millisecond value. When a date or time literal is included in a message 
  *    selector, it should be an integer literal for a millisecond value. The 
  *    standard way to produce millisecond values is to use 
  *    <CODE>java.util.Calendar</CODE>.
  *
  * <P>Although SQL supports fixed decimal comparison and arithmetic, JMS 
  *    message selectors do not. This is the reason for restricting exact 
  *    numeric literals to those without a decimal (and the addition of 
  *    numerics with a decimal as an alternate representation for 
  *    approximate numeric values).
  *
  * <P>SQL comments are not supported.
  *
  * @version     1.1 April 2, 2002
  * @author      Mark Hapner
  * @author      Rich Burridge
  * @author      Kate Stout
  *
  * @see         javax.jms.MessageConsumer#receive()
  * @see         javax.jms.MessageConsumer#receive(long)
  * @see         javax.jms.MessageConsumer#receiveNoWait()
  * @see         javax.jms.MessageListener#onMessage(Message)
  * @see         javax.jms.BytesMessage
  * @see         javax.jms.MapMessage
  * @see         javax.jms.ObjectMessage
  * @see         javax.jms.StreamMessage
  * @see         javax.jms.TextMessage
  */

public interface Message {

    /** The message producer's default delivery mode is <CODE>PERSISTENT</CODE>.
     *
     *  @see DeliveryMode#PERSISTENT
     */
    static final int DEFAULT_DELIVERY_MODE = DeliveryMode.PERSISTENT;

    /** The message producer's default priority is 4. 
     */
    static final int DEFAULT_PRIORITY = 4;

    /** The message producer's default time to live is unlimited; the message 
     *  never expires. 
     */
    static final long DEFAULT_TIME_TO_LIVE = 0;


    /** Gets the message ID.
      *
      * <P>The <CODE>JMSMessageID</CODE> header field contains a value that 
      * uniquely identifies each message sent by a provider.
      *  
      * <P>When a message is sent, <CODE>JMSMessageID</CODE> can be ignored. 
      * When the <CODE>send</CODE> or <CODE>publish</CODE> method returns, it 
      * contains a provider-assigned value.
      *
      * <P>A <CODE>JMSMessageID</CODE> is a <CODE>String</CODE> value that 
      * should function as a 
      * unique key for identifying messages in a historical repository. 
      * The exact scope of uniqueness is provider-defined. It should at 
      * least cover all messages for a specific installation of a 
      * provider, where an installation is some connected set of message 
      * routers.
      *
      * <P>All <CODE>JMSMessageID</CODE> values must start with the prefix 
      * <CODE>'ID:'</CODE>. 
      * Uniqueness of message ID values across different providers is 
      * not required.
      *
      * <P>Since message IDs take some effort to create and increase a
      * message's size, some JMS providers may be able to optimize message
      * overhead if they are given a hint that the message ID is not used by
      * an application. By calling the 
      * <CODE>MessageProducer.setDisableMessageID</CODE> method, a JMS client 
      * enables this potential optimization for all messages sent by that 
      * message producer. If the JMS provider accepts this
      * hint, these messages must have the message ID set to null; if the 
      * provider ignores the hint, the message ID must be set to its normal 
      * unique value.
      *
      * @return the message ID
      *
      * @exception JMSException if the JMS provider fails to get the message ID 
      *                         due to some internal error.
      * @see javax.jms.Message#setJMSMessageID(String)
      * @see javax.jms.MessageProducer#setDisableMessageID(boolean)
      */ 
 
    String
    getJMSMessageID() throws JMSException;


    /** Sets the message ID.
      *  
      * <P>JMS providers set this field when a message is sent. This method