/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef _CMS_MESSAGE_H_
#define _CMS_MESSAGE_H_

#include <cms/Config.h>
#include <cms/Destination.h>
#include <cms/CMSException.h>
#include <cms/DeliveryMode.h>

namespace cms{
   
    /**
     * Root of all messages.  As in JMS, a message is comprised of
     * 3 parts: CMS-specific headers, user-defined properties, and
     * the body.
     * 
     * @see JMS API
     */
    class CMS_API Message
    {         
    public:
   
        virtual ~Message(){}
      
        /**
         * Clone this message exactly, returns a new instance that the
         * caller is required to delete.
         * 
         * @return new copy of this message
         */
        virtual Message* clone() const = 0;                
        
        /**
         * Acknowledges all consumed messages of the session of this consumed 
         * message.
         * 
         * All consumed CMS messages support the acknowledge method for use 
         * when a client has specified that its CMS session's consumed messages 
         * are to be explicitly acknowledged. By invoking acknowledge on a 
         * consumed message, a client acknowledges all messages consumed by the 
         * session that the message was delivered to.
         * 
         * Calls to acknowledge are ignored for both transacted sessions and 
         * sessions specified to use implicit acknowledgement modes.
         * 
         * A client may individually acknowledge each message as it is consumed, 
         * or it may choose to acknowledge messages as an application-defined 
         * group (which is done by calling acknowledge on the last received 
         * message of the group, thereby acknowledging all messages consumed by 
         * the session.)
         * 
         * Messages that have been received but not acknowledged may be 
         * redelivered.
         */
        virtual void acknowledge() const throw( CMSException ) = 0;
      
        /**
         * Clears out the body of the message.  This does not clear the
         * headers or properties.
         */
        virtual void clearBody() = 0;
        
        /**
         * Clears out the message body. Clearing a message's body does not clear 
         * its header values or property entries.
         * 
         * If this message body was read-only, calling this method leaves the 
         * message body in the same state as an empty body in a newly created 
         * message.
         */
        virtual void clearProperties() = 0;
        
        /**
         * Retrieves the propery names.
         * 
         * @return The complete set of property names currently in this
         * message.
         */
        virtual std::vector<std::string> getPropertyNames() const = 0;
        
        /**
         * Indicates whether or not a given property exists.
         * 
         * @param name 
         *      The name of the property to look up.
         * @return True if the property exists in this message.
         */
        virtual bool propertyExists( const std::string& name ) const = 0;
        
        /**
         * Gets a boolean property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @return The value for the named property.
         * @throws CMSException if the property does not exist.
         */
        virtual bool getBooleanProperty( const std::string& name ) const 
            throw( CMSException ) = 0;
            
        /**
         * Gets a byte property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @return The value for the named property.
         * @throws CMSException if the property does not exist.
         */
        virtual unsigned char getByteProperty( const std::string& name ) const 
            throw( CMSException ) = 0;
            
        /**
         * Gets a double property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @return The value for the named property.
         * @throws CMSException if the property does not exist.
         */
        virtual double getDoubleProperty( const std::string& name ) const 
            throw( CMSException ) = 0;
            
        /**
         * Gets a float property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @return The value for the named property.
         * @throws CMSException if the property does not exist.
         */
        virtual float getFloatProperty( const std::string& name ) const 
            throw( CMSException ) = 0;
            
        /**
         * Gets a int property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @return The value for the named property.
         * @throws CMSException if the property does not exist.
         */
        virtual int getIntProperty( const std::string& name ) const 
            throw( CMSException ) = 0;
            
        /**
         * Gets a long property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @return The value for the named property.
         * @throws CMSException if the property does not exist.
         */
        virtual long long getLongProperty( const std::string& name ) const 
            throw( CMSException ) = 0;
            
        /**
         * Gets a short property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @return The value for the named property.
         * @throws CMSException if the property does not exist.
         */
        virtual short getShortProperty( const std::string& name ) const 
            throw( CMSException ) = 0;
            
        /**
         * Gets a string property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @return The value for the named property.
         * @throws CMSException if the property does not exist.
         */
        virtual std::string getStringProperty( const std::string& name ) const 
            throw( CMSException ) = 0;
        
        /**
         * Sets a boolean property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @param value 
         *      The value for the named property.
         * @throws CMSException
         */
        virtual void setBooleanProperty( const std::string& name,
            bool value ) throw( CMSException ) = 0;
            
        /**
         * Sets a byte property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @param value 
         *      The value for the named property.
         * @throws CMSException
         */
        virtual void setByteProperty( const std::string& name,
            unsigned char value ) throw( CMSException ) = 0;
            
        /**
         * Sets a double property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @param value 
         *      The value for the named property.
         * @throws CMSException
         */
        virtual void setDoubleProperty( const std::string& name,
            double value ) throw( CMSException ) = 0;
            
