|
Siena (v.1.5.5) API documentation | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectsiena.HierarchicalDispatcher
public class HierarchicalDispatcher
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. 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
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 |
---|
public int DefaultThreadCount
setReceiver(PacketReceiver, int)
for
the semantics of this value. DefaultThreadCount
is used to create threads upon call to setReceiver(PacketReceiver)
.
setReceiver(PacketReceiver)
,
setReceiver(PacketReceiver,int)
,
setMaster(String)
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
Constructor Detail |
---|
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()
Method Detail |
---|
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 file
SienaException
- 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
file
SienaException
- wrong format for the store filepublic void setPacketSenderFactory(PacketSenderFactory f)
setDefaultPacketSenderFactory(PacketSenderFactory)
public static void setDefaultPacketSenderFactory(PacketSenderFactory f)
setPacketSenderFactory(PacketSenderFactory)
public void processOneRequest() throws SienaException
MaxFailedConnectionsDuration
is 5000 (i.e., 5 seconds).
SienaException
DefaultThreadCount
,
setReceiver(PacketReceiver)
,
setReceiver(PacketReceiver, int)
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 setListener(int port) throws java.io.IOException
setReceiver()
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
java.io.IOException
- when the given port is already in usepublic 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)
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 suspended
SienaException
Siena.resume(siena.Notifiable)
public void resume(Notifiable n) throws SienaException
Siena
n
.
resume
in interface Siena
n
- subscriber to be resumed
SienaException
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 subscriber
SienaException
Siena.unsubscribe(siena.Filter, siena.Notifiable)
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 subscriber
SienaException
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 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 publisher
SienaException
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 publisher
SienaException
Siena.unadvertise(siena.Filter, java.lang.String)
public void unadvertise(java.lang.String id) throws SienaException
unadvertise
in interface Siena
id
- identifier of the publisher
SienaException
Siena.unadvertise(siena.Filter, java.lang.String)
public void unsubscribe(Notifiable n) throws SienaException
Siena
unsubscribe
in interface Siena
n
- is the subscriber
SienaException
Siena.subscribe(siena.Filter, siena.Notifiable)
|
Siena (v.1.5.5) API documentation | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |