//File: CosNotifyFilter.idl
//Part of the Notification Service

#ifndef _COS_NOTIFY_FILTER_IDL_
#define _COS_NOTIFY_FILTER_IDL_


#include <CosNotifyComm.idl>

#pragma prefix "omg.org"

/**
 * The CosNotifyFilter module defines the interfaces supported by the filter objects used
 * by the Notification Service. Two different types of filter objects are defined here. The
 * first type support the Filter interface and encapsulate the constraints which will be
 * used by a proxy object associated with a notification channel in order to make
 * decisions about which events to forward, and which to discard. The second type
 * support the MappingFilter interface and encapsulate constraints along with associated
 * values, whereby the constraints determine whether a proxy object will alter the way it
 * treats each event with respect to a particular property of the event, and the value
 * specifies the property value the proxy would apply to each event which satisfies the
 * associated constraint. In addition to the two types of filter object interface defined in
 * this module, the CosNotifyFilter module also defines the FilterFactory interface
 * which supports the operations required to create each type of filter object, and the
 * FilterAdmin interface which supports operations which enable an interface (Proxy or
 * Admin) which inherits it to manage a list of Filter instances.
 */
module CosNotifyFilter
{
    typedef long ConstraintID;

    struct ConstraintExp
    {
        CosNotification::EventTypeSeq event_types;
        string constraint_expr;
    };

    typedef sequence<ConstraintID> ConstraintIDSeq;
    typedef sequence<ConstraintExp> ConstraintExpSeq;

    struct ConstraintInfo
    {
        ConstraintExp constraint_expression;
        ConstraintID constraint_id;
    };

    typedef sequence<ConstraintInfo> ConstraintInfoSeq;

    struct MappingConstraintPair
    {
        ConstraintExp constraint_expression;
        any result_to_set;
    };

    typedef sequence<MappingConstraintPair> MappingConstraintPairSeq;

    struct MappingConstraintInfo
    {
        ConstraintExp constraint_expression;
        ConstraintID constraint_id;
        any value;
    };

    typedef sequence<MappingConstraintInfo> MappingConstraintInfoSeq;

    typedef long CallbackID;
    typedef sequence<CallbackID> CallbackIDSeq;

    exception UnsupportedFilterableData {};
    exception InvalidGrammar {};
    exception InvalidConstraint {ConstraintExp constr;};
    exception DuplicateConstraintID {ConstraintID id;};

    exception ConstraintNotFound {ConstraintID id;};
    exception CallbackNotFound {};

    exception InvalidValue {ConstraintExp constr; any value;};

    /**
     * The Filter interface defines the behaviors supported by objects which encapsulate
     * constraints used by the proxy objects associated with an event channel in order to
     * determine which events they receive will be forwarded, and which will be discarded.
     * Each object supporting the Filter interface can encapsulate a sequence of any number
     * of constraints. Each event received by a proxy object which has one or more objects
     * supporting the Filter interface associated with it must satisfy at least one of the
     * constraints associated with one of its associated Filter objects in order to be forwarded
     * (either to another proxy object or to the consumer, depending on the type of proxy the
     * filter is associated with), otherwise it will be discarded.
     * Each constraint encapsulated by a filter object is a structure comprised of two main
     * components. The first component is a sequence of data structures, each of which
     * indicates an event type comprised of a domain and a type name. The second
     * component is a boolean expression over the properties of an event, expressed in some
     * constraint grammar (more on this below). For a given constraint, the sequence of event
     * type structures in the first component nominates a set of event types to which the
     * constraint expression in the second component applies. Each element of the sequence
     * can contain strings which will be matched for equality against the domain_name and
     * type_name fields of each event being evaluated by the filter object, or it could contain
     * strings with wildcard symbols (*), indicating a pattern match should be performed
     * against the type contained in each event, rather than a comparison for equality when
     * determining if the boolean expression should be applied to the event, or the event
     * should simply be discarded without even attempting to apply the boolean expression.
     * Note that an empty sequence included as the first component of a constraint implies
     * that the associated expression applies to all types of events, as does a sequence
     * comprised of a single element whose domain and type name are both set to either the
     * empty string or else the wildcard symbol alone contained in quotes.
     * The constraint expressions associated with a particular object supporting the Filter
     * interface are expressed as strings which obey the syntax of a particular constraint
     * grammar.
     * As long as such user-defined filter objects support the Filter interface, they can be
     * attached to Proxy or Admin objects in the same fashion as the default Filter objects
     * supported by the implementation of the service are, and the channel should be able to
     * use them to filter events in the same fashion.
     * The Filter interface supports the operations required to manage the constraints
     * associated with an object instance which supports the interface, along with a readonly
     * attribute which identifies the particular constraint grammar in which the constraints
     * encapsulated by this object have meaning. In addition, the Filter interface supports
     * three variants of the match operation which can be invoked by an associated proxy
     * object upon receipt of an event (the specific variant selected depends upon whether the
     * event is received in the form of an Any, a Structured Event, or a Typed Event), to
     * determine if the event should be forwarded or discarded, based on whether or not the
     * event satisfies at least one criteria encapsulated by the filter object.
     * The Filter interface also supports operations which enable a client to associate with
     * the target filter object any number of “callbacks” which are notified each time there is
     * a change to the list of event types which the constraints encapsulated by the filter
     * object could potentially cause proxies to which the filter is attached to receive.
     * Operations are also defined to support administration of this callback list by unique
     * identifier.
     */
    interface Filter
    {

