org.javagroups
Class JChannel

java.lang.Object
  |
  +--org.javagroups.Channel
        |
        +--org.javagroups.JChannel

All Implemented Interfaces:

Transport

public class JChannel

extends Channel

JChannel is a pure Java implementation of Channel When a JChannel object is instantiated it automatically sets up the protocol stack

Version:

$Revision: 1.47 $

Author:

Bela Ban, Filip Hanik

Field Summary

Fields inherited from class org.javagroups.Channel

AUTO_GETSTATE, AUTO_RECONNECT, BLOCK, channel_listener, GET_STATE_EVENTS, LOCAL, SUSPECT, up_handler, VIEW

Constructor Summary

	JChannel() initializes the JChannel with its default settings and default protocol stack
protected	JChannel(boolean dummy) initializes the JChannel with its default settings and default protocol stack
	JChannel(java.lang.Object properties) creates a new JChannel with the protocol stack as defined in the properties parameter.

Method Summary

void	blockOk() Called to acknowledge a block() (callback in MembershipListener or BlockEvent received from call to receive()).
void	close() Destroys the channel. After this method has been called, the channel us unusable. This operation will disconnect the channel and close the channel receive queue immediately
void	connect(java.lang.String channel_name) Connects the channel to a group. If the channel is already connected, an error message will be printed to the error log If the channel is closed a ChannelClosed exception will be thrown This method starts the protocol stack by calling ProtocolStack.start then it sends an Event.CONNECT event down the stack and waits to receive a CONNECT_OK event Once the CONNECT_OK event arrives from the protocol stack, any channel listeners are notified and the channel is considered connected
void	disconnect() Disconnects the channel if it is connected.
void	down(Event evt) Sends a message through the protocol stack if the stack is available
boolean	getAllStates(java.util.Vector targets, long timeout) Retrieves the current group state.
java.lang.String	getChannelName() returns the name of the channel if the channel is not connected or if it is closed it will return null
Address	getLocalAddress() returns the local address of the channel returns null if the channel is closed
int	getNumMessages() Returns the number of messages that are waiting.
java.lang.Object	getOpt(int option) returns the value of an option.
java.lang.String	getProperties() returns the protocol stack configuration in string format.
ProtocolStack	getProtocolStack() Returns the protocol stack.
boolean	getState(Address target, long timeout) Retrieves the current group state.
View	getView() returns the current view. if the channel is not connected or if it is closed it will return null
boolean	isConnected() returns true if the Connect operation has been called successfully
boolean	isOpen() returns true if the Open operation has been called successfully
void	open() Opens the channel. this does the following actions 1.
java.lang.Object	peek(long timeout) Just peeks at the next message, view or block.
java.lang.String	printProtocolSpec(boolean include_properties) Returns a pretty-printed form of all the protocols.
java.lang.Object	receive(long timeout) Blocking receive method.
void	returnState(byte[] state) Called by the application is response to receiving a getState() object when calling receive(). When the application receives a getState() message on the receive() method, it should call returnState() to reply with the state of the application
void	send(Address dst, Address src, java.io.Serializable obj) creates a new message with the destination address, and the source address and the object as the message value
void	send(Message msg) implementation of the Transport interface. Sends a message through the protocol stack
void	setOpt(int option, java.lang.Object value) sets a channel option the options can be either
java.lang.String	toString(boolean details)
void	up(Event evt) Callback method Called by the ProtocolStack when a message is received.

Methods inherited from class org.javagroups.Channel

option2String, setChannelListener, setUpHandler

Methods inherited from class java.lang.Object

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

Constructor Detail

JChannel

protected JChannel(boolean dummy)
            throws ChannelException

initializes the JChannel with its default settings and default protocol stack

JChannel

public JChannel()
         throws ChannelException

initializes the JChannel with its default settings and default protocol stack

JChannel

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

creates a new JChannel with the protocol stack as defined in the properties parameter. an example of this parameter is
"UDP:PING:FD:STABLE:NAKACK:UNICAST:FRAG:FLUSH:GMS:VIEW_ENFORCER:STATE_TRANSFER:QUEUE"
Another example is http://www.filip.net/javagroups/javagroups-protocol.xml

Parameters:

properties - the protocol stack setup, if null, the default protocol stack will be used

Method Detail

