Siena (Siena 2.0.4 API Documentation)
Date: 2015-05-17

siena

## Interface Siena

- All Known Implementing Classes:
    DVDRPDispatcher, HierarchicalDispatcher, ThinClient

      public interface Siena

  interface of the Siena event notification service. implementations of this interface are access points to the Siena service. Applications use them to publish, subscribe, unsubscribe, etc. Applications should `shutdown()` a Siena service access point when it is no longer needed.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `advertise(Filter f, java.lang.String id)` advertises a set of notifications.
    `void` | `publish(Notification n)` publish a notification.
    `void` | `resume(Notifiable n)` resumes the delivery of notifications to the given subscriber `n`.
    `void` | `shutdown()` closes this Siena service access point.
    `void` | `subscribe(Filter f, Notifiable n)` subscribes for events matching Filter f.
    `void` | `subscribe(Pattern p, Notifiable n)` subscribes for sequences of events matching pattern p.
    `void` | `suspend(Notifiable n)` suspends the delivery of notifications to the given subscriber `n`.
    `void` | `unadvertise(Filter f, java.lang.String id)` cancel previous advertisements.
    `void` | `unadvertise(java.lang.String id)` cancel all previous advertisements for object id.
    `void` | `unsubscribe(Filter f, Notifiable n)` cancels the subscriptions, posted by n, whose filter f' is covered by filter f.
    `void` | `unsubscribe(Notifiable n)` cancels all the subscriptions posted by n.
    `void` | `unsubscribe(Pattern p, Notifiable n)` cancels the subscriptions, posted by n, whose pattern p' is covered by pattern p.

- - ### Method Detail

    - #### publish

          void publish(Notification n)
                       throws SienaException

      publish a notification.
      Parameters:
        `n` - The notification to publish.
      Throws:
        `SienaException`
      See Also:
        `Notification`

    - #### subscribe

          void subscribe(Filter f,
                       Notifiable n)
                         throws SienaException

      subscribes for events matching Filter f.

      Notice that given the distributed nature of some implementations of Siena, there exist race conditions that might affect the semantics of subscriptions. Specifically, a subscriber might miss some notifications published before (or while) the subscription is processed by Siena.

      Parameters:
        `n` - is the subscriber
        `f` - is the subscription
      Throws:
        `SienaException`
      See Also:
        `unsubscribe(siena.Filter, siena.Notifiable)`

    - #### subscribe

          void subscribe(Pattern p,
                       Notifiable n)
                         throws SienaException

      subscribes for sequences of events matching pattern p.

      Notice that given the distributed nature of some implementations of Siena interface, there exist race conditions that might affect the semantics of subscriptions. A subscriber might miss some notifications published before or while the subscription is processed by Siena.

      Also, keep in mind that the current implementation of Siena does not enforce any temporal order for the delivery of notifications. This limitation might affect the recognition of patterns. For example, two notifications x and y, generated at time tx and ty respectively, with tx < ty, in that order matching a pattern P=(fx fy), might in fact reach the subscriber at times Tx and Ty, with Tx > Ty, in which case pattern P would not be matched.

      Parameters:
        `n` - is the subscriber
        `p` - is the subscription pattern
      Throws:
        `SienaException`
      See Also:
        `unsubscribe(siena.Filter, siena.Notifiable)`

    - #### unsubscribe

          void unsubscribe(Filter f,
                         Notifiable n)
                           throws SienaException

      cancels the subscriptions, posted by n, whose filter f' is covered by filter f.

      Unsubscriptions might incurr in the same kind of race conditions as subscriptions. Siena will stop sending notifications to the subscriber only after it has completed the processing of the unsubscriptions. Due to the distributed nature of some implementations of Siena, this might result in some additional ``unsolicited'' notifications.

      Parameters:
        `n` - is the subscriber
      Throws:
        `SienaException`
      See Also:
        `subscribe(siena.Filter, siena.Notifiable)`

    - #### unsubscribe

          void unsubscribe(Pattern p,
                         Notifiable n)
                           throws SienaException

      cancels the subscriptions, posted by n, whose pattern p' is covered by pattern p.

      Unsubscriptions might incurr in the same kind of race conditions as subscriptions. Siena will stop sending notifications to the subscriber only after it has completed the processing of the unsubscription. Due to the distributed nature of some implementations of Siena, this might result in some additional ``unsolicited'' notifications.

      Parameters:
        `n` - is the subscriber
      Throws:
        `SienaException`
      See Also:
        `subscribe(siena.Filter, siena.Notifiable)`

    - #### unsubscribe

          void unsubscribe(Notifiable n)
                           throws SienaException

      cancels all the subscriptions posted by n.
      Parameters:
        `n` - is the subscriber
      Throws:
        `SienaException`
      See Also:
        `subscribe(siena.Filter, siena.Notifiable)`

    - #### advertise

          void advertise(Filter f,
                       java.lang.String id)
                         throws SienaException

      advertises a set of notifications. Tells Siena that the object identified by id might publish notifications matching the advertisement filter f.
      Parameters:
        `f` - advertisement filter. Notice that this filter is interpreted differently than a subscription filter. For more information, consult the Siena documentation.
        `id` - identifier of the publisher
      Throws:
        `SienaException`
      See Also:
        `unadvertise(siena.Filter, java.lang.String)`

    - #### unadvertise

          void unadvertise(Filter f,
                         java.lang.String id)
                           throws SienaException

      cancel previous advertisements. Cancels those regarding publisher id, whose advertisement filter f' is covered by advertisement filter f.
      Parameters:
        `f` - advertisement filter. Notice that this filter is interpreted differently than a subscription filter. For more information, consult the Siena documentation.
        `id` - identifier of the publisher
      Throws:
        `SienaException`
      See Also:
        `unadvertise(siena.Filter, java.lang.String)`

    - #### unadvertise

          void unadvertise(java.lang.String id)
                           throws SienaException

      cancel all previous advertisements for object id.
      Parameters:
        `id` - identifier of the publisher
      Throws:
        `SienaException`
      See Also:
        `unadvertise(siena.Filter, java.lang.String)`

    - #### suspend

          void suspend(Notifiable n)
                       throws SienaException

      suspends the delivery of notifications to the given subscriber `n`.
      Parameters:
        `n` - subscriber to be suspended
      Throws:
        `SienaException`
      See Also:
        `resume(siena.Notifiable)`

    - #### resume

          void resume(Notifiable n)
                      throws SienaException

      resumes the delivery of notifications to the given subscriber `n`.
      Parameters:
        `n` - subscriber to be resumed
      Throws:
        `SienaException`
      See Also:
        `resume(siena.Notifiable)`

    - #### shutdown

          void shutdown()
                        throws SienaException

      closes this Siena service access point. This method releases any system resources associated with the access point. In case this access point is connected to other Siena servers, this method will properly disconnect it.
      Throws:
        `SienaException`

Copyright © 2000-2005 University of Colorado.
Copyright © 2005-2011 Antonio Carzaniga.
This documentation is maintained by Antonio Carzaniga