path: root/TAO/orbsvcs/orbsvcs/CosNotifyFilter.idl

/**
 * @file CosNotifyFilter.idl
 *
 * @brief Defines the CosNotifyFilter module
 *
 * $Id$
 *
 * This module is taken from the standard CORBA Notification Service
 * 1.0, as described in:
 *
 * http://www.omg.org/technology/documents/formal/notification_service.htm
 *
 * In particular the following two documents were used:
 * formal/2000-06-20
 * formal/01-03-03
 *
 * @author Pradeep Gore <pradeep@cs.wustl.edu>
 */

#ifndef _COS_NOTIFY_FILTER_IDL_
#define _COS_NOTIFY_FILTER_IDL_

#include <orb.idl>

#include "CosNotifyComm.idl"

#pragma prefix "omg.org"

/**
 * @namespace CosNotifyFilter
 *
 * @brief Defines the interfaces used in Event Filtering
 */
module CosNotifyFilter
{
  /// Constraints are assigned IDs by each Filter object, and can be
  /// modified using those IDs.
  typedef long ConstraintID;

  /**
   * @struct ConstraintExp
   *
   * @brief Defines a constraint expression.
   */
  struct ConstraintExp {
    /// The list of event types accepted
    CosNotification::EventTypeSeq event_types;
    /// A constraint (or filtering) expression
    string constraint_expr;
  };

  /// A sequence of constraint IDs
  typedef sequence<ConstraintID> ConstraintIDSeq;

  /// A sequence of constraint expressions
  typedef sequence<ConstraintExp> ConstraintExpSeq;

  /**
   * @struct ConstraintInfo
   *
   * @brief Helper data structure to modify a constraint expression.
   */
  struct ConstraintInfo {
    /// New constraint expression
    ConstraintExp constraint_expression;
    /// ID of the expression modified
    ConstraintID constraint_id;
  };

  /// Sequence of Constraint infos, modify multiple constraints.
  typedef sequence<ConstraintInfo> ConstraintInfoSeq;

  /**
   * @struct MappingConstraintPair
   *
   * @brief Helper structure used to modify a mapping constraint
   * expression.
   */
  struct MappingConstraintPair {
    /// Constraint expression
    ConstraintExp constraint_expression;
    /// Value to set in the property if the constraint expression
    /// matches
    any result_to_set;
  };

  /// Sequence of mapping constraint pairs
  typedef sequence<MappingConstraintPair> MappingConstraintPairSeq;

  /**
   * @struct MappingConstraintInfo
   *
   * @brief Helper structure used to represent a mapping constraint,
   * its property value and the ID assigned to it in a MappingFilter.
   */
  struct MappingConstraintInfo {
    ConstraintExp constraint_expression;
    ConstraintID constraint_id;
    any value;
  };
  /// A list of MappingConstraintInfo
  typedef sequence<MappingConstraintInfo> MappingConstraintInfoSeq;

  /// Each callback object receives a unique ID when it is attached to
  /// a Filter
  typedef long CallbackID;

  /// Batch management of callback objects in the Filter interface
  typedef sequence<CallbackID> CallbackIDSeq;

  /**
   * @exception UnsupportedFilterableData
   *
   * @brief Exception raised when an event with unsupported filtered
   * data is tested against a Filter.
   */
  exception UnsupportedFilterableData {};

  /**
   * @exception InvalidGrammar
   *
   * @brief Exception raised if the filtering expression is using an
   * invalid grammar.
   */
  exception InvalidGrammar {};

  /**
   * @exception InvalidConstraint
   *
   * @brief Exception raised if a constraint's grammar does not match
   *   the Filter grammar.
   *
   * The constraint that is deemed invalid is returned as part of the
   * exception.
   */
  exception InvalidConstraint {
    /// Constraint that caused the problem
    ConstraintExp constr;
  };

  /**
   * @exception DuplicateConstraintID
   *
   * @brief Exception raised if a duplicate ID is used while modifying
   * or removing multiple constraints.
   */
  exception DuplicateConstraintID {
    /// ID causing the problem
    ConstraintID id;
  };

  /**
   * @exception ConstraintNotFound
   *
   * @brief Exception raised if a constraint ID is not found while
   * modifying or removing multiple constraints.
   */
  exception ConstraintNotFound {
    /// ID causing the problem
    ConstraintID id;
  };

  /**
   * @exception CallbackNotFound
   *
   * @brief Exception raised if the application tries to remove a
   *        Filter callback that does not exists.
   */
  exception CallbackNotFound {};

  /**
   * @exception InvalidValue
   *
   * @brief Exception raised if a modification or addition of a
   * mapping constraint does not matches the mapping filter type.
   */
  exception InvalidValue {
    /// Constraint expression that cause the problem
    ConstraintExp constr;
    /// Value that caused the problem
    any value;
  };

