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 Details

    • 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

    • getTypeId

      @Deprecated String getTypeId()
      Deprecated.
      Gets the plugin ID deprecated in favor of getPluginId()
      See Also:

    • 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
      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

      @Deprecated void check(List<org.pentaho.di.core.CheckResultInterface> remarks, JobMeta jobMeta)
      Deprecated.
      use check(List, JobMeta, VariableSpace, Repository, IMetaStore)
      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

    • 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.