org.jgroups

Class JChannel

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.

Properties

Properties are used to configure a channel, and are accepted in several forms; the String form is described here. A property string consists of a number of properties separated by colons. For example:

"<prop1>(arg1=val1):<prop2>(arg1=val1;arg2=val2):<prop3>:<propn>"

Each property relates directly to a protocol layer, which is implemented as a Java class. When a protocol stack is to be created based on the above property string, the first property becomes the bottom-most layer, the second one will be placed on the first, etc.: the stack is created from the bottom to the top, as the string is parsed from left to right. Each property has to be the name of a Java class that resides in the org.jgroups.protocols package.

Note that only the base name has to be given, not the fully specified class name (e.g., UDP instead of org.jgroups.protocols.UDP).

Each layer may have 0 or more arguments, which are specified as a list of name/value pairs in parentheses directly after the property. In the example above, the first protocol layer has 1 argument, the second 2, the third none. When a layer is created, these properties (if there are any) will be set in a layer by invoking the layer's setProperties() method

As an example the property string below instructs JGroups to create a JChannel with protocols UDP, PING, FD and GMS:

"UDP(mcast_addr=228.10.9.8;mcast_port=5678):PING:FD:GMS"

The UDP protocol layer is at the bottom of the stack, and it should use mcast address 228.10.9.8. and port 5678 rather than the default IP multicast address and port. The only other argument instructs FD to output debug information while executing. Property UDP refers to a class UDP, which is subsequently loaded and an instance of which is created as protocol layer. If any of these classes are not found, an exception will be thrown and the construction of the stack will be aborted.

Version:
$Revision: 1.45.2.1 $
Authors:
Bela Ban
Filip Hanik

Field Summary

static String
DEFAULT_PROTOCOL_STACK
The default protocol stack used by the default constructor.
protected org.jgroups.JChannel.CloserThread
closer
Thread responsible for closing a channel and potentially reconnecting to it (e.g., when shunned).
protected Log
log
protected long
received_bytes
protected long
received_msgs
protected long
sent_bytes
protected long
sent_msgs
protected boolean
stats
Collect statistics

Fields inherited from class org.jgroups.Channel

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

Constructor Summary

JChannel()
Constructs a JChannel instance with the protocol stack specified by the DEFAULT_PROTOCOL_STACK member.
JChannel(Element properties)
Constructs a JChannel instance with the protocol stack configuration contained by the specified XML element.
JChannel(File properties)
Constructs a JChannel instance with the protocol stack configuration contained by the specified file.
JChannel(Object properties)
Deprecated. Use the constructors with specific parameter types instead.
JChannel(String properties)
Constructs a JChannel instance with the protocol stack configuration based upon the specified properties parameter.
JChannel(URL properties)
Constructs a JChannel instance with the protocol stack configuration indicated by the specified URL.
JChannel(ProtocolStackConfigurator configurator)
Constructs a JChannel instance with the protocol stack configuration contained by the protocol stack configurator 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.
void
connect(String channel_name)
Connects the channel to a group.
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
String
dumpQueue()
Map
dumpStats()
Returns a map of statistics of the various protocols and of the channel itself.
String
dumpTimerQueue()
void
enableStats(boolean stats)
boolean
getAllStates(Vector targets, long timeout)
Retrieves the current group state.
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
protected Log
getLog()
int
getNumMessages()
int
getNumberOfTasksInTimer()
Object
getOpt(int option)
returns the value of an option.
String
getProperties()
returns the protocol stack configuration in string format.
ProtocolStack
getProtocolStack()
Returns the protocol stack.
long
getReceivedBytes()
long
getReceivedMessages()
long
getSentBytes()
long
getSentMessages()
boolean
getState(Address target, long timeout)
Retrieves the current group state.
View
getView()
Returns the current view.
boolean
isConnected()
returns true if the Connect operation has been called successfully
boolean
isOpen()
returns true if the Open operation has been called successfully
boolean
isSuspended()
void
open()
Opens the channel.
Object
peek(long timeout)
Just peeks at the next message, view or block.
String
printProtocolSpec(boolean include_properties)
Returns a pretty-printed form of all the protocols.
Object
receive(long timeout)
Blocking receive method.
void
resetStats()
void
resume()
Send() unblocks
void
returnState(byte[] state)
Called by the application is response to receiving a getState() object when calling receive().
void
send(Address dst, Address src, 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)
Sends a message through the protocol stack.
void
setOpt(int option, Object value)
Sets a channel option.
void
shutdown()
Shuts down the channel without disconnecting
boolean
statsEnabled()
void
suspend()
Send() blocks from now on, until resume() is called
String
toString(boolean details)
void
up(Event evt)
Callback method
Called by the ProtocolStack when a message is received.

