Class JChannel
- All Implemented Interfaces:
Closeable, AutoCloseable
- Direct Known Subclasses:
ForkChannel
The state machine for a channel is as follows: a channel is created (unconnected). The channel is connected to a cluster (connected). Messages can now be sent and received. The channel is disconnected from the cluster (unconnected). The channel could now be connected to a different cluster again. The channel is closed (closed).
Only a single sender is allowed to be connected to a channel at a time, but there can be more than one channel in an application.
Messages can be sent to the cluster members using the send method and messages can be received by setting
a Receiver in setReceiver(Receiver) and implementing the Receiver.receive(Message) callback.
- Since:
- 2.0
- Author:
- Bela Ban
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected List<AddressGenerator> protected Adminprotected Set<ChannelListener> protected Stringprotected booleanprotected Addressprotected final Lockprotected final Logprotected Stringprotected DiagnosticsHandler.ProbeHandlerprotected ProtocolStackprotected Receiverprotected JChannel.Stateprotected final Promise<StateTransferResult> protected booleanprotected UpHandlerprotected View -
Constructor Summary
ConstructorsConstructorDescriptionJChannel()Creates aJChannelwith the default stackJChannel(boolean create_protocol_stack) Creates a JChannel without a protocol stack; used for programmatic creation of channel and protocol stackJChannel(InputStream input) Creates a channel with a configuration based on an input stream.Constructs a JChannel instance with the protocol stack configuration based upon the specified properties parameter.Creates a channel from a list of protocols.JChannel(ProtocolStackConfigurator configurator) Constructs a JChannel with the protocol stack configuration contained by the protocol stack configurator parameter.Creates a channel from an array of protocols. -
Method Summary
Modifier and TypeMethodDescriptionprotected JChannel_close(boolean disconnect) protected JChannelprotected boolean_preConnect(String cluster_name) addAddressGenerator(AddressGenerator address_generator) Sets the newAddressGenerator.addChannelListener(ChannelListener listener) Adds a ChannelListener that will be notified when a connect, disconnect or close occursaddress()admin()protected JChannelprotected JChannelprotected JChannelcleanup()voidclose()Destroys the channel and its associated resources (e.g.Joins the cluster.Joins the cluster and gets the state from a specified state provider.protected AddressLeaves the cluster (disconnects the channel if it is connected).Sends an event down the protocol stack.Sends a message down asynchronously.Returns a map of statistics of the various protocols and of the channel itselfprotected AddressgenerateAddress(String name) booleangetName()Returns the protocol stack configuration in string format.getState()Retrieves the full state from the target member.
The state transfer is initiated by invoking getState() on this channel.static StringgetView()protected JChannelinit()Initializes all variables.protected final JChannelinit(ProtocolStackConfigurator configurator) protected ObjectinvokeCallback(int type, Object arg) booleanisClosed()booleanbooleanbooleanisOpen()log()name()protected JChannelprotected JChannelprotected JChannelprotected JChannelnotifyListeners(Consumer<ChannelListener> func, String msg) printProtocolSpec(boolean include_props) Dumps all protocols in string format.booleanremoveAddressGenerator(AddressGenerator address_generator) removeChannelListener(ChannelListener listener) Sends a message.Sends a message to a destination.Helper method to create a Message with given parameters and invokesend(Message).Sends a message.protected JChannelGenerates local_addr.setDiscardOwnMessages(boolean flag) Sets the logical name for the channel.stack()stack(ProtocolStack st) stack(ProtocolStack st, boolean delete_old_stack) protected JChannelstartStack(String cluster_name) protected JChannelstopStack(boolean stop, boolean destroy) toString()toString(boolean details) Callback method
Called by the ProtocolStack when a message is received.up(MessageBatch batch) Callback invoked by the protocol stack to deliver a message batchview()
-
Field Details
-
receiver
-
local_addr
-
name
-
cluster_name
-
view
-
state
-
prot_stack
-
up_handler
-
channel_listeners
-
log
-
address_generators
-
state_promise
-
state_transfer_supported
protected boolean state_transfer_supported -
probe_handler
-
admin
-
discard_own_messages
protected boolean discard_own_messages -
lock
-
-
Constructor Details
-
JChannel
public JChannel(boolean create_protocol_stack) Creates a JChannel without a protocol stack; used for programmatic creation of channel and protocol stack- Parameters:
create_protocol_stack- If true, the default config is used. If false, no protocol stack is created
-
JChannel
-
JChannel
-
JChannel
Creates a channel with a configuration based on an input stream.- Parameters:
input- An input stream, pointing to a streamed configuration. It is the caller's resposibility to close the input stream after the constructor returns- Throws:
Exception
-
JChannel
Constructs a JChannel with the protocol stack configuration contained by the protocol stack configurator parameter.All the public constructors of this class eventually delegate to this method.
- Parameters:
configurator- A protocol stack configurator containing a JGroups protocol stack configuration.- Throws:
Exception
-
JChannel
Creates a channel from an array of protocols. Note that after aclose(), the protocol list should not be reused, ie. new JChannel(protocols) would reuse the same protocol list, and this might lead to problems!- Parameters:
protocols- The list of protocols, from bottom to top, ie. the first protocol in the list is the transport, the last the top protocol- Throws:
Exception
-
JChannel
Creates a channel from a list of protocols. Note that after aclose(), the protocol list should not be reused, ie. new JChannel(protocols) would reuse the same protocol list, and this might lead to problems !- Parameters:
protocols- The list of protocols, from bottom to top, ie. the first protocol in the list is the transport, the last the top protocol- Throws:
Exception
-
-
Method Details
-
log
-
admin
-
getReceiver
-
setReceiver
-
receiver
-
getAddress
-
address
-
getName
-
name
-
name
-
clusterName
-
getView
-
view
-
getProtocolStack
-
stack
-
stack
-
getUpHandler
-
setUpHandler
-
getDiscardOwnMessages
public boolean getDiscardOwnMessages() -
setDiscardOwnMessages
-
probeHandler
-
probeHandler
-
stack
-
getAddressAsString
-
getAddressAsUUID
-
setName
-
getClusterName
-
getViewAsString
-
getState
-
isOpen
public boolean isOpen() -
isConnected
public boolean isConnected() -
isConnecting
public boolean isConnecting() -
isClosed
public boolean isClosed() -
getVersion
-
addChannelListener
Adds a ChannelListener that will be notified when a connect, disconnect or close occurs -
removeChannelListener
-
clearChannelListeners
-
addAddressGenerator
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.- Parameters:
address_generator-- Since:
- 2.12
-
removeAddressGenerator
-
getProperties
Returns the protocol stack configuration in string format. An example of this property is"UDP:PING:FDALL:STABLE:NAKACK2:UNICAST3:FRAG2:GMS"
-
printProtocolSpec
Dumps all protocols in string format. If include_props is set, the attrs of each protocol are also printed -
dumpStats
-
dumpStats
-
dumpStats
-
connect
Joins the cluster. The application is now able to receive messages from cluster members, views and to send messages to (all or single) cluster members. This is a no-op if already connected.All channels connecting to the same cluster name form a cluster; messages sent to the cluster will be received by all cluster members.
- Parameters:
cluster_name- The name of the cluster to join- Throws:
Exception- The protocol stack cannot be startedIllegalStateException- The channel is closed
-
connect
Joins the cluster and gets the state from a specified state provider.This method invokes
connectandgetStatemethods. If the channel is closed an exception will be thrown.- Parameters:
cluster_name- the cluster name to connect to. Cannot be null.target- the state provider. If null, the state will be fetched from coordinator, unless this channel is coordinator.timeout- the timeout for state transfer.- Throws:
Exception- Connecting to the cluster or state transfer was not successfulIllegalStateException- The channel is closed and therefore cannot be used
-
disconnect
Leaves the cluster (disconnects the channel if it is connected). If the channel is closed or disconnected, this operation is ignored. The channel can then be used to join the same or a different cluster again.- See Also:
-
close
public void close()Destroys the channel and its associated resources (e.g. the protocol stack). After a channel has been closed, invoking methods on it will throw aChannelClosedexception (or results in a null operation). It is a no-op if the channel is already closed.If the channel is connected to a cluster,
disconnect()will be called first.- Specified by:
closein interfaceAutoCloseable- Specified by:
closein interfaceCloseable
-
send
Sends a message. The message contains- a destination address (Address). A
nulladdress 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
- Parameters:
msg- the message to be sent. Destination and buffer should be set. A null destination means to send to all group members.- Throws:
IllegalStateException- thrown if the channel is disconnected or closedException
- a destination address (Address). A
-
send
Helper method to create a Message with given parameters and invokesend(Message).- Parameters:
dst- destination address for the message. If null, the message will be sent to all cluster membersobj- a serializable object. Will be marshalled into the byte buffer of the message. If it is not serializable, an exception will be thrown- Throws:
Exception- exception thrown if message sending was not successful
-
send
Sends a message. Seesend(Address,byte[],int,int)for details- Parameters:
dst- destination address for the message. If null, the message will be sent to all cluster membersbuf- buffer message payload- Throws:
Exception- exception thrown if the message sending was not successful
-
send
Sends a message to a destination.- Parameters:
dst- the destination address. If null, the message will be sent to all cluster nodes (= cluster members)buf- the buffer to be sentoffset- the offset into the bufferlength- the length of the data to be sent. Has to be smaller thanq buf.length - offset. This will sendlengthbytes starting atoffset- Throws:
Exception- thrown if send() failed
-
getState
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 theReceiver.getState(java.io.OutputStream)callback and sends the state to this node, the state receiver. After the state is received by the state receiver, theReceiver.setState(java.io.InputStream)callback is invoked to install the state.- 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, or until the state has been received- Throws:
IllegalStateException- the channel was closed or disconnected, or the flush (if present) failedStateTransferException- raised if there was a problem during the state transferException- See Also:
-
down
Sends an event down the protocol stack. Note that - contrary tosend(Message), if the event is a message, no checks are performed whether the channel is closed or disconnected. Note that this method is not typically used by applications.- Parameters:
evt- the message to send down, encapsulated in an event
-
down
-
down
Sends a message down asynchronously. The sending is executed in the transport's thread pool. If the pool is full and the message is marked asMessage.TransientFlag.DONT_BLOCK, then it will be dropped, otherwise it will be sent on the caller's thread.- Parameters:
msg- The message to be sentasync- Whether to send the message asynchronously- Returns:
- A CompletableFuture of the result (or exception)
-
up
-
up
-
up
Callback invoked by the protocol stack to deliver a message batch -
toString
-
toString
-
_preConnect
-
_connect
-
cleanup
-
invokeCallback
-
init
- Throws:
Exception
-
init
Initializes all variables. Used after close() or disconnect(), to be ready for new connect() -
startStack
-
setAddress
Generates local_addr. Sends down a REMOVE_ADDRESS (if existing address was present) and a SET_LOCAL_ADDRESS -
generateAddress
-
checkClosed
-
checkClosedOrNotConnected
-
_close
-
stopStack
-
determineCoordinator
-
notifyChannelConnected
-
notifyChannelDisconnected
-
notifyChannelClosed
-
notifyListeners
-