//
// Notification Service IDL Description
//

#ifndef _COS_NOTIFICATION_IDL_
#define _COS_NOTIFICATION_IDL_

/**
 * The CoSNotification module defines the Structured Event data type, along with a data
 * type used for transmitting sequences of Structured Events. In addition, this module
 * provides constant declarations for each of the standard quality of service (QoS) and
 * administrative properties supported by all Notification Service implementations. Some
 * properties also have associated constant declarations which indicate their possible
 * settings. Finally, administrative interfaces are defined for managing sets of QoS and
 * administrative properties.
 */
module CosNotification
{
    typePrefix CosNotification "omg.org";

    typedef string Istring;
    typedef Istring PropertyName;
    typedef any PropertyValue;

    /**
     * This structure represents a property. For the OMG, a property is a name-value pair.
     */
    struct Property
    {
        PropertyName name;
        PropertyValue value;
    };
    typedef sequence<Property> PropertySeq;

    /**
     * The following are the same, but serve different purposes.
     */
    typedef PropertySeq OptionalHeaderFields;
    typedef PropertySeq FilterableEventBody;
    typedef PropertySeq QoSProperties;
    typedef PropertySeq AdminProperties;

    /**
     * This structure is an interval containing a low value and a high value.
     */
    struct PropertyRange
    {
        PropertyValue low_val;
        PropertyValue high_val;
    };

    /**
     * This structure links a PropertyName with a property range erpresenting all
     * possible values for this property.
     */
    struct NamedPropertyRange
    {
        PropertyName name;
        PropertyRange range;
    };
    typedef sequence<NamedPropertyRange> NamedPropertyRangeSeq;


    /**
     * This enumration contains all Error Code of the UnsupportedQoS exception
     * UNSUPPORTED_PROPERTY This property is not supported by this
     * implementation for this type of target object.
     * UNAVAILABLE_PROPERTY This property cannot be set (to any value) in the
     * current context.
     * UNSUPPORTED_VALUE The value requested for this property is not supported
     * by this implementation for this type of target object.
     * A range of values which would be supported is
     * returned.
     * UNAVAILABLE_VALUE The value requested for this property is not supported
     * in the current context. A range of values which
     * would be supported is returned.
     * BAD_PROPERTY This property name is unrecognized. The
     * implementation knows nothing about it.
     * BAD_TYPE The type supplied for the value of this property is
     * incorrect.
     * BAD_VALUE An illegal value is supplied for this property. A range
     * of values which would be supported is returned.
     */
    enum QoSError_code
    {
        UNSUPPORTED_PROPERTY,
        UNAVAILABLE_PROPERTY,
        UNSUPPORTED_VALUE,
        UNAVAILABLE_VALUE,
        BAD_PROPERTY,
        BAD_TYPE,
        BAD_VALUE
    };


    /**
     * This struture symbolizes an error on a Property. It is composed of an ErrorCode, the property
     * name on which the error occurs and the range of available values.
     */
    struct PropertyError
    {
        QoSError_code code;
        PropertyName name;
        PropertyRange available_range;
    };
    typedef sequence<PropertyError> PropertyErrorSeq;


    /**
     * This exception is thrown when a QoS parameter doesn't correspond to a
     * valid QoS property.
     * This exception contains as data a sequence of data structures, each of which
     * identifies the name of a QoS property in the input list whose requested setting could
     * not be satisfied, along with an error code and a range of settings for the property which
     * could be satisfied. The meanings of the error codes which might be returned are
     * described in the QoSError_code enumeration.
     */
    exception UnsupportedQoS { PropertyErrorSeq qos_err; };

    /**
     * This exception is thrown when a Admin parameter doesn't correspond to a
     * valid Admin property.
     * This exception has associated with it a list of
     * name-value pairs of which each name identifies an administrative property whose
     * requested setting could not be satisfied, and each associated value the closest setting
     * for that property which could be satisfied.
     */
    exception UnsupportedAdmin { PropertyErrorSeq admin_err; };