        /**
         * Sets a float property.
         * @param name 
         *      The name of the property to retrieve.
         * @param value 
         *      The value for the named property.
         * @throws CMSException
         */
        virtual void setFloatProperty( const std::string& name,
            float value ) throw( CMSException ) = 0;
            
        /**
         * Sets a int property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @param value 
         *      The value for the named property.
         * @throws CMSException
         */
        virtual void setIntProperty( const std::string& name,
            int value ) throw( CMSException ) = 0;
            
        /**
         * Sets a long property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @param value 
         *      The value for the named property.
         * @throws CMSException
         */
        virtual void setLongProperty( const std::string& name,
            long long value ) throw( CMSException ) = 0;
            
        /**
         * Sets a short property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @param value 
         *      The value for the named property.
         * @throws CMSException
         */
        virtual void setShortProperty( const std::string& name,
            short value ) throw( CMSException ) = 0;
            
        /**
         * Sets a string property.
         * 
         * @param name 
         *      The name of the property to retrieve.
         * @param value 
         *      The value for the named property.
         * @throws CMSException
         */
        virtual void setStringProperty( const std::string& name,
            const std::string& value ) throw( CMSException ) = 0;
      
        /**
         * Gets the correlation ID for the message.
         * 
         * This method is used to return correlation ID values that are either 
         * provider-specific message IDs or application-specific String values.
         * 
         * @return string representation of the correlation Id
         */
        virtual std::string getCMSCorrelationID() const = 0;

        /**
         * Sets the correlation ID for the message.
         * 
         * A client can use the CMSCorrelationID header field to link one 
         * message with another. A typical use is to link a response message 
         * with its request message.
         * 
         * CMSCorrelationID can hold one of the following:
         * 
         *  - A provider-specific message ID
         *  - An application-specific String
         *  - A provider-native byte[] value 
         * 
         * Since each message sent by a CMS provider is assigned a message ID 
         * value, it is convenient to link messages via message ID. All message 
         * ID values must start with the 'ID:' prefix.
         * 
         * 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 CMSCorrelationID to hold a value referencing 
         * some external information. Application-specified values must not 
         * start with the 'ID:' prefix; this is reserved for provider-generated 
         * message ID values.
         * 
         * If a provider supports the native concept of correlation ID, a CMS 
         * client may need to assign specific CMSCorrelationID values to match 
         * those expected by clients that do not use the CMS API. A byte[] value 
         * is used for this purpose. CMS providers without native correlation ID 
         * values are not required to support byte[] values. The use of a byte[] 
         * value for CMSCorrelationID is non-portable.
         * 
         * @param correlationId
         *      The message ID of a message being referred to.
         */
        virtual void setCMSCorrelationID( const std::string& correlationId ) = 0;

        /**
         * Gets the DeliveryMode for this message
         * 
         * @return DeliveryMode enumerated value.
         */
        virtual int getCMSDeliveryMode() const = 0;

        /**
         * Sets the DeliveryMode for this message
         * 
         * CMS 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 mode
         *      DeliveryMode enumerated value.
         */
        virtual void setCMSDeliveryMode( int mode ) = 0;
      
        /**
         * Gets the Destination object for this message.
         * 
         * The CMSDestination header field contains the destination to which the 
         * message is being sent.
         * 
         * When a message is sent, this field is ignored. After completion of 
         * the send or publish method, the field holds the destination specified 
         * by the method.
         * 
         * When a message is received, its CMSDestination value must be 
         * equivalent to the value assigned when it was sent.
         * 
         * @return Destination object
         */
        virtual const Destination* getCMSDestination() const = 0;
      
        /**
         * Sets the Destination object for this message.
         * 
         * CMS 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
         *      Destination Object
         */
        virtual void setCMSDestination( const Destination* destination ) = 0;
      
        /**
         * Gets the message's expiration value.
         * 
         * When a message is sent, the CMSExpiration header field is left 
         * unassigned. After completion of the send or publish method, it holds 
         * the expiration time of the message. This is the sum of the 
         * time-to-live value specified by the client and the GMT at the time 
         * of the send or publish.
         * 
         * If the time-to-live is specified as zero, CMSExpiration is set to 
         * zero to indicate that the message does not expire.
         * 
         * When a message's expiration time is reached, a provider should 
         * discard it. The CMS API does not define any form of notification of 
         * message expiration.
         * 
         * Clients should not receive messages that have expired; however, the 
         * CMS API does not guarantee that this will not happen.
         * 
         * @return the time the message expires, which is the sum of the 
         * time-to-live value specified by the client and the GMT at the time 
         * of the send
         */
        virtual long long getCMSExpiration() const = 0;
      
        /**
         * Sets the message's expiration value.
         * 
         * CMS 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 expireTime 
         *      the message's expiration time
         */
        virtual void setCMSExpiration( long long expireTime ) = 0;
      
