org.jgroups
Class EnsChannel

java.lang.Object
  extended byorg.jgroups.Channel
      extended byorg.jgroups.EnsChannel
All Implemented Interfaces:
Hot_Callbacks, Transport

public class EnsChannel
extends Channel
implements Hot_Callbacks

EnsChannel is an implementation of Channel based on Ensemble. It maps a process group to a channel. Requirements are the presence of an executable called outboard (which is Ensemble) and gossip running.


Field Summary
 
Fields inherited from class org.jgroups.Channel
AUTO_GETSTATE, AUTO_RECONNECT, BLOCK, channel_listener, GET_STATE_EVENTS, LOCAL, SUSPECT, up_handler, VIEW
 
Constructor Summary
EnsChannel()
           
EnsChannel(java.lang.Object props)
          Creates a new EnsChannel, which spawns an outboard process and connects to it.
EnsChannel(java.lang.Object props, java.lang.String transport_props, int outboard_port)
          Creates a new EnsChannel.
 
Method Summary
 void acceptedView(Hot_GroupContext gctx, java.lang.Object env, Hot_ViewState viewState)
          Called to update you with the new view
 void block(Hot_GroupContext gctx, java.lang.Object env)
          Called to let you know Ensemble is blocking
 void blockOk()
          Called to acknowledge a block() (callback in MembershipListener or BlockEvent received from call to Receive).
 void close()
          Destroys the channel and its associated resources (e.g.
 void connect(java.lang.String channel_name)
          Connects the channel to a group.
 void disconnect()
          Disconnects the channel from the current group (if connected), leaving the group.
 void exit(Hot_GroupContext gctx, java.lang.Object env)
          Called upon an Exit
 void finalize()
           
 boolean getAllStates(java.util.Vector targets, long timeout)
          Retrieve all states of the group members.
 java.lang.String getChannelName()
          Returns the group address of the group of which the channel is a member.
 Address getLocalAddress()
          Returns the channel's own address.
 java.lang.Object getOpt(int option)
          Gets an option.
 boolean getState(Address target, long timeout)
          Retrieve the state of the group.
 View getView()
          Gets the current view.
 void heartbeat(Hot_GroupContext gctx, java.lang.Object env, int rate)
          Called to issue you a heartbeat
 boolean isConnected()
          Determines whether the channel is connected to a group.
 boolean isOpen()
          Determines whether the channel is open, ie.
 java.lang.Object peek(long timeout)
          Returns the next message, view, block, suspect or other event without removing it from the queue.
 java.lang.Object receive(long timeout)
          Receives a message, a view change or a block event.
 void receiveCast(Hot_GroupContext gctx, java.lang.Object env, Hot_Endpoint origin, Hot_Message msg)
          Called when Ensemble receives a Cast from your group
 void receiveSend(Hot_GroupContext gctx, java.lang.Object env, Hot_Endpoint origin, Hot_Message msg)
          Called when Ensemble receives a point-to-point message for you
 void returnState(byte[] state)
          Called by the application is response to receiving a getState() object when calling receive().
 void send(Address dst, Address src, java.io.Serializable obj)
          Helper method.
 void send(Message msg)
          Sends a message to a (unicast) destination.
 void setOpt(int option, java.lang.Object value)
          Sets an option.
 
Methods inherited from class org.jgroups.Channel
down, getNumMessages, open, option2String, setChannelListener, setUpHandler
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EnsChannel

public EnsChannel()
           throws ChannelException

EnsChannel

public EnsChannel(java.lang.Object props)
           throws ChannelException
Creates a new EnsChannel, which spawns an outboard process and connects to it.


EnsChannel

public EnsChannel(java.lang.Object props,
                  java.lang.String transport_props,
                  int outboard_port)
           throws ChannelException
Creates a new EnsChannel. Instead of spawning a new outboard process, it connects to an already running outboard process (on the same machine) using outboard_port. This allows multiple EnsChannels to share a copy of outboard. If the port is 0, outboard will be spawned. Parameter transport_props defines the type of transport to be used (UDP, ATM, IP MCAST etc).

Parameters:
transport_props - Transport parameters. Null means use default (UDP). Example: "UDP:DEERING" uses IP multicast (gossip is not needed in this case).
outboard_port - Port on which the local outboard process is listening. The outboard process has to be started before. Value of 0 means spawn outboard nevertheless.
Method Detail

connect

public void connect(java.lang.String channel_name)
             throws ChannelClosedException
Description copied from class: Channel
Connects the channel to a group. The client is now able to receive group messages, views and block events (depending on the options set) and to send messages to (all or single) group members. This is a null operation if already connected.

All channels with the same name form a group, that means all messages sent to the group will be received by all channels connected to the same channel name.

Specified by:
connect in class Channel
Parameters:
channel_name - The name of the chanel to connect to.
Throws:
ChannelClosedException - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
See Also:
Channel.disconnect()

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.

Specified by:
disconnect in class Channel
See Also:
Channel.connect(String)

close

public void close()
Description copied from class: Channel
Destroys the channel and its associated resources (e.g. the protocol stack). After a channel has been closed, invoking methods on it throws the ChannelClosed exception (or results in a null operation). It is a null operation if the channel is already closed.

If the channel is connected to a group, disconnec()t will be called first.

Specified by:
close in class Channel

isOpen

public boolean isOpen()
Description copied from class: Channel
Determines whether the channel is open, ie. the protocol stack has been created (may not be connected though).

Specified by:
isOpen in class Channel

isConnected

public boolean isConnected()
Description copied from class: Channel
Determines whether the channel is connected to a group. This implies it is open. If true is returned, then the channel can be used to send and receive messages.

Specified by:
isConnected in class Channel

finalize

public void finalize()

send

public void send(Message msg)
          throws ChannelNotConnectedException,
                 ChannelClosedException
Description copied from class: Channel
Sends a message to a (unicast) destination. The message contains
  1. a destination address (Address). 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.

Specified by:
send in interface Transport
Specified by:
send in 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:
ChannelClosedException - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
ChannelNotConnectedException - The channel must be connected to send messages.

send

public void send(Address dst,
                 Address src,
                 java.io.Serializable obj)
          throws ChannelNotConnectedException,
                 ChannelClosedException
Description copied from class: Channel
Helper method. Will create a Message(dst, src, obj) and use send(Message).

Specified by:
send in class Channel
Parameters:
dst - Destination address for message. If null, message will be sent to all current group members
src - Source (sender's) address. If null, it will be set by the protocol's transport layer before being put on the wire. Can usually be set to null.
obj - Serializable object. Will be serialized into the byte buffer of the Message. If it is not serializable, the byte buffer will be null.
Throws:
ChannelNotConnectedException
ChannelClosedException

receive

public java.lang.Object receive(long timeout)
                         throws ChannelNotConnectedException,
                                ChannelClosedException,
                                TimeoutException
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).
  8. ExitEvent. Signals that this member was forced to leave the group (e.g. caused by the member being suspected. The member can rejoin the group by calling open(). If the AUTO_RECONNECT is set (see setOpt()), the reconnect will be done automatically.
The instanceof operator can be used to discriminate between different types returned.

Specified by:
receive in interface Transport
Specified by:
receive in class Channel
Parameters:
timeout - Value in milliseconds. Value <= 0 means wait forever
Returns:
A Message, View, BlockEvent, SuspectEvent, GetStateEvent, SetStateEvent or ExitEvent, depending on what is on top of the internal queue.
Throws:
TimeoutException - Thrown when a timeout has occurred.
ChannelNotConnectedException - The channel must be connected to receive messages.
ChannelClosedException - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.

peek

public java.lang.Object peek(long timeout)
                      throws ChannelNotConnectedException,
                             ChannelClosedException,
                             TimeoutException
Description copied from class: Channel
Returns the next message, view, block, suspect or other event without removing it from the queue.

Specified by:
peek in 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:
ChannelClosedException - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
ChannelNotConnectedException - The channel must be connected to receive messages.
TimeoutException - Thrown when a timeout has occurred.
See Also:
Channel.receive(long)

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.

Specified by:
getView in class Channel
Returns:
The current view.

getLocalAddress

public Address 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.

Specified by:
getLocalAddress in class Channel
Returns:
The channel's address. Generated by the underlying transport, and opaque. Addresses can be used as destination in the Send operation.

getChannelName

public java.lang.String getChannelName()
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.

Specified by:
getChannelName in 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. 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. Turn the reception of VIEW events on/off (value is Boolean). Default is on.
  3. SUSPECT. Turn the reception of SUSPECT events on/off (value is Boolean). Default is on.
  4. LOCAL. Receive its own broadcast messages to the group (value is Boolean). Default is on.
  5. GET_STATE_EVENTS. 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).
  6. AUTO_RECONNECT. Turn auto-reconnection on/off. If on, when a member if forced out of a group (EXIT event), then we will reconnect.
  7. AUTO_GETSTATE. Turn automatic fetching of state after an auto-reconnect on/off. This also sets AUTO_RECONNECT to true (if not yet set).
This method can be called on an unconnected channel. Calling this method on a closed channel has no effect.

Specified by:
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.

Specified by:
getOpt in 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.

Specified by:
blockOk in class Channel

getState

public boolean getState(Address target,
                        long timeout)
Description copied from class: Channel
Retrieve the state of the group. Will usually contact the oldest group member to get the state. When the method returns true, a SetStateEvent will have been added to the channel's queue, causing receive() to return the state in one of the next invocations. If false, no state will be retrieved by receive().

Specified by:
getState in class Channel
Parameters:
target - The address of the member from which the state is to be retrieved. If it is null, the coordinator 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)
Description copied from class: Channel
Retrieve all states of the group members. Will contact all group members to get the states. When the method returns true, a SetStateEvent will have been added to the channel's queue, causing Receive to return the states in one of the next invocations. If false, no states will be retrieved by Receive.