        /**
         * The constraint_grammar attribute is a readonly attribute which identifies the particular
         * grammar within which the constraint expressions encapsulated by the target filter
         * object have meaning. The value of this attribute is set upon creation of a filter object
         * instance, based on the input provided to the factory creation operation for the filter
         * instance.
         *
         */
        readonly attribute string constraint_grammar;

        /**
         * The add_constraints operation is invoked by a client in order to associate one or more
         * new constraints with the target filter object. The operation accepts as input a sequence
         * of constraint data structures, each element of which consists of a sequence of event
         * type structures (described in section 3.2.1) and a constraint expressed within the
         * constraint grammar supported by the target object. Upon processing each constraint,
         * the target object associates a numeric identifier with the constraint that is unique
         * among all constraints it encapsulates. If any of the constraints in the input sequence is
         * not a valid expression within the supported constraint grammar, the InvalidConstraint
         * exception is raised. This exception contains as data the specific constraint expression
         * that was determined to be invalid. Upon successful processing of all input constraint
         * expressions, the add_constraints operation returns a sequence in which each element
         * will be a structure including one of the input constraint expressions, along with the
         * unique identifier assigned to it by the target filter object.
         * Note that the semantics of the add_constraints operation are such that its side-effects
         * are performed atomically upon the target filter object. Once add_constraints is invoked
         * by a client, the target filter object is temporarily disabled from usage by any proxy
         * object it may be associated with. The operation is then carried out, either successfully
         * adding all of the input constraints to the target object or none of them (in the case one
         * of the input expressions was invalid). Upon completion of the operation, the target
         * filter object is effectively re-enabled and can once again be used by associated filter
         * objects in order to make event forwarding decisions.
         *
         * @param constraint_list Constraint Expressions
         * @return ConstraintInfo array. Each element contain constraint exp and ID associated
         * @exception org.omg.CosNotifyFilter.InvalidConstraint If an Constraint doesn't respect
         * grammar
         */
        ConstraintInfoSeq add_constraints (in ConstraintExpSeq constraint_list)
            raises (InvalidConstraint);

        /**
         * The modify_constraints operation is invoked by a client in order to modify the
         * constraints associated with the target filter object. This operation can be used both to
         * remove constraints currently associated with the target filter object, and to modify the
         * constraint expressions of constraints which have previously been added to the target
         * filter object.
         * The operation accepts two input parameters. The first input parameter is a sequence of
         * numeric values which are each intended to be the unique identifier associated with one
         * of the constraints currently encapsulated by the target filter object. If all input
         * values supplied within a particular invocation of this operation are valid, then
         * the specific constraints identified by the values contained in the first input
         * parameter will be deleted from the list of those encapsulated by the target filter 
         * object.
         * The second input parameter to this operation is a sequence of structures, each of which
         * contains a constraint structure and a numeric value. The numeric value contained by
         * each element of the sequence is intended to be the unique identifier associated with
         * one of the constraints currently encapsulated by the target filter object. If all input
         * values supplied within a particular invocation of this operation are valid, then the
         * constraint expression associated with the already encapsulated constraint identified by
         * the numeric value contained within each element of the input sequence will be
         * modified to the new constraint expression that is contained within the same sequence
         * element.
         * If any of the numeric values supplied within either of the two input sequences does not
         * correspond to the unique identifier associated with some constraint currently
         * encapsulated by the target filter object, the ConstraintNotFound exception is raised.
         * This exception contains as data the specific identifier which was supplied as input but
         * did not correspond to the identifier of some constraint encapsulated by the target
         * object. If any of the constraint expressions supplied within an element of the second
         * input sequence is not a valid expression in terms of the constraint grammar supported
         * by the target object, the InvalidConstraint exception is raised. This exception
         * contains as data the specific constraint that was determined to be invalid.
         * Note that the semantics of the modify_constraints operation are such that its
         * side-effects are performed atomically upon the target filter object. Once 
         * modify_constraints is invoked by a client, the target filter object is temporarily 
         * disabled from usage by any proxy object it may be associated with. The operation 
         * is then carried out, either successfully deleting all of the constraints identified in
         * the first input sequence and modifying those associated with constraints identified in 
         * the second input sequence, or performing no side effects to the target object 
         * (in the case one of the inputs was invalid). Upon completion of the operation, the target 


         * filter object is effectively re-enabled and can once again be used by associated filter
         * objects in order to make event forwarding decisions.
         *
         * @param del_list ID's of constraint exp to be delete
         * @param modify_list ConstraintInfo containing all constraint to be modified
         * @exception org.omg.CosNotifyFilter.InvalidConstraint If a constraint doesn't respect
         * grammar
         * @exception org.omg.CosNotifyFilter.ConstraintNotFound Invalid ID's
         */
        void modify_constraints (in ConstraintIDSeq del_list,
              in ConstraintInfoSeq modify_list)
            raises (InvalidConstraint, ConstraintNotFound);

