JavaGroups
Class JChannel

java.lang.Object
  |
  +--JavaGroups.Channel
        |
        +--JavaGroups.JChannel

public class JChannel

extends Channel

JChannel is a pure Java implementation of Channel.

Fields inherited from class JavaGroups.Channel

BLOCK, GET_STATE_EVENTS, LOCAL, SUSPECT, VIEW

Constructor Summary

JChannel()

JChannel(java.lang.Object properties)

Method Summary

void	BlockOk() Called to acknowledge a Block (callback in MembershipListener or BlockEvent received from call to Receive).
void	Close() Destroys the channel.
void	Connect(java.lang.Object group_address) Connects the channel to a group.
void	Disconnect() Disconnects the channel from the current group (if connected), leaving the group.
void	Down(Event evt) Access to event mechanism of channels.
void	finalize()
boolean	GetAllStates(java.util.Vector targets, long timeout) Retrieves the current group state.
java.lang.Object	GetGroupAddress() Returns the group address of the group of which the channel is a member.
java.lang.Object	GetLocalAddress() Returns the channel's own address.
java.lang.Object	GetOpt(int option) Gets an option.
boolean	GetState(java.lang.Object target, long timeout) Retrieves the current group state.
View	GetView() Gets the current view.
java.lang.Object	Peek(long timeout) Just peeks at the next message, view or block.
java.lang.Object	Receive(long timeout) Receives a message, a view change or a block event.
void	ReturnState(java.lang.Object state) Called by the application is response to receiving a GetState object when calling Receive.
void	Send(Message msg) Sends a message to a destination.
void	SetOpt(int option, java.lang.Object value) Sets an option.
void	Up(Event evt) Called by the ProtocolStack when a message is received.

Methods inherited from class JavaGroups.Channel

SetChannelListener, SetUpHandler

Methods inherited from class java.lang.Object

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

Constructor Detail

JChannel

public JChannel()
         throws ChannelException

JChannel

public JChannel(java.lang.Object properties)
         throws ChannelException

Method Detail

Connect

public void Connect(java.lang.Object group_address)
             throws ChannelClosed

Connects the channel to a group.

Overrides:

Connect in class Channel

Parameters:

group_address - A String denoting the group name.

Disconnect

public void Disconnect()

Description copied from class: Channel

Disconnects the channel from the current group (if connected), leaving the group. It is a null operation if not connected. It is a null operation if the channel is closed.

Overrides:

Disconnect in class Channel

Tags copied from class: Channel

See Also:

Channel.Connect

Close

public void Close()

Destroys the channel. After this method has been called, the channel us unusable.

Overrides:

Close in class Channel

finalize

public void finalize()

Send

public void Send(Message msg)
          throws ChannelNotConnected,
                 ChannelClosed

Description copied from class: Channel

Sends a message to a destination. The message contains

1. a destination address (Object). A null address sends the message to all group members.
2. a source address. Can be left empty. Will be filled in by the protocol stack.
3. a byte buffer. The message contents.
4. several additional fields. They can be used by application programs (or patterns). E.g. a message ID, a oneway field which determines whether a response is expected etc.

Overrides:

Send in class Channel

Tags copied from class: Channel

Parameters:

msg - The message to be sent. Destination and buffer should be set. A null destination means to send to all group members.

Throws:

ChannelNotConnected - The channel must be connected to send messages.

ChannelClosed - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.

Receive

public java.lang.Object Receive(long timeout)
                         throws ChannelNotConnected,
                                ChannelClosed,
                                Timeout

Description copied from class: Channel

Receives a message, a view change or a block event. By using SetOpt, the type of objects to be received can be determined (e.g. not views and blocks, just messages). The possible types returned can be:

1. Message. Normal message
2. Event. All other events (used by JChannel)
3. View. A view change.
4. BlockEvent. A block event indicating an impending view change.
5. SuspectEvent. A notification of a suspected member.
6. GetStateEvent. The current state of the application should be returned using ReturnState.
7. SetStateEvent. The state of a single/all members as requested previously by having called Channel.GetState(s).

The instanceof operator can be used to discriminate between different types returned.

Overrides:

Receive in class Channel

Tags copied from class: Channel

Parameters:

timeout - Value in milliseconds. Value <= 0 means wait forever

Returns:

A Message, View, BlockEvent,SuspectEvent, GetStateEvent object or SetStateEvent, depending on what is on top of the internal queue.

Throws:

ChannelNotConnected - The channel must be connected to receive messages.

ChannelClosed - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.

Timeout - Thrown when a timeout has occurred.

Peek

public java.lang.Object Peek(long timeout)
                      throws ChannelNotConnected,
                             ChannelClosed,
                             Timeout

Just peeks at the next message, view or block. Does not install new view if view is received

Overrides:

Peek in class Channel

Tags copied from class: Channel

Parameters:

timeout - Value in milliseconds. Value <= 0 means wait forever

Returns:

A Message, View, BlockEvent, SuspectEvent, GetStateEvent or SetStateEvent object, depending on what is on top of the internal queue.

Throws:

ChannelNotConnected - The channel must be connected to receive messages.

ChannelClosed - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.

Timeout - Thrown when a timeout has occurred.

See Also:

Receive

GetView

public View GetView()

Description copied from class: Channel

Gets the current view. This does not retrieve a new view, use Receive to do so. The view may only be available after a successful Connect. The result of calling this method on an unconnected channel is implementation defined (may return null). Calling it on a channel that is not enabled to receive view events (via SetOpt) returns null. Calling this method on a closed channel returns a null view.

Overrides:

GetView in class Channel

Tags copied from class: Channel

Returns:

The current view.

GetLocalAddress

public java.lang.Object GetLocalAddress()

Description copied from class: Channel

Returns the channel's own address. The result of calling this method on an unconnected channel is implementation defined (may return null). Calling this method on a closed channel returns null.

Overrides:

GetLocalAddress in class Channel

Tags copied from class: Channel

Returns:

The channel's address. Generated by the underlying transport, and opaque. Addresses can be used as destination in the Send operation.

GetGroupAddress

public java.lang.Object GetGroupAddress()

Description copied from class: Channel

Returns the group address of the group of which the channel is a member. This is the object that was the argument to Connect. Calling this method on a closed channel returns null.

Overrides:

GetGroupAddress in class Channel

Tags copied from class: Channel

Returns:

The group address

SetOpt

public void SetOpt(int option,
                   java.lang.Object value)

Description copied from class: Channel

Sets an option. The following options are currently recognized:

1. BLOCK (0). Turn the reception of BLOCK events on/off (value is Boolean). Default is off. If set to on, receiving VIEW events will be set to on, too.
2. VIEW (1). Turn the reception of VIEW events on/off (value is Boolean). Default is on.
3. SUSPECT (2). Turn the reception of SUSPECT events on/off (value is Boolean). Default is on.
4. LOCAL (3). Receive its own broadcast messages to the group (value is Boolean). Default is on.
5. GET_STATE_EVENTS (4). Turn the reception of GetState events on/off (value is Boolean). Default is off, which means that no other members can ask this member for its state (null will be returned).

This method can be called on an unconnected channel. Calling this method on a closed channel has no effect.

Overrides:

SetOpt in class Channel

GetOpt

public java.lang.Object GetOpt(int option)

Description copied from class: Channel

Gets an option. This method can be called on an unconnected channel. Calling this method on a closed channel returns null.

Overrides:

GetOpt in class Channel

Tags copied from class: Channel

Parameters:

option - The option to be returned.

Returns:

The object associated with an option.

BlockOk

public void BlockOk()

Description copied from class: Channel

Called to acknowledge a Block (callback in MembershipListener or BlockEvent received from call to Receive). After sending BlockOk, no messages should be sent until a new view has been received. Calling this method on a closed channel has no effect.

Overrides:

BlockOk in class Channel

GetState

public boolean GetState(java.lang.Object target,
                        long timeout)

Retrieves the current group state. Sends GET_STATE event down to STATE_TRANSFER layer. Blocks until STATE_TRANSFER sends up a GET_STATE_OK event or until timeout milliseconds have elapsed. The argument of GET_STATE_OK should be a single object.

Overrides:

GetState in class Channel

Tags copied from class: Channel

Parameters:

target - The address of the member from which the state is to be retrieved. If it is null, the oldest member is contacted.

timeout - Milliseconds to wait for the response (0 = wait indefinitely).

Returns:

boolean True if the state was retrieved successfully, otherwise false.

GetAllStates

public boolean GetAllStates(java.util.Vector targets,
                            long timeout)

Retrieves the current group state. Sends GET_STATE event down to STATE_TRANSFER layer. Blocks until STATE_TRANSFER sends up a GET_STATE_OK event or until timeout milliseconds have elapsed. The argument of GET_STATE_OK should be a vector of objects.

Overrides:

GetAllStates in class Channel

Tags copied from class: Channel

Parameters:

targets - A list of members which are contacted for states. If the list is null, all the current members of the group will be contacted.

timeout - Milliseconds to wait for the response (0 = wait indefinitely).

Returns:

boolean True if the state was retrieved successfully, otherwise false.

ReturnState

public void ReturnState(java.lang.Object state)

Description copied from class: Channel

Called by the application is response to receiving a GetState object when calling Receive.

Overrides:

ReturnState in class Channel

Tags copied from class: Channel

Parameters:

state - The state of the application as a Serializable or Externaizable (to send over the network).

Up

public void Up(Event evt)

Called by the ProtocolStack when a message is received. It will be added to the message queue from which subsequent Receives will dequeue it.

Down

public void Down(Event evt)

Description copied from class: Channel

Access to event mechanism of channels. Enables to send and receive events, used by building blocks to communicate with (building block) specific protocol layers. Currently useful only with JChannel.

Overrides:

Down in class Channel