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

siena

## Class NotificationInputSequencer

- java.lang.Object
- - siena.NotificationInputSequencer

- All Implemented Interfaces:
    Notifiable

      public class NotificationInputSequencer
      extends java.lang.Object
      implements Notifiable

  a notifiable wrapper that attempts to deliver notifications in the order they were published. An input sequencer can be used to provide sequence-ordered delivery of notifications to a subscriber. An input sequencer works, on the subscriber side, together with one or more output sequencers, each one associated with a publisher. An ouput sequencer identifies a logical sequence of notifications. A publisher that intends to publish notifications within a sequence must publish them through an output sequencer (see `NotificationOutputSequencer.publish(Notification)` or `NotificationOutputSequencer.tagNotification(Notification)`). Notifications published through an output sequencer are tagged with a sequence id, identifying that output sequencer, and therefore the logical sequence, and a sequence number, identifying a particular message within the same logical sequence.

  An input sequencer acts as a wrapper for a subscriber, intercepting notifications destined to the subscriber, and forwarding them on to the subscriber so as to guarantee the sequential ordering of messages within each sequence. In particular, an input sequencer maintains a table containing a buffer and some additional information for each active sequence. The input sequencer then processes incoming notifications as follows:

  - notifications that are not associated with any sequence are immediately passed on to the subscriber;
  - notifications that are associated with a sequence S and that have a sequence number that does not create any gaps with previously notified notifications in S, are also immediately passed on the the subscriber;
  - notifications that are associated with a sequence S and that have a sequence number that creates a gap with previously notified notifications in S are stored in a queue ordered by sequence number.
  - the first notification stored in the queue is passed on to the subscriber as soon as the gaps in the notifications sequence are correctly filled, or as soon as the notification buffer is full, or after a configurable amount of time, measured since the time the notification was received and inserted into the buffer.
  - notifications that have a sequence number lower than the one of the latest notification passed to the subscriber are dropped.

  In order to support multiple sequences, an input sequencer maintains a buffer and a counter for each sequence. The buffer and couter for sequence S are created as soon as the sequencer receives the first notification tagged with sequence id S. Since the sequencer can not determine when a sequence is no longer active, the sequencer deallocates buffers and counters by running a garbage-collection function at regular intervals. This fuction destroys sequence buffers and counters that have not been used for a configurable amount of time (see `setCleanupInterval(int)` and `setCleanupTimeout(long)`.)

  Example: ``

            Siena siena;
            Filter f;
            Notifiable n;
            // ...
            // siena = new ...
            // f = new Filter();
            // f.addConstraint ...
            // n = ...
            // ...
            NotificationInputSequencer sequencer;
            sequencer = new NotificationInputSequencer(n);
            siena.subscribe(f, sequencer);
            // ...

  See Also:
    `NotificationOutputSequencer`, `Notifiable`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DefaultBufferSize` default size for notification buffers.
    `static int` | `DefaultCleanupInterval` default interval before sequencer cleans up its buffers table.
    `static long` | `DefaultCleanupTimeout` default timeout before a sequence is considered dead.
    `static long` | `DefaultLatency` default maximum latency for buffered notifications Initial value is 10000ms (i.e., 10 seconds).

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NotificationInputSequencer(Notifiable c)` creates an input sequencer that wraps the given notifiable

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `void` | `setBufferSize(int s)` sets the size of sequence buffers The sequencer stores out-of-sequence notifications in sequence buffers, waiting for notifications to come in to fill the sequence gaps.
    `void` | `setCleanupInterval(int i)` sets the number of new sequences seen before a table cleanup The sequencer runs a periodic cleanup function to deallocate buffers and counters for inactive sequences.
    `void` | `setCleanupTimeout(long t)` sets the amount of idle time before a sequence buffer is considered inactive.
    `void` | `setLatency(long l)` sets the maximum latency for queued notifications Notifications that would create a gap in their sequence are buffered by the sequencer.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DefaultBufferSize

          public static int DefaultBufferSize

      default size for notification buffers. Initial value is 50.
      See Also:
        `setBufferSize(int)`

    - #### DefaultLatency

          public static long DefaultLatency

      default maximum latency for buffered notifications Initial value is 10000ms (i.e., 10 seconds).
      See Also:
        `setLatency(long)`

    - #### DefaultCleanupInterval

          public static int DefaultCleanupInterval

      default interval before sequencer cleans up its buffers table. The sequencer uses a cleanup function to remove the state associated with sequences that are considered dead. This cleanup function is executed periodically, when the sequencer sees a new sequece id. This parameter determines the number of new sequence ids seen before the cleanup function is triggered.

      A negative value means infinite, that means that the cleanup function is never executed. Initial value is 16.

      See Also:
        `setCleanupInterval(int)`

    - #### DefaultCleanupTimeout

          public static long DefaultCleanupTimeout

      default timeout before a sequence is considered dead. Initial value is 600000 (i.e., 10 minutes).
      See Also:
        `setCleanupTimeout(long)`

  - ### Constructor Detail

    - #### NotificationInputSequencer

          public NotificationInputSequencer(Notifiable c)

      creates an input sequencer that wraps the given notifiable

  - ### Method Detail

    - #### setLatency

          public void setLatency(long l)

      sets the maximum latency for queued notifications Notifications that would create a gap in their sequence are buffered by the sequencer. The sequencer then waits for other notifications to come in to fill the sequence gap. This parameter determines the maximum amount of time, in milliseconds, that a sequencer would wait before passing the notification on to the subscriber.
      See Also:
        `DefaultLatency`

    - #### setBufferSize

          public void setBufferSize(int s)

      sets the size of sequence buffers The sequencer stores out-of-sequence notifications in sequence buffers, waiting for notifications to come in to fill the sequence gaps. This parameter determines the size of sequence buffers.
      See Also:
        `DefaultBufferSize`

    - #### setCleanupInterval

          public void setCleanupInterval(int i)

      sets the number of new sequences seen before a table cleanup The sequencer runs a periodic cleanup function to deallocate buffers and counters for inactive sequences. A sequence is considered inactive is no messages are received for that sequence for more than a configurable amount of time (see `setCleanupTimeout(long)`.) This parameter determines how often this cleanup function is executed by the sequencer. In particular, the cleanup function is executed before a new sequence is activated, every i new sequences.
      See Also:
        `DefaultCleanupInterval`

    - #### setCleanupTimeout

          public void setCleanupTimeout(long t)

      sets the amount of idle time before a sequence buffer is considered inactive. A sequence is considered inactive when no notifications are received for that sequence in more than T milliseconds. This method sets the value of T for this sequencer. The buffers and counters associated with inactive sequences are periodically garbage-collected and destroyed.
      See Also:
        `DefaultCleanupTimeout`

    - #### notify

          public void notify(Notification n)
                      throws SienaException

      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
      Throws:
        `SienaException`
      See Also:
        `Siena.subscribe(Filter,Notifiable)`

    - #### notify

          public void notify(Notification[] s)
                      throws SienaException

      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
      Throws:
        `SienaException`
      See Also:
        `Siena.subscribe(Pattern,Notifiable)`

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