|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.jgroups.Channel
org.jgroups.JChannel
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.
Field Summary | |
protected org.jgroups.JChannel.CloserThread |
closer
Thread responsible for closing a channel and potentially reconnecting to it (e.g., when shunned). |
static java.lang.String |
DEFAULT_PROTOCOL_STACK
The default protocol stack used by the default constructor. |
protected org.apache.commons.logging.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, 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(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 | |
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.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 |
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 |
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. |
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. |
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 |
public static final java.lang.String DEFAULT_PROTOCOL_STACK
protected org.jgroups.JChannel.CloserThread closer
protected final org.apache.commons.logging.Log log
protected boolean stats
protected long sent_msgs
protected long received_msgs
protected long sent_bytes
protected long received_bytes
Constructor Detail |
public JChannel() throws ChannelException
JChannel
instance with the protocol stack
specified by the DEFAULT_PROTOCOL_STACK
member.
ChannelException
- if problems occur during the initialization of
the protocol stack.public JChannel(java.io.File properties) throws ChannelException
JChannel
instance with the protocol stack
configuration contained by the specified file.
properties
- a file containing a JGroups XML protocol stack
configuration.
ChannelException
- if problems occur during the configuration or
initialization of the protocol stack.public JChannel(org.w3c.dom.Element properties) throws ChannelException
JChannel
instance with the protocol stack
configuration contained by the specified XML element.
properties
- a XML element containing a JGroups XML protocol stack
configuration.
ChannelException
- if problems occur during the configuration or
initialization of the protocol stack.public JChannel(java.net.URL properties) throws ChannelException
JChannel
instance with the protocol stack
configuration indicated by the specified URL.
properties
- a URL pointing to a JGroups XML protocol stack
configuration.
ChannelException
- if problems occur during the configuration or
initialization of the protocol stack.public JChannel(java.lang.String properties) throws ChannelException
JChannel
instance with the protocol stack
configuration based upon the specified properties parameter.
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.
ChannelException
- if problems occur during the configuration and
initialization of the protocol stack.protected JChannel(ProtocolStackConfigurator configurator) throws ChannelException
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.
configurator
- a protocol stack configurator containing a JGroups
protocol stack configuration.
ChannelException
- if problems occur during the initialization of
the protocol stack.public JChannel(java.lang.Object properties) throws ChannelException
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.Method Detail |
public ProtocolStack getProtocolStack()
protected org.apache.commons.logging.Log getLog()
getLog
in class Channel
public java.lang.String getProperties()
public boolean statsEnabled()
public void enableStats(boolean stats)
public void resetStats()
public long getSentMessages()
public long getSentBytes()
public long getReceivedMessages()
public long getReceivedBytes()
public int getNumberOfTasksInTimer()
public java.lang.String dumpTimerQueue()
public java.lang.String printProtocolSpec(boolean include_properties)
public void connect(java.lang.String channel_name) throws ChannelException, ChannelClosedException
connect
in class Channel
channel_name
- A String
denoting the group name. Cannot be null.
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.Channel.disconnect()
public void disconnect()
disconnect
in class Channel
Channel.connect(String)
public void close()
close
in class Channel
public void shutdown()
public void open() throws ChannelException
open
in class Channel
ChannelException
public boolean isOpen()
isOpen
in class Channel
public boolean isConnected()
isConnected
in class Channel
public int getNumMessages()
Channel
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).
getNumMessages
in class Channel
public java.lang.String dumpQueue()
dumpQueue
in class Channel
public java.util.Map dumpStats()
dumpStats
in class Channel
public void send(Message msg) throws ChannelNotConnectedException, ChannelClosedException
send
in interface Transport
send
in class Channel
msg
- the message to be sent through the protocol stack,
the destination of the message is specified inside the message itself
ChannelNotConnectedException
ChannelClosedException
public void send(Address dst, Address src, java.io.Serializable obj) throws ChannelNotConnectedException, ChannelClosedException
send
in class Channel
dst
- - the destination address of the message, null for all memberssrc
- - the source address of the messageobj
- - the value of the message
ChannelNotConnectedException
ChannelClosedException
send(org.jgroups.Message)
public java.lang.Object receive(long timeout) throws ChannelNotConnectedException, ChannelClosedException, TimeoutException
receive
in interface Transport
receive
in class Channel
timeout
- the number of milliseconds to wait if the receive queue is empty. 0 means wait forever
TimeoutException
- if a timeout occured prior to a new message was received
ChannelNotConnectedException
ChannelClosedException
peek(long)
public java.lang.Object peek(long timeout) throws ChannelNotConnectedException, ChannelClosedException, TimeoutException
peek
in class Channel
timeout
- Value in milliseconds. Value <= 0 means wait forever
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.Channel.receive(long)
public View getView()
getView
in class Channel
public Address getLocalAddress()
getLocalAddress
in class Channel
Send
operation.public java.lang.String getChannelName()
getChannelName
in class Channel
public void setOpt(int option, java.lang.Object value)
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
setOpt
in class Channel
option
- the parameter option Channel.VIEW, Channel.SUSPECT, etcvalue
- the value to set for this optionpublic java.lang.Object getOpt(int option)
getOpt
in class Channel
option
- the option you want to see the value for
setOpt(int, java.lang.Object)
public void blockOk()
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.
blockOk
in class Channel
public boolean getState(Address target, long timeout) throws ChannelNotConnectedException, ChannelClosedException
timeout
milliseconds have elapsed. The argument of GET_STATE_OK should be a single object.
getState
in class Channel
target
- - the target member to receive the state from. if null, state is retrieved from coordinatortimeout
- - the number of milliseconds to wait for the operation to complete successfully
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.public boolean getAllStates(java.util.Vector targets, long timeout) throws ChannelNotConnectedException, ChannelClosedException
timeout
milliseconds have elapsed. The argument of GET_STATE_OK should be a vector of objects.
getAllStates
in class Channel
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
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.public void returnState(byte[] state)
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
returnState
in class Channel
state
- The state of the application as a byte buffer
(to send over the network).public void up(Event evt)
Receive
s will dequeue it.
evt
- the event carrying the message from the protocol stackpublic void down(Event evt)
down
in class Channel
evt
- the message to send down, encapsulated in an eventpublic void suspend()
public void resume()
public boolean isSuspended()
public java.lang.String toString(boolean details)
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |