Package org.pentaho.di.job.entry

Interface JobEntryInterface

  • All Known Implementing Classes:
    JobEntryCheckFilesLocked, JobEntryColumnsExist, JobEntryCopyFiles, JobEntryCopyMoveResultFilenames, JobEntryCreateFile, JobEntryCreateFolder, JobEntryDelay, JobEntryDeleteFile, JobEntryDeleteFiles, JobEntryDeleteFolders, JobEntryDeleteResultFilenames, JobEntryDosToUnix, JobEntryEmpty, JobEntryEval, JobEntryEvalFilesMetrics, JobEntryEvalTableContent, JobEntryFileCompare, JobEntryFileExists, JobEntryFilesExist, JobEntryFolderIsEmpty, JobEntryFoldersCompare, JobEntryHTTP, JobEntryJob, JobEntryMoveFiles, JobEntryMssqlBulkLoad, JobEntryMysqlBulkFile, JobEntryMysqlBulkLoad, JobEntryPGPDecryptFiles, JobEntryPGPEncryptFiles, JobEntryPGPVerify, JobEntryPing, JobEntrySendNagiosPassiveCheck, JobEntrySetVariables, JobEntryShell, JobEntrySimpleEval, JobEntrySNMPTrap, JobEntrySpecial, JobEntrySQL, JobEntrySuccess, JobEntrySyslog, JobEntryTableExists, JobEntryTalendJobExec, JobEntryTelnet, JobEntryTrans, JobEntryTruncateTables, JobEntryUnZip, JobEntryWaitForFile, JobEntryWaitForSQL, JobEntryWebServiceAvailable, JobEntryWriteToFile, JobEntryWriteToLog, JobEntryZipFile, MissingEntry
    public interface JobEntryInterface
    JobEntryInterface is the main Java interface that a plugin implements. The responsibilities of the implementing class are listed below:

    • Maintain job entry settings
      The implementing class typically keeps track of job entry settings using private fields with corresponding getters and setters. The dialog class implementing JobEntryDialogInterface 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 job entry is duplicated in Spoon. It needs to return a deep copy of this job entry object. It is essential that the implementing class creates proper deep copies if the job entry 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 job entry settings
      The plugin needs to be able to serialize its settings to both XML and a PDI repository. The interface methods are as follows:

      String getXML()
      This method is called by PDI whenever a job entry needs to serialize its settings to XML. It is called when saving a job in Spoon. 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.pentaho.di.core.xml.XMLHandler is typically used to construct the XML string.

      void loadXML(...)
      This method is called by PDI whenever a job entry needs to read its settings from XML. The XML node containing the job entry's settings is passed in as an argument. Again, the helper class org.pentaho.di.core.xml.XMLHandler is typically used to conveniently read the settings from the XML node.

      void saveRep(...)
      This method is called by PDI whenever a job entry needs to save its settings to a PDI repository. The repository object passed in as the first argument provides a convenient set of methods for serializing job entry settings. When calling repository serialization methods, job id and job entry id are required. The job id is passed in to saveRep() as an argument, and the job entry id can be obtained by a call to getObjectId() inherited from the base class.

      void loadRep(...)
      This method is called by PDI whenever a job entry needs to read its configuration from a PDI repository. The job entry id given in the arguments should be used as the identifier when using the repository's serialization methods.

      Hint: When developing plugins, make sure the serialization code is in synch with the settings available from the job entry dialog. When testing a plugin in Spoon, PDI will internally first save and load a copy of the job.

    • Provide access to dialog class
      PDI needs to know which class will take care of the settings dialog for the job entry. The interface method getDialogClassName() must return the name of the class implementing the JobEntryDialogInterface.

    • Provide information about possible outcomes
      A job entry 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 job entry performs a task that does not produce a boolean outcome, like the dummy job entry, it may make sense to suppress the true and false outgoing hops. There are other job entries, which carry an inherent boolean outcome, like the "file exists" job entry for instance. It may make sense in such cases to suppress the unconditional outgoing hop.

      The job entry plugin class must implement two methods to indicate to PDI which outgoing hops it supports:

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

      boolean isUnconditional()
      This method must return true if the job entry supports the unconditional outgoing hop. If the job entry does not support the unconditional hop, it must return false.

    • Execute a job entry task
      The class implementing JobEntryInterface executes the actual job entry task by implementing the following method:

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

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

      prev_result.setNrErrors(..)
      The job entry 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.

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

      Finally, the passed in prev_result object must be returned.

    Since:
    18-06-04
    Author:
    Matt Casters

    • Method Detail

      • execute

        org.pentaho.di.core.Result execute​(org.pentaho.di.core.Result prev_result,
                                   int nr)
                            throws org.pentaho.di.core.exception.KettleException
        Execute the job entry. The previous result and number of rows are provided to the method for the purpose of chaining job entries, transformations, etc.
        Parameters:
        prev_result - the previous result
        nr - the number of rows
        Returns:
        the Result object from execution of this job entry
        Throws:
        org.pentaho.di.core.exception.KettleException - if any Kettle exceptions occur

      • setParentJob

        void setParentJob​(Job job)
        Sets the parent job.
        Parameters:
        job - the parent job

      • getParentJob

        Job getParentJob()
        Gets the parent job.
        Returns:
        the parent job

      • getLogChannel

        org.pentaho.di.core.logging.LogChannelInterface getLogChannel()
        Gets the log channel.
        Returns:
        the log channel

      • setRepository

        void setRepository​(Repository repository)
        Sets the repository.
        Parameters:
        repository - the new repository

      • setMetaStore

        void setMetaStore​(org.pentaho.metastore.api.IMetaStore metaStore)
        Sets the MetaStore
        Parameters:
        metaStore - The new MetaStore to use

      • clear

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

      • getObjectId

        org.pentaho.di.repository.ObjectId getObjectId()
        Gets the object id.
        Returns:
        the object id

      • setObjectId

        void setObjectId​(org.pentaho.di.repository.ObjectId id)
        Sets the object id.
        Parameters:
        id - the new object id

      • getName

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

      • setName

        void setName​(String name)
        Sets the name for this job entry.
        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 job entry
        Returns:
        the description

      • setDescription

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

      • setChanged

        void setChanged()
        Sets whether the job entry has changed

      • setChanged

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

      • hasChanged

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

      • loadXML

        @Deprecated