    // Define the Structured Event structure

    /**
     * The event type is composed of two elements: A domiain name and a type name.
     * The domain name identifies the particular vertical industry domain in which the event
     * type is defined (for example telecommunications, finance, health care).
     * The type name which categorizes the type of event uniquely within the domain (for example
     * CommunicationAlarm, StockQuote, VitalSigns).
     * Note that the combination of the domain_type and type_name fields could be used as
     * indexes into the event type repository
     */
    struct EventType
    {
        string domain_name;
        string type_name;
    };
    typedef sequence<EventType> EventTypeSeq;

    /**
     * The fixed portion of the event header is comprised of two elements: An EventType and a name.
     * The event name may uniquely identify the specific instance of event being transmitted.
     *
     * @see EventType
     */
    struct FixedEventHeader
    {
        EventType event_type;
        string event_name;
    };

    /**
     * Each event is comprised of two main components: a header and a body.
     * The header can be further decomposed into a fixed portion and a variable portion.
     * The goal of this decomposition is to minimize the size of the header which is required
     * in every Structured Event message, thus enabling lightweight messages where the overhead
     * of supplying additional header fields is viewed as less desirable than any functional
     * benefit achieved by supplying these fields (e.g., additional header fields may contain
     * QoS requirements for the message).
     *
     * @see FixedEventHeader
     */
    struct EventHeader
    {
        FixedEventHeader fixed_header;
        OptionalHeaderFields variable_header;
    };

    /**
     * A structured event
     */
    struct StructuredEvent
    {
        EventHeader header;
        FilterableEventBody filterable_data;
        any remainder_of_body;
    }; // StructuredEvent
    typedef sequence<StructuredEvent> EventBatch;

    // The following constant declarations define the standard
    // QoS property names and the associated values each property
    // can take on. The name/value pairs for each standard property
    // are grouped, beginning with a string constant defined for the
    // property name, followed by the values the property can take on.

    /**
     * There are a variety of delivery policies known in distributed systems, such as best-effort,
     * at-least-once, at-most-once, and exactly-once. However most of these only
     * make sense in a point-to-point, request-reply communication model. The Notification
     * Service is by definition a point-to-multipoint delivery mechanism with no explicit
     * reply mechanism.
     * The Notification Service treats the reliability of specific events, and the reliability of
     * the connections which provide a transport for events between clients of the notification
     * channel and the channel, as separate issues, and thus defines two separate QoS
     * properties to represent them: EventReliability and ConnectionReliability. Each of these
     * properties can take on one of two possible numeric constant values: BestEffort or
     * Persistent. The meanings associated with the settings of these properties are inter-related,
     * and are thus defined together below.
     * EventReliability=BestEffort & ConnectionReliability=BestEffort: No specific delivery
     * guarantees are made. In the presence of failures, the event may or may not be received
     * by each of the consumers, and a given consumer may receive the same event multiple
     * times.
     * EventReliability=BestEffort & ConnectionReliability=Persistent: The notification
     * channel will maintain all information about its connected clients persistently, implying
     * that connections will not be lost (logically) upon failure of the process within which
     * the notification channel is executing. Any clients which connect to the channel using
     * persistent object references may fail, but unless these object references raise an
     * OBJECT_NOT_EXIST exception, the channel will continue to retry using them.
     * Clients which then re-instantiate objects with these references will (logically)
     * reconnect to their associated proxies. The channel will not, however, store any
     * buffered events persistently. The implication of this combination is that upon restart
     * from a failure of the notification channel server process, the channel will automatically
     * re-establish connections to each of its clients, but will not attempt to retransmit any
     * events that had been buffered at the time the failure occurred.
     * EventReliability=Persistent & ConnectionRelability=BestEffort: This combination has
     * no meaning and need not be supported by a conformant Notification Service
     * implementation.
     * EventReliability=Persisent & ConnectionReliability=Persistent: Each event is
     * guaranteed to be delivered to all consumers registered to receive it at the time the event
     * was delivered to the channel, within expiry limits. If the connection between the
     * channel and a consumer is lost for any reason, the channel will persistently store any
     * events destined for that consumer until either each event times out due to expiry limits,
     * or the consumer once again becomes available and the channel is subsequently able to
     * deliver the events to all registered consumers. In addition, upon restart from a failure
     * the notification channel will automatically re-establish connections to all clients that
     * were connected to it at the time the failure occurred.
     * Note that the QoS properties related to reliability can be set at the channel, group, and
     * proxy levels, but not on an individual event basis. A component at a lower level in the
     * hierarchy may only override either property related to reliability by a value that
     * represents the same or a lower reliability level. For example, it is not possible (or
     * meaningful) to set EventReliability=Persistent at the group admin level, if at the
     * channel level EventReliability has been set to BestEffort.
     */
    const string EventReliability = "EventReliability";
    const short BestEffort = 0;
    const short Persistent = 1;