Specified by:
getAllStates in 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(byte[] state)
Description copied from class: Channel
Called by the application is response to receiving a getState() object when calling receive().

Specified by:
returnState in class Channel
Parameters:
state - The state of the application as a byte buffer (to send over the network).

receiveCast

public void receiveCast(Hot_GroupContext gctx,
                        java.lang.Object env,
                        Hot_Endpoint origin,
                        Hot_Message msg)
Description copied from interface: Hot_Callbacks
Called when Ensemble receives a Cast from your group

Specified by:
receiveCast in interface Hot_Callbacks

receiveSend

public void receiveSend(Hot_GroupContext gctx,
                        java.lang.Object env,
                        Hot_Endpoint origin,
                        Hot_Message msg)
Description copied from interface: Hot_Callbacks
Called when Ensemble receives a point-to-point message for you

Specified by:
receiveSend in interface Hot_Callbacks

acceptedView

public void acceptedView(Hot_GroupContext gctx,
                         java.lang.Object env,
                         Hot_ViewState viewState)
Description copied from interface: Hot_Callbacks
Called to update you with the new view

Specified by:
acceptedView in interface Hot_Callbacks

heartbeat

public void heartbeat(Hot_GroupContext gctx,
                      java.lang.Object env,
                      int rate)
Description copied from interface: Hot_Callbacks
Called to issue you a heartbeat

Specified by:
heartbeat in interface Hot_Callbacks

block

public void block(Hot_GroupContext gctx,
                  java.lang.Object env)
Description copied from interface: Hot_Callbacks
Called to let you know Ensemble is blocking

Specified by:
block in interface Hot_Callbacks

exit

public void exit(Hot_GroupContext gctx,
                 java.lang.Object env)
Description copied from interface: Hot_Callbacks
Called upon an Exit

Specified by:
exit in interface Hot_Callbacks


Copyright © 2001,2002 www.jgroups.com . All Rights Reserved.