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

/**
 * @file CosNotifyComm.idl
 *
 * @brief Define the CosNotifyComm 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_COMM_IDL_
#define _COS_NOTIFY_COMM_IDL_

#include "CosNotification.idl"
#include "CosEventComm.idl"

#pragma prefix "omg.org"

/**
 * @namespace CosNotifyComm
 *
 * @brief Define the interfaces implemented by users of the CORBA
 *        Notification Service.
 */
module CosNotifyComm
{
  /**
   * @exception InvalidEventType
   *
   * @brief Exception raised to indicate that an EventType is
   * syntactically or semantically invalid.
   */
  exception InvalidEventType {
    /// Type of invalid event
    CosNotification::_EventType type;
  };

  /**
   * @interface NotifyPublish
   *
   * @brief Defines interface to report changes in the events
   *        published to a consumer.
   *
   * Interfaces that represent consumers (or the consumer aspects of
   * an Notification Service) provide this interface to receive
   * notifications in the list of events they support.
   */
  interface NotifyPublish {
    /// Report a change in the list of publications.
    /**
     * @param added The list of new event types that the consumer can
     *   expect.
     * @param removed The list of event types that the consumer should
     *   no longer expect.
     * @throws InvalidEventType if the one or more event types
     *   provided is invalid
     */
    void offer_change (in CosNotification::EventTypeSeq added,
                       in CosNotification::EventTypeSeq removed )
      raises ( InvalidEventType );
  };

  /**
   * @interface NotifySubscribe
   *
   * @brief Defines interface to report changes in the events required
   *        from a supplier.
   *
   * Interfaces that represent suppliers (or the supplier aspects of
   * the Notification Service) provide this interface to receive
   * changes
   */
  interface NotifySubscribe {
    /// Report a change in the list of subscriptions
    /**
     * @param added The list of new event types that are interesting
     *   for the supplier's peer.
     * @param removed The list of event types that are no longer
     *   interesting for the supplier's peer.
     * @throws InvalidEventType if the one or more event types
     *   provided is invalid
     */
    void subscription_change(in CosNotification::EventTypeSeq added,
                             in CosNotification::EventTypeSeq removed )
      raises ( InvalidEventType );
  };

  /**
   * @interface PushConsumer
   *
   * @brief Defines the interface used by push-style consumers
   *
   * Push-style consumers passively accept events as anys.
   */
  interface PushConsumer :
    NotifyPublish,
    CosEventComm::PushConsumer {
  };

  /**
   * @interface PullConsumer
   *
   * @brief Defines the interface used by pull-style consumers
   *
   * Pull-style consumer actively query the Notification Service to
   * receive events.
   */
  interface PullConsumer :
    NotifyPublish,
    CosEventComm::PullConsumer {
  };

  /**
   * @interface PullSupplier
   *
   * @brief Defines the interface used by pull-style suppliers
   *
   * Pull-style suppliers passively provide events to the Notification
   * Service.
   */
  interface PullSupplier :
    NotifySubscribe,
    CosEventComm::PullSupplier {
  };

  /**
   * @interface PushSupplier
   *
   * @brief Defines the interface used by push-style suppliers
   *
   * Push-style suppliers actively provide events to the Notifcation
   * Service.
   */
  interface PushSupplier :
    NotifySubscribe,
    CosEventComm::PushSupplier {
  };

  /**
   * @interface StructuredPushConsumer
   *
   * @brief Defines the interface used by push-style consumers of
   * structured events
   *
   * Push-style consumers passively receive events from the
   * Notification Service.  The events are provided using the
   * CosNotification::StructuredEvent structure.
   */
  interface StructuredPushConsumer : NotifyPublish {
    /// Receive one structured event
    /**
     * This operation is invoked to provide one event to the
     * consumer.
     * @throws CosEventComm::Disconnected if the object considers
     *   itself no longer connected to its peer.
     */
    void push_structured_event(
              in CosNotification::StructuredEvent notification)
      raises(CosEventComm::Disconnected);

    /// The peer has disconnected
    /**
     * This operation is invoked by the consumer peer when it wishes
     * to disconnect.  The consumer can safely assume that no more
     * events will follow this request.
     */
    void disconnect_structured_push_consumer();
  };

  /**
   * @interface StructuredPullConsumer
   *
   * @brief Defines the interface used by pull-style consumers of
   * structured events
   *
   * Pull-style consumers actively retrieve events from the
   * Notification Service.  The events use the
   * CosNotification::StructuredEvent format.
   */
  interface StructuredPullConsumer : NotifyPublish {
    /// The peer has disconnected
    /**
     * This operation is invoked by the consumer peer when it wishes
     * to disconnect.  The consumer can safely assume that no more
     * events will follow this request.
     */
    void disconnect_structured_pull_consumer();
  };

  /**
   * @interface StructuredPullSupplier
   *
   * @brief Defines the interface used by pull-style suppliers of
   * structured events
   *
   * Pull-style suppliers passively generate events for the
   * Notification Service.  The events use the
   * CosNotification::StructuredEvent format.
   */
  interface StructuredPullSupplier : NotifySubscribe {
    /// Pull (blocking) one event from the supplier.
    /**
     * This operation should block until the next event becomes
     * available.
     * @throws CosEventComm::Disconnected if the object considers
     *   itself no longer connected to its peer.
     */
    CosNotification::StructuredEvent pull_structured_event()
      raises(CosEventComm::Disconnected);

