Siena (v.1.5.5) API documentation

siena
Class HierarchicalDispatcher

java.lang.Object
  extended by siena.HierarchicalDispatcher
All Implemented Interfaces:
java.lang.Runnable, Siena

public class HierarchicalDispatcher
extends java.lang.Object
implements Siena, java.lang.Runnable

implementation of a Siena event notification service. This is the primary implementation of the Siena event notification service. A HierarchicalDispatcher can serve as a Siena event service for local (same Java VM) clients as well as remote clients. HierarchicalDispatchers can also be combined in a distributed architecture with other dispatchers. Every dispatcher can be connected to a master dispatcher, thereby forming a hierarchical structure. The hierarchy of dispatchers is assembled incrementally as new dispatchers are created and connected to a master that already belongs to the hierarchy.

A HierarchicalDispatcher uses a PacketReceiver to receive notifications, subscriptions and unsubscriptions from external clients and from its master dispatcher. In order to receive and process external requests, a HierarchicalDispatcher can either use a pool of internal threads, or it can use users' threads. See DefaultThreadCount, setReceiver(PacketReceiver), and setReceiver(PacketReceiver, int)

See Also:
Siena, ThinClient

Field Summary
 int DefaultThreadCount
          default number of threads handling external requests.
 long MaxFailedConnectionsDuration
          milliseconds before automatic unsubscription is activated.
 int MaxFailedConnectionsNumber
          number of failed notifications before a subscriber is implicitly disconnected.
 
Constructor Summary
HierarchicalDispatcher()
          creates a dispatcher.
HierarchicalDispatcher(java.lang.String id)
          creates a dispatcher with a specific identity.
 
Method Summary
 void advertise(Filter f, java.lang.String id)
          this method has no effect.
 void clearSubscriptions()
          removes all subscriptions from any notifiable.
 java.lang.String getIdentity()
          returns the identity of this dispatcher.
 java.lang.String getMaster()
          returns the address of the master server associated with this dispatcher.
 PacketReceiver getReceiver()
          returns the listener associated with this dispatcher.
 void initStore(java.lang.String fn)
          initializes the subscription storage mechanism.
 void loadSubscriptions(java.lang.String fname)
          loads remote subscriptions and client information from a file.
 void processOneRequest()
          process a single request, using the caller's thread.
 void publish(Notification e)
          publish a notification.
 void resume(Notifiable n)
          resumes the delivery of notifications to the given subscriber n.
 void resumeMaster()
          resumes the connection with the master server.
 void run()
           
 void saveSubscriptions(java.lang.String fname)
          saves remote subscriptions and client information to a file.
static void setDefaultPacketSenderFactory(PacketSenderFactory f)
          default packet-sender factory for HierarchicalDispatcher interfaces every new HierarchicalDispatcher objects is assigned this factory
 void setListener(int port)
          Deprecated. as of Siena 1.1.0, replaced by setReceiver()
 void setMaster(java.lang.String address)
          connects this dispatcher to a master dispatcher.
 void setPacketSenderFactory(PacketSenderFactory f)
          sets the packet-sender factory associated with this HierarchicalDispatcher
 void setReceiver(PacketReceiver r)
          sets the packet receiver for this server.
 void setReceiver(PacketReceiver r, int threads)
          sets the packet receiver for this server.
 void setStoreRefreshCounter(int c)
          configures the subscription storage mechanism.
 void setStoreRefreshTimeout(long t)
          configures the subscription storage mechanism.
 void shutdown()
          closes this dispatcher.
 void subscribe(Filter f, Notifiable n)
          subscribes for events matching Filter f.
 void subscribe(Pattern p, Notifiable n)
          subscribes for sequences of events matching pattern p.
 void suspend(Notifiable n)
          suspends the delivery of notifications to the given subscriber n.
 void suspendMaster()
          suspends the connection with the master server of this dispatcher.
 void unadvertise(Filter f, java.lang.String id)
          this method has no effect.
 void unadvertise(java.lang.String id)
          this method has no effect.
 void unsubscribe(Filter f, Notifiable n)
          cancels the subscriptions, posted by n, whose filter f' is covered by filter f.
 void unsubscribe(Notifiable n)
          cancels all the subscriptions posted by n.
 void unsubscribe(Pattern p, Notifiable n)
          cancels the subscriptions, posted by n, whose pattern p' is covered by pattern p.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DefaultThreadCount

