org.pentaho.di.job.entry
Interface JobEntryInterface

All Known Implementing Classes:

JobEntryAbort, JobEntryAddResultFilenames, JobEntryCheckDbConnections, JobEntryCheckFilesLocked, JobEntryColumnsExist, JobEntryConnectedToRepository, JobEntryCopyFiles, JobEntryCopyMoveResultFilenames, JobEntryCreateFile, JobEntryCreateFolder, JobEntryDelay, JobEntryDeleteFile, JobEntryDeleteFiles, JobEntryDeleteFolders, JobEntryDeleteResultFilenames, JobEntryDosToUnix, JobEntryDTDValidator, JobEntryEmpty, JobEntryEval, JobEntryEvalFilesMetrics, JobEntryEvalTableContent, JobEntryExportRepository, JobEntryFileCompare, JobEntryFileExists, JobEntryFilesExist, JobEntryFolderIsEmpty, JobEntryFoldersCompare, JobEntryFTP, JobEntryFTPDelete, JobEntryFTPPUT, JobEntryFTPSGet, JobEntryFTPSPUT, JobEntryGetPOP, JobEntryHTTP, JobEntryJob, JobEntryMail, JobEntryMailValidator, JobEntryMoveFiles, JobEntryMSAccessBulkLoad, JobEntryMsgBoxInfo, JobEntryMssqlBulkLoad, JobEntryMysqlBulkFile, JobEntryMysqlBulkLoad, JobEntryPGPDecryptFiles, JobEntryPGPEncryptFiles, JobEntryPGPVerify, JobEntryPing, JobEntrySetVariables, JobEntrySFTP, JobEntrySFTPPUT, JobEntryShell, JobEntrySimpleEval, JobEntrySNMPTrap, JobEntrySpecial, JobEntrySQL, JobEntrySSH2GET, JobEntrySSH2PUT, JobEntrySuccess, JobEntrySyslog, JobEntryTableExists, JobEntryTalendJobExec, JobEntryTrans, JobEntryTruncateTables, JobEntryUnZip, JobEntryWaitForFile, JobEntryWaitForSQL, JobEntryWebServiceAvailable, JobEntryWriteToFile, JobEntryWriteToLog, JobEntryXMLWellFormed, JobEntryXSDValidator, JobEntryXSLT, JobEntryZipFile

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:
  
  public 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:
  
  public 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.
  
  public 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.
  
  public 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.
  
  public 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:
  
  public 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.
  
  public 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:
  
  public 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 Summary

