Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> [ jgroups overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

org.jgroups
Class JChannel  

java.lang.Object
  org.jgroups.Channel
      org.jgroups.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.

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 org.jgroups.protocols.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.44 $

---

Nested Class Summary
(package private)  class	JChannel.CloserThread

 

Field Summary
private  byte[]	additional_data           Used to maintain additional data across channel disconnects/reconnects.
private  boolean	auto_getstate
private  boolean	auto_reconnect
private  org.jgroups.util.CondVar	block_sending           block send()/down() if true (unlocked by UNBLOCK_SEND event)
private  java.lang.String	channel_name
private  boolean	closed
protected  JChannel.CloserThread	closer           Thread responsible for closing a channel and potentially reconnecting to it (e.g., when shunned).
private  org.jgroups.util.Promise	connect_promise           To wait until we have connected successfully
private  boolean	connected
static java.lang.String	DEFAULT_PROTOCOL_STACK           The default protocol stack used by the default constructor.
private  org.jgroups.util.Promise	disconnect_promise           To wait until we have been disconnected from the channel
(package private) static java.lang.String	FORCE_PROPS
private static long	GET_STATE_DEFAULT_TIMEOUT
private  Address	local_addr
private  org.jgroups.util.Promise	local_addr_promise           To wait until a local address has been assigned
private  long	LOCAL_ADDR_TIMEOUT           wait until we have a non-null local_addr
protected  org.apache.commons.logging.Log	log
private  org.jgroups.util.Queue	mq
private  View	my_view
private  java.lang.String	props
private  org.jgroups.stack.ProtocolStack	prot_stack
private  boolean	receive_blocks
private  boolean	receive_get_states
private  boolean	receive_local_msgs
private  boolean	receive_suspects
private  boolean	receive_views
protected  long	received_bytes
protected  long	received_msgs
protected  long	sent_bytes
protected  long	sent_msgs
private  org.jgroups.util.Promise	state_promise
private  boolean	state_transfer_supported           True if a state transfer protocol is available, false otherwise
protected  boolean	stats           Collect statistics
private  java.lang.Object	suspend_mutex
private  boolean	suspended

 

Fields inherited from class org.jgroups.Channel

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

 

Constructor Summary
	JChannel()           Constructs a JChannel instance with the protocol stack specified by the DEFAULT_PROTOCOL_STACK member.
	JChannel(org.w3c.dom.Element properties)           Constructs a JChannel instance with the protocol stack configuration contained by the specified XML element.
	JChannel(java.io.File properties)           Constructs a JChannel instance with the protocol stack configuration contained by the specified file.
	JChannel(java.lang.Object properties)           Deprecated. Use the constructors with specific parameter types instead.
protected	JChannel(org.jgroups.conf.ProtocolStackConfigurator configurator)           Constructs a JChannel instance with the protocol stack configuration contained by the protocol stack configurator parameter.
	JChannel(java.lang.String properties)           Constructs a JChannel instance with the protocol stack configuration based upon the specified properties parameter.
	JChannel(java.net.URL properties)           Constructs a JChannel instance with the protocol stack configuration indicated by the specified URL.

 

Method Summary
private  void	_close(boolean disconnect, boolean close_mq)           Disconnects and closes the channel.
(package private)  boolean	_getState(Event evt, long timeout)           Receives the state from the group and modifies the JChannel.state object This method initializes the local state variable to null, and then sends the state event down the stack.
void	blockOk()           Called to acknowledge a block() (callback in MembershipListener or BlockEvent received from call to receive()).
private  void	checkClosed()           health check throws a ChannelClosed exception if the channel is closed
private  void	checkNotConnected()           health check. throws a ChannelNotConnected exception if the channel is not connected
void	close()           Destroys the channel.
void	connect(java.lang.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
private  java.util.Map	dumpChannelStats()
java.lang.String	dumpQueue()
java.util.Map	dumpStats()           Returns a map of statistics of the various protocols and of the channel itself.
java.lang.String	dumpTimerQueue()
void	enableStats(boolean stats)
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
(package private) static java.lang.Object	getEvent(Event evt)           returns the value of the event These objects will be returned
Address	getLocalAddress()           returns the local address of the channel returns null if the channel is closed
protected  org.apache.commons.logging.Log	getLog()
int	getNumberOfTasksInTimer()
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.
org.jgroups.stack.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.
private  void	handleExit(Event evt)           Creates a separate thread to close the protocol stack.
private  void	init()           Initializes all variables.
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.
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	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, 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)           Sends a message through the protocol stack.
void	setOpt(int option, java.lang.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
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.jgroups.Channel

addChannelListener, notifyChannelClosed, notifyChannelConnected, notifyChannelDisconnected, notifyChannelReconnected, notifyChannelShunned, option2String, removeChannelListener, setChannelListener, setReceiver, setUpHandler

 

Methods inherited from class java.lang.Object

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

 

Field Detail

DEFAULT_PROTOCOL_STACK

public static final java.lang.String DEFAULT_PROTOCOL_STACK

The default protocol stack used by the default constructor.

See Also:

Constant Field Values

---

FORCE_PROPS

static final java.lang.String FORCE_PROPS

See Also:

Constant Field Values

---

props

private java.lang.String props

---

local_addr

private Address local_addr

---

channel_name

private java.lang.String channel_name

---

my_view

private View my_view

---

mq

private final org.jgroups.util.Queue mq

---

prot_stack

private org.jgroups.stack.ProtocolStack prot_stack

---

closer

protected JChannel.CloserThread closer

Thread responsible for closing a channel and potentially reconnecting to it (e.g., when shunned).

---

local_addr_promise

private final org.jgroups.util.Promise local_addr_promise

To wait until a local address has been assigned

---

connect_promise

private final org.jgroups.util.Promise connect_promise

To wait until we have connected successfully

---

disconnect_promise

private final org.jgroups.util.Promise disconnect_promise

To wait until we have been disconnected from the channel

---

state_promise

private final org.jgroups.util.Promise state_promise

---

suspend_mutex

private final java.lang.Object suspend_mutex

---

suspended

private boolean suspended

---

LOCAL_ADDR_TIMEOUT

private long LOCAL_ADDR_TIMEOUT

wait until we have a non-null local_addr

---

GET_STATE_DEFAULT_TIMEOUT

private static final long GET_STATE_DEFAULT_TIMEOUT

See Also:

Constant Field Values

---

receive_views

private boolean receive_views

---

receive_suspects

private boolean receive_suspects

---

receive_blocks

private boolean receive_blocks

---

receive_local_msgs

private boolean receive_local_msgs

---

receive_get_states

private boolean receive_get_states

---

auto_reconnect

private boolean auto_reconnect

---

auto_getstate

private boolean auto_getstate

---

connected

private boolean connected

---

block_sending

private final org.jgroups.util.CondVar block_sending

block send()/down() if true (unlocked by UNBLOCK_SEND event)

---

closed

private boolean closed

---

state_transfer_supported

private boolean state_transfer_supported

True if a state transfer protocol is available, false otherwise

---

additional_data

private byte[] additional_data

Used to maintain additional data across channel disconnects/reconnects. This is a kludge and will be remove as soon as JGroups supports logical addresses

---

log

protected final org.apache.commons.logging.Log log

---

stats

protected boolean stats

Collect statistics

---

sent_msgs

protected long sent_msgs

---

received_msgs

protected long received_msgs

---

sent_bytes

protected long sent_bytes

---

received_bytes

protected long received_bytes

Constructor Detail

JChannel

public JChannel()
         throws ChannelException

Constructs a JChannel instance with the protocol stack specified by the DEFAULT_PROTOCOL_STACK member.

---

JChannel

public JChannel(java.io.File properties)
         throws ChannelException

Constructs a JChannel instance with the protocol stack configuration contained by the specified file.

---

JChannel

public JChannel(org.w3c.dom.Element properties)
         throws ChannelException

Constructs a JChannel instance with the protocol stack configuration contained by the specified XML element.

---

JChannel

public JChannel(java.net.URL properties)
         throws ChannelException

Constructs a JChannel instance with the protocol stack configuration indicated by the specified URL.

---

JChannel

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

Constructs a JChannel instance with the protocol stack configuration based upon the specified properties parameter.

---

JChannel

protected JChannel(org.jgroups.conf.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.

---

JChannel

public JChannel(java.lang.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

Method Detail

getProtocolStack

public org.jgroups.stack.ProtocolStack getProtocolStack()

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

---

getLog

protected org.apache.commons.logging.Log getLog()

Specified by:

getLog in class 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"

---

statsEnabled

public boolean statsEnabled()

---

enableStats

public void enableStats(boolean stats)

---

resetStats

public void resetStats()

---

getSentMessages

public long getSentMessages()

---

getSentBytes

public long getSentBytes()

---

getReceivedMessages

public long getReceivedMessages()

---

getReceivedBytes

public long getReceivedBytes()

---

getNumberOfTasksInTimer

public int getNumberOfTasksInTimer()

---

dumpTimerQueue

public java.lang.String dumpTimerQueue()

---

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

---

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

---

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

---

shutdown

public void shutdown()

Shuts down the channel without disconnecting

Specified by:

shutdown 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

---

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) 55 . 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

---

dumpQueue

public java.lang.String dumpQueue()

Overrides:

dumpQueue in class Channel

---

dumpStats

public java.util.Map dumpStats()

Returns a map of statistics of the various protocols and of the channel itself.

Specified by:

dumpStats in class Channel

---

dumpChannelStats

private java.util.Map dumpChannelStats()

---

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

Specified by:

send in class Channel

---

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

---

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

---

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

---

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

---

getLocalAddress

public Address getLocalAddress()

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

Specified by:

getLocalAddress in class Channel

---

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

---

setOpt

public void setOpt(int option,
                   java.lang.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

Specified by:

setOpt in class Channel

---

getOpt

public java.lang.Object getOpt(int option)

returns the value of an option.

Specified by:

getOpt in class Channel

---

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

---

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

---

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

---

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.

---

down

public void down(Event evt)

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

Overrides:

down in class Channel

---

suspend

public void suspend()

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

---

resume

public void resume()

Send() unblocks

---

isSuspended

public boolean isSuspended()

---

toString

public java.lang.String toString(boolean details)

---

init

private void init()

Initializes all variables. Used after close() or disconnect(), to be ready for new connect()

---

checkNotConnected

private final void checkNotConnected()
                              throws ChannelNotConnectedException

health check.
throws a ChannelNotConnected exception if the channel is not connected

---

checkClosed

private final void checkClosed()
                        throws ChannelClosedException

health check
throws a ChannelClosed exception if the channel is closed

---

getEvent

static java.lang.Object getEvent(Event evt)

returns the value of the event
These objects will be returned

 Event Type    - Return Type
 Event.MSG           - returns a Message object
 Event.VIEW_CHANGE   - returns a View object
 Event.SUSPECT       - returns a SuspectEvent object
 Event.BLOCK         - returns a new BlockEvent object
 Event.GET_APPLSTATE - returns a GetStateEvent object
 Event.STATE_RECEIVED- returns a SetStateEvent object
 Event.Exit          - returns an ExitEvent object
 All other           - return the actual Event object
 

---

_getState

boolean _getState(Event evt,
                  long timeout)
            throws ChannelNotConnectedException,
                   ChannelClosedException

Receives the state from the group and modifies the JChannel.state object
This method initializes the local state variable to null, and then sends the state event down the stack. It waits for a GET_STATE_OK event to bounce back

---

_close

private void _close(boolean disconnect,
                    boolean close_mq)

Disconnects and closes the channel. This method does the folloing things

1. Calls this.disconnect if the disconnect parameter is true
2. Calls Queue.close on mq if the close_mq parameter is true
3. Calls ProtocolStack.stop on the protocol stack
4. Calls ProtocolStack.destroy on the protocol stack
5. Sets the channel closed and channel connected flags to true and false
6. Notifies any channel listener of the channel close operation

---

handleExit

private void handleExit(Event evt)

Creates a separate thread to close the protocol stack. This is needed because the thread that called JChannel.up() with the EXIT event would hang waiting for up() to return, while up() actually tries to kill that very thread. This way, we return immediately and allow the thread to terminate.

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> [ jgroups overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---