//
// Event Service Specification (as of February 6th)
//
// Read this design document for further implementation information:
// 'http://www.cca-forum.org/download/spec/EventSpecificationIssues.pdf'


/** Exception used by EventService, Topic and Subscription methods. */
interface EventServiceException extends CCAException {
}

/** Interface to Event Service for a event publisher. A publisher can
    send events by acquiring a specific topic on which to publish. */
interface PublisherEventService extends cca.Port {

  /** Get a Topic by passing a name that has the form X.Y.Z. The
      method creates a topic of topicName it if it doesn't exist.

	  @topicName - A dot delimited, hierarchical name of the topic
                   on which to publish. Wildcard characters are not
                   allowed for a topicName.

      see also: http://www.cca-forum.org/download/spec/EventSpecificationIssues.pdf
  */
  cca.Topic getTopic(in string topicName) throws EventServiceException;

  /** Returns true if topic already exists, false otherwise */
  bool existsTopic(in string topicName);
}

/** Interface to Event Service for a event subscriber. In order to get
    events delivered to us we use this service to get a Subscription
    and register a listener to this Subscription. In order to force
    the event service to process the events in the queue, a subscriber
    may call processEvents() */
interface SubscriberEventService extends cca.Port {

  /** Subscribe to one or more topics. 

      @subscriptionName - A dot delimited hierarchical name selecting
                          the list of topics to get events from. Wildcard 
                          characters (*,?)  are allowed for a subscriptionName 
                          to denote more than one topic.

      see also: http://www.cca-forum.org/download/spec/EventSpecificationIssues.pdf
  */
  cca.Subscription getSubscription(in string subscriptionName) 
	throws EventServiceException;

  /** Process published events. When the subscriber calls this method,
      this thread or some other one delivers each event by calling
      processEvent(...) on each listener belonging to each specific
      Subscription */
  void processEvents() throws EventServiceException;
}

/** Payload of an event. The event's header is created
    by the framework and may contain a timestamp or information
    about the publisher etc. The body of the event is created
    by the publisher using the Topic interface.*/
interface Event extends sidl.io.Serializable {

  /** Return the event's header. The header is usually generated
      by the framework and holds bookkeeping information

  */
  cca.TypeMap getHeader();

  /** Returs the event's body. The body is the information the 
      publisher is sending to the subscribers
  */
  cca.TypeMap getBody();
}

/** Interface implemented by components interested in events. */
interface EventListener {

  /** This is where event processing by a listener takes place. This
      is a call-back method that a topic subscriber implements and 
      gets called for each new event.

      @topicName - The topic for which the Event was created and sent.
      @theEvent - The payload.
  */
  void processEvent(in string topicName, copy in Event theEvent);
}

/** Interface through which events are sent by publishers. */  
interface Topic {

  /** Returns the topic name associated with this object */
  string getTopicName();

  /** Publish an event. 
	  
      @eventName - The name of this event. It is perhaps not a crucial
                   piece of information. Can be inserted into the
                   header or the body of the event by the event
                   service.
      @eventBody - A typemap containing all the information to be 
                   sent out.
  */
  void sendEvent(in string eventName, in cca.TypeMap eventBody) 
	throws EventServiceException;
}

/** Mechanism for keeping track of a subscription of one or more
    topics. A subscription corresponds to one or more publishing
    topics.*/
interface Subscription {

  /** Adds a listener to the collection of listeners for this Subscription.
      
      @listenerKey - It is used as an index to the collection (STL
                     map) and the parameter \em theListener is a
                     pointer to the /em Listener class.
      @theListener - A pointer to the object that will listen for events.
  */
  void registerEventListener(in string listenerKey, in EventListener theListener) 
            throws EventServiceException;

  /**
     Removes a listener from the collection of listeners for this Topic.

     @listenerKey - It is used as an index to remove this listener.
   */
  void unregisterEventListener(in string listenerKey);

  /** Returns the name for this Subscription object */
  string getSubscriptionName();
}