Methods inherited from class org.jgroups.Channel

addChannelListener, blockOk, close, connect, disconnect, down, dumpQueue, dumpStats, getAllStates, getChannelName, getLocalAddress, getLog, getNumMessages, getOpt, getState, getView, isConnected, isOpen, notifyChannelClosed, notifyChannelConnected, notifyChannelDisconnected, notifyChannelReconnected, notifyChannelShunned, open, option2String, peek, receive, removeChannelListener, returnState, send, send, setChannelListener, setOpt, setReceiver, setUpHandler

Field Details

DEFAULT_PROTOCOL_STACK

public static final String DEFAULT_PROTOCOL_STACK
The default protocol stack used by the default constructor.

closer

protected org.jgroups.JChannel.CloserThread closer
Thread responsible for closing a channel and potentially reconnecting to it (e.g., when shunned).

log

protected final Log log

received_bytes

protected long received_bytes

received_msgs

protected long received_msgs

sent_bytes

protected long sent_bytes

sent_msgs

protected long sent_msgs

stats

protected boolean stats
Collect statistics

Constructor Details

JChannel

public JChannel()
            throws ChannelException
Constructs a JChannel instance with the protocol stack specified by the DEFAULT_PROTOCOL_STACK member.
Throws:
ChannelException - if problems occur during the initialization of the protocol stack.

JChannel

public JChannel(Element properties)
            throws ChannelException
Constructs a JChannel instance with the protocol stack configuration contained by the specified XML element.
Parameters:
properties - a XML element containing a JGroups XML protocol stack configuration.
Throws:
ChannelException - if problems occur during the configuration or initialization of the protocol stack.

JChannel

public JChannel(File properties)
            throws ChannelException
Constructs a JChannel instance with the protocol stack configuration contained by the specified file.
Parameters:
properties - a file containing a JGroups XML protocol stack configuration.
Throws:
ChannelException - if problems occur during the configuration or initialization of the protocol stack.

JChannel

public JChannel(Object properties)
            throws ChannelException

Deprecated. Use the constructors with specific parameter types instead.

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"
Other examples can be found in the ./conf directory
Parameters:
properties - the protocol stack setup; if null, the default protocol stack will be used. The properties can also be a java.net.URL object or a string that is a URL spec. The JChannel will validate any URL object and String object to see if they are a URL. In case of the parameter being a url, the JChannel will try to load the xml from there. In case properties is a org.w3c.dom.Element, the ConfiguratorFactory will parse the DOM tree with the element as its root element.

JChannel

public JChannel(String properties)
            throws ChannelException
Constructs a JChannel instance with the protocol stack configuration based upon the specified properties parameter.
Parameters:
properties - an old style property string, a string representing a system resource containing a JGroups XML configuration, a string representing a URL pointing to a JGroups XML XML configuration, or a string representing a file name that contains a JGroups XML configuration.
Throws:
ChannelException - if problems occur during the configuration and initialization of the protocol stack.

JChannel

public JChannel(URL properties)
            throws ChannelException
Constructs a JChannel instance with the protocol stack configuration indicated by the specified URL.
Parameters:
properties - a URL pointing to a JGroups XML protocol stack configuration.
Throws:
ChannelException - if problems occur during the configuration or initialization of the protocol stack.

JChannel

protected JChannel(ProtocolStackConfigurator configurator)
            throws ChannelException
Constructs a JChannel instance with the protocol stack configuration contained by the protocol stack configurator parameter.

All of the public constructors of this class eventually delegate to this method.

Parameters:
configurator - a protocol stack configurator containing a JGroups protocol stack configuration.
Throws:
ChannelException - if problems occur during the initialization of the protocol stack.

Method Details

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.
Overrides:
blockOk in interface Channel

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
Overrides:
close in interface Channel

connect

