message.java

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

      * can be used to change the value for a message that has been received.
      *
      * @param id the ID of the message
      *
      * @exception JMSException if the JMS provider fails to set the message ID 
      *                         due to some internal error.
      *
      * @see javax.jms.Message#getJMSMessageID()
      */ 

    void
    setJMSMessageID(String id) throws JMSException;


    /** Gets the message timestamp.
      *  
      * <P>The <CODE>JMSTimestamp</CODE> header field contains the time a 
      * message was 
      * handed off to a provider to be sent. It is not the time the 
      * message was actually transmitted, because the actual send may occur 
      * later due to transactions or other client-side queueing of messages.
      *
      * <P>When a message is sent, <CODE>JMSTimestamp</CODE> is ignored. When 
      * the <CODE>send</CODE> or <CODE>publish</CODE>
      * method returns, it contains a time value somewhere in the interval 
      * between the call and the return. The value is in the format of a normal 
      * millis time value in the Java programming language.
      *
      * <P>Since timestamps 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 timestamp is not used by an 
      * application. By calling the
      * <CODE>MessageProducer.setDisableMessageTimestamp</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 timestamp set to zero; if the 
      * provider ignores the hint, the timestamp must be set to its normal 
      * value.
      *
      * @return the message timestamp
      *
      * @exception JMSException if the JMS provider fails to get the timestamp
      *                         due to some internal error.
      *
      * @see javax.jms.Message#setJMSTimestamp(long)
      * @see javax.jms.MessageProducer#setDisableMessageTimestamp(boolean)
      */

    long
    getJMSTimestamp() throws JMSException;


    /** Sets the message timestamp.
      *  
      * <P>JMS providers set this field when a message is sent. This method
      * can be used to change the value for a message that has been received.
      *
      * @param timestamp the timestamp for this message
      *  
      * @exception JMSException if the JMS provider fails to set the timestamp
      *                         due to some internal error.
      *
      * @see javax.jms.Message#getJMSTimestamp()
      */

    void
    setJMSTimestamp(long timestamp) throws JMSException;


    /** Gets the correlation ID as an array of bytes for the message.
      *  
      * <P>The use of a <CODE>byte[]</CODE> value for 
      * <CODE>JMSCorrelationID</CODE> is non-portable.
      *
      * @return the correlation ID of a message as an array of bytes
      *
      * @exception JMSException if the JMS provider fails to get the correlation
      *                         ID due to some internal error.
      *  
      * @see javax.jms.Message#setJMSCorrelationID(String)
      * @see javax.jms.Message#getJMSCorrelationID()
      * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
      */

    byte []
    getJMSCorrelationIDAsBytes() throws JMSException;


    /** Sets the correlation ID as an array of bytes for the message.
      * 
      * <P>The array is copied before the method returns, so
      * future modifications to the array will not alter this message header.
      *  
      * <P>If a provider supports the native concept of correlation ID, a 
      * JMS client may need to assign specific <CODE>JMSCorrelationID</CODE> 
      * values to match those expected by native messaging clients. 
      * JMS providers without native correlation ID values are not required to 
      * support this method and its corresponding get method; their 
      * implementation may throw a
      * <CODE>java.lang.UnsupportedOperationException</CODE>. 
      *
      * <P>The use of a <CODE>byte[]</CODE> value for 
      * <CODE>JMSCorrelationID</CODE> is non-portable.
      *
      * @param correlationID the correlation ID value as an array of bytes
      *  
      * @exception JMSException if the JMS provider fails to set the correlation
      *                         ID due to some internal error.
      *  
      * @see javax.jms.Message#setJMSCorrelationID(String)
      * @see javax.jms.Message#getJMSCorrelationID()
      * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
      */

    void
    setJMSCorrelationIDAsBytes(byte[] correlationID) throws JMSException;


    /** Sets the correlation ID for the message.
      *  
      * <P>A client can use the <CODE>JMSCorrelationID</CODE> header field to 
      * link one message with another. A typical use is to link a response 
      * message with its request message.
      *  
      * <P><CODE>JMSCorrelationID</CODE> can hold one of the following:
      *    <UL>
      *      <LI>A provider-specific message ID
      *      <LI>An application-specific <CODE>String</CODE>
      *      <LI>A provider-native <CODE>byte[]</CODE> value
      *    </UL>
      *  
      * <P>Since each message sent by a JMS provider is assigned a message ID
      * value, it is convenient to link messages via message ID. All message ID
      * values must start with the <CODE>'ID:'</CODE> prefix.
      *  
      * <P>In some cases, an application (made up of several clients) needs to
      * use an application-specific value for linking messages. For instance,
      * an application may use <CODE>JMSCorrelationID</CODE> to hold a value 
      * referencing some external information. Application-specified values 
      * must not start with the <CODE>'ID:'</CODE> prefix; this is reserved for 
      * provider-generated message ID values.
      *  
      * <P>If a provider supports the native concept of correlation ID, a JMS
      * client may need to assign specific <CODE>JMSCorrelationID</CODE> values 
      * to match those expected by clients that do not use the JMS API. A 
      * <CODE>byte[]</CODE> value is used for this
      * purpose. JMS providers without native correlation ID values are not
      * required to support <CODE>byte[]</CODE> values. The use of a 
      * <CODE>byte[]</CODE> value for <CODE>JMSCorrelationID</CODE> is 
      * non-portable.
      *  
      * @param correlationID the message ID of a message being referred to
      *  
      * @exception JMSException if the JMS provider fails to set the correlation
      *                         ID due to some internal error.
      *  
      * @see javax.jms.Message#getJMSCorrelationID()
      * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
      * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
      */ 

    void
    setJMSCorrelationID(String correlationID) throws JMSException;


    /** Gets the correlation ID for the message.
      *  
      * <P>This method is used to return correlation ID values that are 
      * either provider-specific message IDs or application-specific 
      * <CODE>String</CODE> values.
      *
      * @return the correlation ID of a message as a <CODE>String</CODE>
      *
      * @exception JMSException if the JMS provider fails to get the correlation
      *                         ID due to some internal error.
      *
      * @see javax.jms.Message#setJMSCorrelationID(String)
      * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
      * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
      */ 
 
    String
    getJMSCorrelationID() throws JMSException;


    /** Gets the <CODE>Destination</CODE> object to which a reply to this 
      * message should be sent.
      *  
      * @return <CODE>Destination</CODE> to which to send a response to this 
      *         message
      *
      * @exception JMSException if the JMS provider fails to get the  
      *                         <CODE>JMSReplyTo</CODE> destination due to some 
      *                         internal error.
      *
      * @see javax.jms.Message#setJMSReplyTo(Destination)
      */ 
 
    Destination
    getJMSReplyTo() throws JMSException;


    /** Sets the <CODE>Destination</CODE> object to which a reply to this 
      * message should be sent.
      *  
      * <P>The <CODE>JMSReplyTo</CODE> header field contains the destination 
      * where a reply 
      * to the current message should be sent. If it is null, no reply is 
      * expected. The destination may be either a <CODE>Queue</CODE> object or
      * a <CODE>Topic</CODE> object.
      *
      * <P>Messages sent with a null <CODE>JMSReplyTo</CODE> value may be a 
      * notification of some event, or they may just be some data the sender 
      * thinks is of interest.
      *
      * <P>Messages with a <CODE>JMSReplyTo</CODE> value typically expect a 
      * response. A response is optional; it is up to the client to decide.  
      * These messages are called requests. A message sent in response to a 
      * request is called a reply.
      *
      * <P>In some cases a client may wish to match a request it sent earlier 
      * with a reply it has just received. The client can use the 
      * <CODE>JMSCorrelationID</CODE> header field for this purpose.
      *
      * @param replyTo <CODE>Destination</CODE> to which to send a response to 
      *                this message
      *
      * @exception JMSException if the JMS provider fails to set the  
      *                         <CODE>JMSReplyTo</CODE> destination due to some 
      *                         internal error.
      *
      * @see javax.jms.Message#getJMSReplyTo()
      */ 

    void
    setJMSReplyTo(Destination replyTo) throws JMSException;


    /** Gets the <CODE>Destination</CODE> object for this message.
      *  
      * <P>The <CODE>JMSDestination</CODE> header field contains the 
      * destination to which the message is being sent.
      *  
      * <P>When a message is sent, this field is ignored. After completion
      * of the <CODE>send</CODE> or <CODE>publish</CODE> method, the field 
      * holds the destination specified by the method.
      *  
      * <P>When a message is received, its <CODE>JMSDestination</CODE> value 
      * must be equivalent to the value assigned when it was sent.
      *
      * @return the destination of this message
      *  
      * @exception JMSException if the JMS provider fails to get the destination
      *                         due to some internal error.
      *  
      * @see javax.jms.Message#setJMSDestination(Destination)
      */ 

    Destination
    getJMSDestination() throws JMSException;


    /** Sets the <CODE>Destination</CODE> object for this message.
      *  
      * <P>JMS providers set this field when a message is sent. This method 
      * can be used to change the value for a message that has been received.
      *
      * @param destination the destination for this message
      *  
      * @exception JMSException if the JMS provider fails to set the destination
      *                         due to some internal error.
      *  
      * @see javax.jms.Message#getJMSDestination()
      */ 

    void
    setJMSDestination(Destination destination) throws JMSException;


    /** Gets the <CODE>DeliveryMode</CODE> value specified for this message.
      *  
      * @return the delivery mode for this message
      *  
      * @exception JMSException if the JMS provider fails to get the 
      *                         delivery mode due to some internal error.
      *  
      * @see javax.jms.Message#setJMSDeliveryMode(int)
      * @see javax.jms.DeliveryMode
      */ 
 
    int
    getJMSDeliveryMode() throws JMSException;
 
 
    /** Sets the <CODE>DeliveryMode</CODE> value for this message.
      *  
      * <P>JMS providers set this field when a message is sent. This method 
      * can be used to change the value for a message that has been received.
      *
      * @param deliveryMode the delivery mode for this message