    /// Pull (non-blocking) one event from the supplier.
    /**
     * The try_pull operation does not block: if the event data is
     * available, it returns the event data and sets the has_event
     * parameter to true; if the event is not available, it sets the
     * has_event parameter to false and the event data is returned
     * as long with an undefined value.
     * @throws CosEventComm::Disconnected if the object considers
     *   itself no longer connected to its peer.
     */
    CosNotification::StructuredEvent try_pull_structured_event(
                                out boolean has_event)
      raises(CosEventComm::Disconnected);

    /// The peer has disconnected
    /**
     * This operation is invoked by the consumer peer when it wishes
     * to disconnect.  The consumer can safely assume that no more
     * events will follow this request.
     */
    void disconnect_structured_pull_supplier();
  };

  /**
   * @interface StructuredPushSupplier
   *
   * @brief Defines the interface used by push-style suppliers that
   *   provide structure events.
   *
   * Push-style suppliers actively provide events, in this case using
   * the CosEventComm::StructuredEvent format.
   */
  interface StructuredPushSupplier : NotifySubscribe {
    /// The peer has disconnected
    /**
     * This operation is invoked by the consumer peer when it wishes
     * to disconnect.  The consumer can safely assume that no more
     * events will follow this request.
     */
    void disconnect_structured_push_supplier();
  };

  /**
   * @interface SequencePushConsumer
   *
   * @brief Defines the interface used by push-style consumers that
   *   interested in event batches.
   *
   * Push-style consumer passively accept events, in this case
   * multiple events can be delivered simulatneously.
   */
  interface SequencePushConsumer : NotifyPublish {
    /// Receive an event batch
    /**
     * This operation is invoked to provide an event batch to the
     * consumer.
     * @throws CosEventComm::Disconnected if the object considers
     *   itself no longer connected to its peer.
     */
    void push_structured_events(
              in CosNotification::EventBatch notifications)
      raises(CosEventComm::Disconnected);

    /// The peer has disconnected
    /**
     * This operation is invoked by the consumer peer when it wishes
     * to disconnect.  The consumer can safely assume that no more
     * events will follow this request.
     */
    void disconnect_sequence_push_consumer();
  };

  /**
   * @interface SequencePullConsumer
   *
   * @brief Defines the interface used by pull-style consumers that
   * deal with event batches.
   *
   * Pull-style consumer actively query the Notification Service for
   * events, this particular interface can obtain multiple events
   * simultaneously.
   */
  interface SequencePullConsumer : NotifyPublish {
    /// The peer has disconnected
    /**
     * This operation is invoked by the consumer peer when it wishes
     * to disconnect.  The consumer can safely assume that no more
     * events will follow this request.
     */
    void disconnect_sequence_pull_consumer();
  };

  /**
   * @interface SequencePullSupplier
   *
   * @brief Defines the interface used by pull-style suppliers that
   * provide event batches.
   *
   * Pull-style suppliers passively provide events to the Notification
   * Service. This particular interface can provide multiple events
   * simultaneously.
   */
  interface SequencePullSupplier : NotifySubscribe {
    /// Pull (blocking) an event batch from the supplier
    /**
     * @param max_number Maximum number of events expected by the
     *        caller.
     * @throws CosEventComm::Disconnected if the object considers
     *   itself no longer connected to its peer.
     */
    CosNotification::EventBatch pull_structured_events(
                                in long max_number )
      raises(CosEventComm::Disconnected);

    /// Pull (non-blocking) an event batch from the supplier
    /**
     * @param max_number Maximum number of events expected by the
     *        caller.
     * @param has_event Return FALSE if there are no events available,
     *        TRUE otherwise.
     * @throws CosEventComm::Disconnected if the object considers
     *   itself no longer connected to its peer.
     */
    CosNotification::EventBatch try_pull_structured_events(
                                in long max_number,
                                out boolean has_event)
      raises(CosEventComm::Disconnected);

    /// The peer has disconnected
    /**
     * This operation is invoked by the consumer peer when it wishes
     * to disconnect.  The consumer can safely assume that no more
     * events will follow this request.
     */
    void disconnect_sequence_pull_supplier();
  };

  /**
   * @interface SequencePushSupplier
   *
   * @brief Defines the interface used by push-style suppliers that
   * provide event batches.
   *
   * Push-style suppliers actively generate events for the
   * Notification Service. This particular interface can provide
   * multiple events simultaneously.
   */
  interface SequencePushSupplier : NotifySubscribe {
    /// The peer has disconnected
    /**
     * This operation is invoked by the consumer peer when it wishes
     * to disconnect.  The consumer can safely assume that no more
     * events will follow this request.
     */
    void disconnect_sequence_push_supplier();
  };
};

#pragma prefix ""

#endif /* _COS_NOTIFY_COMM_IDL_ */