void loadXML​(Node entrynode,
             List<org.pentaho.di.core.database.DatabaseMeta> databases,
             List<SlaveServer> slaveServers,
             Repository rep)
      throws org.pentaho.di.core.exception.KettleXMLException
        Deprecated.
        use loadXML(Node, List, List, Repository, IMetaStore)
        This method is called by PDI whenever a job entry needs to read its settings from XML. The XML node containing the job entry's settings is passed in as an argument. Again, the helper class org.pentaho.di.core.xml.XMLHandler is typically used to conveniently read the settings from the XML node.
        Parameters:
        entrynode - the top-level XML node
        databases - the list of databases
        slaveServers - the list of slave servers
        rep - the repository object
        Throws:
        org.pentaho.di.core.exception.KettleXMLException - if any errors occur during the loading of the XML

      • loadXML

        void loadXML​(Node entrynode,
             List<org.pentaho.di.core.database.DatabaseMeta> databases,
             List<SlaveServer> slaveServers,
             Repository rep,
             org.pentaho.metastore.api.IMetaStore metaStore)
      throws org.pentaho.di.core.exception.KettleXMLException
        This method is called by PDI whenever a job entry needs to read its settings from XML. The XML node containing the job entry's settings is passed in as an argument. Again, the helper class org.pentaho.di.core.xml.XMLHandler is typically used to conveniently read the settings from the XML node.
        Parameters:
        entrynode - the top-level XML node
        databases - the list of databases
        slaveServers - the list of slave servers
        rep - the repository object
        metaStore - The metaStore to optionally load from.
        Throws:
        org.pentaho.di.core.exception.KettleXMLException - if any errors occur during the loading of the XML

      • getXML

        String getXML()
        This method is called by PDI whenever a job entry needs to serialize its settings to XML. It is called when saving a job in Spoon. 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.pentaho.di.core.xml.XMLHandler is typically used to construct the XML string.
        Returns:
        the xml representation of the job entry

      • saveRep

        @Deprecated