void	check(List<CheckResultInterface> remarks, JobMeta jobMeta) Allows JobEntry objects to check themselves for consistency
void	clear() This method should clear out any variables, objects, etc.
Object	clone() This method is called when a job entry is duplicated in Spoon.
boolean	evaluates() This method must return true if the job entry supports the true/false outgoing hops.
Result	execute(Result prev_result, int nr) Execute the job entry.
String	exportResources(VariableSpace space, Map<String,ResourceDefinition> definitions, ResourceNamingInterface namingInterface, Repository repository) Exports the object to a flat-file system, adding content with filename keys to a set of definitions.
String	getDescription() Gets the description of this job entry
String	getDialogClassName() Get the name of the class that implements the dialog for the job entry JobEntryBase provides a default
String	getFilename() Gets the filename of the job entry.
LogChannelInterface	getLogChannel() Gets the log channel.
String	getName() Gets the name of this job entry.
ObjectId	getObjectId() Gets the object id.
Job	getParentJob() Gets the parent job.
String	getPluginId() Gets the plugin id.
String	getRealFilename() Gets the real filename of the job entry, by substituting any environment variables present in the filename.
List<ResourceReference>	getResourceDependencies(JobMeta jobMeta) Get a list of all the resource dependencies that the step is depending on.
List<SQLStatement>	getSQLStatements(Repository repository) Gets the SQL statements needed by this job entry to execute successfully.
List<SQLStatement>	getSQLStatements(Repository repository, VariableSpace space) Gets the SQL statements needed by this job entry to execute successfully, given a set of variables.
String	getTypeId() Deprecated. in favor of getPluginId()
DatabaseMeta[]	getUsedDatabaseConnections() This method returns all the database connections that are used by the job entry.
String	getXML() This method is called by PDI whenever a job entry needs to serialize its settings to XML.
boolean	hasChanged() Checks whether the job entry has changed
boolean	hasRepositoryReferences() Checks whether the job entry defines one or more references to a repository object
boolean	isDummy() Checks if this job entry is a dummy entry
boolean	isEvaluation() Checks if the job entry is an evaluation
boolean	isJob() Checks if the job entry executes a job
boolean	isMail() Checks if the job entry sends email
boolean	isShell() Checks if the job entry executes a shell program
boolean	isSpecial() Checks if the job entry is of a special type (Start, Dummy, etc.)
boolean	isStart() Checks if the job entry has started
boolean	isTransformation() Checks if this job entry executes a transformation
boolean	isUnconditional() This method must return true if the job entry supports the unconditional outgoing hop.
void	loadRep(Repository rep, ObjectId id_jobentry, List<DatabaseMeta> databases, List<SlaveServer> slaveServers) This method is called by PDI whenever a job entry needs to read its configuration from a PDI repository.
void	loadXML(Node entrynode, List<DatabaseMeta> databases, List<SlaveServer> slaveServers, Repository rep) This method is called by PDI whenever a job entry needs to read its settings from XML.
void	lookupRepositoryReferences(Repository repository) Look up the references after import
boolean	resetErrorsBeforeExecution() Checks whether a reset of the number of errors is required before execution.
void	saveRep(Repository rep, ObjectId id_job) This method is called by PDI whenever a job entry needs to save its settings to a PDI repository.
void	setChanged() Sets whether the job entry has changed
void	setChanged(boolean ch) Sets whether the job entry has changed
void	setDescription(String description) Sets the description of this job entry
void	setName(String name) Sets the name for this job entry.
void	setObjectId(ObjectId id) Sets the object id.
void	setParentJob(Job job) Sets the parent job.
void	setPluginId(String pluginId) Sets the plugin id.
void	setRepository(Repository repository) Sets the repository.

Method Detail

execute

Result execute(Result prev_result,
               int nr)
               throws 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:

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

LogChannelInterface getLogChannel()

Gets the log channel.

Returns:

the log channel

setRepository

void setRepository(Repository repository)

Sets the repository.

Parameters:

repository - the new repository

clear

void clear()

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

getObjectId

ObjectId getObjectId()

Gets the object id.

Returns:

the object id

setObjectId

void setObjectId(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

String getTypeId()

Deprecated. in favor of getPluginId()

Gets the plugin ID

See Also:

getPluginId()

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

void loadXML(Node entrynode,
             List<DatabaseMeta> databases,
             List<SlaveServer> slaveServers,
             Repository rep)
             throws 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

Throws:

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

void saveRep(Repository rep,
             ObjectId id_job)
             throws 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 object

id_job - the id_job

Throws:

KettleException - if any errors occur during the save

loadRep

void loadRep(Repository rep,
             ObjectId id_jobentry,
             List<DatabaseMeta> databases,
             List<SlaveServer> slaveServers)
             throws 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

id_jobentry - the id of the job entry

databases - the list of databases

slaveServers - the list of slave servers

Throws:

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

List<SQLStatement> getSQLStatements(Repository repository)
                                    throws KettleException

Gets the SQL statements needed by this job entry to execute successfully.

Parameters:

repository - the repository

Returns:

a list of SQL statements

Throws:

KettleException - if any errors occur during the generation of SQL statements

getSQLStatements

List<SQLStatement> getSQLStatements(Repository repository,
                                    VariableSpace space)
                                    throws KettleException

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:

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

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<CheckResultInterface> remarks,
           JobMeta jobMeta)

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

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

String exportResources(VariableSpace space,
                       Map<String,ResourceDefinition> definitions,
                       ResourceNamingInterface namingInterface,
                       Repository repository)
                       throws 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

Returns:

The filename for this object. (also contained in the definitions map)

Throws:

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 KettleException

Look up the references after import

Parameters:

repository - the repository to reference.

Throws:

KettleException - if any errors occur during the lookup