Siena (v.1.5.5) API documentation

siena
Class NotificationBuffer

java.lang.Object
  extended by siena.NotificationBuffer
All Implemented Interfaces:
Notifiable

public class NotificationBuffer
extends java.lang.Object
implements Notifiable

a "mailbox" for notifications functions as a proxy notifiable. It receives and stores notifications and sequences of notifications from Siena. Notifications and sequences can be retrieved synchronously (blocking) or asynchronously (non-blocking).

Example:

      Siena siena;
      Filter f;
      // ...
      // siena = new ...
      // f = new Filter();
      // f.addConstraint ...
      // ...
      NotificationBuffer queue = new NotificationBuffer();
      siena.subscribe(f, queue);
      Notification n = queue.getNotification(-1); // infinite timeout
      System.out.println(n.toString());
  

Notice that NotificationBuffer handles notifications and sequences (of notifications) separately.

See Also:
Notification, Notifiable

Constructor Summary
NotificationBuffer()
          constructs an empty NotificationBuffer with unlimited capacity this NotificationBuffer will grow dynamically to store any number of notifications and sequences.
NotificationBuffer(int dimension)
          constructs an empty NotificationBuffer with limited capacity this NotificationBuffer will hold up to dimension notifications and dimension sequences.
 
Method Summary
 Notification getNotification()
          attempts to extract a notification (non-blocking) attempts to extract a notification.
 Notification getNotification(long timeout)
          attempts to extract a notification (blocking) attempts to extract a notification.
 Notification[] getSequence()
           
 Notification[] getSequence(long timeout)
          attempts to extract a sequence of notification (non-blocking) attempts to extract a sequence of notifications.
 int notificationsCount()
          number of available notifications
 void notify(Notification n)
          sends a Notification to this Notifable Since version 1.0.1 of the Siena API it is safe to modify the Notification object received through this method.
 void notify(Notification[] s)
          sends a sequence of Notifications to this Notifable Since version 1.0.1 of the Siena API it is safe to modify the Notification objects received through this method.
 int sequencesCount()
          the number of available sequences of notifications
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NotificationBuffer

public NotificationBuffer()
constructs an empty NotificationBuffer with unlimited capacity this NotificationBuffer will grow dynamically to store any number of notifications and sequences.


NotificationBuffer

public NotificationBuffer(int dimension)
constructs an empty NotificationBuffer with limited capacity this NotificationBuffer will hold up to dimension notifications and dimension sequences. If more notifications (or sequences) are received, stored notifications (or sequences) will be discarded on a first-in-first-out basis.

Parameters:
dimension - maximum capacity. Must be > 0
Method Detail

notificationsCount

public int notificationsCount()
number of available notifications

Returns:
count of available notifications

sequencesCount

public int sequencesCount()
the number of available sequences of notifications

Returns:
count of available sequences

notify

public void notify(Notification n)
Description copied from interface: Notifiable
sends a Notification to this Notifable Since version 1.0.1 of the Siena API it is safe to modify the Notification object received through this method. Note that:
  1. any previous version of the Siena API assumes that clients do not modify these notifications;
  2. the current solution incurrs in an unnecessary cost by having to duplicate every notification. Therefore, it is a temporary solution. The plan is to implement immutable notifications and to pass those to subscribers.
necessary duplication of notifications can be expensive, especially if the same notification must be copied to numerous subscribers.

Specified by:
notify in interface Notifiable
Parameters:
n - notification passed to the notifiable
See Also:
Siena.subscribe(Filter,Notifiable)

notify

public void notify(Notification[] s)
Description copied from interface: Notifiable
sends a sequence of Notifications to this Notifable Since version 1.0.1 of the Siena API it is safe to modify the Notification objects received through this method. Please read the notes in the above documentation of Notifiable.notify(Notification), which apply to this method as well.

Specified by:
notify in interface Notifiable
Parameters:
s - sequence of notifications passed to the notifiable
See Also:
Siena.subscribe(Pattern,Notifiable)

getNotification

public Notification getNotification()
attempts to extract a notification (non-blocking) attempts to extract a notification. This method returns immediately. It returns the first available notification or null if none is available.

Returns:
first available notification or null

getNotification

public Notification getNotification(long timeout)
                             throws java.lang.InterruptedException
attempts to extract a notification (blocking) attempts to extract a notification. This method might block if no notification is available. If the given timeout is > 0, this method blocks for at most timeout milliseconds, otherwise (when timeout <= 0) it blocks until a notification becomes available. It returns the first available notification or null in case the timeout expired.

Returns:
first available notification or null
Throws:
java.lang.InterruptedException

getSequence

public Notification[] getSequence()
                           throws java.lang.InterruptedException
Throws:
java.lang.InterruptedException

getSequence

public Notification[] getSequence(long timeout)
                           throws java.lang.InterruptedException
attempts to extract a sequence of notification (non-blocking) attempts to extract a sequence of notifications. This method might block if no notification is available. If the given timeout is > 0, this method blocks for at most timeout milliseconds, otherwise (when timeout >= 0) it blocks until a notification becomes available. It returns the first available notification or null in case the timeout expired.

Returns:
first available notification or null
Throws:
java.lang.InterruptedException

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