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:

DESIGN:

POSITION IN STACK:

EVENTS PRODUCED:

EVENTS CONSUMED:

THREADS:

See Also:
View

Constructor Index

 o REACH()
Create the protocol object.

Method Index

 o deliverLocalViewChanges()
deliver any views that have changed to the layers above, by calling upHandleEvent.
 o dnInit()
Initialize the protocol object after the protocol stack has been created.
 o dnRegisterTalker(iBusURL)
Called by the object above or by an iBus application to register as a talker for a channel.
 o dnSubscribe(iBusURL)
Called by the object above or by an iBus application to subscribe for a certain channel.
 o dnTerminate()
Terminate any threads in the protocol object.
 o dnUnregisterTalker(iBusURL)
Called by the object above or by an iBus application to unregister as a talker from a channel.
 o dnUnsubscribe(iBusURL)
Called by the object above or by an iBus application to unsubscribe from a certain channel.
 o getGroupInfo(iBusURL)
Returns the GroupInfo object for a member.
 o getHbeat()
Returns the hbeat property.
 o getTimeout()
Returns the timeout property.
 o heartBeatChannel(iBusURL)
convert an iBus channel to an URL that denotes the associated heartbeat channel.
 o isFdetect()
Returns the fdetect property.
 o removeGroupInfo(iBusURL)
Remove the GroupInfo object for member.
 o run()
A thread that periodically sends heartbeats and also checks for missing heartbeats:
 o sendHeartbeat(REACH_GroupMember, iBusURL)
Sends a heartbeat a certain hannel specified.
 o setFdetect(boolean)
Set the fdetect property.
 o setGroupInfo(REACH_GroupInfo)
Add a GroupInfo object to groupinfos_.
 o setHbeat(int)
Set the hbeat property.
 o setTimeout(int)
Set the timeout property.
 o startHeartbeat(iBusURL, boolean, boolean, int)
Do the registration necessary to start transmitting heartbeats for a given channel.
 o stopHeartbeat(iBusURL, boolean, boolean)
Called by dnUnsubscribe and dnUnregisterTalker to stop the heartbeat for a given channel.
 o upHandleEvent(Event)
Called by the protocol object below to pass an event up to me.

Constructors

 o REACH
 public REACH()
Create the protocol object.

Methods

 o 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
 o dnTerminate
 public void dnTerminate()
Terminate any threads in the protocol object.

Overrides:
dnTerminate in class ProtocolObject
 o 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
 o 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
 o 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
 o 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
 o 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
 o run
 public void run()
A thread that periodically sends heartbeats and also checks for missing heartbeats:

 o getHbeat
 public int getHbeat()
Returns the hbeat property.

Returns:
the hbeat property
 o setHbeat
 public void setHbeat(int hbeat)
Set the hbeat property.

Parameters:
hbeat - the value of the hbeat property
 o getTimeout
 public int getTimeout()
Returns the timeout property.

Returns:
the timeout property
 o setTimeout
 public void setTimeout(int timeout)
Set the timeout property.

Parameters:
timeout - the value of the hbeat property
 o isFdetect
 public boolean isFdetect()
Returns the fdetect property.

Returns:
the fdetect property
 o setFdetect
 public void setFdetect(boolean fd)
Set the fdetect property.

Parameters:
fd - the new value of the fdetect property
 o 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
 o 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
 o 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
 o 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.
 o 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.
 o removeGroupInfo
 protected synchronized void removeGroupInfo(iBusURL member)
Remove the GroupInfo object for member.

Parameters:
member - the URL of the GroupInfo to remove
 o deliverLocalViewChanges
 protected void deliverLocalViewChanges()
deliver any views that have changed to the layers above, by calling upHandleEvent.

 o 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