Siena (v.1.5.5) API documentation

siena
Interface Siena

All Known Implementing Classes:
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
 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

Siena (v.1.5.5) API documentation

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