  /**
   * @interface Filter
   *
   * @brief Interface used to manipulate and evaluate filters.
   *
   * An event filter posseses multiple constraints, each constraint
   * applies to a limited range of event types, the filter is accepted
   * if it matches one or more constraint expressions that apply to
   * its event type.
   */
  interface Filter {
    /// Constraint grammar used in this filter
    /**
     * All filtering expressions in the filter should use this
     * grammar.
     */
    readonly attribute string constraint_grammar;

    /// Add constraints to a filter
    /**
     * Return the constraints and their IDs.
     *
     * @throws InvalidConstraint if one or more constraints contain
     *    invalid an invalid expression in the Filter constraint
     *    grammar.
     */
    ConstraintInfoSeq add_constraints (
                          in ConstraintExpSeq constraint_list)
      raises (InvalidConstraint);

    /// Modify and/or remove multiple constraints in the Filter
    /**
     * The operation can raise InvalidConstraint if one or more
     * constraints contain invalid expressions in the constraint
     * grammar.
     *
     * @param del_list List of constraint IDs to be removed
     * @param modify_list List of constrained modified
     *
     * @throws ConstraintNotFound If one or more of the ConstraintID
     * supplied are not found.
     */
    void modify_constraints (
             in ConstraintIDSeq del_list,
             in ConstraintInfoSeq modify_list)
      raises (InvalidConstraint, ConstraintNotFound);

    /// Obtain the one or more constraints given their IDs
    /**
     * @param id_list List of IDs queried
     *
     * @throws ConstraintNotFound if one or more of
     * the ConstraintID supplied are not found.
     */
    ConstraintInfoSeq get_constraints(
                          in ConstraintIDSeq id_list)
      raises (ConstraintNotFound);

    /// The all the constraints in the Filter
    ConstraintInfoSeq get_all_constraints();

    /// Remove all the constraints from the Filter
    void remove_all_constraints();

    /// Destroy the Filter
    void destroy();

    /// Match a regular event against the constraints in the filter
    /**
     * @param filterable_data The Notification Service event to be
     *   tested against the constraints in this Filter
     * @return TRUE if at least one constraint evaluates to TRUE for
     *   the event.
     * @throws UnsupportedFilterableData if the event contents do not
     *    match the filtering expression, for example, if the
     *    expression for a filterable field expects a string, but the
     *    actual value is a number.
     */
    boolean match ( in any filterable_data )
      raises (UnsupportedFilterableData);

    /// Match a structured event against the constraints in the filter
    /**
     * @param filterable_data The Notification Service event to be
     *   tested against the constraints in this Filter
     * @return TRUE if at least one constraint expression evaluates
     *   to TRUE for the event.
     * @throws UnsupportedFilterableData if the event contents do not
     *    match the filtering expression, for example, if the
     *    expression for a filterable field expects a string, but the
     *    actual value is a number.
     */
    boolean match_structured (
                in CosNotification::StructuredEvent filterable_data )
      raises (UnsupportedFilterableData);

    /// Match a typed event against the constraints in the filter
    /**
     * @param filterable_data The sequence of properties that make the
     *   filterable portion of the Typed event.
     * @return TRUE if at least one constraint expression evaluates
     *   to TRUE for the event.
     * @throws UnsupportedFilterableData if the event contents do not
     *    match the filtering expression, for example, if the
     *    expression for a filterable field expects a string, but the
     *    actual value is a number.
     */
    boolean match_typed (
                in CosNotification::PropertySeq filterable_data )
      raises (UnsupportedFilterableData);

    /// Add a callback interface to the filter
    /**
     * Filters can communicate changes in the list of event types they
     * potentially accept.
     *
     * @param callback the object interested about changes in the
     *   Filter event type list.
     * @return A unique ID attached to the callback interface.
     */
    CallbackID attach_callback (
                   in CosNotifyComm::NotifySubscribe callback);

    /// Remove a callback interface from the filter
    /**
     * @param callback The ID of the callback removed
     *
     * @throws CallbackNotFound if the callback id supplied is not
     *   found in the internal list of callbacks.
     */
    void detach_callback ( in CallbackID callback)
      raises ( CallbackNotFound );

    /// Return all the callback IDs in the Filter object
    CallbackIDSeq get_callbacks();
  };

  /**
   * @interface MappingFilter
   *
   * @brief Mapping filters can be used to change properties of an
   *   event as it traverses the Notification Service.
   */
  interface MappingFilter {
    /// Return the constraint grammar used in the mapping filter
    readonly attribute string constraint_grammar;

    /// Return the type code for the property affected by this mapping
    /// filter
    readonly attribute CORBA::TypeCode value_type;

    /// Return the default value set by this mapping filter
    /**
     * The default value is used if there are no mapping constraint
     * expressions matching the event.
     */
    readonly attribute any default_value;

