public class HierarchicalDispatcher extends java.lang.Object implements Siena, java.lang.Runnable
HierarchicalDispatcher
can serve as a Siena event service for
local (same Java VM) clients as well as remote clients.
HierarchicalDispatcher
s 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)
Siena
,
ThinClient
Modifier and Type | Field and Description |
---|---|
int |
chokePeriod |
protected int |
cleanup_max_r |
protected long |
cleanup_max_t |
protected int |
cleanup_rounds |
protected long |
cleanup_time |
protected siena.ContactsTable |
contacts |
int |
DefaultThreadCount
default number of threads handling external requests.
|
protected SFFHeartbeat |
heartbeat |
protected siena.IFManager |
ifmanager |
protected PacketReceiver |
listener |
protected siena.NeighborNode |
master |
protected Interface |
master_interface |
protected java.util.List<siena.PatternMatcher> |
matchers |
long |
MaxFailedConnectionsDuration
milliseconds before automatic unsubscription is activated.
|
int |
MaxFailedConnectionsNumber
number of failed notifications before a subscriber is implicitly
disconnected.
|
protected byte[] |
my_identity |
protected boolean |
sff |
protected SFFTable |
sffTable |
protected byte[] |
sndbuf |
protected siena.SENPPacket |
spkt |
protected java.lang.String |
storeFileName |
protected siena.Poset |
subscriptions |
protected java.util.Map<siena.Subscriber,siena.SimplePredicate> |
subscriptionsMap |
Constructor and Description |
---|
HierarchicalDispatcher()
creates a dispatcher.
|
HierarchicalDispatcher(java.lang.String id)
creates a dispatcher with a specific identity.
|
Modifier and Type | Method and Description |
---|---|
void |
advertise(Filter f,
java.lang.String id)
this method has no effect.
|
void |
clearSubscriptions()
removes all subscriptions from any notifiable.
|
protected void |
configure(siena.SENPPacket req) |
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.
|
protected siena.Subscriber |
map_subscriber(siena.SENPPacket req) |
protected void |
map(siena.SENPPacket req) |
void |
processOneRequest()
process a single request, using the caller's thread.
|
protected void |
processRequest(siena.SENPPacket req) |
void |
publish(Notification e)
publish a notification.
|
protected void |
publish(siena.SENPPacket req) |
void |
resume(Notifiable n)
resumes the delivery of notifications to the given subscriber
n . |
protected void |
resume(siena.SENPPacket req) |
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.
|
void |
setChoke(int chokePeriod) |
static void |
setDefaultPacketSenderFactory(PacketSenderFactory f)
default packet-sender factory for HierarchicalDispatcher interfaces
every new HierarchicalDispatcher objects is assigned this factory
|
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 |
startHeartbeat() |
void |
subscribe(Filter f,
Notifiable n)
subscribes for events matching Filter f.
|
protected void |
subscribe(Filter f,
siena.Subscriber s,
siena.SENPPacket req) |
void |
subscribe(Pattern p,
Notifiable n)
subscribes for sequences of events matching pattern p.
|
protected void |
subscribe(siena.SENPPacket req) |
void |
suspend(Notifiable n)
suspends the delivery of notifications to the given subscriber
n . |
protected void |
suspend(siena.SENPPacket req) |
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.
|
protected void |
unsubscribe(Filter f,
siena.Subscriber s,
siena.SENPPacket req) |
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.
|
protected void |
unsubscribe(siena.SENPPacket req) |
void |
updateFWTable() |
protected int cleanup_max_r
protected int cleanup_rounds
protected long cleanup_time
protected long cleanup_max_t
protected java.lang.String storeFileName
protected siena.Poset subscriptions
protected siena.ContactsTable contacts
protected siena.IFManager ifmanager
protected Interface master_interface
protected siena.NeighborNode master
protected PacketReceiver listener
protected byte[] my_identity
protected java.util.List<siena.PatternMatcher> matchers
protected siena.SENPPacket spkt
protected byte[] sndbuf
public int chokePeriod
protected SFFHeartbeat heartbeat
protected SFFTable sffTable
protected java.util.Map<siena.Subscriber,siena.SimplePredicate> subscriptionsMap
protected boolean sff
public int DefaultThreadCount
setReceiver(PacketReceiver, int)
for the semantics of this
value. DefaultThreadCount
is used to create threads upon
call to setReceiver(PacketReceiver)
.public int MaxFailedConnectionsNumber
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!
}
MaxFailedConnectionsDuration
public long MaxFailedConnectionsDuration
MaxFailedConnectionsDuration
is 5000
(i.e., 5 seconds).MaxFailedConnectionsNumber
public HierarchicalDispatcher(java.lang.String id)
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.
id
- identity given to the dispatcher.public HierarchicalDispatcher()
public void setStoreRefreshTimeout(long t)
The default timeout is 10000 (i.e., 10 seconds).
public void setStoreRefreshCounter(int c)
setStoreRefreshTimeout(long)
for a more formal description of
the semantics of this parameter.
The default counter value is 5.
public void initStore(java.lang.String fn) throws java.io.IOException, SienaException
setStoreRefreshTimeout(long)
and
setStoreRefreshCounter(int)
for information on how to configure
the refresh rate of the storage mechanism.java.io.IOException
- on errors opening the given store fileSienaException
- wrong format for the store filepublic void saveSubscriptions(java.lang.String fname) throws java.io.IOException
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.java.io.IOException
- on errors writing into the given store filepublic void loadSubscriptions(java.lang.String fname) throws java.io.IOException, SienaException
initStore(String)
if a storage file already exists.java.io.IOException
- on errors reading from the given store fileSienaException
- wrong format for the store filepublic void setPacketSenderFactory(PacketSenderFactory f)
public static void setDefaultPacketSenderFactory(PacketSenderFactory f)
public void startHeartbeat()
public void processOneRequest() throws SienaException
MaxFailedConnectionsDuration
is 5000
(i.e., 5 seconds).public void run()
run
in interface java.lang.Runnable
public void setReceiver(PacketReceiver r)
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.
r
- is the receivershutdown()
,
setReceiver(PacketReceiver, int)
public void setReceiver(PacketReceiver r, int threads)
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.r
- the packet receiverthreads
- 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()
.shutdown()
,
setMaster(String)
public void setMaster(java.lang.String address) throws InvalidSenderException, java.io.IOException, PacketSenderException
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.
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.InvalidSenderException
java.io.IOException
PacketSenderException
setReceiver(PacketReceiver)
,
shutdown()
public void suspendMaster()
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.resumeMaster()
public void resumeMaster()
suspendMaster()
public java.lang.String getIdentity()
HierarchicalDispatcher(String)
public java.lang.String getMaster()
null
if the master
server is not setsetMaster(String)
public PacketReceiver getReceiver()
setReceiver(PacketReceiver)
protected void processRequest(siena.SENPPacket req)
protected void configure(siena.SENPPacket req)
protected void map(siena.SENPPacket req)
protected void suspend(siena.SENPPacket req)
protected void resume(siena.SENPPacket req)
protected void publish(siena.SENPPacket req)
protected void subscribe(siena.SENPPacket req) throws InvalidSenderException, SienaException
InvalidSenderException
SienaException
protected void unsubscribe(Filter f, siena.Subscriber s, siena.SENPPacket req)
protected void unsubscribe(siena.SENPPacket req) throws InvalidSenderException, SienaException
InvalidSenderException
SienaException
protected siena.Subscriber map_subscriber(siena.SENPPacket req) throws InvalidSenderException
InvalidSenderException
public void shutdown()
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.
shutdown
in interface Siena
setReceiver(PacketReceiver)
,
setMaster(String)
public void clearSubscriptions() throws SienaException
SienaException
shutdown()
public void publish(Notification e) throws SienaException
Siena
publish
in interface Siena
e
- The notification to publish.SienaException
Notification
public void suspend(Notifiable n) throws SienaException
Siena
n
.suspend
in interface Siena
n
- subscriber to be suspendedSienaException
Siena.resume(siena.Notifiable)
public void resume(Notifiable n) throws SienaException
Siena
n
.resume
in interface Siena
n
- subscriber to be resumedSienaException
Siena.resume(siena.Notifiable)
public void subscribe(Filter f, Notifiable n) throws SienaException
Siena
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.
subscribe
in interface Siena
f
- is the subscriptionn
- is the subscriberSienaException
Siena.unsubscribe(siena.Filter, siena.Notifiable)
protected void subscribe(Filter f, siena.Subscriber s, siena.SENPPacket req) throws SienaException
SienaException
public void subscribe(Pattern p, Notifiable n) throws SienaException
Siena
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.
subscribe
in interface Siena
p
- is the subscription patternn
- is the subscriberSienaException
Siena.unsubscribe(siena.Filter, siena.Notifiable)
public void unsubscribe(Filter f, Notifiable n)
Siena
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.
unsubscribe
in interface Siena
n
- is the subscriberSiena.subscribe(siena.Filter, siena.Notifiable)
public void unsubscribe(Pattern p, Notifiable n)
Siena
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.
unsubscribe
in interface Siena
n
- is the subscriberSiena.subscribe(siena.Filter, siena.Notifiable)
public void updateFWTable()
public void advertise(Filter f, java.lang.String id) throws SienaException
advertise
in interface Siena
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 publisherSienaException
Siena.unadvertise(siena.Filter, java.lang.String)
public void unadvertise(Filter f, java.lang.String id) throws SienaException
unadvertise
in interface Siena
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 publisherSienaException
Siena.unadvertise(siena.Filter, java.lang.String)
public void unadvertise(java.lang.String id) throws SienaException
unadvertise
in interface Siena
id
- identifier of the publisherSienaException
Siena.unadvertise(siena.Filter, java.lang.String)
public void unsubscribe(Notifiable n) throws SienaException
Siena
unsubscribe
in interface Siena
n
- is the subscriberSienaException
Siena.subscribe(siena.Filter, siena.Notifiable)
public void setChoke(int chokePeriod)
Copyright © 2005-2011 Antonio Carzaniga.
This documentation is maintained by Antonio Carzaniga