        /**
         * The get_constraints operation is invoked to return a sequence of a subset of the
         * constraints associated with the target filter object. The operation accepts as input a
         * sequence of numeric values which should correspond to the unique identifiers of
         * constraints encapsulated by the target object. If one of the input values does not
         * correspond to the identifier of some encapsulated constraint, the ConstraintNotFound
         * exception is raised, containing as data the numeric value that did not correspond to
         * some constraint. Upon successful completion, this operation returns a sequence of data
         * structures, each of which contains one of the input identifiers along with its associated
         * constraint.
         *
         * @param id_list Id of all constraints to get
         * @return ConstraintInfo array
         * @exception  org.omg.CosNotifyFilter.ConstraintNotFound If an ID is invalid. Exception
         * contains this ID
         */
        ConstraintInfoSeq get_constraints(in ConstraintIDSeq id_list)
            raises (ConstraintNotFound);

        /**
         * The get_all_constraints operation returns all of the constraints currently encapsulated
         * by the target filter object. The return value of this operation is a sequence of
         * structures, each of which contains one of the constraints encapsulated by the target
         * object along with its associated unique identifier.
         *
         * @return ConstraintInfo array
         */
        ConstraintInfoSeq get_all_constraints();

        /**
         * The remove_all_constraints operation is invoked to remove all of the constraints
         * currently encapsulated by the target filter object. Upon completion, the target filter
         * object will still exist but have no constraints associated with it.
         *
         */
        void remove_all_constraints();

        /**
         * The destroy operation destroys the target filter object, invalidating its object
         * reference.
         */
        void destroy();

        /**
         * The match operation evaluates the filter constraints associated with the target filter
         * object against an instance of an event supplied to the channel in the form of a
         * CORBA::Any. The operation accepts as input a CORBA::Any which contains an event
         * to be evaluated, and returns a boolean value which will be TRUE in cases where the
         * input event satisfies one of the filter constraints, and FALSE otherwise.
         * If the input parameter contains data that the match operation is not designed to handle,
         * the UnsupportedFilterableData exception will be raised. An example of this would
         * be if the filterable data contained a field whose name corresponds to a standard event
         * field that has a numeric value, but the actual value associated with this field name
         * within the event is a string.
         *
         * @param filterable_data Event
         * @return True if event must be throw, false otherwise
         * @exception org.omg.CosNotifyFilter.UnsupportedFilterableData Event can't be evaluate
         */
        boolean match(in any filterable_data)
            raises (UnsupportedFilterableData);

        /**
         * The match_structured operation evaluates the filter constraints associated with the
         * target filter object against an instance of an event supplied to the channel in the form
         * of a Structured Event. The operation accepts as input a data structure of type
         * CosNotification::StructuredEvent which contains an event to be evaluated, and returns
         * a boolean value which will be TRUE in cases where the input event satisfies one of the
         * filter constraints, and FALSE otherwise. The act of determining whether or not a given
         * event passes a given filter constraint is specific to the type of grammar in which the
         * filter constraint is specified. Thus, this operation will need to be re-implemented for
         * each supported grammar.
         * If the input parameter contains data that the match operation is not designed to handle,
         * the UnsupportedFilterableData exception will be raised. An example of this would
         * be if the filterable data contained a field whose name corresponds to a standard event
         * field that has a numeric value, but the actual value associated with this field name
         * within the event is a string.
         *
         * @param filterable_data Event
         * @return True if event must be throw, false otherwise
         * @exception org.omg.CosNotifyFilter.UnsupportedFilterableData Event can't be evaluate
         */
        boolean match_structured( in CosNotification::StructuredEvent filterable_data )
            raises (UnsupportedFilterableData);

        /**
         * The match operation evaluates the filter constraints associated with the target filter
         * object against an instance of an event supplied to the channel in the form of a typed
         * event. The operation accepts as input a sequence of name-value pairs which contains
         * the contents of the event to be evaluated (how a typed event is converted to a sequence
         * of name-value pairs by the channel is described in section 2.7), and returns a boolean
         * value which will be TRUE in cases where the input event satisfies one of the filter
         * constraints, and FALSE otherwise. The act of determining whether or not a given event
         * passes a given filter constraint is specific to the type of grammar in which the filter
         * constraint is specified. Thus, this operation will need to be re-implemented for each
         * supported grammar.
         * If the input parameter contains data that the match operation is not designed to handle,
         * the UnsupportedFilterableData exception will be raised. An example of this would
         * be if the filterable data contained a field whose name corresponds to a standard event
         * field that has a numeric value, but the actual value associated with this field name
         * within the event is a string.
         *
         * @param filterable_data Event
         * @return True if event must be throw, false otherwise
         * @exception org.omg.CosNotifyFilter.UnsupportedFilterableData Event can't be evaluate
         */
        boolean match_typed( in CosNotification::PropertySeq filterable_data )
            raises (UnsupportedFilterableData);