        /**
         * The CMSMessageID header field contains a value that uniquely 
         * identifies each message sent by a provider. 
         * 
         * When a message is sent, CMSMessageID can be ignored. When the 
         * send or publish method returns, it contains a provider-assigned 
         * value.
         * 
         * A CMSMessageID is a String 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.
         * 
         * All CMSMessageID values must start with the prefix 'ID:'. Uniqueness 
         * of message ID values across different providers is not required.
         * 
         * Since message IDs take some effort to create and increase a 
         * message's size, some CMS 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 MessageProducer.setDisableMessageID 
         * method, a CMS client enables this potential optimization for all 
         * messages sent by that message producer. If the CMS 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 provider-assigned message id
         */
        virtual std::string getCMSMessageID() const = 0;
        
        /**
         * Sets the message ID.
         * 
         * CMS providers set this field when a message is sent. This method can 
         * be used to change the vaue for a message that has been received.
         * 
         * @param id
         *      the ID of the message
         */
        virtual void setCMSMessageID( const std::string& id ) = 0;
      
        /**
         * Gets the message priority level.
         * 
         * The CMS API defines ten levels of priority value, with 0 as the 
         * lowest priority and 9 as the highest. In addition, clients should 
         * consider priorities 0-4 as gradations of normal priority and 
         * priorities 5-9 as gradations of expedited priority.
         * 
         * The CMS API does not require that a provider strictly implement 
         * priority ordering of messages; however, it should do its best to 
         * deliver expedited messages ahead of normal messages.
         * 
         * @return priority value
         */
        virtual int getCMSPriority() const = 0;
      
        /**
         * Sets the Priority Value for this message
         * 
         * CMS 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 priority
         *      priority value for this message
         */
        virtual void setCMSPriority( int priority ) = 0;

        /**
         * Gets an indication of whether this message is being redelivered.
         * 
         * If a client receives a message with the CMSRedelivered field set, it 
         * is likely, but not guaranteed, that this message was delivered 
         * earlier but that its receipt was not acknowledged at that time.
         * 
         * @return true if this message is being redelivered
         */
        virtual bool getCMSRedelivered() const = 0;
      
        /**
         * Specifies whether this message is being redelivered.
         * 
         * This field is set at the time the message is delivered. This method 
         * can be used to change the value for a message that has been received.
         * 
         * @param redelivered
         *      boolean redelivered value
         */
        virtual void setCMSRedelivered( bool redelivered ) = 0;

        /**
         * Gets the Destination object to which a reply to this message should 
         * be sent.
         * 
         * @return Destination to which to send a response to this message
         */
        virtual const cms::Destination* getCMSReplyTo() const = 0;
      
        /**
         * Sets the Destination object to which a reply to this message should 
         * be sent.
         * 
         * The CMSReplyTo 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 Queue object or a Topic 
         * object.
         * 
         * Messages sent with a null CMSReplyTo value may be a notification of 
         * some event, or they may just be some data the sender thinks is of 
         * interest.
         * 
         * Messages with a CMSReplyTo 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.
         * 
         * 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 
         * CMSCorrelationID header field for this purpose.
         * 
         * @param destination
         *      Destination to which to send a response to this message
         */
        virtual void setCMSReplyTo( const cms::Destination* destination ) = 0;

        /**
         * Gets the message timestamp.
         * 
         * The CMSTimestamp 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.
         * 
         * When a message is sent, CMSTimestamp is ignored. When the send or 
         * publish 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.
         * 
         * Since timestamps take some effort to create and increase a message's 
         * size, some CMS 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 MessageProducer.setDisableMessageTimestamp 
         * method, a CMS client enables this potential optimization for all 
         * messages sent by that message producer. If the CMS 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
         */
        virtual long long getCMSTimestamp() const = 0;
      
        /**
         * Sets the message timestamp.
         * 
         * CMS 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
         *      integer time stamp value
         */
        virtual void setCMSTimestamp( long long timeStamp ) = 0;

        /**
         * Gets the message type identifier supplied by the client when the 
         * message was sent.
         * 
         * @return the message type
         * @see setCMSType
         */
        virtual std::string getCMSType() const = 0;
      
        /**
         * Sets the message type.
         * 
         * Some CMS providers use a message repository that contains the 
         * definitions of messages sent by applications. The CMSType header 
         * field may reference a message's definition in the provider's 
         * repository.
         * 
         * The CMS API does not define a standard message definition repository, 
         * nor does it define a naming policy for the definitions it contains.
         * 
         * Some messaging systems require that a message type definition for 
         * each application message be created and that each message specify its 
         * type. In order to work with such CMS providers, CMS clients should 
         * assign a value to CMSType, whether the application makes use of it or 
         * not. This ensures that the field is properly set for those providers 
         * that require it.
         * 
         * To ensure portability, CMS clients should use symbolic values for 
         * CMSType that can be configured at installation time to the values 
         * defined in the current provider's message repository. If string 
         * literals are used, they may not be valid type names for some CMS 
         * providers.
         * 
         * @param type 
         *      the message type
         * @see getCMSType
         */
        virtual void setCMSType( const std::string& type ) = 0;
        
    };
}

#endif /*_CMS_MESSAGE_H_*/