Package adams.flow.control

Class Branch

  • All Implemented Interfaces:
    AdditionalInformationHandler, CleanUpHandler, Destroyable, GlobalInfoSupporter, LoggingLevelHandler, LoggingSupporter, OptionHandler, Pausable, QuickInfoSupporter, ShallowCopySupporter<Actor>, SizeOfHandler, Stoppable, StoppableWithFeedback, ThreadLimiter, VariablesInspectionHandler, FlowPauseStateListener, VariableChangeListener, AtomicExecution, Actor, ActorHandler, ControlActor, ErrorHandler, Flushable, InputConsumer, MutableActorHandler, SubFlowWrapUp, Serializable, Comparable
    Direct Known Subclasses:
    ArrayGenerate
    public class Branch
extends AbstractControlActor
implements InputConsumer, MutableActorHandler, AtomicExecution, ThreadLimiter
    Branches off the flow into several sub-branches, each being supplied with a copy of the same object being passed into this meta-actor. 

    -logging-level <OFF|SEVERE|WARNING|INFO|CONFIG|FINE|FINER|FINEST> (property: loggingLevel)
    The logging level for outputting errors and debugging output.
    default: WARNING
    min-user-mode: Expert
 
    -name <java.lang.String> (property: name)
    The name of the actor.
    default: Branch
 
    -annotation <adams.core.base.BaseAnnotation> (property: annotations)
    The annotations to attach to this actor.
    default:
 
    -skip <boolean> (property: skip)
    If set to true, transformation is skipped and the input token is just forwarded
    as it is.
    default: false
 
    -stop-flow-on-error <boolean> (property: stopFlowOnError)
    If set to true, the flow execution at this level gets stopped in case this
    actor encounters an error; the error gets propagated; useful for critical
    actors.
    default: false
    min-user-mode: Expert
 
    -silent <boolean> (property: silent)
    If enabled, then no errors are output in the console; Note: the enclosing
    actor handler must have this enabled as well.
    default: false
    min-user-mode: Expert
 
    -finish-before-stopping <boolean> (property: finishBeforeStopping)
    If enabled, actor first finishes processing all data before stopping.
    default: false
 
    -stopping-timeout <int> (property: stoppingTimeout)
    The timeout in milliseconds when waiting for actors to finish (<= 0 for
    infinity; see 'finishBeforeStopping').
    default: -1
    minimum: -1
 
    -stopping-warning-interval <int> (property: stoppingWarningInterval)
    The interval in milliseconds to output logging warnings if the actors haven't
    stopped yet (and no stopping timeout set); no warning if <= 0.
    default: 10000
    minimum: -1
 
    -branch <adams.flow.core.Actor> [-branch ...] (property: branches)
    The different branches that branch off and will be supplied with a copy
    of the same object.
    default:
 
    -num-threads <int> (property: numThreads)
    The number of threads to use for parallel execution; > 0: specific number
    of cores to use (capped by actual number of cores available, 1 = sequential
    execution); = 0: number of cores; < 0: number of free cores (eg -2 means
    2 free cores; minimum of one core is used)
    default: 0
    Author:
    fracpete (fracpete at waikato dot ac dot nz)
    See Also:
    Serialized Form

    • Field Detail

      • BACKUP_CURRENT

        public static final String BACKUP_CURRENT
        the key for storing the current token in the backup.
        See Also:
        Constant Field Values

      • m_Branches

        protected List<Actor> m_Branches
        the branches.

      • m_NumThreads

        protected int m_NumThreads
        the number of threads to use for parallel execution.

      • m_ActualNumThreads

        protected int m_ActualNumThreads
        the actual number of threads to use.

      • m_Executor

        protected ExecutorService m_Executor
        the executor service to use for parallel execution.

      • m_CurrentToken

        protected transient Token m_CurrentToken
        the token that gets passed on to all sub-branches.

      • m_HasCallableTransformers

        protected boolean m_HasCallableTransformers
        whether the branch contains callable transformers somewhere or not.

      • m_FinishBeforeStopping

        protected boolean m_FinishBeforeStopping
        whether to finish execution first before stopping.

      • m_StoppingTimeout

        protected int m_StoppingTimeout
        the timeout in milliseconds for stopping in case of atomic execution (<= 0 is infinity).

      • m_StoppingWarningInterval

        protected int m_StoppingWarningInterval
        the interval in msec to warn if actors haven't stopped yet (and not stopping timeout set).

      • m_CollectOutput

        protected boolean m_CollectOutput
        whether to collect the output of the branches.

      • m_CollectedOutput

        protected HashMap<Integer,​Token> m_CollectedOutput
        the collected output.

    • Constructor Detail

      • Branch

        public Branch()
        Default constructor.

      • Branch

        public Branch​(String name)
        Initializes the actor with the specified name.
        Parameters:
        name - the name to use

    • Method Detail

      • setFinishBeforeStopping

        public void setFinishBeforeStopping​(boolean value)
        Sets whether to finish processing before stopping execution.
        Specified by:
        setFinishBeforeStopping in interface AtomicExecution
        Parameters:
        value - if true then actor finishes processing first

      • getFinishBeforeStopping

        public boolean getFinishBeforeStopping()
        Returns whether to finish processing before stopping execution.
        Specified by:
        getFinishBeforeStopping in interface AtomicExecution
        Returns:
        true if actor finishes processing first

      • finishBeforeStoppingTipText

        public String finishBeforeStoppingTipText()
        Returns the tip text for this property.
        Specified by:
        finishBeforeStoppingTipText in interface AtomicExecution
        Returns:
        tip text for this property suitable for displaying in the GUI or for listing the options.

      • setStoppingTimeout

        public void setStoppingTimeout​(int value)
        Sets the timeout for waiting for the sub-flow to stop.
        Specified by:
        setStoppingTimeout in interface AtomicExecution
        Parameters:
        value - timeout in milliseconds (<= 0 for infinity)

      • getStoppingTimeout

        public int getStoppingTimeout()
        Returns the timeout for waiting for the sub-flow to stop.
        Specified by:
        getStoppingTimeout in interface AtomicExecution
        Returns:
        timeout in milliseconds (<= 0 for infinity)

      • stoppingTimeoutTipText

        public String stoppingTimeoutTipText()
        Returns the tip text for this property.
        Specified by:
        stoppingTimeoutTipText in interface AtomicExecution
        Returns:
        tip text for this property suitable for displaying in the GUI or for listing the options.

      • setStoppingWarningInterval

        public void setStoppingWarningInterval​(int value)
        Sets the interval for outputting warnings if the sub-flow hasn't stopped yet (and no stopping timeout set).
        Parameters:
        value - interval in milliseconds (<= 0 no warning)

      • getStoppingWarningInterval

        public int getStoppingWarningInterval()
        Returns the interval for outputting warnings if the sub-flow hasn't stopped yet (and no stopping timeout set).
        Returns:
        interval in milliseconds (<= 0 no warning)

      • stoppingWarningIntervalTipText

        public String stoppingWarningIntervalTipText()
        Returns the tip text for this property.
        Returns:
        tip text for this property suitable for displaying in the GUI or for listing the options.

      • setBranches

        public void setBranches​(Actor[] value)
        Sets the branches.
        Parameters:
        value - the branches

      • getBranches

        public Actor[] getBranches()
        Returns the branches.
        Returns:
        the branches

      • branchesTipText

        public String branchesTipText()
        Returns the tip text for this property.
        Returns:
        tip text for this property suitable for displaying in the GUI or for listing the options.

      • setNumThreads

        public void setNumThreads​(int value)
        Sets the number of threads to use for executing the branches.
        Specified by:
        setNumThreads in interface ThreadLimiter
        Parameters:
        value - the number of threads: -1 = # of CPUs/cores; 0/1 = sequential execution

      • getNumThreads

        public int getNumThreads()
        Returns the number of threads to use for executing the branches.
        Specified by:
        getNumThreads in interface ThreadLimiter
        Returns:
        the number of threads: -1 = # of CPUs/cores; 0/1 = sequential execution

      • numThreadsTipText

        public String numThreadsTipText()
        Returns the tip text for this property.
        Returns:
        tip text for this property suitable for displaying in the GUI or for listing the options.

      • setCollectOutput

        public void setCollectOutput​(boolean value)
        Whether to collect the output of the branches.
        Parameters:
        value - true if to collect the output

      • getCollectOutput

        public boolean getCollectOutput()
        Returns whether the output of the branches is collected.
        Returns:
        true if output collected

      • getCollectedOutput

        public HashMap<Integer,​Token> getCollectedOutput()
        Returns the collected output from the branches, if any.
        Returns:
        the collected output, null if not available

      • get

        public Actor get​(int index)
        Returns the actor at the given position.
        Specified by:
        get in interface ActorHandler
        Specified by:
        get in class AbstractControlActor
        Parameters:
        index - the position
        Returns:
        the actor

      • set

        public String set​(int index,
                  Actor actor)
        Sets the actor at the given position.
        Specified by:
        set in interface ActorHandler
        Specified by:
        set in class AbstractControlActor
        Parameters:
        index - the position
        actor - the actor to set at this position
        Returns:
        null if everything is fine, otherwise the error

      • add

        public String add​(Actor actor)
        Inserts the actor at the end.
        Specified by:
        add in interface MutableActorHandler
        Parameters:
        actor - the actor to insert
        Returns:
        null if everything is fine, otherwise the error

      • add

        public String add​(int index,
                  Actor actor)
        Inserts the actor at the given position.
        Specified by:
        add in interface MutableActorHandler
        Parameters:
        index - the position
        actor - the actor to insert
        Returns:
        null if everything is fine, otherwise the error

      • remove

        public Actor remove​(int index)
        Removes the actor at the given position and returns the removed object.
        Specified by:
        remove in interface MutableActorHandler
        Parameters:
        index - the position
        Returns:
        the removed actor

      • indexOf

        public int indexOf​(String actor)
        Returns the index of the actor.
        Specified by:
        indexOf in interface ActorHandler
        Specified by:
        indexOf in class AbstractControlActor
        Parameters:
        actor - the name of the actor to look for
        Returns:
        the index of -1 if not found

      • accepts

        public Class[] accepts()
        Returns the class that the consumer accepts.
        Specified by:
        accepts in interface InputConsumer
        Returns:
        depends on the sub-branches

      • input

        public void input​(Token token)
        The method that accepts the input token and then processes it.
        Specified by:
        input in interface InputConsumer
        Parameters:
        token - the token to accept and process

      • hasInput

        public boolean hasInput()
        Returns whether an input token is currently present.
        Specified by:
        hasInput in interface InputConsumer
        Returns:
        true if input token present

      • currentInput

        public Token currentInput()
        Returns the current input token, if any.
        Specified by:
        currentInput in interface InputConsumer
        Returns:
        the input token, null if none present

      • checkBranch

        protected String checkBranch​(Actor branch)
        Checks the sub-branch.
        Parameters:
        branch - the branch to check
        Returns:
        null if everything correct, otherwise the error message

      • check

        public String check()
        Checks whether all the connections are valid, i.e., the input and output types fit and whether the flow chain is connected properly.
        Specified by:
        check in interface ActorHandler
        Overrides:
        check in class AbstractControlActor
        Returns:
        null if everything is fine, otherwise the offending connection

      • hasCallableTransformers

        protected boolean hasCallableTransformers()
        Checks for callable transformers that might get accessed by parallel threads.
        Returns:
        true if the branch contains global transformers that are accessed by

      • executeParallel

        protected String executeParallel()
        Executes the branches in parallel.
        Returns:
        null if everything is fine, otherwise error message

      • executeSequential

        protected String executeSequential()
        Executes the branches sequentially.
        Returns:
        null if everything is fine, otherwise error message

      • doExecute

        protected String doExecute()
        Executes the flow item.
        Specified by:
        doExecute in class AbstractActor
        Returns:
        null if everything is fine, otherwise error message