public int DefaultThreadCount
default number of threads handling external requests. Every HierarchicalDispatcher creates a pool of threads to read and process incoming requests. This parameter determines the default number of threads in the pool. The initial default value is 5. See setReceiver(PacketReceiver, int) for the semantics of this value. DefaultThreadCount is used to create threads upon call to setReceiver(PacketReceiver).

See Also:
setReceiver(PacketReceiver), setReceiver(PacketReceiver,int), setMaster(String)

MaxFailedConnectionsNumber

public int MaxFailedConnectionsNumber
number of failed notifications before a subscriber is implicitly disconnected. The default value of MaxFailedConnectionNumber is 2. HierachicalDispatcher implements a garbage collection mechanism for unreachable subscribers. This mechanism implicitly unsubscribes a client when the dispatcher fails to connect to the client for a given number of times and after a given number of milliseconds. More formally, the dispatcher considers the sequence of consecutive failed connections not followed by any successful connection. This sequence is charachterized by two parameters: its length and its duration.

MaxFailedConnectionsNumber represents the upper bound to the length of the sequence, while MaxFailedConnectionsDuration represents the upper bound to the duration of the sequence. For both parameters, a negative value means infinity. removeUnreachableSubscriber() removes all the subscriptions of those subscribers that have not been reachable for more than MaxFailedConnectionsNumber times and more than MaxFailedConnectionsDuration milliseconds. Formally, a subscriber that has not been reachable for T milliseconds for N notifications will be removed according to the following conditions:


        if (MaxFailedConnectionsNumber >= 0 
      && MaxFailedConnectionsDuration >= 0) {
      if (T > MaxFailedConnectionsDuration 
          && N > MaxFailedConnectionsNumber)
          remove it!
        } else if (MaxFailedConnectionsNumber >= 0) {
      if (N > MaxFailedConnectionsNumber)
          remove it!
        } else if (MaxFailedConnectionsDuration >= 0) {
            if (T > MaxFailedConnectionsDuration)
                remove it!
        }
  

See Also:
MaxFailedConnectionsDuration

MaxFailedConnectionsDuration

public long MaxFailedConnectionsDuration
milliseconds before automatic unsubscription is activated. The default value of MaxFailedConnectionsDuration is 5000 (i.e., 5 seconds).

See Also:
MaxFailedConnectionsNumber
Constructor Detail

HierarchicalDispatcher

public HierarchicalDispatcher(java.lang.String id)
creates a dispatcher with a specific identity. Every object involved in Siena communications must have a unique identity. Strictly speaking, with the hierarchical protocol (used by this implementation) the identity of an object must be unique within the group of clients of the same master server. However, because client-master connections can be dynamically reconfigured, it is best to use globally-unique identities.

Also, notice that the hierarchical protocol reserves the identity "\000" for its internal use. Therefore, the string "\000" must never be used as an identity.

Parameters:
id - identity given to the dispatcher.

HierarchicalDispatcher

public HierarchicalDispatcher()
creates a dispatcher.

Method Detail

setStoreRefreshTimeout

public void setStoreRefreshTimeout(long t)
configures the subscription storage mechanism. This server will refresh its database of subscriptions after processing an incoming request, whenever it has processed more than n subscription or unsubscription requests, or t milliseconds have passed since the last refresh. requests that may be processed without refreshing the subscription storage.

The default timeout is 10000 (i.e., 10 seconds).


setStoreRefreshCounter

public void setStoreRefreshCounter(int c)
configures the subscription storage mechanism. Determines the maximum number of subscription or unsubscription requests that may be processed without refreshing the subscription store. See setStoreRefreshTimeout(long) for a more formal description of the semantics of this parameter.

The default counter value is 5.


initStore

public void initStore(java.lang.String fn)
               throws java.io.IOException,
                      SienaException