void saveRep​(Repository rep,
             org.pentaho.di.repository.ObjectId id_job)
      throws org.pentaho.di.core.exception.KettleException
        Deprecated.
        use saveRep(Repository, IMetaStore, ObjectId)
        This method is called by PDI whenever a job entry needs to save its settings to a PDI repository. The repository object passed in as the first argument provides a convenient set of methods for serializing job entry settings. When calling repository serialization methods, job id and job entry id are required. The job id is passed in to saveRep() as an argument, and the job entry id can be obtained by a call to getObjectId() inherited from the base class.
        Parameters:
        rep - the repository object
        id_job - the id_job
        Throws:
        org.pentaho.di.core.exception.KettleException - if any errors occur during the save

      • saveRep

        void saveRep​(Repository rep,
             org.pentaho.metastore.api.IMetaStore metaStore,
             org.pentaho.di.repository.ObjectId id_job)
      throws org.pentaho.di.core.exception.KettleException
        This method is called by PDI whenever a job entry needs to save its settings to a PDI repository. The repository object passed in as the first argument provides a convenient set of methods for serializing job entry settings. When calling repository serialization methods, job id and job entry id are required. The job id is passed in to saveRep() as an argument, and the job entry id can be obtained by a call to getObjectId() inherited from the base class.
        Parameters:
        rep - the repository
        metaStore - the MetaStore to use
        id_job - the id_job
        Throws:
        org.pentaho.di.core.exception.KettleException - if any errors occur during the save

      • loadRep

        @Deprecated
void loadRep​(Repository rep,
             org.pentaho.di.repository.ObjectId id_jobentry,
             List<org.pentaho.di.core.database.DatabaseMeta> databases,
             List<SlaveServer> slaveServers)
      throws org.pentaho.di.core.exception.KettleException
        Deprecated.
        use loadRep(Repository, IMetaStore, ObjectId, List, List)
        This method is called by PDI whenever a job entry needs to read its configuration from a PDI repository. The job entry id given in the arguments should be used as the identifier when using the repository's serialization methods.
        Parameters:
        rep - the repository object
        id_jobentry - the id of the job entry
        databases - the list of databases
        slaveServers - the list of slave servers
        Throws:
        org.pentaho.di.core.exception.KettleException - if any errors occur during the load

      • loadRep

        void loadRep​(Repository rep,
             org.pentaho.metastore.api.IMetaStore metaStore,
             org.pentaho.di.repository.ObjectId id_jobentry,
             List<org.pentaho.di.core.database.DatabaseMeta> databases,
             List<SlaveServer> slaveServers)
      throws org.pentaho.di.core.exception.KettleException
        This method is called by PDI whenever a job entry needs to read its configuration from a PDI repository. The job entry id given in the arguments should be used as the identifier when using the repository's serialization methods.
        Parameters:
        rep - the repository object
        metaStore - the MetaStore to use
        id_jobentry - the id of the job entry
        databases - the list of databases
        slaveServers - the list of slave servers
        Throws:
        org.pentaho.di.core.exception.KettleException - if any errors occur during the load

      • isStart

        boolean isStart()
        Checks if the job entry has started
        Returns:
        true if started, false otherwise

      • isDummy

        boolean isDummy()
        Checks if this job entry is a dummy entry
        Returns:
        true if this job entry is a dummy entry, false otherwise

      • clone

        Object clone()
        This method is called when a job entry is duplicated in Spoon. It needs to return a deep copy of this job entry object. It is essential that the implementing class creates proper deep copies if the job entry 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

      • evaluates

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

      • isUnconditional

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

      • isEvaluation

        boolean isEvaluation()
        Checks if the job entry is an evaluation
        Returns:
        true if the job entry is an evaluation, false otherwise

      • isTransformation

        boolean isTransformation()
        Checks if this job entry executes a transformation
        Returns:
        true if this job entry executes a transformation, false otherwise

      • isJob

        boolean isJob()
        Checks if the job entry executes a job
        Returns:
        true if the job entry executes a job, false otherwise

      • isShell

        boolean isShell()
        Checks if the job entry executes a shell program
        Returns:
        true if the job entry executes a shell program, false otherwise

      • isMail

        boolean isMail()
        Checks if the job entry sends email
        Returns:
        true if the job entry sends email, false otherwise

      • isSpecial

        boolean isSpecial()
        Checks if the job entry is of a special type (Start, Dummy, etc.)
        Returns:
        true if the job entry is of a special type, false otherwise

      • getSQLStatements

        @Deprecated