getProtocolStack

public ProtocolStack getProtocolStack()

Returns the protocol stack. Currently used by Debugger. Specific to JChannel, therefore not visible in Channel

getProperties

public java.lang.String getProperties()

returns the protocol stack configuration in string format. an example of this property is
"UDP:PING:FD:STABLE:NAKACK:UNICAST:FRAG:FLUSH:GMS:VIEW_ENFORCER:STATE_TRANSFER:QUEUE"

printProtocolSpec

public java.lang.String printProtocolSpec(boolean include_properties)

Returns a pretty-printed form of all the protocols. If include_properties is set, the properties for each protocol will also be printed.

connect

public void connect(java.lang.String channel_name)
             throws ChannelException,
                    ChannelClosedException

Connects the channel to a group.
If the channel is already connected, an error message will be printed to the error log
If the channel is closed a ChannelClosed exception will be thrown
This method starts the protocol stack by calling ProtocolStack.start
then it sends an Event.CONNECT event down the stack and waits to receive a CONNECT_OK event
Once the CONNECT_OK event arrives from the protocol stack, any channel listeners are notified
and the channel is considered connected

Specified by:

connect in class Channel

Parameters:

channel_name - A String denoting the group name. Cannot be null.

Throws:

ChannelException - The protocol stack cannot be started

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()

Disconnects the channel if it is connected. If the channel is closed, this operation is ignored
Otherwise the following actions happen in the listed order

1. The JChannel sends a DISCONNECT event down the protocol stack
   
2. Blocks until the channel to receives a DISCONNECT_OK event
   
3. Sends a STOP_QUEING event down the stack
   
4. Stops the protocol stack by calling ProtocolStack.stop()
   
5. Notifies the listener, if the listener is available
   

Specified by:

disconnect in class Channel

See Also:

Channel.connect(String)

close

public void close()

Destroys the channel.
After this method has been called, the channel us unusable.
This operation will disconnect the channel and close the channel receive queue immediately

Specified by:

close in class Channel

open

public void open()
          throws ChannelException

Opens the channel.
this does the following actions
1. Resets the receiver queue by calling Queue.reset
2. Sets up the protocol stack by calling ProtocolStack.setup
3. Sets the closed flag to false.

Overrides:

open in class Channel

ChannelException

isOpen

public boolean isOpen()

returns true if the Open operation has been called successfully

Specified by:

isOpen in class Channel

isConnected

public boolean isConnected()

returns true if the Connect operation has been called successfully

Specified by:

isConnected in class Channel

getNumMessages

public int getNumMessages()

Description copied from class: Channel

Returns the number of messages that are waiting. Those messages can be removed by Channel.receive(long). Note that this number could change after calling this method and before calling receive() (e.g. the latter method might be called by a different thread).

Overrides:

getNumMessages in class Channel

Returns:

The number of messages on the queue, or -1 if the queue/channel is closed/disconnected.

send

public void send(Message msg)
          throws ChannelNotConnectedException,
                 ChannelClosedException

implementation of the Transport interface.
Sends a message through the protocol stack

Specified by:

send in interface Transport

Specified by:

send in class Channel

Parameters:

msg - the message to be sent through the protocol stack, the destination of the message is specified inside the message itself

Throws:

ChannelNotConnectedException

ChannelClosedException

send

public void send(Address dst,
                 Address src,
                 java.io.Serializable obj)
          throws ChannelNotConnectedException,
                 ChannelClosedException

creates a new message with the destination address, and the source address and the object as the message value

Specified by:

send in class Channel

Parameters:

dst - - the destination address of the message, null for all members

src - - the source address of the message

obj - - the value of the message

Throws:

ChannelNotConnectedException

ChannelClosedException

See Also:

send(org.javagroups.Message)

receive

public java.lang.Object receive(long timeout)
                         throws ChannelNotConnectedException,
                                ChannelClosedException,
                                TimeoutException

Blocking receive method. This method returns the object that was first received by this JChannel and that has not been received before. After the object is received, it is removed from the receive queue.
If you only want to inspect the object received without removing it from the queue call JChannel.peek
If no messages are in the receive queue, this method blocks until a message is added or the operation times out
By specifying a timeout of 0, the operation blocks forever, or until a message has been received.

Specified by:

receive in interface Transport