        /**
         *
         * The attach_callback operation accepts as input the reference to an object supporting
         * the CosNotifyComm::NotifySubscribe interface, and returns a numeric value
         * assigned to this callback that is unique to all such callbacks currently associated with
         * the target object. This operation is invoked to associate with the target filter object
         * an object supporting the CosNotifyComm::NotifySubscribe interface. This interface is
         * inherited by all supplier interfaces (either those that are clients of a notification
         * channel, or those that are proxy objects within a notification channel) defined by the
         * Notification Service, and supports a subscription_change operation. After this
         * operation has been successfully invoked on a filter object, each time the set of
         * constraints associated with the target filter object is modified (either by an invocation
         * of its add_constraints or its modify_constraints operations), the filter object will
         * invoke the subscription_change object of all its associated callback objects in order to
         * inform suppliers to which the target filter object is attached of the change in the set
         * of event types to which clients of the filter object subscribe. This enables suppliers to
         * make intelligent decisions about which types of events it should actually produce, and
         * which it can suppress the production of. This mechanism is described in more detail in
         * section 2.6.
         *
         * @param callback
         * @return CallBacK ID
         */
        CallbackID attach_callback( in CosNotifyComm::NotifySubscribe callback );

        /**
         * The detach_callback operation accepts as input a numeric value which should be one
         *   of the unique identifiers associated with one of the callback objects attached to the
         * target filter object. If the input value does not correspond to the unique identifier of
         * a callback object currently attached to the target filter object, the CallbackNotFound
         * exception is raised. Otherwise, the callback object to which the input value
         * corresponds is removed from the list of those associated with the target filter object,
         * so that subsequent changes to the event type subscription list encapsulated by the target
         * filter object will not be propagated to the callback object which is being detached.
         *
         * @param callback Callback ID
         * @exception org.omg.CosNotifyFilter.CallbackNotFound ID not exist
         */
        void detach_callback ( in CallbackID callback )
            raises ( CallbackNotFound );

        /**
         * The get_callbacks operation accepts no input parameters and returns the sequence of
         * all unique identifiers associated with callback objects attached to the target filter
         * object.
         */
        CallbackIDSeq get_callbacks();

    }; // Filter

    /**
     * The MappingFilter interface defines the behaviors of objects which encapsulate a
     * sequence of constraint-value pairs, where each constraint is a structure of the same
     * type as that described in section 3.2.1, and each value represents a possible setting of a
     * particular property of an event. Note that setting of a particular property is not
     * intended to imply that any contents of the event will be altered as a result of applying
     * a mapping filter, but rather the way a proxy treats the event with respect to a particular
     * property (i.e., priority or lifetime) could change. Upon receiving each event, a proxy
     * object with an associated object supporting the MappingFilter interface will invoke
     * the appropriate match operation variant (depending upon whether the event is received
     * in the form of an untyped event, a Structured Event, or a typed event) on the mapping
     * filter object in order to determine how it should modify a particular property value
     * associated with the event to one of the values associated with one of the constraints
     * encapsulated by the mapping filter. Internally, the mapping filter object applies the
     * constraints it encapsulates to the event in order to determine whether or not the event’s
     * property should be modified to one of the values associated with a constraint, or else
     * the default value associated with the mapping filter.
     * Each instance of an object supporting the MappingFilter interface is typically
     * associated with a specific event property. For instance, in this specification
     * MappingFilter object instances are used to affect the properties of priority and
     * lifetime for events received by a proxy supplier object. Each event received by a proxy
     * object which has an object supporting the MappingFilter interface associated with it
     * must satisfy at least one of the constraints associated with the MappingFilter object in
     * order to have its property value modified, otherwise the property will remain
     * unchanged. A specific instance supporting the MappingFilter interface typically
     * applies its encapsulated constraints in an order which begins with the best possible
     * property setting (e.g., the highest priority or the longest lifetime), and ends with the
     * worst possible property setting. As soon as a matching constraint is encountered, the
     * associated value is returned as an output parameter and the proxy which invoked the
     * operation proceeds to modify the property of the event to the new value.
     * The constraint expressions associated with a particular object supporting the
     * MappingFilter interface are expressed as strings which obey the syntax of a particular
     * constraint grammar (i.e. a BNF). Every conformant implementation of this service
     * must support constraint expressions expressed in the default constraint grammar
     * described in section 2.4. In addition, implementations may support other constraint
     * grammars, and/or users of this service may implement their own filter objects which
     * allow constraints to be expressed in terms of an alternative constraint grammar. As
     * long as such user-defined filter objects support the MappingFilter interface, they can
     * be attached to proxy objects in the same fashion as the default MappingFilter objects
     * supported by the implementation of the service are, and the channel should be able to
     * use them to potentially affect the properties of events in the same fashion.
     * The MappingFilter interface supports the operations required to manage the
     * constraint-value pairs associated with an object instance which supports the interface.
     * In addition, the MappingFilter interface supports a readonly attribute which identifies
     * the particular constraint grammar in which the constraints encapsulated by this object
     * have meaning. The MappingFilter interface also supports a readonly attribute which
     * identifies the typecode associated with the datatype of the specific property value it is
     * intended to affect, and another readonly attribute which holds the default value which
     * will be returned as the result of a match operation in cases when the event in question
     * is found to satisfy none of the constraints encapsulated by the mapping filter. Lastly,
     * the MappingFilter interface supports three variants of the operation which will be
     * invoked by an associated proxy object upon receipt of an event, to determine how the
     * property of the event which the target mapping filter object was designed to affect
     * should be modified.
     * The operations supported by the MappingFilter object are described in more detail
     * within the following subsections.
     */
    interface MappingFilter
    {

