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

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

    Constructors
    Constructor and Description
    `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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 `Notification`s 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 `Notification`s 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`

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