    /**
     * There are a variety of delivery policies known in distributed systems, such as best-effort,
     * at-least-once, at-most-once, and exactly-once. However most of these only
     * make sense in a point-to-point, request-reply communication model. The Notification
     * Service is by definition a point-to-multipoint delivery mechanism with no explicit
     * reply mechanism.
     * The Notification Service treats the reliability of specific events, and the reliability of
     * the connections which provide a transport for events between clients of the notification
     * channel and the channel, as separate issues, and thus defines two separate QoS
     * properties to represent them: EventReliability and ConnectionReliability. Each of these
     * properties can take on one of two possible numeric constant values: BestEffort or
     * Persistent. The meanings associated with the settings of these properties are inter-related,
     * and are thus defined together below.
     * EventReliability=BestEffort & ConnectionReliability=BestEffort: No specific delivery
     * guarantees are made. In the presence of failures, the event may or may not be received
     * by each of the consumers, and a given consumer may receive the same event multiple
     * times.
     * EventReliability=BestEffort & ConnectionReliability=Persistent: The notification
     * channel will maintain all information about its connected clients persistently, implying
     * that connections will not be lost (logically) upon failure of the process within which
     * the notification channel is executing. Any clients which connect to the channel using
     * persistent object references may fail, but unless these object references raise an
     * OBJECT_NOT_EXIST exception, the channel will continue to retry using them.
     * Clients which then re-instantiate objects with these references will (logically)
     * reconnect to their associated proxies. The channel will not, however, store any
     * buffered events persistently. The implication of this combination is that upon restart
     * from a failure of the notification channel server process, the channel will automatically
     * re-establish connections to each of its clients, but will not attempt to retransmit any
     * events that had been buffered at the time the failure occurred.
     * EventReliability=Persistent & ConnectionRelability=BestEffort: This combination has
     * no meaning and need not be supported by a conformant Notification Service
     * implementation.
     * EventReliability=Persisent & ConnectionReliability=Persistent: Each event is
     * guaranteed to be delivered to all consumers registered to receive it at the time the event
     * was delivered to the channel, within expiry limits. If the connection between the
     * channel and a consumer is lost for any reason, the channel will persistently store any
     * events destined for that consumer until either each event times out due to expiry limits,
     * or the consumer once again becomes available and the channel is subsequently able to
     * deliver the events to all registered consumers. In addition, upon restart from a failure
     * the notification channel will automatically re-establish connections to all clients that
     * were connected to it at the time the failure occurred.
     * Note that the QoS properties related to reliability can be set at the channel, group, and
     * proxy levels, but not on an individual event basis. A component at a lower level in the
     * hierarchy may only override either property related to reliability by a value that
     * represents the same or a lower reliability level. For example, it is not possible (or
     * meaningful) to set EventReliability=Persistent at the group admin level, if at the
     * channel level EventReliability has been set to BestEffort.
     */
    const string ConnectionReliability = "ConnectionReliability";
    // Can take on the same values as EventReliability