    /// Add multiple mapping constraints to the filter
    /**
     * @param pair_list List of constraint expressions and the
     *   corresponding property value
     *
     * @return The list of constraint expressions, their values, and
     *   the IDs assigned to them in this Filter.
     *
     * @throws InvalidConstraint if one or more constraint expressions
     *   do not match the constraint grammar of this mapping filter
     * @throws InvalidValue if the value in one or more mapping
     *   constraint pairs does not match the type code for this
     *   mapping filter.
     */
    MappingConstraintInfoSeq add_mapping_constraints (
                                in MappingConstraintPairSeq pair_list)
        raises (InvalidConstraint, InvalidValue);

    /// Modify and/or remove mapping constraints in the filter
    /**
     * @param del_list list of constraint IDs that should be removed
     * @param modify_list list of constraints that would be modified
     *
     * @throws InvalidConstraint if one or more constraint expressions
     *   do not match the constraint grammar of this mapping filter
     * @throws InvalidValue if the value in one or more mapping
     *   constraint pairs does not match the type code for this
     *   mapping filter.
     * @throws ConstraintNotFound if one or more mapping constraint
     *   IDs are not found in the filter
     */
    void modify_mapping_constraints (
             in ConstraintIDSeq del_list,
             in MappingConstraintInfoSeq modify_list)
      raises (InvalidConstraint, InvalidValue, ConstraintNotFound);

    /// Retrieve multiple mapping constraints from the filter
    /**
     * @param id_list the list of mapping constraint IDs requested
     * @return The list of constraint expressions, their values and
     *   IDs.
     * @throws ConstraintNotFound if one or more mapping constraint
     *   IDs are not found in the filter
     */
    MappingConstraintInfoSeq get_mapping_constraints (
                                 in ConstraintIDSeq id_list)
      raises (ConstraintNotFound);

    /// Get all the mapping constraints from the Filter
    MappingConstraintInfoSeq get_all_mapping_constraints();

    /// Remove all the mapping constraints in the Filter
    void remove_all_mapping_constraints();

    /// Destroy the mapping filter
    void destroy();

    /// Test an event against the mapping constraints
      boolean match ( in any filterable_data,
                      out any result_to_set )
        raises (UnsupportedFilterableData);

      boolean match_structured (
                  in CosNotification::StructuredEvent filterable_data,
                  out any result_to_set)
        raises (UnsupportedFilterableData);

      boolean match_typed (
                  in CosNotification::PropertySeq filterable_data,
                  out any result_to_set)
        raises (UnsupportedFilterableData);
  };

  /**
   * @interface FilterFactory
   *
   * @brief Create Filter and MappingFilter objects
   */
  interface FilterFactory {
    /// Create a new Filter object
    /**
     * @param constraint_grammar The name of the grammar used for this
     *   filter
     * @throws InvalidGrammar The grammar name provided is invalid or
     *   unsupported
     */
    Filter create_filter (in string constraint_grammar)
                        raises (InvalidGrammar);

    /// Create a new MappingFilter object
    /**
     * @param constraint_grammar The name of the grammar used for this
     *   filter
     * @param default_value The default property value used if no
     *   mapping constraint matches
     * @throws InvalidGrammar The grammar name provided is invalid or
     *   unsupported
     */
    MappingFilter create_mapping_filter (
                       in string constraint_grammar,
                       in any default_value)
      raises(InvalidGrammar);
  };

  /// Each filter is assigned a unique ID
  typedef long FilterID;

  /// List of filter IDs
  typedef sequence<FilterID> FilterIDSeq;

  /**
   * @exception FilterNotFound
   *
   * @brief Exception raised if a filter ID is not found.
   */
  exception FilterNotFound {};

  /**
   * @interface FilterAdmin
   *
   * @brief Interface used to modify the Filters attached to a
   *   Notification Service component
   */
  interface FilterAdmin {
    /// Add a filter
    /**
     * @param new_filter Filter to be added
     * @return The ID assigned to the new filter
     */
    FilterID add_filter ( in Filter new_filter );

    /// Remove a filter
    /**
     * @param filter ID of the filter to be removed
     * @throws FilterNotFound if the filter ID is not found in this
     *   FilterAdmin
     */
    void remove_filter ( in FilterID filter )
      raises ( FilterNotFound );

    /// Get a filter
    /**
     * @param filter ID of the filter returned
     * @return The filter
     * @throws FilterNotFound if the filter ID is not found in this
     *   FilterAdmin
     */
    Filter get_filter ( in FilterID filter )
      raises ( FilterNotFound );

    /// Get the IDs of all the filters
    /**
     * @return The list of all filter IDs in this component
     */
    FilterIDSeq get_all_filters();

    /// Remove all the filters from this component
    void remove_all_filters();
  };
};

#pragma prefix ""

#endif /* _COS_NOTIFY_FILTER_IDL_ */