All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class iBus.Stack

java.lang.Object
   |
   +----iBus.ProtocolObject
           |
           +----iBus.Stack

public class Stack
extends ProtocolObject
Class Stack is used by the iBus application programmer to create an iBus protocol stack. A protocol stack is defined by a quality of service string of the form
"PROTOCOL1(name1=val1,name2=val2):PROTOCOL2:...:PROTOCOLn"
for example
"NAK(hbd=3):IPMCAST"

The (...) argument list contains protocol object specific properties settings and is optional.

Many stack properties can be accessed by invoking set/get methods on the protocol object. For that you first need to obtain a reference to the protocol object to be tailored:
Stack s = new Stack("IPMCAST"); REACH reach = (REACH)s.getProtocolObject("REACH"); reach.setTimeout(10000);

QOS Aliases. Those do not correspond to protocol objects but are expanded by the Stack class

The QOS string is first expanded and then tokenized. Each protocol object is then loaded and instantiated. Stack looks first into the iBus.layers directory to locate the class file of a protocol object. If the object is not found there, the CLASSPATH is consulted.

EVENTS PRODUCED:
- none

EVENTS HANDLED:
- evMessage
- evLostMessage
- evView

EVENTS CONSUMED:
- none


Variable Index

 o aliases_
String/String table that maps aliases into QOS strings:
 o mbrMonitors_
a Hashtable of url/Hashtable entries.
 o package_
the name of the iBus package:
 o pt2ptQOS
Alias for Point-to-Point QOS:
 o receivers_
a Hashtable of url/Hashtable entries.
 o registrations_
a Hashtable of the URLs we are registered for as a talker:
 o reliableQOS
Alias for reliable multicast QOS:
 o unreliableQOS
Alias for unreliable multicast QOS:
 o vsyncQOS
Alias for Virtual Synchrony QOS:

Constructor Index

 o Stack()
Create a protocol stack the application can use to send and receive Postings.
 o Stack(String)
Create a protocol stack that the application can use to send and receive Postings.

Method Index

 o dispose()
Dispose of the stack.
 o dnFlush()
Flush the protocol object.
 o dnInit()
Initialize the protocol object after the protocol stack has been created.
 o finalize()
Unsubscribe from internal channels and stop threads
 o getBottom()
Return the bottommost protocol object in the stack.
 o getExpandedQOS()
Return the quality of service string that was used to create this stack.
 o getProtocolObject(String)
Return the protocol object named pname
 o getQOS()
Return the quality of service string that was used to create this stack.
 o getStackURL()
Return the point-to-point URL needed to send messages to this stack.
 o getTop()
Return the topmost protocol object in the stack.
 o parseParams(String, Hashtable)
Parse any argument list that is provided to a protocol name.
 o parseQos()
 o pull(iBusURL, Posting)
Pull a posting.
 o push(iBusURL, Posting)
Multicast a posting to channel denoted by ``url''.
 o readyToExit()
Resume any thread that was suspended by waitTillExit.
 o registerMonitor(iBusURL, Membership)
Register an upcall object for receiving membership change notifications.
 o registerTalker(iBusURL)
Register as a talker for a channel.
 o subscribe(iBusURL, Receiver)
Subscribe to an iBus URL.
 o unregisterMonitor(iBusURL, Membership)
Unregister an upcall object set by registerMonitor
 o unregisterTalker(iBusURL)
Unregister as a talker from a channel.
 o unsubscribe(iBusURL, Receiver)
Unsubscribe from an iBus URL.
 o unsubscribeAll()
Close all channels this Stack has subscribed to or registered for
 o upHandleEvent(Event)
Called by the protocol object below to pass an event up to me.
 o waitTillExit()
Block the calling thread until readyToExit is called by some other thread.

Variables

 o reliableQOS
 public static final String reliableQOS
Alias for reliable multicast QOS:

 o unreliableQOS
 public static final String unreliableQOS
Alias for unreliable multicast QOS:

 o vsyncQOS
 public static final String vsyncQOS
Alias for Virtual Synchrony QOS:

 o pt2ptQOS
 public static final String pt2ptQOS
Alias for Point-to-Point QOS:

 o package_
 protected static final String package_
the name of the iBus package:

 o receivers_
 protected Hashtable receivers_
a Hashtable of url/Hashtable entries. The Hashtables contain the Receiver objects that are registered to the URL:

 o registrations_
 protected Hashtable registrations_
a Hashtable of the URLs we are registered for as a talker:

 o mbrMonitors_
 protected Hashtable mbrMonitors_
a Hashtable of url/Hashtable entries. The Hashtable contains the Membership objects that were registered by registerMonitor for the given channel:

 o aliases_
 protected static final Hashtable aliases_
String/String table that maps aliases into QOS strings:

Constructors

 o Stack
 public Stack()
Create a protocol stack the application can use to send and receive Postings. With this constructor no QOS is used, the stack is to be composed manually using the attach() method.

 o Stack
 public Stack(String qos)
Create a protocol stack that the application can use to send and receive Postings.

Parameters:
qos - the quality of service string, e.g., "NAK:IPMCAST"

Methods

 o dnInit
 public 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 unsubscribeAll
 public synchronized void unsubscribeAll() throws iBusException
Close all channels this Stack has subscribed to or registered for

Throws: iBusException
on internal errors
 o finalize
 protected void finalize() throws Throwable
Unsubscribe from internal channels and stop threads

