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


Variable Index

 o above_
 o below_
 o name_

Constructor Index

 o ProtocolObject(String)
Creates a protocol object and assigns a name to it.

Method Index

 o above()
Return the object above
 o attach(ProtocolObject)
Attach ProtocolObject ``below'' below myself.
 o below()
Return the object below
 o checkNameValueList(String)
Ensures that each name in nameValueList_ is an element of the space delimited string names_allow.
 o 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).
 o dnFlush()
Flush the protocol object.
 o dnGetStackURL()
Called by the API protocol object to obtain an URL used to reply to this stack.
 o dnInit()
Initialize the protocol object after the protocol stack is created.
 o dnPull(iBusURL, MessageEvent)
Called by the object above to issue a blocking pull request.
 o dnPullReply(MessageEvent, PullContext, MessageEvent)
Reply to a pull request.
 o 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:
 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 to subscribe to a channel.
 o dnTerminate()
Terminate any threads in the protocol object.
 o dnThrottle(boolean)
The stack is getting overloaded.
 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 getName()
Return the name of this kind of protocol object
 o getNameValueList()
Gets the object's name-value list.
 o getStack()
Obtain the stack this object belongs to.
 o getValueAsInt(String)
Returns a parameter value as an Integer
 o getValueAsString(String)
Returns a parameter value as a String.
 o setNameValueList(Hashtable)
Sets the object's name-value list.
 o setStack(Stack)
Specify the stack this object belongs to.
 o upHandleEvent(Event)
Called by the protocol object beneath to pass an event up to me.

Variables

 o name_
 protected String name_
 o above_
 protected transient ProtocolObject above_
 o below_
 protected transient ProtocolObject below_

Constructors

 o 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

Methods

 o 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.

 o dnTerminate
 public void dnTerminate()
Terminate any threads in the protocol object. The object is unusable afterwards.

 o dnFlush
 public void dnFlush()
Flush the protocol object. Deliver any buffered messages.

 o 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.
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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.
 o attach
 public ProtocolObject attach(ProtocolObject below)
Attach ProtocolObject ``below'' below myself.

Parameters:
below - the object to attach below this object
Returns:
the below parameter
 o above
 public ProtocolObject above()
Return the object above

Returns:
the object above
 o below
 public ProtocolObject below()
Return the object below

Returns:
the object below
 o getName
 public String getName()
Return the name of this kind of protocol object

Returns:
the name of this kind of protocol object
 o setStack
 public void setStack(Stack s)
Specify the stack this object belongs to.

Parameters:
s - the iBus protocol stack this object belongs to
 o getStack
 public Stack getStack()
Obtain the stack this object belongs to.

Returns:
the iBus protocol stack this object belongs to
 o 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.
 o 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
 o 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
 o setNameValueList
 public void setNameValueList(Hashtable nvlist)
Sets the object's name-value list.

Parameters:
nvlist - the object's name-value list
 o 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