    /**
     * The event service does not define the order in which events are delivered to a
     * consumer. One way to be explicit is to allow delivery to be based on the priority of an
     * event. Priority is represented as a short value, where -32,767 is the lowest priority and
     * 32,767 the highest. The default priority for all events is 0. By default, the notification
     * channel will attempt to deliver messages to consumers in priority order.
     * It is possible for a consumer to override the priority assigned to a message through the
     * use of mapping filters.
     */
    const string Priority = "Priority";
    const short LowestPriority = -32767;
    const short HighestPriority = 32767;
    const short DefaultPriority = 0;

    /**
     * It is often desired that an event be held until at least a specified time, and become
     * eligible for delivery only after that time. StartTime, a TimeBase::UtcT encoded value,
     * states an absolute earliest delivery time (e.g., January 1, 2000), after which the event
     * can be delivered.
     * Note that StartTime can only be used in the manner indicated above on a per-message
     * basis, and thus has an associated UtcT value only when supplied as a QoS property
     * within the header of a Structured Event. At other levels where QoS can be set (i.e.,
     * Proxies, Admins, and Channels), a StartTimeSupported QoS property is defined which
     * has an associated boolean value, indicating whether or not the setting of StartTime on
     * a per-message basis is supported.
     */
    const string StartTime = "StartTime";
    // StartTime takes a value of type TimeBase::UtcT.

    /**
     * StopTime, a TimeBase::UtcT encoded value, states an absolute expiry time (e.g.,
     * January 1st, 2001), after which the event can be discarded.
     */
    const string StopTime = "StopTime";
    // StopTime takes a value of type TimeBase::UtcT.

    /**
     * Timeout, a TimeBase::TimeT encoded value, states a relative expiry time (e.g., 10
     * minutes from now), after which the event can be discarded. It is possible for a
     * consumer to override the value associated with this property through the use of
     * mapping filters.
     */
    const string Timeout = "Timeout";
    // Timeout takes on a value of type TimeBase::TimeT

    /**
     * This QoS property sets the policy used by a given proxy to order the events it has
     * buffered for delivery (either to another proxy or a consumer).
     */
    const string OrderPolicy = "OrderPolicy";

    /**
     * Any ordering policy is permitted.
     */
    const short AnyOrder = 0;

    /**
     * Events should be delivered in the order of their arrival.
     */
    const short FifoOrder = 1;

    /**
     * Events should be buffered in priority order, such that higher priority
     * events will be delivered before lower priority events.
     */
    const short PriorityOrder = 2;

    /**
     * Events should be buffered in the order of shortest expiry deadline
     * first, such that events that are destined to timeout soonest should be delivered first.
     */
    const short DeadlineOrder = 3;

    /**
     * This QoS property enables a user of the Notification Service to specify in what order
     * the channel should begin discarding events in the case of an internal buffer overflow. If
     * set only on a per-channel basis, the chosen discard policy will be applied whenever a
     * supplier attempts to send a new event to the channel, and the total number of events
     * already queued within the channel is equal to the MaxQueueLength administrative
     * property (defined in section 2.5.7). If set on a per-ConsumerAdmin basis, the chosen
     * discard policy will be applied whenever the number of events queued on behalf of one
     *  of the consumers connected to one of the proxy suppliers created by the
     * ConsumerAdmin exceeds the MaxEventsPerConsumer setting for that consumer. If set
     * on a per-proxy supplier basis, the chosen discard policy will be applied whenever the
     * number of events queued on behalf of the consumer connected to the proxy supplier
     * exceeds the MaxEventsPerConsumer setting for that proxy supplier. Note that in these
     * latter two cases, an event will only be “discarded” with respect to its scheduled
     * delivery to the consumer(s) on whose behalf the policy is being applied. In other
     * words, if the event targeted for discarding is scheduled for delivery to any consumer(s)
     * on whose behalf the discard policy was not invoked, the event remains queued for
     * those consumers.
     */
    const string DiscardPolicy = "DiscardPolicy";
    // DiscardPolicy takes on the same values as OrderPolicy, plus
  
