siena
Class NotificationBuffer

java.lang.Object
  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