Throws: Throwable
to stop finalization
Overrides:
finalize in class Object
 o dispose
 public synchronized void dispose()
Dispose of the stack. This must be called to release internal resources.

 o dnFlush
 public void dnFlush()
Flush the protocol object. Deliver any buffered messages, call flush on any output streams.

Overrides:
dnFlush in class ProtocolObject
 o registerTalker
 public void registerTalker(iBusURL channel) throws AlreadyRegistered, CommException
Register as a talker for a channel. This is to be done exactly once before any data can be pushed to the channel. If you only want to receive from a channel then you don't have to call this method.

Parameters:
channel - the channel to register with
Throws: AlreadyRegistered
if this stack is already registered with the channel
Throws: CommException
in case of a communication error
 o unregisterTalker
 public void unregisterTalker(iBusURL channel) throws NotRegistered, CommException
Unregister as a talker from a channel. This is to be done exactly once to indicate that the application will not be pushing to the channel any more. unregisterTalker allows internal resources to be released.

Parameters:
channel - the channel to unregister with
Throws: NotRegistered
if this stack is not registered with the channel
Throws: CommException
in case of a communication error
 o push
 public void push(iBusURL channel,
                  Posting p) throws CommException, NotRegistered
Multicast a posting to channel denoted by ``url''. Note that you have to call registerTalker before you can push to a channel.

Parameters:
channel - the destination channel of the posting
p - the posting to be sent
Throws: CommException
in case of a communication error
Throws: NotRegistered
in case registerTalker was not called for channel
 o pull
 public Posting[] pull(iBusURL channel,
                       Posting request) throws CommException, NotRegistered
Pull a posting. A request posting is transmitted to the channel. The listeners dispatch the request in their dispatchPull upcall and return a reply posting. Depending on the protocol stack, one or all reply postings are returned. If no reply posting is received within the specified timeout, an array with zero elements is returned.

Parameters:
channel - the iBus channel to transmit the requst posting to
request - the request posting to transmit
Returns:
an array of zero or more reply postings
Throws: NotRegistered
if this stack is not registered with the channel
Throws: CommException
in case of a communication error
 o subscribe
 public synchronized void subscribe(iBusURL channel,
                                    Receiver rcv) throws AlreadySubscribed, CommException
Subscribe to an iBus URL. Subscribing to an URL such as ibus://xxx/a also yields postings that are sent to any extension of the URL, such as ibus://xxx/a/b etc.

Parameters:
channel - the URL to subscribe to
rcv - the receiver of the postings
Throws: AlreadySubscribed
if this stack is already subscribed to channel
Throws: CommException
in case of a communication error
 o unsubscribe
 public synchronized void unsubscribe(iBusURL channel,
                                      Receiver rcv) throws NotSubscribed, CommException
Unsubscribe from an iBus URL.

Parameters:
channel - the URL to unsubscribe from
rcv - the receiver of the postings
Throws: NotSubscribed
if this stack is not subscribed to channel
Throws: CommException
in case of a communication error
 o registerMonitor
 public synchronized void registerMonitor(iBusURL channel,
                                          Membership m) throws AlreadyRegistered
Register an upcall object for receiving membership change notifications. A membership change occurs when an application subscribes, unsubscribes, or crashes. Note that there needs to be a membership layer such as REACH in the stack in order to receive membership notifications.

Parameters:
channel - the channel to monitor
m - the object to invoke on membership changes
Throws: AlreadyRegistered
if m was already registered for channel
 o unregisterMonitor
 public synchronized void unregisterMonitor(iBusURL channel,
                                            Membership m) throws NotRegistered
Unregister an upcall object set by registerMonitor

Parameters:
channel - the channel to unregister from
m - the monitor to unregister
Throws: NotRegistered
if m is not registered for channel
 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 getQOS
 public String getQOS()
Return the quality of service string that was used to create this stack.

Returns:
the quality of service string of this stack
 o getExpandedQOS
 public String getExpandedQOS()
Return the quality of service string that was used to create this stack.

Returns:
the quality of service string of this stack
 o getStackURL
 public iBusURL getStackURL()
Return the point-to-point URL needed to send messages to this stack.

Returns:
the point-to-point URL of this stack
 o getProtocolObject
 public ProtocolObject getProtocolObject(String pname)
Return the protocol object named pname

Parameters:
pname - the name of the protocol object to return
Returns:
the protocol object named pname, null if no such object exists in the stack
 o getTop
 public ProtocolObject getTop()
Return the topmost protocol object in the stack.

Returns:
the topmost protocol object
 o getBottom
 public ProtocolObject getBottom()
Return the bottommost protocol object in the stack. This typically is a communication object (e.g, iBus.IPMCAST).

Returns:
the bottommost protocol object
 o waitTillExit
 public synchronized void waitTillExit()
Block the calling thread until readyToExit is called by some other thread. iBus will be handling events normally while the calling thread is blocked.

 o readyToExit
 public synchronized void readyToExit()
Resume any thread that was suspended by waitTillExit.

 o parseQos
 protected void parseQos()
 o parseParams
 protected String parseParams(String proto,
                              Hashtable nvlist)
Parse any argument list that is provided to a protocol name. Arguments are specified in the format PROTONAME(name1=val1,name2=val2,...,nameN=valN).

Parameters:
proto - the protocol string incl. parameter list
nvlist - to hold the name/value list
Returns:
the protocol name without any argument list.

All Packages  Class Hierarchy  This Package  Previous  Next  Index