jbora
Class JBora

java.lang.Object
  jbora.JBora

public class JBora

extends Object

The main class. A JBora object can be used for interacting with a group.

First you join the group. Then you can receive events and multicast messages. Finally you leave the group. Once you have left the group, you cannot reuse the object.

Implementation notes: A JBora object is shared amongst all application threads within the same process, but you may have multiple JBora processes withing the same VM, as long as you assign them different group member names. Each process within the group will be identified by JBora as: name@host_name.
JBora object delegates access to the underlying group communication system to a private SpreadJBora object. The SpreadJBora object will create one SpreadListener thread, that is the only thread that actually receives view changes and multicasts from the underlying group communication system.

The JBora.receive() operation extracts (FIFO) one event at the time from the system end returns it to the user.

This product uses software developed by Spread Concepts LLC for use in the Spread toolkit.
For more information about Spread, see www.spread.org.

Author:

Alberto Bartoli, Milan Prica

Constructor Summary

JBora(int w, int num, String myName, String groupName)

Method Summary

void	close() Close the connection to Spread.
View	getCurrentView() Returns the current view of the group.
ProcessID	getMySelf() Returns the ID of the executing process
void	join() Join the group (name of the group is specified in the JBora constructor).
void	leave() Leave the group.
Message	localCall(Message req) Primitive for intra-process communication.
void	localRespond(Message req, Message resp) Responds to a localCall.
void	multiCast(Message msg) Sends a message (multicasts) to all members of the current View.
PropagateEvent	propagate(Message msg) Multicasts a message to all current view members and returns a PropagateEvent containing: A list of members that replied: ProcessID[]; Reply message from each member that replied: Vector; Other events received during propagation: Event[].
Event	receive() Receives an Event from JBora.
int	whiteBoardRead(ProcessID proc) Reads the whiteboard value associated with the specified view member.
void	whiteBoardUpdate(int val) Updates the whiteboard value associated with the invoking process

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JBora

public JBora(int w,
             int num,
             String myName,
             String groupName)
      throws JBoraException

Parameters:

w - Maximum waiting time (in msec) before sending white board information

num - Maximum number of group members (necessary for determining primariness)

myName - Name of the invoking group member

groupName - Name of the group that will be joined

Throws:

PanicException - Error while connecting to the Spread daemon

JBoraException

Method Detail

join

public void join()
          throws AlreadyJoinedException,
                 NotJoinedException,
                 PanicException

Join the group (name of the group is specified in the JBora constructor). It returns immediately.

Throws:

AlreadyJoinedException - Process already joined

PanicException - Unrecoverable error

NotJoinedException

leave

public void leave()
           throws PanicException,
                  NotJoinedException

Leave the group. It returns immediately.

Throws:

NotJoinedException - Process not joined

PanicException - Unrecoverable error

close

public void close()
           throws PanicException,
                  NotJoinedException

Close the connection to Spread.

Throws:

PanicException

NotJoinedException

multiCast

public void multiCast(Message msg)
               throws PanicException,
                      NotJoinedException,
                      MessageTooBigException

Sends a message (multicasts) to all members of the current View.

Parameters:

msg - Message

Throws:

NotJoinedException - Process not joined

MessageTooBigException - Message too big

PanicException - Unrecoverable error

receive

public Event receive()
              throws PanicException,
                     NotJoinedException

Receives an Event from JBora. This method is NOT "Thread safe" (meaning only one thread per process should call receive() method).
If the Event received is a view change, subsequent invocations to getCurrentView() will get a reference to that Event.

Returns:

Event received

Throws:

NotJoinedException - Process not joined

PanicException - Unrecoverable error

propagate

public PropagateEvent propagate(Message msg)
                         throws PanicException,
                                NotJoinedException,
                                MessageTooBigException

Multicasts a message to all current view members and returns a PropagateEvent containing:

• A list of members that replied: ProcessID[];
• Reply message from each member that replied: Vector;
• Other events received during propagation: Event[].

If a view change occurs during the propagation, the whole process of propagation restarts.

This method is NOT a "Thread safe" method. (Should be invoked by only one thread per process.)

propagate(msg) operation was designed to simplify the exchange of application-defined information upon a view expansion (a view change installing a view with a process that was not a member of the previous view). It is a blocking operation that multicasts msg and terminates upon receiving a message sent through grp.propagate() from each member of the (new) view.

If any view member chooses to call propagate(), then every group member must do so after a trigger event (normally a view expansion) -- otherwise the propagate() call will not complete.

JBora.propagate(msg) is similar to a loop that executes JBora.receive() and terminates upon receiving a message from each view member. This operation encapsulates many low-level details that otherwise would have to be programmed explicitly, in particular, the handling of messages and view changes delivered while exchanging application-defined information upon a view expansion.

Parameters:

msg - Message to propagate

Returns:

PropagateEvent

Throws:

PanicException - Error while communicating to the group

NotJoinedException - The server has not joined the group

MessageTooBigException - The message is too big

whiteBoardRead

public int whiteBoardRead(ProcessID proc)
                   throws JBoraException,
                          NotJoinedException

Reads the whiteboard value associated with the specified view member.

Parameters:

proc - Process ID

Returns:

Value

Throws:

WhiteboardException

JBoraException

NotJoinedException

whiteBoardUpdate

public void whiteBoardUpdate(int val)
                      throws JBoraException,
                             NotJoinedException

Updates the whiteboard value associated with the invoking process

Parameters:

val - Value

Throws:

WhiteboardException

JBoraException

NotJoinedException

localCall

public Message localCall(Message req)
                  throws PanicException

Primitive for intra-process communication. Sends a request message and waits until a response is received. Typically, the request will be read by another thread of this process invoking receive and the response will be sent by that thread by invoking localRespond.

Parameters:

req - Request message

Returns:

Response message

Throws:

PanicException - Unrecoverable error

localRespond

public void localRespond(Message req,
                         Message resp)
                  throws PanicException

Responds to a localCall.

Parameters:

req - Request message

resp - Response message

Throws:

PanicException - Unrecoverable error (attempt to write into a ResponseContainer where something has already been written, The request was not obtained via receive(), or that request was already answered.).

getCurrentView

public View getCurrentView()

Returns the current view of the group.

Returns:

Current view

getMySelf

public ProcessID getMySelf()

Returns the ID of the executing process

Returns:

Owner ID

Throws:

NotJoinedException - The owner is null (not joined)