        /**
         * The constraint_grammar attribute is a readonly attribute which identifies the particular
         * grammar within which the constraint expressions encapsulated by the target filter
         * object have meaning. The value of this attribute is set upon creation of a mapping filter
         * object instance, based on the input provided to the factory creation operation for the
         * mapping filter instance.
         * The dependency of a filter object on its constraints being expressed within a particular
         * constraint grammar manifests itself within the implementation of the match operations
         * described below, which must be able to parse the constraints to determine whether or
         * not a particular event satisfies one of them.
         * Every conformant implementation of the Notification Service must support an
         * implementation of the MappingFilter object which supports the default constraint
         * grammar described in section 2.4. The value which the constraint_grammar attribute is
         * set to in the case the target filter object supports this default grammar will be
         * EXTENDED_TCL. In addition, implementations and/or end users may provide
         * additional implementations of the MappingFilter interface which support different
         * constraint grammars, and thus would set the constraint_grammar attribute to a
         * different value upon creation of such a filter object.
         */
        readonly attribute string constraint_grammar;

        /**
         * The value_type attribute is a readonly attribute which identifies the datatype of the
         * property value which the target mapping filter object was designed to affect. Note that
         * the factory creation operation for mapping filter objects accepts as an input parameter
         * the default_value to associate with the mapping filter instance. This default_value is a
         * CORBA::Any. Upon creation of a mapping filter, the Typecode associated with the
         * default_value is extracted from the CORBA::Any, and its value is assigned to this
         * attribute. The value_type attribute thus serves mainly as a convenience for clients
         * attempting to examine the state of a mapping filter object.
         */
        readonly attribute CORBA::TypeCode value_type;

        /**
         * The default_value attribute is a readonly attribute that will be the output parameter
         * returned as the result of any match operation during which the input event is found to
         * satisfy none of the constraints encapsulated by the mapping filter, within which the
         * constraints encapsulated by the target filter object have meaning. The value of this
         * attribute is set upon creation of a mapping filter object instance, based on the input
         * provided to the factory creation operation for the mapping filter instance.
         */
        readonly attribute any default_value;

        /**
         * The add_mapping_constraints operation is invoked by a client in order to associate
         * specific mapping constraints with the target filter object. Note that a mapping
         * constraint is comprised of a constraint structure paired with an associated value. The
         * operation accepts as input one parameter that is a sequence of constraint-value pairs.
         * Each constraint in this sequence must be expressed within the constraint grammar
         * supported by the target object, and each associated value must be of the data type
         * indicated by the value_type attribute of the target object.
         * Upon processing the each element in the input sequence, the target object associates a
         * numeric identifier with this constraint-value pair that is unique among all those that it
         * encapsulates. If any of the constraint expressions in the input sequence is not a valid
         * expression within the supported constraint grammar, the InvalidConstraint exception
         * is raised. This exception contains as data the specific constraint that was determined to
         * be invalid. If any of the values supplied in the input sequence is not of the same
         * datatype as that indicated by the value_type attribute associated with the target object,
         * the InvalidValue exception is raised. This exception contains as data both the invalid
         * value and its corresponding constraint in the first input sequence. Upon successful
         * processing of all input constraints, the add_mapping_constraints operation returns a
         * sequence in which each element will be a structure including one of the input
         * constraint expressions, its corresponding value, and the unique identifier assigned to
         * this constraint-value pair by the target filter object.
         * Note that the semantics of the add_mapping_constraints operation are such that its
         * side-effects are performed atomically upon the target filter object. Once
         * add_mapping_constraints is invoked by a client, the target filter object is temporarily
         * disabled from usage by any proxy object it may be associated with. The operation is
         * then carried out, either successfully adding all of the input constraint-value pairs to
         * the target object or none of them (in the case one of the input expressions or values was
         * invalid). Upon completion of the operation, the target filter object is effectively
         * re-enabled and can once again be used by associated filter objects in order to make event
         * property mapping decisions.
         */
        MappingConstraintInfoSeq add_mapping_constraints (
              in MappingConstraintPairSeq pair_list )
            raises ( InvalidConstraint, InvalidValue );

