org.jgroups.stack
Class Protocol
java.lang.Object
org.jgroups.stack.Protocol
public abstract class Protocol
extends java.lang.Object
The Protocol class provides a set of common services for protocol layers. Each layer has to
be a subclass of Protocol and override a number of methods (typically just
up()
,
Down
and
getName
. Layers are stacked in a certain order to form
a protocol stack.
Events are passed from lower
layers to upper ones and vice versa. E.g. a Message received by the UDP layer at the bottom
will be passed to its higher layer as an Event. That layer will in turn pass the Event to
its layer and so on, until a layer handles the Message and sends a response or discards it,
the former resulting in another Event being passed down the stack.
Each layer has 2 FIFO queues, one for up Events and one for down Events. When an Event is
received by a layer (calling the internal upcall
ReceiveUpEvent
), it is placed
in the up-queue where it will be retrieved by the up-handler thread which will invoke method
Up
of the layer. The same applies for Events traveling down the stack. Handling
of the up-handler and down-handler threads and the 2 FIFO queues is donw by the Protocol
class, subclasses will almost never have to override this behavior.
The important thing to bear in mind is that Events have to passed on between layers in FIFO
order which is guaranteed by the Protocol implementation and must be guranteed by subclasses
implementing their on Event queuing.
Note that each class implementing interface Protocol MUST provide an empty, public
constructor !
down_handler
protected org.jgroups.stack.DownHandler down_handler
down_queue
protected Queue down_queue
down_thread
protected boolean down_thread
down_thread_prio
protected int down_thread_prio
props
protected Properties props
up_handler
protected org.jgroups.stack.UpHandler up_handler
up_queue
protected Queue up_queue
up_thread
protected boolean up_thread
up_thread_prio
protected int up_thread_prio
destroy
public void destroy()
This method is called on a
Channel.close()
.
Does some cleanup; after the call the VM will terminate
down
public void down(Event evt)
An event is to be sent down the stack. The layer may want to examine its type and perform
some action on it, depending on the event's type. If the event is a message MSG, then
the layer may need to add a header to it (or do nothing at all) before sending it down
the stack using passDown()
. In case of a GET_ADDRESS event (which tries to
retrieve the stack's address from one of the bottom layers), the layer may need to send
a new response event back up the stack using passUp()
.
getDownProtocol
public Protocol getDownProtocol()
getDownQueue
public Queue getDownQueue()
getName
public String getName()
getProperties
public Properties getProperties()
getUpProtocol
public Protocol getUpProtocol()
getUpQueue
public Queue getUpQueue()
handleSpecialDownEvent
protected boolean handleSpecialDownEvent(Event evt)
These are special internal events that should not be handled by protocols
- boolean True: the event should be passed further down the stack. False: the event should
be discarded (not passed down the stack)
init
public void init()
throws Exception
Called after instance has been created (null constructor) and before protocol is started.
Properties are already set. Other protocols are not yet connected and events cannot yet be sent.
passDown
public void passDown(Event evt)
Causes the event to be forwarded to the next layer down in the hierarchy.Typically called
by the implementation of Down
(when done).
passUp
public void passUp(Event evt)
Causes the event to be forwarded to the next layer up in the hierarchy. Typically called
by the implementation of Up
(when done).
providedDownServices
public Vector providedDownServices()
List of events that are provided to layers below (they will be handled when sent down from
below).
- Vector (of Integers)
providedUpServices
public Vector providedUpServices()
List of events that are provided to layers above (they will be handled when sent down from
above).
- Vector (of Integers)
receiveDownEvent
protected void receiveDownEvent(Event evt)
Internal method, should not be called by clients. Used by ProtocolStack. I would have
used the 'friends' modifier, but this is available only in C++ ... If the down_handler thread
is not available (down_thread == false), then directly call the down() method: we will run on the
caller's thread (e.g. the protocol layer above us).
receiveUpEvent
protected void receiveUpEvent(Event evt)
Internal method, should not be called by clients. Used by ProtocolStack. I would have
used the 'friends' modifier, but this is available only in C++ ... If the up_handler thread
is not available (down_thread == false), then directly call the up() method: we will run on the
caller's thread (e.g. the protocol layer below us).
requiredDownServices
public Vector requiredDownServices()
List of events that are required to be answered by some layer below.
- Vector (of Integers)
requiredUpServices
public Vector requiredUpServices()
List of events that are required to be answered by some layer above.
- Vector (of Integers)
setDownProtocol
public void setDownProtocol(Protocol down_prot)
setProperties
public boolean setProperties(Properties props)
Configures the protocol initially. A configuration string consists of name=value
items, separated by a ';' (semicolon), e.g.:
"loopback=false;unicast_inport=4444"
setPropertiesInternal
public boolean setPropertiesInternal(Properties props)
Called by Configurator. Removes 2 properties which are used by the Protocol directly and then
calls setProperties(), which might invoke the setProperties() method of the actual protocol instance.
setProtocolStack
public void setProtocolStack(ProtocolStack stack)
setUpProtocol
public void setUpProtocol(Protocol up_prot)
start
public void start()
throws Exception
This method is called on a
Channel.connect(String)
. Starts work.
Protocols are connected and queues are ready to receive events.
Will be called
from bottom to top. This call will replace
the
START and
START_OK events.
startDownHandler
public void startDownHandler()
Used internally. If overridden, call this method first. Only creates the down_handler thread
if down_thread is true
startUpHandler
public void startUpHandler()
Used internally. If overridden, call this method first. Only creates the up_handler thread
if down_thread is true
stop
public void stop()
This method is called on a
Channel.disconnect()
. Stops work (e.g. by closing multicast socket).
Will be called
from top to bottom. This means that at the time of the method invocation the
neighbor protocol below is still working. This method will replace the
STOP,
STOP_OK,
CLEANUP and
CLEANUP_OK events. The ProtocolStack guarantees that
when this method is called all messages in the down queue will have been flushed
stopInternal
public void stopInternal()
Used internally. If overridden, call parent's method first
up
public void up(Event evt)
An event was received from the layer below. Usually the current layer will want to examine
the event type and - depending on its type - perform some computation
(e.g. removing headers from a MSG event type, or updating the internal membership list
when receiving a VIEW_CHANGE event).
Finally the event is either a) discarded, or b) an event is sent down
the stack using passDown()
or c) the event (or another event) is sent up
the stack using passUp()
.
Copyright B) 2001,2002 www.jgroups.com . All Rights Reserved.