Package org.apache.hop.workflow.action

Interface IAction

  • All Superinterfaces:
    IExtensionData, IHasLogChannel, IVariables
    All Known Implementing Classes:
    ActionBase, ActionDummy, ActionStart, MissingAction
    public interface IAction
extends IVariables, IHasLogChannel, IExtensionData
    IAction is the main Java interface that a plugin implements. The responsibilities of the implementing class are listed below:

    • Maintain action settings
      The implementing class typically keeps track of action settings using private fields with corresponding getters and setters. The dialog class implementing IActionDialog is using the getters and setters to copy the user supplied configuration in and out of the dialog.

      The following interface method also falls into the area of maintaining settings:

      Object clone()
      This method is called when a action is duplicated in HopGui. It needs to return a deep copy of this action object. It is essential that the implementing class creates proper deep copies if the action configuration is stored in modifiable objects, such as lists or custom helper objects. This interface does not extend Cloneable, but the implementing class will provide a similar method due to this interface.
    • Serialize action settings
      The plugin needs to be able to serialize its settings to XML. The interface methods are as follows:

      String getXml()
      This method is called by Apache Hop whenever a action needs to serialize its settings to XML. It is called when saving a workflow in HopGui. The method returns an XML string, containing the serialized settings. The string contains a series of XML tags, typically one tag per setting. The helper class org.apache.hop.core.xml.XmlHandler is typically used to construct the XML string.

      void loadXml(...)
      This method is called by Hop whenever a action needs to read its settings from XML. The XML node containing the action's settings is passed in as an argument. Again, the helper class org.apache.hop.core.xml.XmlHandler is typically used to conveniently read the settings from the XML node.


      Hint: When developing plugins, make sure the serialization code is in sync with the settings available from the action dialog. When testing a plugin in HopGui, Hop will internally first save and load a copy of the workflow.
    • Provide access to dialog class
      Hop needs to know which class will take care of the settings dialog for the action. The interface method getDialogClassName() must return the name of the class implementing the IActionDialog.
    • Provide information about possible outcomes
      A action may support up to three types of outgoing hops: true, false, and unconditional. Sometimes it does not make sense to support all three possibilities. For instance, if the action performs a task that does not produce a boolean outcome, like the dummy action, it may make sense to suppress the true and false outgoing hops. There are other actions, which carry an inherent boolean outcome, like the "file exists" action for instance. It may make sense in such cases to suppress the unconditional outgoing hop.

      The action plugin class must implement two methods to indicate to Apache Hop which outgoing hops it supports:

      boolean isEvaluation()
      This method must return true if the action supports the true/false outgoing hops. If the action does not support distinct outcomes, it must return false.

      boolean isUnconditional()
      This method must return true if the action supports the unconditional outgoing hop. If the action does not support the unconditional hop, it must return false.
    • Execute a action task
      The class implementing IAction executes the actual action task by implementing the following method:

      Result execute(..)
      The execute() method is going to be called by Hop when it is time for the action to execute its logic. The arguments are a result object, which is passed in from the previously executed action and an integer number indicating the distance of the action from the start entry of the workflow.

      The action should execute its configured task, and report back on the outcome. A action does that by calling certain methods on the passed in Result object:

      prevResult.setNrErrors(..)
      The action needs to indicate whether it has encountered any errors during execution. If there are errors, setNrErrors must be called with the number of errors encountered (typically this is 1). If there are no errors, setNrErrors must be called with an argument of 0.

      prevResult.setResult(..)
      The action must indicate the outcome of the task. This value determines which output hops can be followed next. If a action does not support evaluation, it need not call prevResult.setResult().

      Finally, the passed in prevResult object must be returned.

    • Method Detail

      • execute

        Result execute​(Result prevResult,
               int nr)
        throws HopException
        Execute the action. The previous result and number of rows are provided to the method for the purpose of chaining actions, pipelines, etc.
        Parameters:
        prevResult - the previous result
        nr - the number of rows
        Returns:
        the Result object from execution of this action
        Throws:
        HopException - if any Hop exceptions occur

      • setParentWorkflow

        void setParentWorkflow​(IWorkflowEngine<WorkflowMeta> workflow)
        Sets the parent workflow.
        Parameters:
        workflow - the parent workflow

      • setMetadataProvider

        void setMetadataProvider​(IHopMetadataProvider metadataProvider)
        Sets the MetaStore
        Parameters:
        metadataProvider - The new MetaStore to use

      • clear

        void clear()
        This method should clear out any variables, objects, etc. used by the action.

      • getName

        String getName()
        Gets the name of this action.
        Returns:
        the name

      • setName

        void setName​(String name)
        Sets the name for this action.
        Parameters:
        name - the new name

      • getPluginId

        String getPluginId()
        Gets the plugin id.
        Returns:
        the plugin id

      • setPluginId

        void setPluginId​(String pluginId)
        Sets the plugin id.
        Parameters:
        pluginId - the new plugin id

      • getDescription

        String getDescription()
        Gets the description of this action
        Returns:
        the description

      • setDescription

        void setDescription​(String description)
        Sets the description of this action
        Parameters:
        description - the new description

      • setChanged

        void setChanged()
        Sets whether the action has changed

      • setChanged

        void setChanged​(boolean ch)
        Sets whether the action has changed
        Parameters:
        ch - true if the action has changed, false otherwise

      • hasChanged

        boolean hasChanged()
        Checks whether the action has changed
        Returns:
        true if whether the action has changed

      • loadXml

        void loadXml​(Node actionNode,
             IHopMetadataProvider metadataProvider,
             IVariables variables)
      throws HopXmlException
        This method is called by Apache Hop whenever a action needs to read its settings from XML. The XML node containing the action's settings is passed in as an argument. Again, the helper class org.apache.hop.core.xml.XmlHandler is typically used to conveniently read the settings from the XML node.
        Parameters:
        actionNode - the top-level XML node
        metadataProvider - The metadataProvider to optionally load from.
        variables -
        Throws:
        HopXmlException - if any errors occur during the loading of the XML

      • getXml

        String getXml()
        This method is called by Apache Hop whenever a action needs to serialize its settings to XML. It is called when saving a workflow in HopGui. The method returns an XML string, containing the serialized settings. The string contains a series of XML tags, typically one tag per setting. The helper class org.apache.hop.core.xml.XmlHandler is typically used to construct the XML string.
        Returns:
        the xml representation of the action

      • isStart

        boolean isStart()
        Checks if the action is a starting point
        Returns:
        true if starting point, false otherwise

      • clone

        Object clone()
        This method is called when a action is duplicated in HopGui. It needs to return a deep copy of this action object. It is essential that the implementing class creates proper deep copies if the action configuration is stored in modifiable objects, such as lists or custom helper objects.
        Returns:
        a clone of the object

      • resetErrorsBeforeExecution

        boolean resetErrorsBeforeExecution()
        Checks whether a reset of the number of errors is required before execution.
        Returns:
        true if a reset of the number of errors is required before execution, false otherwise

      • isEvaluation

        boolean isEvaluation()
        This method must return true if the action supports the true/false outgoing hops. If the action does not support distinct outcomes, it must return false.
        Returns:
        true if the action supports the true/false outgoing hops, false otherwise

      • isUnconditional

        boolean isUnconditional()
        This method must return true if the action supports the unconditional outgoing hop. If the action does not support the unconditional hop, it must return false.
        Returns:
        true if the action supports the unconditional outgoing hop, false otherwise

      • isPipeline

        boolean isPipeline()
        Checks if this action executes a pipeline
        Returns:
        true if this action executes a pipeline, false otherwise

      • isWorkflow

        boolean isWorkflow()
        Checks if the action executes a workflow
        Returns:
        true if the action executes a workflow, false otherwise

      • getSqlStatements

        List<SqlStatement> getSqlStatements​(IHopMetadataProvider metadataProvider,
                                    IVariables variables)
                             throws HopException
        Gets the SQL statements needed by this action to execute successfully, given a set of variables.
        Parameters:
        metadataProvider - the MetaStore to use
        variables - a variable variables object containing variable bindings
        Returns:
        a list of SQL statements
        Throws:
        HopException - if any errors occur during the generation of SQL statements

      • getDialogClassName

        String getDialogClassName()
        Get the name of the class that implements the dialog for the action. ActionBase provides a default
        Returns:
        the name of the class implementing the dialog for the action

      • getFilename

        String getFilename()
        Gets the filename of the action. This method is used by actions and pipelines that call or refer to other actions.
        Returns:
        the filename

      • getRealFilename

        String getRealFilename()
        Gets the real filename of the action, by substituting any environment variables present in the filename.
        Returns:
        the real (resolved) filename for the action

      • check

        void check​(List<ICheckResult> remarks,
           WorkflowMeta workflowMeta,
           IVariables variables,
           IHopMetadataProvider metadataProvider)
        Allows Action objects to check themselves for consistency
        Parameters:
        remarks - List of CheckResult objects indicating consistency status
        workflowMeta - the metadata object for the action
        variables - the variable variables to resolve string expressions with variables with
        metadataProvider - the MetaStore to load common elements from

      • getResourceDependencies

        List<ResourceReference> getResourceDependencies​(IVariables variables,
                                                WorkflowMeta workflowMeta)
        Get a list of all the resource dependencies that the transform is depending on.
        Returns:
        a list of all the resource dependencies that the transform is depending on

      • exportResources

        String exportResources​(IVariables variables,
                       Map<String,​ResourceDefinition> definitions,
                       IResourceNaming namingInterface,
                       IHopMetadataProvider metadataProvider)
                throws HopException
        Exports the object to a flat-file system, adding content with filename keys to a set of definitions. The supplied resource naming interface allows the object to name appropriately without worrying about those parts of the implementation specific details.
        Parameters:
        variables - The variable variables to resolve (environment) variables with.
        definitions - The map containing the filenames and content
        namingInterface - The resource naming interface allows the object to be named appropriately
        metadataProvider - the metadataProvider to load external metadata from
        Returns:
        The filename for this object. (also contained in the definitions map)
        Throws:
        HopException - in case something goes wrong during the export

      • getReferencedObjectDescriptions

        String[] getReferencedObjectDescriptions()
        Returns:
        The objects referenced in the transform, like a a pipeline, a workflow, a mapper, a reducer, a combiner, ...

      • isReferencedObjectEnabled

        boolean[] isReferencedObjectEnabled()
        Returns:
        true for each referenced object that is enabled or has a valid reference definition.

      • loadReferencedObject

        IHasFilename loadReferencedObject​(int index,
                                  IHopMetadataProvider metadataProvider,
                                  IVariables variables)
                           throws HopException
        Load the referenced object
        Parameters:
        index - the referenced object index to load (in case there are multiple references)
        metadataProvider - the metadataProvider
        variables - the variable variables to use
        Returns:
        the referenced object once loaded
        Throws:
        HopException

      • setParentWorkflowMeta

        default void setParentWorkflowMeta​(WorkflowMeta workflowMeta)
        At save and run time, the system will attempt to set the workflowMeta so that it can be accessed by the actions if necessary. This default method will be applied to all actions that do not need to be aware of the parent WorkflowMeta
        Parameters:
        workflowMeta - the WorkflowMeta to which this IAction belongs

      • getParentWorkflowMeta

        default WorkflowMeta getParentWorkflowMeta()
        Return Gets the parent workflowMeta. This default method will throw an exception if a action attempts to call the getter when not implemented.