        /**
         * The modify_mapping_constraints operation is invoked by a client in order to modify
         * the constraint-value pairs associated with the target filter object. This operation can
         * be used both to remove constraint-value pairs currently associated with the target filter
         * object, and to modify the constraints and/or values of constraint-value pairs which
         * have previously been added to the target filter object.
         * The operation accepts two input paramaters. The first input parameter is a sequence of
         * numeric values which are each intended to be the unique identifier associated with one
         * of the constraint-value pairs currently encapsulated by the target filter object. If all
         * input values supplied within a particular invocation of this operation are valid, then
         * the specific constraint-value pairs identified by the values contained in the first input
         * parameter will be deleted from the list of those encapsulated by the target filter
         * object. The second input parameter to this operation is a sequence of structures, each of
         * which contains a constraint structure, an Any value, and a numeric identifier. The
         * numeric identifier contained by each element of the sequence is intended to be the unique
         * identifier associated with one of the constraint-value pairs currently encapsulated by
         * the target filter object. If all input values supplied within a particular invocation of
         * the operation are valid, then the constraint associated with the already encapsulated
         * constraint-value pair identified by the numeric identifier contained within each element
         * of the input sequence will be modified to the new constraint that is contained within
         * the same sequence element. Likewise, the data value associated with the already
         * encapsulated constraint-value pair identified by the numeric identifier contained within
         * each element of the input sequence will be modified to the new data value that is
         * contained in the same element of the sequence.
         * If any of the numeric identifiers supplied within either of the two input sequences does
         * not correspond to the unique identifier associated with some constraint-value pairs
         * currently encapsulated by the target filter object, the ConstraintNotFound exception
         * is raised. This exception contains as data the specific identifier which was supplied as
         * input but did not correspond to the identifier of some constraint-value pair
         * encapsulated by the target object. If any of the constraint expressions supplied within
         * an element of the second input sequence is not a valid expression in terms of the
         * constraint grammar supported by the target object, the InvalidConstraint exception is
         * raised. This exception contains as data the specific constraint that was determined to be
         * invalid. If any of the values supplied in the second input sequence is not of the same
         * datatype as that indicated by the value_type attribute associated with the target object,
         * the InvalidValue exception is raised. This exception contains as data both the invalid
         * value and its corresponding constraint expression.
         * Note that the semantics of the modify_mapping_constraints operation are such that its
         * side-effects are performed atomically upon the target filter object. Once
         * modify_mapping_constraints is invoked by a client, the target filter object is
         * temporarily disabled from usage by any proxy object it may be associated with. The
         * operation is then carried out, either successfully deleting all of the constraint-value
         * pairs identified in the first input sequence and modifying the constraints and values
         * associated with constraints identified in the second input sequence, or performing no
         * side effects to the target object (in the case one of the inputs was invalid). Upon
         * completion of the operation, the target filter object is effectively re-enabled and can
         * once again be used by associated filter objects in order to make event property
         * mapping decisions.
         */
        void modify_mapping_constraints (
                in ConstraintIDSeq del_list,
                in MappingConstraintInfoSeq modify_list)
            raises (InvalidConstraint, InvalidValue,
                        ConstraintNotFound);

        /**
         * The get_mapping_constraints operation is invoked to return a sequence of a subset of
         * the constraint-value pairs associated with the target filter object. The operation
         * accepts as input a sequence of numeric values which should correspond to the unique
         * identifiers of constraint-value pairs encapsulated by the target object. If one of the
         * input values does not correspond to the identifier of some encapsulated constraint-value
         * pair, the ConstraintNotFound exception is raised, containing as data the
         * numeric value that did not correspond to some such pair. Upon successful completion,
         * this operation returns a sequence of data structures, each of which contains one of the
         * input identifiers along with its associated constraint structure and constraint value.
         */
        MappingConstraintInfoSeq get_mapping_constraints (
              in ConstraintIDSeq id_list )
            raises ( ConstraintNotFound );

        /**
         * The get_all_mapping_constraints operation returns all of the constraint-value pairs
         * currently encapsulated by the target filter object. The return value of this operation is
         * a sequence of structures, each of which contains one of the constraints encapsulated by
         * the target object along with its associated value and unique identifier.
         */
        MappingConstraintInfoSeq get_all_mapping_constraints();