    /**
     * The last event received will be the first discarded.
     */
    const short LifoOrder = 4;

    /**
     * This QoS property has meaning in the case of consumers that register to receive
     * sequences of Structured Events. For any such consumer, this property indicates the
     * maximum number of events that will be delivered within each sequence. The data type
     * associated with this property is long.
     */
    const string MaximumBatchSize = "MaximumBatchSize";
    // MaximumBatchSize takes on a value of type long

    /**
     * This QoS property also has meaning in the case of consumers that register to receive
     * sequences of Structured Events. For any such consumer, this property defines the
     * maximum period of time the channel will collect individual events into a sequence
     * before delivering the sequence to the consumer. If the number of events received
     * within a given PacingInterval equals or exceeds MaximumBatchSize, the consumer
     * will receive a sequence of events whose length equals MaximumBatchSize. Otherwise,
     * the consumer will receive however many events arrived at the proxy supplier during
     * the PacingInterval. The data type of the value associated with this property is
     * TimeBase::UtcT.
     */
    const string PacingInterval = "PacingInterval";
    // PacingInterval takes on a value of type TimeBase::TimeT

    const string StartTimeSupported = "StartTimeSupported";
    // StartTimeSupported takes on a boolean value

    const string StopTimeSupported = "StopTimeSupported";
    // StopTimeSupported takes on a boolean value

    /**
     * As described in section 2.5.7, an administrative property can be set on the channel to
     * bound the maximum number of events a given channel is allowed to queue at any
     * given point in time. Note, however, that a single badly behaved consumer could result
     * in the channel holding the maximum number of events it is allowed to queue for an
     * extended period of time, preventing further event communication through the channel.
     * Thus, the MaximumEventsPerConsumer property helps to avoid this situation by
     * bounding the maximum number of events the channel will queue on behalf of a given
     * consumer. If set only on a per-channel basis, the value of this property applies to all
     * consumers connected to the channel. If set on a per-ConsumerAdmin basis, this
     * property applies to all consumers connected to proxy suppliers created by that
     * ConsumerAdmin. If set on a per-proxy supplier basis, this property applies to the
     * consumer connected to the given proxy supplier. Note that setting this property on a
     * SupplierAdmin or proxy consumer has no meaning.
     */
    const string MaxEventsPerConsumer = "MaxEventsPerConsumer";
    // MaxEventsPerConsumer takes on a value of type long

    /**
     * The QoSAdmin interface defines operations which enable clients to get and set the
     * values of QoS properties. It also defines an operation that can verify whether or not a
     * set of requested QoS property settings can be satisfied, along with returning
     * information about the range of possible settings for additional QoS properties.
     * QoSAdmin is intended to be an abstract interface which is inherited by the Proxy,
     * Admin, and Event Channel interfaces defined in the CosNotifyChannelAdmin and
     * CosTypedNotifyChannelAmin modules. The semantics of the operations supported
     * by this interface are defined below.
     */
    interface QoSAdmin
    {

        /**
         * The get_qos operation takes no input parameters, and returns a sequence of name-value
         * pairs which encapsulates the current quality of service settings for the target
         * object (which could be an Event Channel, Admin, or Proxy object).
         *
         * @return Object QosProperties
         */
        QoSProperties get_qos();