public void connect(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.
Overrides:
connect in interface 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.

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
Overrides:
disconnect in interface Channel

down

public void down(Event evt)
Sends a message through the protocol stack if the stack is available
Overrides:
down in interface Channel
Parameters:
evt - the message to send down, encapsulated in an event

dumpQueue

public String dumpQueue()
Overrides:
dumpQueue in interface Channel

dumpStats

public Map dumpStats()
Returns a map of statistics of the various protocols and of the channel itself.
Overrides:
dumpStats in interface Channel
Returns:
Map. A map where the keys are the protocols ("channel" pseudo key is used for the channel itself") and the values are property maps.

dumpTimerQueue

public String dumpTimerQueue()

enableStats

public void enableStats(boolean stats)

getAllStates

public boolean getAllStates(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.
Overrides:
getAllStates in interface 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

getChannelName

public String getChannelName()
returns the name of the channel if the channel is not connected or if it is closed it will return null
Overrides:
getChannelName in interface Channel

getLocalAddress

public Address getLocalAddress()
returns the local address of the channel returns null if the channel is closed
Overrides:
getLocalAddress in interface Channel

getLog

protected Log getLog()
Overrides:
getLog in interface Channel

getNumMessages

public int getNumMessages()
Overrides:
getNumMessages in interface Channel

getNumberOfTasksInTimer

public int getNumberOfTasksInTimer()

getOpt

public Object getOpt(int option)
returns the value of an option.
Overrides:
getOpt in interface Channel
Parameters:
option - the option you want to see the value for
Returns:
the object value, in most cases java.lang.Boolean

getProperties

public 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"

getProtocolStack

public ProtocolStack getProtocolStack()
Returns the protocol stack. Currently used by Debugger. Specific to JChannel, therefore not visible in Channel

getReceivedBytes

public long getReceivedBytes()

getReceivedMessages

public long getReceivedMessages()

getSentBytes

public long getSentBytes()

getSentMessages

public long getSentMessages()

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.
Overrides:
getState in interface 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

getView

public View getView()
Returns the current view.
If the channel is not connected or if it is closed it will return null.
Overrides:
getView in interface Channel
Returns:
returns the current group view, or null if the channel is closed or disconnected

isConnected

public boolean isConnected()
returns true if the Connect operation has been called successfully
Overrides:
isConnected in interface Channel

isOpen

public boolean isOpen()
returns true if the Open operation has been called successfully
Overrides:
isOpen in interface Channel

isSuspended

public boolean isSuspended()

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 interface Channel

peek

public 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
Overrides:
peek in interface Channel

printProtocolSpec

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

receive

public 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
Overrides:
receive in interface Channel
Parameters:
timeout - the number of milliseconds to wait if the receive queue is empty. 0 means wait forever
Throws:
TimeoutException - if a timeout occured prior to a new message was received
ChannelNotConnectedException -
ChannelClosedException -
See Also:
peek(long)

resetStats

public void resetStats()

resume

public void resume()
Send() unblocks

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
Overrides:
returnState in interface Channel
Parameters:
state - The state of the application as a byte buffer (to send over the network).

send

public void send(Address dst,
                 Address src,
                 Serializable obj)
            throws ChannelNotConnectedException,
                   ChannelClosedException
creates a new message with the destination address, and the source address and the object as the message value
Overrides:
send in interface 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
See Also:
JChannel.send

send

public void send(Message msg)
            throws ChannelNotConnectedException,
                   ChannelClosedException
Sends a message through the protocol stack. Implements the Transport interface.
Specified by:
send in interface Transport
Overrides:
send in interface Channel
Parameters:
msg - the message to be sent through the protocol stack, the destination of the message is specified inside the message itself

setOpt

public void setOpt(int option,
                   Object value)
Sets a channel option. The options can be one of the following:
  • 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

Overrides:
setOpt in interface Channel
Parameters:
option - the parameter option Channel.VIEW, Channel.SUSPECT, etc
value - the value to set for this option

shutdown

public void shutdown()
Shuts down the channel without disconnecting

statsEnabled

public boolean statsEnabled()

suspend

public void suspend()
Send() blocks from now on, until resume() is called

toString

public String toString(boolean details)

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

Copyright B) 1998-2005 Bela Ban. All Rights Reserved.