initializes the subscription storage mechanism. The server implements a periodic persistent storage mechanism for subscriptions and contact information for remote clients. This method defines the storage file name. If a storage file already exists, the server attempts to load previously saved subscriptions from that file. This mechanism is periodic in the sense that the server flushes its tables to a file at configurable intervals. See setStoreRefreshTimeout(long) and setStoreRefreshCounter(int) for information on how to configure the refresh rate of the storage mechanism.

Throws:
java.io.IOException - on errors opening the given store file
SienaException - wrong format for the store file

saveSubscriptions

public void saveSubscriptions(java.lang.String fname)
                       throws java.io.IOException
saves remote subscriptions and client information to a file. Saves the all the contact information regarding remote subscribers, and all their subscriptions into the given file. This method is implicitly called at configurable intervals by the storage function of the server. See initStore(String) for information on how to initialize the automatic storage mechanism, and setStoreRefreshTimeout(long) and setStoreRefreshCounter(int) for information on how to configure the refresh rate of the storage mechanism.

Throws:
java.io.IOException - on errors writing into the given store file

loadSubscriptions

public void loadSubscriptions(java.lang.String fname)
                       throws java.io.IOException,
                              SienaException
loads remote subscriptions and client information from a file. This method can be called to load subscriptions and contact information from a file. This method is implicitly called by initStore(String) if a storage file already exists.

Throws:
java.io.IOException - on errors reading from the given store file
SienaException - wrong format for the store file

setPacketSenderFactory

public void setPacketSenderFactory(PacketSenderFactory f)
sets the packet-sender factory associated with this HierarchicalDispatcher

See Also:
setDefaultPacketSenderFactory(PacketSenderFactory)

setDefaultPacketSenderFactory

public static void setDefaultPacketSenderFactory(PacketSenderFactory f)
default packet-sender factory for HierarchicalDispatcher interfaces every new HierarchicalDispatcher objects is assigned this factory

See Also:
setPacketSenderFactory(PacketSenderFactory)

processOneRequest

public void processOneRequest()
                       throws SienaException
process a single request, using the caller's thread. The default value of MaxFailedConnectionsDuration is 5000 (i.e., 5 seconds).

Throws:
SienaException
See Also:
DefaultThreadCount, setReceiver(PacketReceiver), setReceiver(PacketReceiver, int)

run

public void run()
Specified by:
run in interface java.lang.Runnable

setReceiver

public void setReceiver(PacketReceiver r)
sets the packet receiver for this server. A packet receiver accepts notifications, subscriptions, and other requests on some communication channel. setReceiver will shut down any previously activated receiver for this dispatcher. This method does not guarantee a transactional switch to a new receiver. This means that some requests might get lost while the server has closed the old port and before it reopens the new port.

This method simply calls setReceiver(PacketReceiver, int) using DefaultThreadCount as a default value.

Parameters:
r - is the receiver
See Also:
shutdown(), setReceiver(PacketReceiver, int)

setReceiver

public void setReceiver(PacketReceiver r,
                        int threads)
sets the packet receiver for this server. A packet receiver accepts notifications, subscriptions, and other requests on some communication channel. setReceiver will shut down any previously activated receiver for this dispatcher. This method does not guarantee a transactional switch to a new receiver. This means that some requests might get lost while the server has closed the old port and before it reopens the new port.

Parameters:
r - the packet receiver
threads - is the number of threads associated with the receiver, and therefore to the whole server. A positive value causes this dispatcher to create threads. A value of 0 causes the dispatcher not to create any thread, In this case, the application must explicitly call processOneRequest().
See Also:
shutdown(), setMaster(String)

setListener

public void setListener(int port)
                 throws java.io.IOException
Deprecated. as of Siena 1.1.0, replaced by setReceiver()

creates a TCP-based packet receiver for this server.

Parameters:
port - is the port number allocated by the listener, 0 allocates a random available port number, the default value for Siena is SENP.DEFAULT_PORT
Throws:
java.io.IOException - when the given port is already in use

setMaster

public void setMaster(java.lang.String address)
               throws InvalidSenderException,
                      java.io.IOException,
                      PacketSenderException