        /**
         * The set_qos operation takes as an input parameter a sequence of name-value pairs
         * which encapsulates quality of service property settings that a client is requesting that
         * the target object (which could be an Event Channel, Admin, or Proxy object) support
         * as its default quality of service. If the implementation of the target object is not
         * capable of supporting any of the requested quality of service settings, or if any of the
         * requested settings would be in conflict with a QoS property defined at a higher level of
         * the object hierarchy with respect to QoS , the UnsupportedQoS
         * exception is raised. This exception contains as data a sequence of data structures, each
         * of which identifies the name of a QoS property in the input list whose requested setting
         * could not be satisfied, along with an error code and a range of settings for the property
         * which could be satisfied. The meanings of the error codes which might be returned are
         * described in Table 2-5 of CosNotification Service specification
         *
         * @param qos QosProperties to assign to object
         * @exception org.omg.CosNotification.UnsupportedQoS
         */
        void set_qos ( in QoSProperties qos)
            raises ( UnsupportedQoS );

        /**
         * The validate_qos operation accepts as input a sequence of QoS property name-value
         * pairs which specify a set of QoS settings that a client would like to know if the target
         * object is capable of supporting. If the any of the requested settings could not be
         * satisfied by the target object, the operation raises the UnsupportedQoS exception.
         * This exception contains as data a sequence of data structures, each of which identifies
         * the name of a QoS property in the input list whose requested setting could not be
         * satisfied, along with an error code and a range of settings for the property which could
         * be satisfied. The meanings of the error codes which might be returned are described in
         * Table 2-5.
         * If all requested QoS property value settings could be satisfied by the target object, the
         * operation returns successfully (without actually setting the QoS properties on the target
         * object) with an output parameter that contains a sequence of PropertyRange data
         * structures. Each element in this sequence includes the name of a an additional QoS
         * property supported by the target object which could have been included on the input
         * list and resulted in a successful return from the operation., along with the range of
         * values that would have been acceptable for each such property.
         *
         * @param required_qos
         * @param available_qos
         * @exception org.omg.CosNotification.UnsupportedQoS
         */
        void validate_qos ( in QoSProperties required_qos,
              out NamedPropertyRangeSeq available_qos )
            raises ( UnsupportedQoS );

	}; // QosAdmin


    // Admin properties are defined in similar manner as QoS
    // properties. The only difference is that these properties
    // are related to channel administration policies, as opposed
    // message quality of service

    const string MaxQueueLength = "MaxQueueLength";
    // MaxQueueLength takes on a value of type long

    const string MaxConsumers = "MaxConsumers";
    // MaxConsumers takes on a value of type long

    const string MaxSuppliers = "MaxSuppliers";
    // MaxSuppliers takes on a value of type long

    const string RejectNewEvents = "RejectNewEvents";
    // RejectNewEvents takes on a value of type Boolean

    /**
     * The AdminPropertiesAdmin interface defines operations which enable clients to get
     * and set the values of administrative properties. This interface is intended to be an
     * abstract interface which is inherited by the Event Channel interfaces defined in the
     * CosNotifyChannelAdmin and CosTypedNotifyChannelAmin modules. The
     * semantics of the operations supported by this interface are defined below.
     *
     */
    interface AdminPropertiesAdmin
    {

        /**
         * The get_admin operation takes no input parameters, and returns a sequence of name-value
         * pairs which encapsulates the current administrative settings for the target
         * channel.
         *
         * @return All Admin Properties
         */
        AdminProperties get_admin();

        /**
         * The set_admin operation takes as an input parameter a sequence of name-value pairs
         * which encapsulates administrative property settings that a client is requesting that the
         * target channel support. If the implementation of the target object is not capable of
         * supporting any of the requested administrative property settings, the
         * UnsupportedAdmin exception is raised. This exception has associated with it a list of
         * name-value pairs of which each name identifies an administrative property whose
         * requested setting could not be satisfied, and each associated value the closest setting
         * for that property which could be satisfied.
         *
         * @param admin Array of admin property
         * @exception org.omg.CosNotification.UnsupportedAdmin If implementation doesn't support a
         * property
         */
         void set_admin (in AdminProperties admin)
             raises ( UnsupportedAdmin);
	
    }; // AdminPropertiesAdmin

}; // CosNotification

#endif // _COS_NOTIFICATION_IDL_