List<org.pentaho.di.core.SQLStatement> getSQLStatements​(Repository repository)
                                                 throws org.pentaho.di.core.exception.KettleException
        Deprecated.
        use getSQLStatements(Repository, IMetaStore, VariableSpace)
        Gets the SQL statements needed by this job entry to execute successfully.
        Parameters:
        repository - the repository
        Returns:
        a list of SQL statements
        Throws:
        org.pentaho.di.core.exception.KettleException - if any errors occur during the generation of SQL statements

      • getSQLStatements

        @Deprecated
List<org.pentaho.di.core.SQLStatement> getSQLStatements​(Repository repository,
                                                        org.pentaho.di.core.variables.VariableSpace space)
                                                 throws org.pentaho.di.core.exception.KettleException
        Deprecated.
        use getSQLStatements(Repository, IMetaStore, VariableSpace)
        Gets the SQL statements needed by this job entry to execute successfully, given a set of variables.
        Parameters:
        repository - the repository object
        space - a variable space object containing variable bindings
        Returns:
        a list of SQL statements
        Throws:
        org.pentaho.di.core.exception.KettleException - if any errors occur during the generation of SQL statements

      • getSQLStatements

        List<org.pentaho.di.core.SQLStatement> getSQLStatements​(Repository repository,
                                                        org.pentaho.metastore.api.IMetaStore metaStore,
                                                        org.pentaho.di.core.variables.VariableSpace space)
                                                 throws org.pentaho.di.core.exception.KettleException
        Gets the SQL statements needed by this job entry to execute successfully, given a set of variables.
        Parameters:
        repository - the repository object
        metaStore - the MetaStore to use
        space - a variable space object containing variable bindings
        Returns:
        a list of SQL statements
        Throws:
        org.pentaho.di.core.exception.KettleException - if any errors occur during the generation of SQL statements

      • getDialogClassName

        @Deprecated
String getDialogClassName()
        Deprecated.
        As of release 8.1, use annotated-based dialog instead {@see org.pentaho.di.core.annotations.PluginDialog}
        Get the name of the class that implements the dialog for the job entry JobEntryBase provides a default
        Returns:
        the name of the class implementing the dialog for the job entry

      • getFilename

        String getFilename()
        Gets the filename of the job entry. This method is used by job entries and transformations that call or refer to other job entries.
        Returns:
        the filename

      • getRealFilename

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

      • getUsedDatabaseConnections

        org.pentaho.di.core.database.DatabaseMeta[] getUsedDatabaseConnections()
        This method returns all the database connections that are used by the job entry.
        Returns:
        an array of database connections meta-data, which is empty if no connections are used.

      • check

        void check​(List<org.pentaho.di.core.CheckResultInterface> remarks,
           JobMeta jobMeta,
           org.pentaho.di.core.variables.VariableSpace space,
           Repository repository,
           org.pentaho.metastore.api.IMetaStore metaStore)
        Allows JobEntry objects to check themselves for consistency
        Parameters:
        remarks - List of CheckResult objects indicating consistency status
        jobMeta - the metadata object for the job entry
        space - the variable space to resolve string expressions with variables with
        repository - the repository to load Kettle objects from
        metaStore - the MetaStore to load common elements from

      • getResourceDependencies

        List<ResourceReference> getResourceDependencies​(JobMeta jobMeta)
        Get a list of all the resource dependencies that the step is depending on.
        Returns:
        a list of all the resource dependencies that the step is depending on

      • exportResources

        @Deprecated