connects this dispatcher to a master dispatcher. If this dispatcher is already connected to a master dispatcher, setMaster disconnects the old one and connects the new one, thereby unsubscribing all the top-level subscriptions and resubscribing with the new one. This method should be used only when this dispatcher needs to switch to a different master, it is not necessary (it is in fact very inefficient) to set the master before every subscription or notification.

This method does not guarantee a transactional switch. This means that some notifications might be lost when the server has detached from the old master and before it re-subscribes with the new master_interface.

If this dispatcher does not have a packet receiver associated with it, setMaster implicitly sets up one for the dispatcher. The default receiver is a TCPPacketReceiver listening to a randomly allocated port. If you are not happy with the default decision, you should call setReceiver() before you call setMaster.

When address is null, simply disconnect from the current master server.

Parameters:
address - is the external identifier of the master dispatcher (e.g., "ka:host.domain.edu:8765"), or null to disconnect from the ccurrent master server.
Throws:
InvalidSenderException
java.io.IOException
PacketSenderException
See Also:
setReceiver(PacketReceiver), shutdown()

suspendMaster

public void suspendMaster()
suspends the connection with the master server of this dispatcher. This causes the master server to stop sending notification to this dispatcher. The master correctly maintains all the existing subscriptions so that the flow of notification can be later resumed (see resumeMaster. This operation can be used when this dispatcher, that is this virtual machine, is going to be temporarily disconnected from the network or somehow unreachable from its master server.

See Also:
resumeMaster()

resumeMaster

public void resumeMaster()
resumes the connection with the master server. This causes the master server to resume sending notification to this dispatcher.

See Also:
suspendMaster()

getIdentity

public java.lang.String getIdentity()
returns the identity of this dispatcher. every object in a Siena network has a unique identifier. This method returns the identifier of this dispatcher.

See Also:
HierarchicalDispatcher(String)

getMaster

public java.lang.String getMaster()
returns the address of the master server associated with this dispatcher.

Returns:
address of the master server or null if the master server is not set
See Also:
setMaster(String)

getReceiver

public PacketReceiver getReceiver()
returns the listener associated with this dispatcher.

Returns:
receiver of this dispatcher (possibly null)
See Also:
setReceiver(PacketReceiver)

shutdown

public void shutdown()
closes this dispatcher. If this dispatcher has an active listener then closes the active listener. If this dispatcher has a master server, then cancels every subscription with the master server.

Some implementations of the Java VM do not respond correctly to shutdown(). In particular, Sun's jvm1.3rc1-linux is known not to work correctly. Sun's jvm1.3-solaris, jvm1.3-win32, and jvm1.2.2-linux work correctly.

Specified by:
shutdown in interface Siena
See Also:
setReceiver(PacketReceiver), setMaster(String)

clearSubscriptions

public void clearSubscriptions()
                        throws SienaException
removes all subscriptions from any notifiable. clears all the subscriptions from local or remote clients. In case this server has a master server, it instructs the master server to clear all the subscriptions associated with this dispatcher. This method is also useful in case this dispatcher re-uses both a listener and an identity from a previous dispatcher that crashed or did not otherwise shutdown properly.

Throws:
SienaException
See Also:
shutdown()

publish

public void publish(Notification e)
             throws SienaException
Description copied from interface: Siena
publish a notification.

Specified by:
publish in interface Siena
Parameters:
e - The notification to publish.
Throws:
SienaException
See Also:
Notification

suspend

public void suspend(Notifiable n)
             throws SienaException
Description copied from interface: Siena
suspends the delivery of notifications to the given subscriber n.

Specified by:
suspend in interface Siena
Parameters:
n - subscriber to be suspended
Throws:
SienaException
See Also:
Siena.resume(siena.Notifiable)

resume

public void resume(Notifiable n)
            throws SienaException
Description copied from interface: Siena
resumes the delivery of notifications to the given subscriber n.

Specified by:
resume in interface Siena
Parameters:
n - subscriber to be resumed
Throws:
SienaException
See Also:
Siena.resume(siena.Notifiable)

subscribe

public void subscribe(Filter f,
                      Notifiable n)
               throws SienaException
Description copied from interface: Siena
subscribes for events matching Filter f.

Notice that given the distributed nature of some implementations of Siena, there exist race conditions that might affect the semantics of subscriptions. Specifically, a subscriber might miss some notifications published before (or while) the subscription is processed by Siena.

Specified by:
subscribe in interface Siena
Parameters:
f - is the subscription
n - is the subscriber
Throws:
SienaException
See Also:
Siena.unsubscribe(siena.Filter, siena.Notifiable)

subscribe

public void subscribe(Pattern p,
                      Notifiable n)
               throws SienaException
Description copied from interface: Siena
subscribes for sequences of events matching pattern p.

Notice that given the distributed nature of some implementations of Siena interface, there exist race conditions that might affect the semantics of subscriptions. A subscriber might miss some notifications published before or while the subscription is processed by Siena.

Also, keep in mind that the current implementation of Siena does not enforce any temporal order for the delivery of notifications. This limitation might affect the recognition of patterns. For example, two notifications x and y, generated at time tx and ty respectively, with tx < ty, in that order matching a pattern P=(fx fy), might in fact reach the subscriber at times Tx and Ty, with Tx > Ty, in which case pattern P would not be matched.

Specified by:
subscribe in interface Siena
Parameters:
p - is the subscription pattern
n - is the subscriber
Throws:
SienaException
See Also:
Siena.unsubscribe(siena.Filter, siena.Notifiable)

unsubscribe

public void unsubscribe(Filter f,
                        Notifiable n)
Description copied from interface: Siena
cancels the subscriptions, posted by n, whose filter f' is covered by filter f.

Unsubscriptions might incurr in the same kind of race conditions as subscriptions. Siena will stop sending notifications to the subscriber only after it has completed the processing of the unsubscriptions. Due to the distributed nature of some implementations of Siena, this might result in some additional ``unsolicited'' notifications.

Specified by:
unsubscribe in interface Siena
n - is the subscriber
See Also:
Siena.subscribe(siena.Filter, siena.Notifiable)

unsubscribe

public void unsubscribe(Pattern p,
                        Notifiable n)
Description copied from interface: Siena
cancels the subscriptions, posted by n, whose pattern p' is covered by pattern p.

Unsubscriptions might incurr in the same kind of race conditions as subscriptions. Siena will stop sending notifications to the subscriber only after it has completed the processing of the unsubscription. Due to the distributed nature of some implementations of Siena, this might result in some additional ``unsolicited'' notifications.

Specified by:
unsubscribe in interface Siena
n - is the subscriber
See Also:
Siena.subscribe(siena.Filter, siena.Notifiable)

advertise

public void advertise(Filter f,
                      java.lang.String id)
               throws SienaException
this method has no effect. Method not implemented in this Siena server.

Specified by:
advertise in interface Siena
Parameters:
f - advertisement filter. Notice that this filter is interpreted differently than a subscription filter. For more information, consult the Siena documentation.
id - identifier of the publisher
Throws:
SienaException
See Also:
Siena.unadvertise(siena.Filter, java.lang.String)

unadvertise

public void unadvertise(Filter f,
                        java.lang.String id)
                 throws SienaException
this method has no effect. Method not implemented in this Siena server.

Specified by:
unadvertise in interface Siena
Parameters:
f - advertisement filter. Notice that this filter is interpreted differently than a subscription filter. For more information, consult the Siena documentation.
id - identifier of the publisher
Throws:
SienaException
See Also:
Siena.unadvertise(siena.Filter, java.lang.String)

unadvertise

public void unadvertise(java.lang.String id)
                 throws SienaException
this method has no effect. Method not implemented in this Siena server.

Specified by:
unadvertise in interface Siena
Parameters:
id - identifier of the publisher
Throws:
SienaException
See Also:
Siena.unadvertise(siena.Filter, java.lang.String)

unsubscribe

public void unsubscribe(Notifiable n)
                 throws SienaException
Description copied from interface: Siena
cancels all the subscriptions posted by n.

Specified by:
unsubscribe in interface Siena
Parameters:
n - is the subscriber
Throws:
SienaException
See Also:
Siena.subscribe(siena.Filter, siena.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