/*
 * 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_MESSAGEPRODUCER_H_
#define _CMS_MESSAGEPRODUCER_H_

#include <cms/Config.h>
#include <cms/AsyncCallback.h>
#include <cms/Message.h>
#include <cms/Destination.h>
#include <cms/Closeable.h>
#include <cms/CMSException.h>
#include <cms/InvalidDestinationException.h>
#include <cms/MessageFormatException.h>
#include <cms/UnsupportedOperationException.h>
#include <cms/DeliveryMode.h>

namespace cms {

    class MessageTransformer;

    /**
     * A client uses a <code>MessageProducer</code> object to send messages to
     * a Destination. A <code>MessageProducer</code> object is created by
     * passing a <code>Destination</code> object to a message-producer creation
     * method supplied by a session.
     *
     * A client also has the option of creating a message producer without
     * supplying a destination. In this case, a Destination must be provided
     * with every send operation. A typical use for this kind of message
     * producer is to send replies to requests using the request's CMSReplyTo
     * destination.
     *
     * A client can specify a default delivery mode, priority, and time to live
     * for messages sent by a message producer. It can also specify the
     * delivery mode, priority, and time to live for an individual message.<br>
     *
     * A client can specify a time-to-live value in milliseconds for each
     * message it sends. This value defines a message expiration time that is
     * the sum of the message's time-to-live and the GMT when it is sent (for
     * transacted sends, this is the time the client sends the message, not the
     * time the transaction is committed).
     *
     * @since 1.0
     */
    class CMS_API MessageProducer : public Closeable {
    public:

        virtual ~MessageProducer();

        /**
         * Sends the message to the default producer destination, but does not take ownership
         * of the message, caller must still destroy it.  Uses default values for deliveryMode,
         * priority, and time to live.
         *
         * @param message
         *      The message to be sent.
         *
         * @throws CMSException - if an internal error occurs while sending the message.
         * @throws MessageFormatException - if an Invalid Message is given.
         * @throws InvalidDestinationException - if a client uses this method with a
         *         MessageProducer with an invalid destination.
         * @throws UnsupportedOperationException - if a client uses this method with a
         *         MessageProducer that did not specify a destination at creation time.
         */
        virtual void send(Message* message) = 0;

        /**
         * Sends the message to the default producer destination, but does not take ownership
         * of the message, caller must still destroy it.  Uses default values for deliveryMode,
         * priority, and time to live.  If the AsyncCallback parameter is set this method will
         * return immediately and the call-back will be notified once the CMS Provider as
         * acknowledge receipt of the Message or an Error occurs.
         *
         * @param message
         *      The message to be sent.
         * @param onComplete
         *      The AsyncCallback instance to notify on send complete or error, caller
         *      retains ownership of this pointer and must destroy it only after the
         *      send completes or the connection is closed.
         *
         * @throws CMSException - if an internal error occurs while sending the message.
         * @throws MessageFormatException - if an Invalid Message is given.
         * @throws InvalidDestinationException - if a client uses this method with a
         *         MessageProducer with an invalid destination.
         * @throws UnsupportedOperationException - if a client uses this method with a
         *         MessageProducer that did not specify a destination at creation time.
         */
        virtual void send(Message* message, AsyncCallback* onComplete) = 0;

        /**
         * Sends the message to the default producer destination, but does
         * not take ownership of the message, caller must still destroy it.
         *
         * @param message
         *      The message to be sent.
         * @param deliveryMode
         *      The delivery mode to be used.
         * @param priority
         *      The priority for this message.
         * @param timeToLive
         *      The time to live value for this message in milliseconds.
         *
         * @throws CMSException - if an internal error occurs while sending the message.
         * @throws MessageFormatException - if an Invalid Message is given.
         * @throws InvalidDestinationException - if a client uses this method with a
         *         MessageProducer with an invalid destination.
         * @throws UnsupportedOperationException - if a client uses this method with a
         *         MessageProducer that did not specify a destination at creation time.
         */
        virtual void send(Message* message, int deliveryMode, int priority, long long timeToLive) = 0;

        /**
         * Sends the message to the default producer destination, but does not take ownership
         * of the message, caller must still destroy it.  If the AsyncCallback parameter is set
         * this method will return immediately and the call-back will be notified once the CMS
         * Provider as acknowledge receipt of the Message or an Error occurs.
         *
         * @param message
         *      The message to be sent.
         * @param deliveryMode
         *      The delivery mode to be used.
         * @param priority
         *      The priority for this message.
         * @param timeToLive
         *      The time to live value for this message in milliseconds.
         * @param onComplete
         *      The AsyncCallback instance to notify on send complete or error, caller
         *      retains ownership of this pointer and must destroy it only after the
         *      send completes or the connection is closed.
         *
         * @throws CMSException - if an internal error occurs while sending the message.
         * @throws MessageFormatException - if an Invalid Message is given.
         * @throws InvalidDestinationException - if a client uses this method with a
         *         MessageProducer with an invalid destination.
         * @throws UnsupportedOperationException - if a client uses this method with a
         *         MessageProducer that did not specify a destination at creation time.
         */
        virtual void send(Message* message, int deliveryMode, int priority,
                          long long timeToLive, AsyncCallback* onComplete) = 0;

        /**
         * Sends the message to the designated destination, but does
         * not take ownership of the message, caller must still destroy it.
         * Uses default values for deliveryMode, priority, and time to live.
         *
         * @param destination
         *      The destination on which to send the message
         * @param message
         *      the message to be sent.
         *
         * @throws CMSException - if an internal error occurs while sending the message.
         * @throws MessageFormatException - if an Invalid Message is given.
         * @throws InvalidDestinationException - if a client uses this method with a
         *         MessageProducer with an invalid destination.
         * @throws UnsupportedOperationException - if a client uses this method with a
         *         MessageProducer that did not specify a destination at creation time.
         */
        virtual void send(const Destination* destination, Message* message) = 0;

        /**
         * Sends the message to the designated destination, but does not take ownership of the
         * message, caller must still destroy it.  Uses default values for deliveryMode, priority,
         * and time to live.  If the AsyncCallback parameter is set this method will return
         * immediately and the call-back will be notified once the CMS Provider as acknowledge
         * receipt of the Message or an Error occurs.
         *
         * @param destination
         *      The destination on which to send the message
         * @param message
         *      the message to be sent.
         * @param onComplete
         *      The AsyncCallback instance to notify on send complete or error, caller
         *      retains ownership of this pointer and must destroy it only after the
         *      send completes or the connection is closed.
         *
         * @throws CMSException - if an internal error occurs while sending the message.
         * @throws MessageFormatException - if an Invalid Message is given.
         * @throws InvalidDestinationException - if a client uses this method with a
         *         MessageProducer with an invalid destination.
         * @throws UnsupportedOperationException - if a client uses this method with a
         *         MessageProducer that did not specify a destination at creation time.
         */
        virtual void send(const Destination* destination, Message* message, AsyncCallback* onComplete) = 0;

        /**
         * Sends the message to the designated destination, but does not take ownership
         * of the message, caller must still destroy it.
         *
         * @param destination
         *      The destination on which to send the message
         * @param message
         *      The message to be sent.
         * @param deliveryMode
         *      The delivery mode to be used.
         * @param priority
         *      The priority for this message.
         * @param timeToLive
         *      The time to live value for this message in milliseconds.
         *
         * @throws CMSException - if an internal error occurs while sending the message.
         * @throws MessageFormatException - if an Invalid Message is given.
         * @throws InvalidDestinationException - if a client uses this method with a
         *         MessageProducer with an invalid destination.
         * @throws UnsupportedOperationException - if a client uses this method with a
         *         MessageProducer that did not specify a destination at creation time.
         */
        virtual void send(const Destination* destination, Message* message,
                          int deliveryMode, int priority, long long timeToLive) = 0;

        /**
         * Sends the message to the designated destination, but does not take ownership
         * of the message, caller must still destroy it.  If the AsyncCallback parameter
         * is set this method will return immediately and the call-back will be notified
         * once the CMS Provider as acknowledge receipt of the Message or an Error occurs.
         *
         * @param destination
         *      The destination on which to send the message
         * @param message
         *      The message to be sent.
         * @param deliveryMode
         *      The delivery mode to be used.
         * @param priority
         *      The priority for this message.
         * @param timeToLive
         *      The time to live value for this message in milliseconds.
         * @param onComplete
         *      The AsyncCallback instance to notify on send complete or error, caller
         *      retains ownership of this pointer and must destroy it only after the
         *      send completes or the connection is closed.
         *
         * @throws CMSException - if an internal error occurs while sending the message.
         * @throws MessageFormatException - if an Invalid Message is given.
         * @throws InvalidDestinationException - if a client uses this method with a
         *         MessageProducer with an invalid destination.
         * @throws UnsupportedOperationException - if a client uses this method with a
         *         MessageProducer that did not specify a destination at creation time.
         */
        virtual void send(const Destination* destination, Message* message, int deliveryMode,
                          int priority, long long timeToLive, AsyncCallback* onComplete) = 0;

        /**
         * Sets the delivery mode for this Producer
         *
         * @param mode
         *      The DeliveryMode
         *
         * @throws CMSException - if an internal error occurs.
         */
        virtual void setDeliveryMode(int mode) = 0;

        /**
         * Gets the delivery mode for this Producer
         *
         * @return The DeliveryMode
         *
         * @throws CMSException - if an internal error occurs.
         */
        virtual int getDeliveryMode() const = 0;

        /**
         * Sets if Message Ids are disabled for this Producer
         *
         * @param value
         *      boolean indicating enable / disable (true / false)
         *
         * @throws CMSException - if an internal error occurs.
         */
        virtual void setDisableMessageID(bool value) = 0;

        /**
         * Gets if Message Ids are disabled for this Producer
         *
         * @return boolean indicating enable / disable (true / false)
         *
         * @throws CMSException - if an internal error occurs.
         */
        virtual bool getDisableMessageID() const = 0;

        /**
         * Sets if Message Time Stamps are disabled for this Producer
         * @param value - boolean indicating enable / disable (true / false)
         *
         * @throws CMSException - if an internal error occurs.
         */
        virtual void setDisableMessageTimeStamp(bool value) = 0;

        /**
         * Gets if Message Time Stamps are disabled for this Producer
         *
         * @return boolean indicating enable / disable (true / false)
         *
         * @throws CMSException - if an internal error occurs.
         */
        virtual bool getDisableMessageTimeStamp() const = 0;

        /**
         * Sets the Priority that this Producers sends messages at
         *
         * @param priority
         *      int value for Priority level
         *
         * @throws CMSException - if an internal error occurs.
         */
        virtual void setPriority(int priority) = 0;

        /**
         * Gets the Priority level that this producer sends messages at
         *
         * @return int based priority level
         *
         * @throws CMSException - if an internal error occurs.
         */
        virtual int getPriority() const = 0;

        /**
         * Sets the Time to Live that this Producers sends messages with.  This
         * value will be used if the time to live is not specified via the
         * send method.
         *
         * @param time
         *      default time to live value in milliseconds
         *
         * @throws CMSException - if an internal error occurs.
         */
        virtual void setTimeToLive(long long time) = 0;

        /**
         * Gets the Time to Live that this producer sends messages with
         *
         * @return Time to live value in milliseconds
         *
         * @throws CMSException - if an internal error occurs.
         */
        virtual long long getTimeToLive() const = 0;

        /**
         * Set an MessageTransformer instance that is applied to all cms::Message objects before they
         * are sent on to the CMS bus.
         *
         * The CMS code never takes ownership of the MessageTransformer pointer which implies that
         * the client code must ensure that the object remains valid for the lifetime of the CMS
         * object to which the MessageTransformer has been assigned.
         *
         * @param transformer
         *      Pointer to the cms::MessageTransformer to apply on each cms:;MessageSend.
         */
        virtual void setMessageTransformer(cms::MessageTransformer* transformer) = 0;

        /**
         * Gets the currently configured MessageTransformer for this MessageProducer.
         *
         * @returns the pointer to the currently set cms::MessageTransformer.
         */
        virtual cms::MessageTransformer* getMessageTransformer() const = 0;

    };

}

#endif /*_CMS_MESSAGEPRODUCER_H_*/