        /**
         * The remove_all_mapping_constraints operation is invoked to remove all of the
         * constraint-value pairs currently encapsulated by the target filter object. Upon
         * completion, the target filter object will still exist but have no constraint-value pairs
         * associated with it.
         */
        void remove_all_mapping_constraints();

        /**
         * The destroy operation destroys the target filter object, invalidating its object
         * reference.
         */
        void destroy();

        /**
         * The match operation is invoked on an object supporting the MappingFilter interface
         * in order to determine how some property value of a particular event supplied to the
         * channel in the form of a CORBA::Any should be modified. The operation accepts an
         * Any as input, which contains the event being evaluated. Upon invocation, the target
         * mapping filter object begins applying the constraints it encapsulates in order according
         * to each constraints associated value, starting with the constraint with the “best”
         * associated value for the specific property the mapping filter object was designed to
         * affect (e.g., the highest priority, the longest lifetime, etc.), and ending with the
         * constraint with the “worst” associated value. Upon encountering a constraint which the
         * input filterable data matches, the operation sets the output parameter contained in its
         * signature to the value associated with the constraint, and sets the return value of the
         * operation to TRUE. If the input filterable data satisfies none of the constraints
         * encapsulated by the target mapping filter object, the return value of the operation is
         * set to FALSE, and the output parameter is set to the value of the default_value attribute
         * associated with the target mapping filter object. The act of determining whether or not
         * a given filterable event data passes a given filter constraint is specific to the type of
         * grammar in which the filter constraint is specified. Thus, this operation will need to be
         * re-implemented for each supported grammar.
         * If the input parameter contains data that the match operation is not designed to handle,
         * the UnsupportedFilterableData exception will be raised. An example of this would
         * be if the filterable data contained a field whose name corresponds to a standard event
         * field that has a numeric value, but the actual value associated with this field name
         * within the event is a string.
         */
        boolean match ( in any filterable_data, out any result_to_set )
           raises ( UnsupportedFilterableData );

        /**
         * The match_structured operation is invoked on an object supporting the MappingFilter
         * interface in order to determine how some property value of a particular event supplied
         * to the channel in the form of a Structured Event should be modified. The operation
         * accepts a CosNotification::StructuredEvent as input, which contains the event being
         * evaluated. Upon invocation, the target mapping filter object begins applying the
         * constraints it encapsulates in order according to each constraints associated value,
         * starting with the constraint with the “best” associated value for the specific property
         * the mapping filter object was designed to affect (e.g., the highest priority, the longest
         * lifetime, etc.), and ending with the constraint with the “worst” associated value. Upon
         * encountering a constraint which the input filterable data matches, the operation sets the
         * output parameter contained in its signature to the value associated with the constraint,
         * and sets the return value of the operation to TRUE. If the input filterable data 
         * satisfies none of the constraints encapsulated by the target mapping filter object, the 
         * return value of the operation is set to FALSE, and the output parameter is set to the
         * value of the default_value attribute associated with the target mapping filter object.
         * The act of determining whether or not a given filterable event data passes a given filter 
         * constraint is specific to the type of grammar in which the filter constraint is
         * specified. Thus, this operation will need to be re-implemented for each supported 
         * grammar. If the input parameter contains data that the match operation is not designed to 
         * handle, the UnsupportedFilterableData exception will be raised. An example of this would
         * be if the filterable data contained a field whose name corresponds to a standard event
         * field that has a numeric value, but the actual value associated with this field name
         * within the event is a string.
         */
        boolean match_structured ( in CosNotification::StructuredEvent filterable_data,
              out any result_to_set )
            raises ( UnsupportedFilterableData );

        /**
         * The match_typed operation is invoked on an object supporting the MappingFilter
         * interface in order to determine how some property value of a particular event supplied
         * to the channel in the form of a typed event should be modified. The operation accepts
         * as input a sequence of name-value pairs which contains the contents of the event to be
         * evaluated (how a typed event is converted to a sequence of name-value pairs by the
         * channel is described in section 2.7). Upon invocation, the target mapping filter object
         * begins applying the constraints it encapsulates in order according to each constraints
         * associated value, starting with the constraint with the “best” associated value for the
         * specific property the mapping filter object was designed to affect (e.g., the highest
         * priority, the longest lifetime, etc.), and ending with the constraint with the “worst”
         * associated value. Upon encountering a constraint which the input filterable data
         * matches, the operation sets the output parameter contained in its signature to the value
         * associated with the constraint, and sets the return value of the operation to TRUE. If
         * the input filterable data satisfies none of the constraints encapsulated by the target
         * mapping filter object, the return value of the operation is set to FALSE, and the output
         * parameter is set to the value of the default_value attribute associated with the target
         * mapping filter object. The act of determining whether or not a given filterable event
         * data passes a given filter constraint is specific to the type of grammar in which the
         * filter constraint is specified. Thus, this operation will need to be re-implemented for
         * each supported grammar.
         * If the input parameter contains data that the match operation is not designed to handle,
         * the UnsupportedFilterableData exception will be raised. An example of this would
         * be if the filterable data contained a field whose name corresponds to a standard event
         * field that has a numeric value, but the actual value associated with this field name
         * within the event is a string.
         */
        boolean match_typed ( in CosNotification::PropertySeq filterable_data,
                out any result_to_set )
            raises ( UnsupportedFilterableData );

    }; // MappingFilter


