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
-
"Reliable" = "DISPATCH:PULL:FRAG:FIFO:NAK:REACH:IPMCAST"
(default)
-
"Unreliable" = "DISPATCH:IPMCAST"
-
"Point-to-point" = "DISPATCH:TCP"
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
-
aliases_
- String/String table that maps aliases into QOS strings:
-
mbrMonitors_
- a Hashtable of url/Hashtable entries.
-
package_
- the name of the iBus package:
-
pt2ptQOS
- Alias for Point-to-Point QOS:
-
receivers_
- a Hashtable of url/Hashtable entries.
-
registrations_
- a Hashtable of the URLs we are registered for as a talker:
-
reliableQOS
- Alias for reliable multicast QOS:
-
unreliableQOS
- Alias for unreliable multicast QOS:
-
vsyncQOS
- Alias for Virtual Synchrony QOS:
-
Stack()
- Create a protocol stack the application can use to send and receive
Postings.
-
Stack(String)
- Create a protocol stack that the application can use to send and receive
Postings.
-
dispose()
- Dispose of the stack.
-
dnFlush()
- Flush the protocol object.
-
dnInit()
- Initialize the protocol object after the protocol stack has been
created.
-
finalize()
- Unsubscribe from internal channels and stop threads
-
getBottom()
- Return the bottommost protocol object in the stack.
-
getExpandedQOS()
- Return the quality of service string that was used to create this stack.
-
getProtocolObject(String)
- Return the protocol object named pname
-
getQOS()
- Return the quality of service string that was used to create this stack.
-
getStackURL()
- Return the point-to-point URL needed to send messages to this stack.
-
getTop()
- Return the topmost protocol object in the stack.
-
parseParams(String, Hashtable)
- Parse any argument list that is provided to a protocol name.
-
parseQos()
-
-
pull(iBusURL, Posting)
- Pull a posting.
-
push(iBusURL, Posting)
- Multicast a posting to channel denoted by ``url''.
-
readyToExit()
- Resume any thread that was suspended by waitTillExit.
-
registerMonitor(iBusURL, Membership)
- Register an upcall object for receiving membership change notifications.
-
registerTalker(iBusURL)
- Register as a talker for a channel.
-
subscribe(iBusURL, Receiver)
- Subscribe to an iBus URL.
-
unregisterMonitor(iBusURL, Membership)
- Unregister an upcall object set by registerMonitor
-
unregisterTalker(iBusURL)
- Unregister as a talker from a channel.
-
unsubscribe(iBusURL, Receiver)
- Unsubscribe from an iBus URL.
-
unsubscribeAll()
- Close all channels this Stack has subscribed to or registered for
-
upHandleEvent(Event)
- Called by the protocol object below to pass an event up to me.
-
waitTillExit()
- Block the calling thread until readyToExit is called by some other
thread.
reliableQOS
public static final String reliableQOS
- Alias for reliable multicast QOS:
unreliableQOS
public static final String unreliableQOS
- Alias for unreliable multicast QOS:
vsyncQOS
public static final String vsyncQOS
- Alias for Virtual Synchrony QOS:
pt2ptQOS
public static final String pt2ptQOS
- Alias for Point-to-Point QOS:
package_
protected static final String package_
- the name of the iBus package:
receivers_
protected Hashtable receivers_
- a Hashtable of url/Hashtable entries. The Hashtables contain
the Receiver objects that are registered to the URL:
registrations_
protected Hashtable registrations_
- a Hashtable of the URLs we are registered for as a talker:
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:
aliases_
protected static final Hashtable aliases_
- String/String table that maps aliases into QOS strings:
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.
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"
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
unsubscribeAll
public synchronized void unsubscribeAll() throws iBusException
- Close all channels this Stack has subscribed to or registered for
- Throws: iBusException
- on internal errors
finalize
protected void finalize() throws Throwable
- Unsubscribe from internal channels and stop threads
- Throws: Throwable
- to stop finalization
- Overrides:
- finalize in class Object
dispose
public synchronized void dispose()
- Dispose of the stack. This must be called to release internal resources.
dnFlush
public void dnFlush()
- Flush the protocol object. Deliver any buffered messages, call
flush on any output streams.
- Overrides:
- dnFlush in class ProtocolObject
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
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
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
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
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
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
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
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
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
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
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
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
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
getTop
public ProtocolObject getTop()
- Return the topmost protocol object in the stack.
- Returns:
- the topmost protocol object
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
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.
readyToExit
public synchronized void readyToExit()
- Resume any thread that was suspended by waitTillExit.
parseQos
protected void parseQos()
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