Siena (v.1.5.5) API documentation

siena
Class NotificationInputSequencer

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

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
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
NotificationInputSequencer(Notifiable c)
          creates an input sequencer that wraps the given notifiable
 
Method Summary
 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.
 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 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
Throws:
SienaException
See Also:
Siena.subscribe(Pattern,Notifiable)

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