    /**
     * The FilterFactory interface defines operations for creating filter objects.
     */
    interface FilterFactory
    {

        /**
         * The create_filter operation is responsible for creating a new forwarding filter object.
         * It takes as input a string parameter which identifies the grammar in which constraints
         * associated with this filter will have meaning. If the client invoking this operation
         * supplies as input the name of a grammar that is not supported by any forwarding filter
         * implementation this factory is capable of creating, the InvalidGrammar exception is
         * raised. Otherwise, the operation returns the reference to an object supporting the Filter
         * interface, which can subsequently be configured to support constraints in the
         * appropriate grammar.
         *
         * @param constraint_grammar Language of filter's constraints
         * @return THe new filter
         * @exception org.omg.CosNotifyFilter.InvalidGrammar The specified grammar is not valid
         */
        Filter create_filter (
              in string constraint_grammar )
            raises ( InvalidGrammar );

        /**
         * The create_mapping_filter operation is responsible for creating a new mapping filter
         * object. It takes as input a string parameter which identifies the grammar in which
         * constraints associated with this filter will have meaning, and an Any which will be set
         * as the default_value of the newly created mapping filter. If the client invoking this
         * operation supplies as input the name of a grammar that is not supported by any
         * mapping filter implementation this factory is capable of creating, the
         * InvalidGrammar exception is raised. Otherwise, the operation returns the reference to
         * an object supporting the MappingFilter interface, which can subsequently be
         * configured to support constraints in the appropriate grammar, along with their
         * associated mapping values.
         *
         *
         * @param constraint_grammar Language of filter's constraints
         * @return The new Mapping Filter
         * @exception org.omg.CosNotifyFilter.InvalidGrammar The specified grammar is not valid
         */
        MappingFilter create_mapping_filter ( in string constraint_grammar, in any default_value )
            raises ( InvalidGrammar );

    }; // FilterFactory

    typedef long FilterID;
    typedef sequence<FilterID> FilterIDSeq;

    exception FilterNotFound {};

    /**
     * The FilterAdmin interface defines operations that enable an object supporting this
     * interface to manage a list of filter objects, each of which supports the Filter interface.
     * This interface is intended to be an abstract interface which is inherited by all of the
     * Proxy and Admin interfaces defined by the Notification Service. The difference in the
     * semantics between a list of filter objects that is associated with an Admin object, and a
     * list that is associated with a Proxy object, is described in section 2.1.2 of the
     * specifiaction.
     */
    interface FilterAdmin
    {

        /**
         * The add_filter operation accepts as input the reference to an object supporting the
         * Filter interface. The affect of this operation is that the input filter object is
         * appended to the list of filter objects associated with the target object upon which the
         * operation was invoked. The operation associates with the newly added filter object a
         * numeric identifier that is unique among all filter objects currently associated with the
         * target, and returns that value as the result of the operation.
         *
         * @param new_filter filter to add
         * @return filter id
         */
        FilterID add_filter ( in Filter new_filter );

        /**
         * The remove_filter operation accepts as input a numeric value that is intended to be the
         * unique identifier of a filter object that is currently associated with the target object.
         * If the identifier supplied does correspond to a filter object currently associated with
         * the target object, then the corresponding filter object will be removed from the list of
         * filters associated with the target object. Otherwise, the FilterNotFound exception will
         * be raised.
         *
         * @param filter Id of the filter
         * @exception org.omg.CosNotifyFilter.FilterNotFound Id doesn't match to any filter
         */
        void remove_filter ( in FilterID filter )
           raises ( FilterNotFound );

        /**
         * The get_filter operation accepts as input a numeric identifier that is intended to
         * correspond to one of the filter objects currently associated with the target object. If
         * this is the case, the object reference of the corresponding filter object is returned.
         * Otherwise, the FilterNotFound exception is raised.
         *
         * @param filter Id of the filter to get
         * @return The filter object
         * @exception org.omg.CosNotifyFilter.FilterNotFound Id doesn't match to any filter
         */
        Filter get_filter ( in FilterID filter )
            raises ( FilterNotFound );

        /**
         * The get_all_filters operation accepts no input parameters, and returns the list of unique
         * identifiers which correspond to all of the filters currently associated with the target
         * object.
         *
         * @return Array of all filters's id
         */
        FilterIDSeq get_all_filters();

        /**
         * The remove_all_filters operation accepts no input parameters, and removes all filter
         * objects from the list of those currently associated with the target object.
         */
        void remove_all_filters();

    }; // FilterAdmin

}; // CosNotifyFilter

#endif /* _COS_NOTIFY_FILTER_IDL_ */
