Create Job Entry Plugins

JobEntryInterface is the main Java interface that a plugin implements.  

Keep Track of Job Entry Settings

The implementing class keeps track of job entry settings using private fields with corresponding get and set methods. The dialog class implementing JobEntryDialogInterface uses these methods to copy the user supplied configuration in and out of the dialog box.

public Object clone()

This method is called when a job entry is duplicated in Spoon. It returns a deep copy of the 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.

Serialize Job Entry Settings

The plugin serializes its settings to both XML and a PDI repository.

public String getXML()

This method is called by PDI whenever a job entry serializes 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, one tag per setting. The helper class, org.pentaho.di.core.xml.XMLHandler, constructs the XML string.

public void loadXML() 

This method is called by PDI whenever a job entry reads its settings from XML. The XML node containing the job entry settings is passed in as an argument. Again, the helper class, org.pentaho.di.core.xml.XMLHandler, is used to read the settings from the XML node.

public void saveRep()

This method is called by PDI whenever a job entry saves 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 reads its configuration from a PDI repository. The job entry id given in the arguments is used as the identifier when using the repositories serialization methods. 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 internally saves and loads a copy of the job before it is executed. 

Provide the Name of the Dialog Class

PDI needs to know which class takes care of the settings dialog box for the job entry. The interface method getDialogClassName() returns 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. 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, such as the File Exists job entry. 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 returns true if the job entry supports the True and False outgoing hops. If the job entry does not support distinct outcomes, it returns false.

public boolean isUnconditional()

This method returns true if the job entry supports the unconditional outgoing hop. If the job entry does not support the unconditional hop, it returns false.

Execute the Job Entry Task

The class implementing JobEntryInterface executes the actual job entry task. 

public Result execute()

The execute() method is 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 specified methods on the passed in result object. 

prev_result.setNrErrors()

The job entry indicates whether it has encountered any errors during execution. If there are errors, setNrErrors calls with the number of errors encountered. Typically, this is 1. If there are no errors, setNrErrors is called with an argument of zero (0).

prev_result.setResult()

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

Finally, the passed in prev_result object is returned.

Interface with the PDI plugin system

The class implementing JobEntryInterface must be annotated with the JobEntry Java annotation. Supply the following annotation attributes:

Please refer to the Sample Job Entry Plugin for a complete implementation example.