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.
JChannel
public JChannel()
throws ChannelException
Constructs a JChannel
instance with the protocol stack
specified by the DEFAULT_PROTOCOL_STACK
member.
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.
properties
- a XML element containing a JGroups XML protocol stack
configuration.
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.
properties
- a file containing a JGroups XML protocol stack
configuration.
ChannelException
- if problems occur during the configuration or
initialization of the protocol stack.
JChannel
public JChannel(Object properties)
throws ChannelException
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
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.
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.
JChannel
public JChannel(URL properties)
throws ChannelException
Constructs a 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.
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.
configurator
- a protocol stack configurator containing a JGroups
protocol stack configuration.
ChannelException
- if problems occur during the initialization of
the protocol stack.
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.
- 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
- 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.
- connect in interface Channel
channel_name
- A String
denoting the group name. Cannot be null.
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
- The JChannel sends a DISCONNECT event down the protocol stack
- Blocks until the channel to receives a DISCONNECT_OK event
- Sends a STOP_QUEING event down the stack
- Stops the protocol stack by calling ProtocolStack.stop()
- Notifies the listener, if the listener is available
- disconnect in interface Channel
down
public void down(Event evt)
Sends a message through the protocol stack if the stack is available
- down in interface Channel
evt
- the message to send down, encapsulated in an event
dumpStats
public Map dumpStats()
Returns a map of statistics of the various protocols and of the channel itself.
- dumpStats in interface Channel
- 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.
- getAllStates in interface 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
- 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
- getChannelName in interface Channel
getLocalAddress
public Address getLocalAddress()
returns the local address of the channel
returns null if the channel is closed
- getLocalAddress in interface Channel
getNumberOfTasksInTimer
public int getNumberOfTasksInTimer()
getOpt
public Object getOpt(int option)
returns the value of an option.
- getOpt in interface Channel
option
- the option you want to see the value for
- 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.
- getState in interface 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
- 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.
- getView in interface Channel
- 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
- isConnected in interface Channel
isOpen
public boolean isOpen()
returns true if the Open operation has been called successfully
- isOpen in interface Channel
isSuspended
public boolean isSuspended()
open
public void open()
throws ChannelException
Opens the channel.
This does the following actions:
- Resets the receiver queue by calling Queue.reset
- Sets up the protocol stack by calling ProtocolStack.setup
- Sets the closed flag to false
- open 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.
- receive in interface Transport
- receive in interface Channel
timeout
- the number of milliseconds to wait if the receive queue is empty. 0 means wait forever
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
- returnState in interface Channel
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
- send in interface Channel
dst
- - the destination address of the message, null for all memberssrc
- - the source address of the messageobj
- - the value of the message
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
- setOpt in interface Channel
option
- the parameter option Channel.VIEW, Channel.SUSPECT, etcvalue
- 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
Receive
s will dequeue it.
evt
- the event carrying the message from the protocol stack