All Packages Class Hierarchy This Package Previous Next Index
Class iBus.layers.REACH
java.lang.Object
|
+----iBus.ProtocolObject
|
+----iBus.layers.REACH
- public class REACH
- extends ProtocolObject
- implements Runnable
REACH: Reachability membership layer
REACH is a simple membership layer. It does *not* provide
Virtual Synchrony. REACH multicasts a periodic heartbeat posting on
each channel
the stack is subscribed to. When REACH receives the first heartbeat posting
from a stack, it creates a View object including the URL of that
stack, along with the URLs of all the other stacks it knows about.
The View is then passed up the stack via upHandleEvent ().
If REACH hasn't been receiving heartbeats from a stack it knows about
for a certain amount of time (defined by REACH.timeout_), it forms
an iBus.View object that excludes that stack, and passes the View up
via upHandleEvent ().
A View contains a vector of ChannelMember objects. A ChannelMember
contains the url of a group member, and whether it is a talker, a listener,
or both. Note that a view change is triggered also when a member
changes its talker/listener status.
Hence, REACH delivers view information that includes the stacks that
appear to be reachable. It does not run any distributed view change
protocol but relies solely on heartbeat information and timeouts.
REACH can be used in conjunction with NAK, making
NAK more reliable by providing it with information on which stacks are
subscribed to a channel. Now NAK can ensure that all the known receivers
have received a certain message, before flushing that message from the
message retransmission cache.
Multiple receivers: Note that when multiple receiver objects are
subscribed
in the same application, then only the *first* subscription triggers a view
change. Hence you can subscribe many local objects to a channel by
triggering just one view change. Only when the *last* local receiver has
unsubscribed a view change is triggered.
Fast registration/unregistration: If an application calls
unregisterTalker and then registerTalker on a given topic, it is likely
that the receivers will not detect that since no heartbeat is missed.
Therefore a registration ID is maintaned per channel. registerTalker
increments the ID and the heartbeat carries it to the receivers.
On detection of a new registration ID a receiver triggers a view change.
PARAMETERS:
-
hbeat: int: > 0. The interval in missliseconds inbetween are-you-alive
heartbeats. Default: 2000.
-
timeout: int: > 0. The timeout in missliseconds after which a stack is
declared as crahed. For applications with many channel members and
heavy traffic, you might want to set this parameter to 15000 or higher,
to reduce the probability of falsely suspecting a healthy
stack as crashed. The higher the value, the longer it takes to
detect a failure. The lower the value, the higher the risk of false
suspicion and message loss. Default: 8 * hbeat.
-
fdetect: int: 0|1. Whether to do failure detection at all. Default: 1.
DESIGN:
-
The REACH layer consists of the following classes: REACH,
REACH_GroupInfo, REACH_GroupMember, REACH_HbeatParam. REACH is the
protocol object, it maintains a Hashtable with one REACH_GroupInfo
for each channel the stack is registered for
(both as a talker or as a listener).
REACH_GroupInfo maintains a Hashtable with one REACH_GroupMember
per channel member it has received a heartbeat from. REACH_HbeatParam
is piggybacekd on outgoing heartbeats.
POSITION IN STACK:
-
Typically just atop IPMCAST, in any case below any NAK layer
.
Only layers residing atop REACH receive view change notifications.
EVENTS PRODUCED:
-
a View event when a new subscriber is detected, or when heartbeats
have been missing from a certain subscriber stack (up)
-
periodical heartbeat postings (down)
EVENTS CONSUMED:
-
Event.evHeartbeat sent by REACH layers.
THREADS:
-
A thread REACH.run() that periodically sends heartbeats and also checks
for missing heartbeats.
- See Also:
- View
-
REACH()
- Create the protocol object.
-
deliverLocalViewChanges()
-
deliver any views that have changed to the layers above,
by calling upHandleEvent.
-
dnInit()
- Initialize the protocol object after the protocol stack has been
created.
-
dnRegisterTalker(iBusURL)
- Called by the object above or by an iBus application to register
as a talker for a channel.
-
dnSubscribe(iBusURL)
- Called by the object above or by an iBus application to subscribe
for a certain channel.
-
dnTerminate()
- Terminate any threads in the protocol object.
-
dnUnregisterTalker(iBusURL)
- Called by the object above or by an iBus application to unregister
as a talker from a channel.
-
dnUnsubscribe(iBusURL)
- Called by the object above or by an iBus application to unsubscribe
from a certain channel.
-
getGroupInfo(iBusURL)
- Returns the GroupInfo object for a member.
-
getHbeat()
- Returns the hbeat property.
-
getTimeout()
- Returns the timeout property.
-
heartBeatChannel(iBusURL)
- convert an iBus channel to an URL that denotes the associated
heartbeat channel.
-
isFdetect()
- Returns the fdetect property.
-
removeGroupInfo(iBusURL)
- Remove the GroupInfo object for member.
-
run()
- A thread that periodically sends heartbeats and also checks
for missing heartbeats:
-
sendHeartbeat(REACH_GroupMember, iBusURL)
- Sends a heartbeat a certain hannel specified.
-
setFdetect(boolean)
- Set the fdetect property.
-
setGroupInfo(REACH_GroupInfo)
- Add a GroupInfo object to groupinfos_.
-
setHbeat(int)
- Set the hbeat property.
-
setTimeout(int)
- Set the timeout property.
-
startHeartbeat(iBusURL, boolean, boolean, int)
- Do the registration necessary to start transmitting heartbeats
for a given channel.
-
stopHeartbeat(iBusURL, boolean, boolean)
- Called by dnUnsubscribe and dnUnregisterTalker to stop the heartbeat
for a given channel.
-
upHandleEvent(Event)
- Called by the protocol object below to pass an event up to me.
REACH
public REACH()
- Create the protocol object.
dnInit
public synchronized void dnInit()
- Initialize the protocol object after the protocol stack has been
created. Also checks that the right parameters were given to the
protocol object.
- Overrides:
- dnInit in class ProtocolObject
dnTerminate
public void dnTerminate()
- Terminate any threads in the protocol object.
- Overrides:
- dnTerminate in class ProtocolObject
dnSubscribe
public synchronized void dnSubscribe(iBusURL channel) throws AlreadySubscribed, CommException
- Called by the object above or by an iBus application to subscribe
for a certain channel.
- Parameters:
- channel - the channel to subscribe to
- Throws: AlreadySubscribed
- if this stack is already
subscribed to channel
- Throws: CommException
- in case of a communication
error
- Overrides:
- dnSubscribe in class ProtocolObject
dnUnsubscribe
public synchronized void dnUnsubscribe(iBusURL channel) throws NotSubscribed, CommException
- Called by the object above or by an iBus application to unsubscribe
from a certain channel.
- Parameters:
- channel - the channel to unsubscribe from
- Throws: NotSubscribed
- if this stack is not subscribed
to channel
- Throws: CommException
- in case of a communication
error
- Overrides:
- dnUnsubscribe in class ProtocolObject
dnRegisterTalker
public synchronized void dnRegisterTalker(iBusURL channel) throws AlreadyRegistered, CommException
- Called by the object above or by an iBus application to register
as a talker for a channel.
- Parameters:
- channel - the channel to register for
- Throws: AlreadyRegistered
- if this stack is already
registered for the channel
- Throws: CommException
- in case of a communication
error
- Overrides:
- dnRegisterTalker in class ProtocolObject
dnUnregisterTalker
public synchronized void dnUnregisterTalker(iBusURL channel) throws NotRegistered, CommException
- Called by the object above or by an iBus application to unregister
as a talker from a channel.
- Parameters:
- channel - the channel to unregister from
- Throws: NotRegistered
- if this stack is not
registered with the channel
- Throws: CommException
- in case of a communication
error
- Overrides:
- dnUnregisterTalker in class ProtocolObject
upHandleEvent
public void upHandleEvent(Event event)
- Called by the protocol object below to pass an event up to me.
An event can be the arrival of a posting, the detection of a failure,
a flow control request, etc.
- Parameters:
- event - determines the type of event
- Overrides:
- upHandleEvent in class ProtocolObject
run
public void run()
- A thread that periodically sends heartbeats and also checks
for missing heartbeats:
getHbeat
public int getHbeat()
- Returns the hbeat property.
- Returns:
- the hbeat property
setHbeat
public void setHbeat(int hbeat)
- Set the hbeat property.
- Parameters:
- hbeat - the value of the hbeat property
getTimeout
public int getTimeout()
- Returns the timeout property.
- Returns:
- the timeout property
setTimeout
public void setTimeout(int timeout)
- Set the timeout property.
- Parameters:
- timeout - the value of the hbeat property
isFdetect
public boolean isFdetect()
- Returns the fdetect property.
- Returns:
- the fdetect property
setFdetect
public void setFdetect(boolean fd)
- Set the fdetect property.
- Parameters:
- fd - the new value of the fdetect property
sendHeartbeat
protected void sendHeartbeat(REACH_GroupMember gm,
iBusURL hbChannel)
- Sends a heartbeat a certain hannel specified.
- Parameters:
- gm - the GroupMember object describing the channel
- hbChannel - the URL of the heartbeat channel
startHeartbeat
protected void startHeartbeat(iBusURL channel,
boolean isListener,
boolean isTalker,
int rid) throws CommException
- Do the registration necessary to start transmitting heartbeats
for a given channel.
NOTE: no exception is thrown in case of double subscription
since doSubscribe is called by both dnSubscribe and
dnregisterTalker
- Parameters:
- channel - the channel to subscribe to
- isListener - true, if a listener is being registered
- isTalker - true, if a talker is being registered
- rid - registration ID used to find out when a talker has
unsubscribed and subscribed without the receiver missing the
heartbeat
- Throws: CommException
- in case of a communication
error
stopHeartbeat
protected boolean stopHeartbeat(iBusURL channel,
boolean isListener,
boolean isTalker) throws CommException
- Called by dnUnsubscribe and dnUnregisterTalker to stop the heartbeat
for a given channel.
- Parameters:
- channel - the channel to unsubscribe from
- isListener - true, if a listener is being unregistered
- isTalker - true, if a talker is being unregistered
- Returns:
- false if no registration exists
- Throws: CommException
- in case of a communication
error
getGroupInfo
protected REACH_GroupInfo getGroupInfo(iBusURL member)
- Returns the GroupInfo object for a member. null is returned
if no such GroupInfo exists.
- Parameters:
- member - the URL for the member's GroupInfo
- Returns:
- GroupInfo object for member. null is returned
if no such GroupInfo exists.
setGroupInfo
protected synchronized boolean setGroupInfo(REACH_GroupInfo gi)
- Add a GroupInfo object to groupinfos_. If a matching GroupInfo already
exists then it is replaced by gi and false is returned.
- Parameters:
- gi - the GroupInfo object to add to groupinfos_. Replace
any matching GroupInfo in groupinfos_.
- Returns:
- true if no matching gi exists, false otherwise.
removeGroupInfo
protected synchronized void removeGroupInfo(iBusURL member)
- Remove the GroupInfo object for member.
- Parameters:
- member - the URL of the GroupInfo to remove
deliverLocalViewChanges
protected void deliverLocalViewChanges()
- deliver any views that have changed to the layers above,
by calling upHandleEvent.
heartBeatChannel
protected static iBusURL heartBeatChannel(iBusURL url)
- convert an iBus channel to an URL that denotes the associated
heartbeat channel.
- Parameters:
- url - the iBus URL to convert
- Returns:
- the URL of the heartbeat channel for url
All Packages Class Hierarchy This Package Previous Next Index