Specified by:

receive in class Channel

Parameters:

timeout - the number of milliseconds to wait if the receive queue is empty. 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 - if a timeout occured prior to a new message was received

ChannelNotConnectedException

ChannelClosedException

See Also:

peek(long)

peek

public java.lang.Object peek(long timeout)
                      throws ChannelNotConnectedException,
                             ChannelClosedException,
                             TimeoutException

Just peeks at the next message, view or block. Does not install new view if view is received
Does the same thing as JChannel.receive but doesn't remove the object from the receiver 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:

ChannelNotConnectedException - The channel must be connected to receive messages.

TimeoutException - Thrown when a timeout has occurred.

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

See Also:

Channel.receive(long)

getView

public View getView()

returns the current view.
if the channel is not connected or if it is closed it will return null

Specified by:

getView in class Channel

Returns:

returns the current group view, or null if the channel is closed or disconnected

getLocalAddress

public Address getLocalAddress()

returns the local address of the channel returns null if the channel is closed

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()

returns the name of the channel if the channel is not connected or if it is closed it will return null

Specified by:

getChannelName in class Channel

Returns:

The group address

setOpt

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

sets a channel option the options can be either

     Channel.BLOCK
     Channel.VIEW
     Channel.SUSPECT
     Channel.LOCAL
     Channel.GET_STATE_EVENTS
     Channel.AUTO_RECONNECT
     Channel.AUTO_GETSTATE
 

There are certain dependencies between the options that you can set, I will try to describe them here
Option: Channel.VIEW option
Value: java.lang.Boolean
Result: set to true the JChannel will receive VIEW change events

Option: Channel.SUSPECT
Value: java.lang.Boolean
Result: set to true the JChannel will receive SUSPECT events

Option: Channel.BLOCK
Value: java.lang.Boolean
Result: set to true will set setOpt(VIEW, true) and the JChannel will receive BLOCKS and VIEW events

Option: GET_STATE_EVENTS
Value: java.lang.Boolean
Result: set to true the JChannel will receive state events

Option: LOCAL
Value: java.lang.Boolean
Result: set to true the JChannel will receive messages that it self sent out.

Option: AUTO_RECONNECT
Value: java.lang.Boolean
Result: set to true and the JChannel will try to reconnect when it is being closed

Option: AUTO_GETSTATE
Value: java.lang.Boolean
Result: set to true, the AUTO_RECONNECT will be set to true and the JChannel will try to get the state after a close and reconnect happens

Specified by:

setOpt in class Channel

Parameters:

option - the parameter option Channel.VIEW, Channel.SUSPECT, etc

value - the value to set for this option

getOpt

public java.lang.Object getOpt(int option)

returns the value of an option.

Specified by:

getOpt in class Channel

Parameters:

option - the option you want to see the value for

Returns:

the object value, in most cases java.lang.Boolean

See Also:

setOpt(int, java.lang.Object)

blockOk

public void blockOk()

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)
                 throws ChannelNotConnectedException,
                        ChannelClosedException

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.

Specified by:

getState in class Channel

Parameters:

target - - the target member to receive the state from. if null, state is retrieved from coordinator

timeout - - the number of milliseconds to wait for the operation to complete successfully

Returns:

true of the state was received, false if the operation timed out

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.

getAllStates

public boolean getAllStates(java.util.Vector targets,
                            long timeout)
                     throws ChannelNotConnectedException,
                            ChannelClosedException

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.

Specified by:

getAllStates in class Channel

Parameters:

targets - - the target members to receive the state from ( an Address list )

timeout - - the number of milliseconds to wait for the operation to complete successfully

Returns:

true of the state was received, false if the operation timed out

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.

returnState

public void returnState(byte[] state)

Called by the application is response to receiving a getState() object when calling receive().
When the application receives a getState() message on the receive() method, it should call returnState() to reply with the state of the application

Specified by:

returnState in class Channel

Parameters:

state - The state of the application as a byte buffer (to send over the network).

up

public void up(Event evt)

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

Parameters:

evt - the event carrying the message from the protocol stack

down

public void down(Event evt)

Sends a message through the protocol stack if the stack is available

Overrides:

down in class Channel

Parameters:

evt - the message to send down, encapsulated in an event

toString

public java.lang.String toString(boolean details)