Class 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
    • 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 and connect(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-channel
        fork_stack_id - The ID to associate the fork-stack with in FORK
        fork_channel_id - The ID used to map fork-channel IDs to ForkChannels in the fork-channels protocol stack
        create_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 thrown
        position - The position at which the newly created FORK will be inserted. ProtocolStack.Position.ABOVE or ProtocolStack.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 and connect(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-channel
        fork_stack_id - The ID to associate the fork-stack with in FORK
        fork_channel_id - The ID used to map fork-channel IDs to ForkChannels in the fork-channels protocol stack
        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
    • 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()
        Overrides:
        setName in class JChannel
      • channelConnected

        public void channelConnected​(JChannel channel)
        Description copied from interface: ChannelListener
        Channel has been connected notification callback
        Specified by:
        channelConnected in interface ChannelListener
        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 interface ChannelListener
        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 interface ChannelListener
        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.

        Overrides:
        connect in class JChannel
        Parameters:
        cluster_name - Ignored, will be the same as the main-channel's cluster name
        Throws:
        java.lang.Exception
        java.lang.IllegalStateException - The channel is closed
      • 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 invokes connect 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 class JChannel
        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 successful
        java.lang.IllegalStateException - The channel is closed and therefore cannot be used
      • 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
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class JChannel
      • send

        public ForkChannel send​(Message msg)
                         throws java.lang.Exception
        Description copied from class: JChannel
        Sends a message. The message contains
        1. a destination address (Address). A null address sends the message to all cluster members.
        2. a source address. Can be left empty as it will be assigned automatically
        3. a byte buffer. The message contents.
        4. several additional fields. They can be used by application programs (or patterns). E.g. a message ID, flags etc
        Overrides:
        send in class JChannel
        Parameters:
        msg - the message to be sent. Destination and buffer should be set. A null destination means to send to all group members.
        Throws:
        java.lang.IllegalStateException - thrown if the channel is disconnected or closed
        java.lang.Exception
      • 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 matching JChannel.stopFlush(List) method with the same list of members used in JChannel.startFlush(List, boolean).

        Overrides:
        startFlush in class JChannel
        automatic_resume - if true call JChannel.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 until JChannel.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 class JChannel
        Parameters:
        automatic_resume - if true call JChannel.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
        Overrides:
        stopFlush in class JChannel
      • 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 matching JChannel.startFlush(List, boolean) method with the same list of members prior to invocation of this method.

        Overrides:
        stopFlush in class JChannel
        Parameters:
        flushParticipants - the flush participants
      • 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()