Package adams.flow.control

Class TryCatch

  • All Implemented Interfaces:
    AdditionalInformationHandler, ClassCrossReference, CleanUpHandler, CrossReference, Destroyable, GlobalInfoSupporter, LoggingLevelHandler, LoggingSupporter, OptionHandler, Pausable, QuickInfoSupporter, ShallowCopySupporter<Actor>, SizeOfHandler, Stoppable, StoppableWithFeedback, VariablesInspectionHandler, FlowPauseStateListener, VariableChangeListener, Actor, ActorHandler, ControlActor, ErrorHandler, ErrorScopeRestrictor, FixedNameActorHandler, Flushable, InputConsumer, OutputProducer, SubFlowWrapUp, Serializable, Comparable
    public class TryCatch
extends AbstractControlActor
implements InputConsumer, OutputProducer, FixedNameActorHandler, ClassCrossReference, ErrorScopeRestrictor
    Safe-guards the execution of the 'try' sequence of actors. In case of an error, the 'catch' sequence is executed to generate output instead.
    This works similar to the Java try-catch-block. Allowing the flow to recover from unexpected errors and, for instance, return default values.
    If the 'try' block fails and the 'catch' block accepts input (doesn't have to be a transformer, it can be just a source, eg SequenceSource), then the same input token is presented to the 'catch' block. This allows you to react to errors better. E.g., if the input token is a filename, then you can create an error message made up of the recorded error and the filename and pass this on.
    Note for developers: If actors use other actors internally, these need to be accessible. This can be achieved by simply implementing the adams.flow.core.InternalActorHandler interface.

    See also:
    adams.flow.control.RaiseError

    Input/output:
    - accepts:
       adams.flow.core.Unknown
    - generates:
       adams.flow.core.Unknown


    -logging-level <OFF|SEVERE|WARNING|INFO|CONFIG|FINE|FINER|FINEST> (property: loggingLevel)
    The logging level for outputting errors and debugging output.
    default: WARNING
 
    -name <java.lang.String> (property: name)
    The name of the actor.
    default: TryCatch
 
    -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 gets stopped in case this actor encounters an error;
     useful for critical actors.
    default: false
 
    -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
 
    -try <adams.flow.core.Actor> (property: try)
    The 'try' branch which is attempted to be executed.
    default: adams.flow.control.SubProcess -name try
 
    -catch <adams.flow.core.Actor> (property: catch)
    The 'catch' branch which gets executed if the 'try' branch fails.
    default: adams.flow.control.SubProcess -name catch
 
    -store-error <boolean> (property: storeError)
    If enabled, then any error gets stored in the specified variable 'errorVariable'
    ; does not modify the variable if there was no error.
    default: false
 
    -error-variable <adams.core.VariableName> (property: errorVariable)
    The name of the variable to store the error messages in.
    default: trycatch
 
    -error-post-processors <adams.flow.control.errorpostprocessor.ErrorPostProcessor> (property: errorPostProcessor)
    The error post-processor to use.
    default: adams.flow.control.errorpostprocessor.Null
    Author:
    fracpete (fracpete at waikato dot ac dot nz)
    See Also:
    Serialized Form

    • Field Detail

      • m_Try

        protected Actor m_Try
        the try branch.

      • m_Catch

        protected Actor m_Catch
        the catch branch.

      • BACKUP_INPUT

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

      • m_InputToken

        protected transient Token m_InputToken
        the current input token.

      • m_ErrorOccurred

        protected String m_ErrorOccurred
        error message in try block.

      • m_StoreError

        protected boolean m_StoreError
        whether to store any error message in a variable.

      • m_PrefixError

        protected boolean m_PrefixError
        whether to prefix the error message with source actor's full name and type.

      • m_ErrorVariable

        protected VariableName m_ErrorVariable
        the variable to store the error in.

      • m_ErrorPostProcessor

        protected ErrorPostProcessor m_ErrorPostProcessor
        the error post-processor to use.

    • Constructor Detail

      • TryCatch

        public TryCatch()

    • Method Detail

      • getDefaultTry

        protected Actor getDefaultTry()
        Returns the default try branch.
        Returns:
        the default branch

      • setTry

        public void setTry​(Actor value)
        Sets the try branch.
        Parameters:
        value - the try branch

      • getTry

        public Actor getTry()
        Returns the try branch.
        Returns:
        the try branch

      • tryTipText

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

      • getDefaultCatch

        protected Actor getDefaultCatch()
        Returns the default catch branch.
        Returns:
        the default branch

      • setCatch

        public void setCatch​(Actor value)
        Sets the catch branch.
        Parameters:
        value - the catch branch

      • getCatch

        public Actor getCatch()
        Returns the try branch.
        Returns:
        the try branch

      • catchTipText

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

      • setStoreError

        public void setStoreError​(boolean value)
        Sets whether to store any error in a variable.
        Parameters:
        value - true if to store error in variable

      • getStoreError

        public boolean getStoreError()
        Returns whether to store any error in a variable.
        Returns:
        true if error gets stored in variable

      • storeErrorTipText

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

      • setPrefixError

        public void setPrefixError​(boolean value)
        Sets whether to add the source actor's full name and type (e.g., 'execute').
        Parameters:
        value - true if to add prefix to error message

      • getPrefixError

        public boolean getPrefixError()
        Returns whether to add the source actor's full name and type (e.g., 'execute').
        Returns:
        true if to add prefix to error message

      • prefixErrorTipText

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

      • setErrorVariable

        public void setErrorVariable​(VariableName value)
        Sets the variable to store the error messages in.
        Parameters:
        value - the name

      • getErrorVariable

        public VariableName getErrorVariable()
        Returns the variable to store the error messages in.
        Returns:
        the name

      • errorVariableTipText

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

      • setErrorPostProcessor

        public void setErrorPostProcessor​(ErrorPostProcessor value)
        Sets the error post-processor to use.
        Parameters:
        value - the post-processor

      • getErrorPostProcessor

        public ErrorPostProcessor getErrorPostProcessor()
        Returns the error post-processor in use.
        Returns:
        the post-processor

      • errorPostProcessorTipText

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

      • 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
        See Also:
        m_InputToken

      • 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

      • 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

      • 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

      • getFixedName

        public String getFixedName​(int index)
        Returns the name for the sub-actor at this position.
        Specified by:
        getFixedName in interface FixedNameActorHandler
        Parameters:
        index - the position of the sub-actor
        Returns:
        the name to use

      • accepts

        public Class[] accepts()
        Returns the class that the consumer accepts.
        Specified by:
        accepts in interface InputConsumer
        Returns:
        the Class of objects that can be processed

      • doExecute

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

      • generates

        public Class[] generates()
        Returns the class of objects that it generates.
        Specified by:
        generates in interface OutputProducer
        Returns:
        the Class of the generated tokens

      • hasPendingOutput

        public boolean hasPendingOutput()
        Checks whether there is pending output to be collected after executing the flow item.

        The method is not allowed allowed to return "true" before the actor has been executed. For actors that return an infinite number of tokens, the m_Executed flag can be returned.
        Specified by:
        hasPendingOutput in interface OutputProducer
        Returns:
        true if there is pending output

      • output

        public Token output()
        Returns the generated token.
        Specified by:
        output in interface OutputProducer
        Returns:
        the generated token