Package org.jgroups.fork
Class ForkChannel
- java.lang.Object
-
- org.jgroups.JChannel
-
- org.jgroups.fork.ForkChannel
-
- All Implemented Interfaces:
java.io.Closeable
,java.lang.AutoCloseable
,ChannelListener
public class ForkChannel extends JChannel implements ChannelListener
Implementation of a ForkChannel, which is a light-weight channel. Not all methods are supported, UnsupportedOperationExceptions will be thrown if an unsupported operation is called. See doc/design/FORK.txt for details- Since:
- 3.4
- Author:
- Bela Ban
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class org.jgroups.JChannel
JChannel.State
-
-
Field Summary
Fields Modifier and Type Field Description protected static java.lang.reflect.Field[]
copied_fields
protected java.lang.String
fork_channel_id
protected JChannel
main_channel
-
Fields inherited from class org.jgroups.JChannel
address_generators, channel_listeners, cluster_name, discard_own_messages, flush_supported, local_addr, log, name, probe_handler, prot_stack, received_bytes, received_msgs, receiver, sent_bytes, sent_msgs, state, state_promise, state_transfer_supported, stats, up_handler, view
-
-
Constructor Summary
Constructors Constructor Description ForkChannel(JChannel main_channel, java.lang.String fork_stack_id, java.lang.String fork_channel_id, boolean create_fork_if_absent, ProtocolStack.Position position, java.lang.Class<? extends Protocol> neighbor, Protocol... protocols)
Creates a new fork-channel from a main-channel.ForkChannel(JChannel main_channel, java.lang.String fork_stack_id, java.lang.String fork_channel_id, Protocol... protocols)
Creates a new fork-channel from a main-channel.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description ForkChannel
addAddressGenerator(AddressGenerator address_generator)
Sets the newAddressGenerator
.void
channelClosed(JChannel channel)
Channel has been closed notification callbackvoid
channelConnected(JChannel channel)
Channel has been connected notification callbackvoid
channelDisconnected(JChannel channel)
Channel has been disconnected notification callbackvoid
close()
Closes the fork-channel, essentially setting its state to CLOSED.ForkChannel
connect(java.lang.String cluster_name)
Connects the fork-channel, which will be operational after this.ForkChannel
connect(java.lang.String cluster_name, Address target, long timeout)
Joins the cluster and gets the state from a specified state provider.protected void
copyFields()
Copies state from main-channel to this fork-channelForkChannel
disconnect()
Removes the fork-channel from the fork-stack's hashmap and resets its state.java.lang.Object
down(Message msg)
protected static FORK
getFORK(JChannel ch, ProtocolStack.Position position, java.lang.Class<? extends Protocol> neighbor, boolean create_fork_if_absent)
Creates a new FORK protocol, or returns the existing one, or throws an exception.ForkChannel
getState(Address target, long timeout)
Retrieves the full state from the target member.JChannel
name(java.lang.String name)
protected void
nullFields()
ForkChannel
send(Message msg)
Sends a message.protected void
setHeader(Message msg)
protected ForkChannel
setLocalAddress(Address local_addr)
ForkChannel
setName(java.lang.String name)
Sets the logical name for the channel.ForkChannel
startFlush(boolean automatic_resume)
Performs the flush of the cluster, ie.ForkChannel
startFlush(java.util.List<Address> flushParticipants, boolean automatic_resume)
Performs the flush of the cluster but only for the specified flush participants.ForkChannel
stopFlush()
Stops the current flush round.ForkChannel
stopFlush(java.util.List<Address> flushParticipants)
Stops the current flush of the cluster for the specified flush participants.-
Methods inherited from class org.jgroups.JChannel
_close, _connect, _preConnect, addChannelListener, address, checkClosed, checkClosedOrNotConnected, cleanup, clearChannelListeners, clusterName, connect, connect, determineCoordinator, down, dumpChannelStats, dumpStats, dumpStats, dumpStats, flushSupported, generateAddress, getAddress, getAddressAsString, getAddressAsUUID, getClusterName, getDiscardOwnMessages, getName, getProperties, getProtocolStack, getReceivedBytes, getReceivedMessages, getReceiver, getSentBytes, getSentMessages, getState, getState, getState, getStats, getUpHandler, getVersion, getView, getViewAsString, init, init, init, invokeCallback, isClosed, isConnected, isConnecting, isOpen, name, notifyChannelClosed, notifyChannelConnected, notifyChannelDisconnected, notifyListeners, printProtocolSpec, receiver, removeAddressGenerator, removeChannelListener, resetStats, send, send, send, setAddress, setDiscardOwnMessages, setReceiver, setStats, setUpHandler, stack, startStack, stats, stats, stopStack, toString, up, up, up, view
-
-
-
-
Field Detail
-
main_channel
protected final JChannel main_channel
-
fork_channel_id
protected final java.lang.String fork_channel_id
-
copied_fields
protected static final java.lang.reflect.Field[] copied_fields
-
-
Constructor Detail
-
ForkChannel
public ForkChannel(JChannel main_channel, java.lang.String fork_stack_id, java.lang.String fork_channel_id, boolean create_fork_if_absent, ProtocolStack.Position position, java.lang.Class<? extends Protocol> neighbor, Protocol... protocols) throws java.lang.Exception
Creates a new fork-channel from a main-channel. The channel is unconnected andconnect(String)
needs to be called to send and receive messages.- Parameters:
main_channel
- The main-channel. The lifetime of the newly created channel will be less than or equal to the main-channelfork_stack_id
- The ID to associate the fork-stack with in FORKfork_channel_id
- The ID used to map fork-channel IDs to ForkChannels in the fork-channels protocol stackcreate_fork_if_absent
- If true, and FORK doesn't exist, a new FORK protocol will be created and inserted into the main-stack at the given position. If false, and FORK doesn't exist, an exception will be thrownposition
- The position at which the newly created FORK will be inserted.ProtocolStack.Position.ABOVE
orProtocolStack.Position.BELOW
are accepted. Ignored if create_fork_if_absent is false.neighbor
- The class of the neighbor protocol below or above which the newly created FORK protocol will be inserted. Ignored if create_fork_if_absent is false.protocols
- A list of protocols (from bottom to top !) to insert as the fork_stack in FORK under the given fork_stack_id. If the fork-stack with fork_stack_id already exists, an exception will be thrown. Can be null if no protocols should be added. This may be the case when an app only wants to use a ForkChannel to mux/demux messages, but doesn't need a different protocol stack.- Throws:
java.lang.Exception
-
ForkChannel
public ForkChannel(JChannel main_channel, java.lang.String fork_stack_id, java.lang.String fork_channel_id, Protocol... protocols) throws java.lang.Exception
Creates a new fork-channel from a main-channel. The channel is unconnected andconnect(String)
needs to be called to send and receive messages. If FORK is not found in the stack, an exception will be thrown.- Parameters:
main_channel
- The main-channel. The lifetime of the newly created channel will be less than or equal to the main-channelfork_stack_id
- The ID to associate the fork-stack with in FORKfork_channel_id
- The ID used to map fork-channel IDs to ForkChannels in the fork-channels protocol stackprotocols
- A list of protocols (from bottom to top !) to insert as the fork_stack in FORK under the given fork_stack_id. If the fork-stack with fork_stack_id already exists, an exception will be thrown. Can be null if no protocols should be added. This may be the case when an app only wants to use a ForkChannel to mux/demux messages, but doesn't need a different protocol stack.- Throws:
java.lang.Exception
-
-
Method Detail
-
setName
public ForkChannel setName(java.lang.String name)
Description copied from class:JChannel
Sets the logical name for the channel. The name will stay associated with this channel for the channel's lifetime (until close() is called). This method must be called before calling connect()
-
channelConnected
public void channelConnected(JChannel channel)
Description copied from interface:ChannelListener
Channel has been connected notification callback- Specified by:
channelConnected
in interfaceChannelListener
- Parameters:
channel
- the channel that has been connected
-
channelDisconnected
public void channelDisconnected(JChannel channel)
Description copied from interface:ChannelListener
Channel has been disconnected notification callback- Specified by:
channelDisconnected
in interfaceChannelListener
- Parameters:
channel
- the disconnected channel
-
channelClosed
public void channelClosed(JChannel channel)
Description copied from interface:ChannelListener
Channel has been closed notification callback- Specified by:
channelClosed
in interfaceChannelListener
- Parameters:
channel
- the closed channel
-
connect
public ForkChannel connect(java.lang.String cluster_name) throws java.lang.Exception
Connects the fork-channel, which will be operational after this. Note that the fork-channel will have the same state as the main-channel, ie. if the main-channel is disconnected, so will the fork-channel be, even if connect() was called. This connect() method essentially adds the fork-channel to the fork-stack's hashmap, ready to send/receive messages as soon as the main-channel has been connected. This method does not affect the main-channel.
-
connect
public ForkChannel connect(java.lang.String cluster_name, Address target, long timeout) throws java.lang.Exception
Description copied from class:JChannel
Joins the cluster and gets the state from a specified state provider. This method essentially invokesconnect
and
getState
methods successively. If FLUSH protocol is in channel's stack definition only one flush is executed for both connecting and fetching state rather than two flushes if we invoke
connect
and
getState
in succession. If the channel is closed an exception will be thrown.
- Overrides:
connect
in classJChannel
- Parameters:
cluster_name
- the cluster name to connect to. Cannot be null.target
- the state provider. If null state will be fetched from coordinator, unless this channel is coordinator.timeout
- the timeout for state transfer.- Throws:
java.lang.Exception
- Connecting to the cluster or state transfer was not successfuljava.lang.IllegalStateException
- The channel is closed and therefore cannot be used
-
disconnect
public ForkChannel disconnect()
Removes the fork-channel from the fork-stack's hashmap and resets its state. Does not affect the main-channel- Overrides:
disconnect
in classJChannel
- See Also:
JChannel.connect(String)
-
close
public void close()
Closes the fork-channel, essentially setting its state to CLOSED. Note that - contrary to a regular channel - a closed fork-channel can be connected again: this means re-attaching the fork-channel to the main-channel
-
send
public ForkChannel send(Message msg) throws java.lang.Exception
Description copied from class:JChannel
Sends a message. The message contains- a destination address (Address). A
null
address sends the message to all cluster members. - a source address. Can be left empty as it will be assigned automatically
- a byte buffer. The message contents.
- several additional fields. They can be used by application programs (or patterns). E.g. a message ID, flags etc
- a destination address (Address). A
-
startFlush
public ForkChannel startFlush(java.util.List<Address> flushParticipants, boolean automatic_resume) throws java.lang.Exception
Description copied from class:JChannel
Performs the flush of the cluster but only for the specified flush participants. All pending messages are flushed out but only for the flush participants. The remaining members in the cluster are not included in the flush. The list of flush participants should be a proper subset of the current view. If this flush is not automatically resumed it is an obligation of the application to invoke the matchingJChannel.stopFlush(List)
method with the same list of members used inJChannel.startFlush(List, boolean)
.- Overrides:
startFlush
in classJChannel
automatic_resume
- if true callJChannel.stopFlush()
after the flush- Throws:
java.lang.Exception
-
startFlush
public ForkChannel startFlush(boolean automatic_resume) throws java.lang.Exception
Description copied from class:JChannel
Performs the flush of the cluster, ie. all pending application messages are flushed out of the cluster and all members ack their reception. After this call returns, no member will be allowed to send any messages untilJChannel.stopFlush()
is called. In the case of flush collisions (another member attempts flush at roughly the same time) start flush will fail by throwing an Exception. Applications can re-attempt flushing after certain back-off period. JGroups provides a helper random sleep time backoff algorithm for flush using Util class.- Overrides:
startFlush
in classJChannel
- Parameters:
automatic_resume
- if true callJChannel.stopFlush()
after the flush- Throws:
java.lang.Exception
-
stopFlush
public ForkChannel stopFlush()
Description copied from class:JChannel
Stops the current flush round. Cluster members are unblocked and allowed to send new and pending messages
-
stopFlush
public ForkChannel stopFlush(java.util.List<Address> flushParticipants)
Description copied from class:JChannel
Stops the current flush of the cluster for the specified flush participants. Flush participants are unblocked and allowed to send new and pending messages. It is an obligation of the application to invoke the matchingJChannel.startFlush(List, boolean)
method with the same list of members prior to invocation of this method.
-
getState
public ForkChannel getState(Address target, long timeout) throws java.lang.Exception
Description copied from class:JChannel
Retrieves the full state from the target member.The state transfer is initiated by invoking getState() on this channel. The state provider in turn invokes the
StateListener.getState(java.io.OutputStream)
callback and sends the state to this node, the state receiver. After the state arrives at the state receiver, theStateListener.setState(java.io.InputStream)
callback is invoked to install the state.- Overrides:
getState
in classJChannel
- Parameters:
target
- the state provider. If null the coordinator is used by defaulttimeout
- the number of milliseconds to wait for the operation to complete successfully. 0 waits forever until the state has been received- Throws:
java.lang.IllegalStateException
- the channel was closed or disconnected, or the flush (if present) failedStateTransferException
- raised if there was a problem during the state transferjava.lang.Exception
- See Also:
StateListener.getState(java.io.OutputStream)
,StateListener.setState(java.io.InputStream)
-
addAddressGenerator
public ForkChannel addAddressGenerator(AddressGenerator address_generator)
Description copied from class:JChannel
Sets the newAddressGenerator
. New addresses will be generated using the new generator. This should not be done while a channel is connected, but before connecting.- Overrides:
addAddressGenerator
in classJChannel
-
setLocalAddress
protected ForkChannel setLocalAddress(Address local_addr)
-
getFORK
protected static FORK getFORK(JChannel ch, ProtocolStack.Position position, java.lang.Class<? extends Protocol> neighbor, boolean create_fork_if_absent) throws java.lang.Exception
Creates a new FORK protocol, or returns the existing one, or throws an exception. Never returns null.- Throws:
java.lang.Exception
-
setHeader
protected void setHeader(Message msg)
-
copyFields
protected void copyFields()
Copies state from main-channel to this fork-channel
-
nullFields
protected void nullFields()
-
-