String exportResources​(org.pentaho.di.core.variables.VariableSpace space,
                       Map<String,​ResourceDefinition> definitions,
                       ResourceNamingInterface namingInterface,
                       Repository repository)
                throws org.pentaho.di.core.exception.KettleException
        Deprecated.
        use exportResources(VariableSpace, Map, ResourceNamingInterface, Repository, IMetaStore)
        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:
        space - The variable space 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
        repository - The repository to load resources from
        Returns:
        The filename for this object. (also contained in the definitions map)
        Throws:
        org.pentaho.di.core.exception.KettleException - in case something goes wrong during the export

      • exportResources

        String exportResources​(org.pentaho.di.core.variables.VariableSpace space,
                       Map<String,​ResourceDefinition> definitions,
                       ResourceNamingInterface namingInterface,
                       Repository repository,
                       org.pentaho.metastore.api.IMetaStore metaStore)
                throws org.pentaho.di.core.exception.KettleException
        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:
        space - The variable space 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
        repository - The repository to load resources from
        metaStore - the metaStore to load external metadata from
        Returns:
        The filename for this object. (also contained in the definitions map)
        Throws:
        org.pentaho.di.core.exception.KettleException - in case something goes wrong during the export

      • hasRepositoryReferences

        boolean hasRepositoryReferences()
        Checks whether the job entry defines one or more references to a repository object
        Returns:
        true if the job entry defines one or more references to a repository object, false otherwise

      • lookupRepositoryReferences

        void lookupRepositoryReferences​(Repository repository)
                         throws org.pentaho.di.core.exception.KettleException
        Look up the references after import
        Parameters:
        repository - the repository to reference.
        Throws:
        org.pentaho.di.core.exception.KettleException - if any errors occur during the lookup

      • getReferencedObjectDescriptions

        String[] getReferencedObjectDescriptions()
        Returns:
        The objects referenced in the step, like a a transformation, a job, 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

        @Deprecated
Object loadReferencedObject​(int index,
                            Repository rep,
                            org.pentaho.di.core.variables.VariableSpace space)
                     throws org.pentaho.di.core.exception.KettleException
        Deprecated.
        use loadReferencedObject(int, Repository, IMetaStore, VariableSpace)
        Load the referenced object
        Parameters:
        index - the referenced object index to load (in case there are multiple references)
        rep - the repository
        space - the variable space to use
        Returns:
        the referenced object once loaded
        Throws:
        org.pentaho.di.core.exception.KettleException

      • loadReferencedObject

        Object loadReferencedObject​(int index,
                            Repository rep,
                            org.pentaho.metastore.api.IMetaStore metaStore,
                            org.pentaho.di.core.variables.VariableSpace space)
                     throws org.pentaho.di.core.exception.KettleException
        Load the referenced object
        Parameters:
        index - the referenced object index to load (in case there are multiple references)
        rep - the repository
        metaStore - the metaStore
        space - the variable space to use
        Returns:
        the referenced object once loaded
        Throws:
        org.pentaho.di.core.exception.KettleException

      • setParentJobMeta

        default void setParentJobMeta​(JobMeta jobMeta)
        At save and run time, the system will attempt to set the jobMeta so that it can be accessed by the jobEntries if necessary. This default method will be applied to all JobEntries that do not need to be aware of the parent JobMeta
        Parameters:
        jobMeta - the JobMeta to which this JobEntryInterface belongs

      • getParentJobMeta

        default JobMeta getParentJobMeta()
        Return Gets the parent jobMeta. This default method will throw an exception if a job entry attempts to call the getter when not implemented.