All Packages Class Hierarchy This Package Previous Next Index
Class iBus.ProtocolObject
java.lang.Object
|
+----iBus.ProtocolObject
- public abstract class ProtocolObject
- extends Object
- implements Serializable
This is the base class of all iBus protocol objects. Protocol objects
are connected to form iBus protocol stacks. When you implement a protocol
object you should use this file as a template.
Typically, a protocol object
implements one specific feature, e.g., flow control, message fragmentation,
membership management, or total ordering. Protocol objects communicate
by invoking upcalls and downcalls on their upper and lower neightbor.
Methods that start with ``up'' are upcalls that are invoked
by the protocol object beneath. Methods that start
with ``dn'' are downcalls that are either invoked by the protocol object
above, or directly by an iBus end-user application.
DESIGN:
- describe the design here.
PARAMETERS:
- specify parameters that can be passed with the quality of service string
POSITION IN STACK:
- describe where this object needs to be positioned in the stack
EVENTS PRODUCED:
- specify iBus events produced by this object
EVENTS HANDLED:
- specify iBus events handled by this object
EVENTS CONSUMED:
- specify iBus events that are discarded by this object
THREADS:
- list any threads that are spawned by the object
-
above_
-
-
below_
-
-
name_
-
-
ProtocolObject(String)
- Creates a protocol object and assigns a name to it.
-
above()
- Return the object above
-
attach(ProtocolObject)
- Attach ProtocolObject ``below'' below myself.
-
below()
- Return the object below
-
checkNameValueList(String)
- Ensures that each name in nameValueList_ is an element of the
space delimited string names_allow.
-
dnBytesAdded(MessageEvent)
- Called by protocol objects such as FRAG to find out how many bytes
are added to the message by that protocol objects below (constant).
-
dnFlush()
- Flush the protocol object.
-
dnGetStackURL()
- Called by the API protocol object to obtain an URL used
to reply to this stack.
-
dnInit()
- Initialize the protocol object after the protocol stack is
created.
-
dnPull(iBusURL, MessageEvent)
- Called by the object above to issue a blocking pull request.
-
dnPullReply(MessageEvent, PullContext, MessageEvent)
- Reply to a pull request.
-
dnPush(iBusURL, MessageEvent)
- Called by the object above to send a message to a channel by
multicast or unicast communication, depending on the channel URL:
-
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 to subscribe to a channel.
-
dnTerminate()
- Terminate any threads in the protocol object.
-
dnThrottle(boolean)
- The stack is getting overloaded.
-
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.
-
getName()
- Return the name of this kind of protocol object
-
getNameValueList()
- Gets the object's name-value list.
-
getStack()
- Obtain the stack this object belongs to.
-
getValueAsInt(String)
- Returns a parameter value as an Integer
-
getValueAsString(String)
- Returns a parameter value as a String.
-
setNameValueList(Hashtable)
- Sets the object's name-value list.
-
setStack(Stack)
- Specify the stack this object belongs to.
-
upHandleEvent(Event)
- Called by the protocol object beneath to pass an event up to me.
name_
protected String name_
above_
protected transient ProtocolObject above_
below_
protected transient ProtocolObject below_
ProtocolObject
public ProtocolObject(String name)
- Creates a protocol object and assigns a name to it.
- Parameters:
- name - the string used to identify this kind of protocol object
dnInit
public void dnInit()
- Initialize the protocol object after the protocol stack is
created. Also checks whether the right parameters were given to the
protocol object.
dnTerminate
public void dnTerminate()
- Terminate any threads in the protocol object. The object is
unusable afterwards.
dnFlush
public void dnFlush()
- Flush the protocol object. Deliver any buffered messages.
dnThrottle
public void dnThrottle(boolean stop)
- The stack is getting overloaded. Tell the senders to slow
down the rate at which they send messages to us.
- Parameters:
- stop - true if throttling is required, false if unthrottling
is required.
upHandleEvent
public void upHandleEvent(Event event)
- Called by the protocol object beneath to pass an event up to me.
An event can be the arrival of a posting, the detection of a failure,
an acknowledgement, etc.
- Parameters:
- event - determines the type of event
dnPush
public void dnPush(iBusURL channel,
MessageEvent msg) throws CommException, NotRegistered
- Called by the object above to send a message to a channel by
multicast or unicast communication, depending on the channel URL:
- Parameters:
- channel - the destination channel of the posting
- msg - the message to be sent
- Throws: CommException
- on communication failure
- Throws: NotRegistered
- in case registerTalker was not called for
the channel
dnPull
public MessageEvent[] dnPull(iBusURL channel,
MessageEvent msg) throws CommException, NotRegistered
- Called by the object above to issue a blocking pull request.
- Parameters:
- channel - the destination channel of the posting
- msg - the request message to be sent
- Returns:
- an array of zero or more reply messages
- Throws: CommException
- on communication failure
- Throws: NotRegistered
- in case registerTalker was not called for
the channel
dnPullReply
public void dnPullReply(MessageEvent reply,
PullContext pctx,
MessageEvent request) throws CommException
- Reply to a pull request.
- Parameters:
- reply - the reply message to return
- pctx - the context of the associated pull request
- request - the request message
- Throws: CommException
- on communication failure
dnSubscribe
public void dnSubscribe(iBusURL channel) throws AlreadySubscribed, CommException
- Called by the object above to subscribe to a channel.
- Parameters:
- channel - the channel to subscribe to
- Throws: AlreadySubscribed
- if this stack is already
subscribed to the channel
- Throws: CommException
- in case of a communication
error
dnUnsubscribe
public 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 the channel
- Throws: CommException
- in case of a communication
error
dnRegisterTalker
public 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
dnUnregisterTalker
public 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
dnGetStackURL
public iBusURL dnGetStackURL()
- Called by the API protocol object to obtain an URL used
to reply to this stack. dnGetStackURL is typically implemented by the
bottommost protocol object only.
- Returns:
- the URL of the stack
dnBytesAdded
public int dnBytesAdded(MessageEvent msg)
- Called by protocol objects such as FRAG to find out how many bytes
are added to the message by that protocol objects below (constant).
(Only protocol objects that can be placed below FRAG need to implement
this function).
- Parameters:
- msg - the message that will be passed down the stack.
- Returns:
- the number of bytes the protocol object will add to
the message.
attach
public ProtocolObject attach(ProtocolObject below)
- Attach ProtocolObject ``below'' below myself.
- Parameters:
- below - the object to attach below this object
- Returns:
- the below parameter
above
public ProtocolObject above()
- Return the object above
- Returns:
- the object above
below
public ProtocolObject below()
- Return the object below
- Returns:
- the object below
getName
public String getName()
- Return the name of this kind of protocol object
- Returns:
- the name of this kind of protocol object
setStack
public void setStack(Stack s)
- Specify the stack this object belongs to.
- Parameters:
- s - the iBus protocol stack this object belongs to
getStack
public Stack getStack()
- Obtain the stack this object belongs to.
- Returns:
- the iBus protocol stack this object belongs to
checkNameValueList
public void checkNameValueList(String names_allow)
- Ensures that each name in nameValueList_ is an element of the
space delimited string names_allow. Terminates the application
with log_.panic () if the stack is malformed.
- Parameters:
- names_allow - space delimited list of parameter names the
object is able to handle.
getValueAsString
public String getValueAsString(String name)
- Returns a parameter value as a String.
- Parameters:
- name - the name of the entry
- Returns:
- the value of parameter name as a String
getValueAsInt
public Integer getValueAsInt(String name)
- Returns a parameter value as an Integer
- Parameters:
- name - the name of the entry
- Returns:
- the value of parameter name as an Integer
setNameValueList
public void setNameValueList(Hashtable nvlist)
- Sets the object's name-value list.
- Parameters:
- nvlist - the object's name-value list
getNameValueList
public Hashtable getNameValueList()
- Gets the object's name-value list.
- Returns:
- the object's name-value list
All Packages Class Hierarchy This Package Previous Next Index