message.java

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

/*
 * @(#)Message.java	1.60 02/04/09
 *
 * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
 *
 *  SUN PROPRIETARY/CONFIDENTIAL.
 * This software is the proprietary information of Sun Microsystems, Inc.  
 * Use is subject to license terms.
 * 
 */


package javax.jms;

import java.util.Enumeration;
import java.util.Properties;

/** The <CODE>Message</CODE> interface is the root interface of all JMS 
  * messages. It defines the message header and the <CODE>acknowledge</CODE> 
  * method used for all messages.
  *
  * <P>Most message-oriented middleware (MOM) products treat messages as 
  * lightweight entities that consist
  * of a header and a payload. The header contains fields used for message
  * routing and identification; the payload contains the application data
  * being sent.
  *
  * <P>Within this general form, the definition of a message varies
  * significantly across products. It would be quite difficult for the JMS API
  * to support all of these message models.
  *
  * <P>With this in mind, the JMS message model has the following goals:
  * <UL>
  *   <LI>Provide a single, unified message API
  *   <LI>Provide an API suitable for creating messages that match the
  *       format used by provider-native messaging applications
  *   <LI>Support the development of heterogeneous applications that span
  *       operating systems, machine architectures, and computer languages
  *   <LI>Support messages containing objects in the Java programming language
  *       ("Java objects")
  *   <LI>Support messages containing Extensible Markup Language (XML) pages
  * </UL>
  *
  * <P>JMS messages are composed of the following parts:
  * <UL>
  *   <LI>Header - All messages support the same set of header fields. 
  *       Header fields contain values used by both clients and providers to 
  *       identify and route messages.
  *   <LI>Properties - Each message contains a built-in facility for supporting
  *       application-defined property values. Properties provide an efficient 
  *       mechanism for supporting application-defined message filtering.
  *   <LI>Body - The JMS API defines several types of message body, which cover
  *       the majority of messaging styles currently in use.
  * </UL>
  *
  * <H4>Message Bodies</H4>
  *
  * <P>The JMS API defines five types of message body:
  * <UL>
  *   <LI>Stream - A <CODE>StreamMessage</CODE> object's message body contains 
  *       a stream of primitive values in the Java programming 
  *       language ("Java primitives"). It is filled and read sequentially.
  *   <LI>Map - A <CODE>MapMessage</CODE> object's message body contains a set 
  *       of name-value pairs, where names are <CODE>String</CODE> 
  *       objects, and values are Java primitives. The entries can be accessed 
  *       sequentially or randomly by name. The order of the entries is 
  *       undefined.
  *   <LI>Text - A <CODE>TextMessage</CODE> object's message body contains a 
  *       <CODE>java.lang.String</CODE> object. This message type can be used
  *       to transport plain-text messages, and XML messages.
  *   <LI>Object - An <CODE>ObjectMessage</CODE> object's message body contains 
  *       a <CODE>Serializable</CODE> Java object.
  *   <LI>Bytes - A <CODE>BytesMessage</CODE> object's message body contains a 
  *       stream of uninterpreted bytes. This message type is for 
  *       literally encoding a body to match an existing message format. In 
  *       many cases, it is possible to use one of the other body types, 
  *       which are easier to use. Although the JMS API allows the use of  
  *       message properties with byte messages, they are typically not used,
  *       since the inclusion of properties may affect the format.
  * </UL>
  *
  * <H4>Message Headers</H4>
  *
  * <P>The <CODE>JMSCorrelationID</CODE> header field is used for linking one 
  * message with
  * another. It typically links a reply message with its requesting message.
  *
  * <P><CODE>JMSCorrelationID</CODE> can hold a provider-specific message ID,
  * an application-specific <CODE>String</CODE> object, or a provider-native 
  * <CODE>byte[]</CODE> value.
  *
  * <H4>Message Properties</H4>
  *
  * <P>A <CODE>Message</CODE> object contains a built-in facility for supporting
  * application-defined property values. In effect, this provides a mechanism 
  * for adding application-specific header fields to a message.
  *
  * <P>Properties allow an application, via message selectors, to have a JMS 
  * provider select, or filter, messages on its behalf using 
  * application-specific criteria.
  *
  * <P>Property names must obey the rules for a message selector identifier. 
  * Property names must not be null, and must not be empty strings. If a property
  * name is set and it is either null or an empty string, an 
  * <CODE>IllegalArgumentException</CODE> must be thrown.
  *
  * <P>Property values can be <CODE>boolean</CODE>, <CODE>byte</CODE>, 
  * <CODE>short</CODE>, <CODE>int</CODE>, <CODE>long</CODE>, <CODE>float</CODE>,
  * <CODE>double</CODE>, and <CODE>String</CODE>.
  *
  * <P>Property values are set prior to sending a message. When a client 
  * receives a message, its properties are in read-only mode. If a 
  * client attempts to set properties at this point, a 
  * <CODE>MessageNotWriteableException</CODE> is thrown. If 
  * <CODE>clearProperties</CODE> is called, the properties can now be both
  * read from and written to. Note that header fields are distinct from 
  * properties. Header fields are never in read-only mode. 
  *
  * <P>A property value may duplicate a value in a message's body, or it may 
  * not. Although JMS does not define a policy for what should or should not 
  * be made a property, application developers should note that JMS providers 
  * will likely handle data in a message's body more efficiently than data in 
  * a message's properties. For best performance, applications should use
  * message properties only when they need to customize a message's header. 
  * The primary reason for doing this is to support customized message 
  * selection.
  *
  * <P>Message properties support the following conversion table. The marked 
  * cases must be supported. The unmarked cases must throw a 
  * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions 
  * may throw a runtime exception if the
  * primitive's <CODE>valueOf</CODE> method does not accept the 
  * <CODE>String</CODE> as a valid representation of the primitive.
  *
  * <P>A value written as the row type can be read as the column type.
  *
  * <PRE>
  * |        | boolean byte short int long float double String 
  * |----------------------------------------------------------
  * |boolean |    X                                       X
  * |byte    |          X     X    X   X                  X 
  * |short   |                X    X   X                  X 
  * |int     |                     X   X                  X 
  * |long    |                         X                  X 
  * |float   |                               X     X      X 
  * |double  |                                     X      X 
  * |String  |    X     X     X    X   X     X     X      X 
  * |----------------------------------------------------------
  * </PRE>
  *
  * <P>In addition to the type-specific set/get methods for properties, JMS 
  * provides the <CODE>setObjectProperty</CODE> and 
  * <CODE>getObjectProperty</CODE> methods. These support the same set of 
  * property types using the objectified primitive values. Their purpose is 
  * to allow the decision of property type to made at execution time rather 
  * than at compile time. They support the same property value conversions.
  *
  * <P>The <CODE>setObjectProperty</CODE> method accepts values of class 
  * <CODE>Boolean</CODE>, <CODE>Byte</CODE>, <CODE>Short</CODE>, 
  * <CODE>Integer</CODE>, <CODE>Long</CODE>, <CODE>Float</CODE>, 
  * <CODE>Double</CODE>, and <CODE>String</CODE>. An attempt 
  * to use any other class must throw a <CODE>JMSException</CODE>.
  *
  * <P>The <CODE>getObjectProperty</CODE> method only returns values of class 
  * <CODE>Boolean</CODE>, <CODE>Byte</CODE>, <CODE>Short</CODE>, 
  * <CODE>Integer</CODE>, <CODE>Long</CODE>, <CODE>Float</CODE>, 
  * <CODE>Double</CODE>, and <CODE>String</CODE>.
  *
  * <P>The order of property values is not defined. To iterate through a 
  * message's property values, use <CODE>getPropertyNames</CODE> to retrieve 
  * a property name enumeration and then use the various property get methods 
  * to retrieve their values.
  *
  * <P>A message's properties are deleted by the <CODE>clearProperties</CODE>
  * method. This leaves the message with an empty set of properties.
  *
  * <P>Getting a property value for a name which has not been set returns a 
  * null value. Only the <CODE>getStringProperty</CODE> and 
  * <CODE>getObjectProperty</CODE> methods can return a null value. 
  * Attempting to read a null value as a primitive type must be treated as 
  * calling the primitive's corresponding <CODE>valueOf(String)</CODE> 
  * conversion method with a null value.
  *
  * <P>The JMS API reserves the <CODE>JMSX</CODE> property name prefix for JMS 
  * defined properties.
  * The full set of these properties is defined in the Java Message Service
  * specification. New JMS defined properties may be added in later versions 
  * of the JMS API.  Support for these properties is optional. The 
  * <CODE>String[] ConnectionMetaData.getJMSXPropertyNames</CODE> method 
  * returns the names of the JMSX properties supported by a connection.
  *
  * <P>JMSX properties may be referenced in message selectors whether or not
  * they are supported by a connection. If they are not present in a
  * message, they are treated like any other absent property.
  *
  * <P>JMSX properties defined in the specification as "set by provider on 
  * send" are available to both the producer and the consumers of the message. 
  * JMSX properties defined in the specification as "set by provider on 
  * receive" are available only to the consumers.
  *
  * <P><CODE>JMSXGroupID</CODE> and <CODE>JMSXGroupSeq</CODE> are standard 
  * properties that clients 
  * should use if they want to group messages. All providers must support them.
  * Unless specifically noted, the values and semantics of the JMSX properties 
  * are undefined.
  *
  * <P>The JMS API reserves the <CODE>JMS_<I>vendor_name</I></CODE> property 
  * name prefix for provider-specific properties. Each provider defines its own 
  * value for <CODE><I>vendor_name</I></CODE>. This is the mechanism a JMS 
  * provider uses to make its special per-message services available to a JMS 
  * client.
  *
  * <P>The purpose of provider-specific properties is to provide special 
  * features needed to integrate JMS clients with provider-native clients in a 
  * single JMS application. They should not be used for messaging between JMS 
  * clients.
  *
  * <H4>Provider Implementations of JMS Message Interfaces</H4>
  *
  * <P>The JMS API provides a set of message interfaces that define the JMS 
  * message 
  * model. It does not provide implementations of these interfaces.
  *
  * <P>Each JMS provider supplies a set of message factories with its 
  * <CODE>Session</CODE> object for creating instances of messages. This allows 
  * a provider to use message implementations tailored to its specific needs.
  *
  * <P>A provider must be prepared to accept message implementations that are 
  * not its own. They may not be handled as efficiently as its own 
  * implementation; however, they must be handled.
  *
  * <P>Note the following exception case when a provider is handling a foreign 
  * message implementation. If the foreign message implementation contains a 
  * <CODE>JMSReplyTo</CODE> header field that is set to a foreign destination 
  * implementation, the provider is not required to handle or preserve the 
  * value of this header field. 
  *
  * <H4>Message Selectors</H4>
  *
  * <P>A JMS message selector allows a client to specify, by
  * header field references and property references, the
  * messages it is interested in. Only messages whose header 
  * and property values
  * match the 
  * selector are delivered. What it means for a message not to be delivered
  * depends on the <CODE>MessageConsumer</CODE> being used (see 
  * {@link javax.jms.QueueReceiver QueueReceiver} and 
  * {@link javax.jms.TopicSubscriber TopicSubscriber}).
  *
  * <P>Message selectors cannot reference message body values.
  *
  * <P>A message selector matches a message if the selector evaluates to 
  * true when the message's header field values and property values are 
  * substituted for their corresponding identifiers in the selector.
  *
  * <P>A message selector is a <CODE>String</CODE> whose syntax is based on a 
  * subset of 
  * the SQL92 conditional expression syntax. If the value of a message selector 
  * is an empty string, the value is treated as a null and indicates that there 
  * is no message selector for the message consumer. 
  *
  * <P>The order of evaluation of a message selector is from left to right 
  * within precedence level. Parentheses can be used to change this order.
  *
  * <P>Predefined selector literals and operator names are shown here in 
  * uppercase; however, they are case insensitive.
  *
  * <P>A selector can contain:
  *
  * <UL>
  *   <LI>Literals:
  *   <UL>
  *     <LI>A string literal is enclosed in single quotes, with a single quote 
  *         represented by doubled single quote; for example, 
  *         <CODE>'literal'</CODE> and <CODE>'literal''s'</CODE>. Like 
  *         string literals in the Java programming language, these use the 
  *         Unicode character encoding.
  *     <LI>An exact numeric literal is a numeric value without a decimal 
  *         point, such as <CODE>57</CODE>, <CODE>-957</CODE>, and  
  *         <CODE>+62</CODE>; numbers in the range of <CODE>long</CODE> are 
  *         supported. Exact numeric literals use the integer literal 
  *         syntax of the Java programming language.
  *     <LI>An approximate numeric literal is a numeric value in scientific 
  *         notation, such as <CODE>7E3</CODE> and <CODE>-57.9E2</CODE>, or a 
  *         numeric value with a decimal, such as <CODE>7.</CODE>, 
  *         <CODE>-95.7</CODE>, and <CODE>+6.2</CODE>; numbers in the range of 
  *         <CODE>double</CODE> are supported. Approximate literals use the 
  *         floating-point literal syntax of the Java programming language.
  *     <LI>The boolean literals <CODE>TRUE</CODE> and <CODE>FALSE</CODE>.
  *   </UL>
  *   <LI>Identifiers:
  *   <UL>
  *     <LI>An identifier is an unlimited-length sequence of letters 
  *         and digits, the first of which must be a letter. A letter is any 
  *         character for which the method <CODE>Character.isJavaLetter</CODE>
  *         returns true. This includes <CODE>'_'</CODE> and <CODE>'$'</CODE>.
  *         A letter or digit is any character for which the method 
  *         <CODE>Character.isJavaLetterOrDigit</CODE> returns true.
  *     <LI>Identifiers cannot be the names <CODE>NULL</CODE>, 
  *         <CODE>TRUE</CODE>, and <CODE>FALSE</CODE>.