Skip to main content
Pentaho Documentation

Maintain Step Settings

The StepMetaInterface is the main Java interface that a plugin implements.

Keep Track Of the Step Settings

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

These interface methods are also used to maintain settings.

void setDefault()

This method is called every time a new step is created and allocates or sets the step configuration to sensible defaults. The values set here are used by Spoon when a new step is created. This is a good place to ensure that the step settings are initialized to non-null values. Values that are null can be cumbersome to deal with in serialization and dialog population, so most PDI step implementations stick to non-null values for all step settings.

public Object clone()

This method is called when a step is duplicated in Spoon. It returns a deep copy of the step meta object. It is essential that the implementing class creates proper deep copies if the step configuration is stored in modifiable objects, such as lists or custom helper objects.

See org.pentaho.di.trans.steps.rowgenerator.RowGeneratorMeta.clone() in the PDI source for an example of creating a deep copy.

Serialize Step Settings

The plugin serializes its settings to both XML and a PDI repository. These interface methods provide this functionality.

public String getXML()

This method is called by PDI whenever a step serializes its settings to XML. It is called when saving a transformation in Spoon. The method returns an XML string containing the serialized step 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 step reads its settings from XML. The XML node containing the step settings is passed in as an argument. Again, the helper class, org.pentaho.di.core.xml.XMLHandler, reads the step settings from the XML node.

public void saveRep()

This method is called by PDI whenever a step saves its settings to a PDI repository. The repository object passed in as the first argument provides a set of methods for serializing step settings. The passed in transformation id and step id are used by the step as identifiers when calling the repository serialization methods.

public void readRep()

This method is called by PDI whenever a step reads its configuration from a PDI repository. The step 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 step dialog. When testing a step in Spoon, PDI internally saves and loads a copy of the transformation before executing it. 

Provide Instances of Other Plugin Classes

The StepMetaInterface plugin class is the main class, tying in with the rest of PDI architecture. It is responsible for supplying instances of the other plugin classes implementing StepDialogInterface, StepInterface, and StepDataInterface. The following methods cover these responsibilities. Each method implementation constructs a new instance of the corresponding class, forwarding the passed in arguments to the constructor.

  • public StepDialogInterface getDialog()
  • public StepInterface getStep()
  • public StepDataInterface getStepData()

Each of these methods returns a new instance of the plugin class implementing StepDialogInterface, StepInterface, and StepDataInterface.

Report Step Changes to the Row Stream

PDI needs to know how a step affects the row structure. A step may be adding or removing fields, as well as modifying the metadata of a field. The method implementing this aspect of a step plugin is getFields().

public void getFields()

Given a description of the input rows, the plugin modifies it to match the structure for its output fields. The implementation modifies the passed in RowMetaInterface object to reflect changes to the row stream. A step adds fields to the row structure. This is done by creating ValueMeta objects, such as the PDI default implementation of ValueMetaInterface, and appending them to the RowMetaInterface object. The Working with Fields section goes into deeper detail about ValueMetaInterface

This sample transformation uses two steps. The Demo step adds the field, demo_field, to empty rows produced by the Generate Rows step. 

Validate Step Settings

Spoon supports a Validate Transformation feature, which triggers a self-check of all steps.  PDI invokes the check() method of each step on the canvas, allowing each step to validate its settings.

public void check()

Each step has the opportunity to validate its settings and verify that the configuration given by the user is reasonable. In addition, a step checks if it is connected to preceding or following steps, if the nature of the step requires that kind of connection. An input step may expect to not have a preceding step for example. The check method passes in a list of check remarks, to which the method appends its validation results. Spoon displays the list of remarks collected from the steps, allowing you to take corrective action in case there are validation warnings or errors.


Interface with the PDI plugin system

The class implementing StepMetaInterface must be annotated with the Step Java annotation. Supply the following annotation attributes:

Attribute Description
id A globally unique ID for the step
image The resource location for the png icon image of the step
name A short label for the step
description A longer description for the step
categoryDescription The category the step should appear under in the PDI step tree. For example Input, Output, Transform, etc.
i18nPackageName If the i18nPackageName attribute is supplied in the annotation attributes, the values of name, description, and categoryDescription are interpreted as i18n keys relative to the message bundle contained in given package. The keys may be supplied in the extended form  i18n:<packagename> key to specify a package that is different from the package given in the i18nPackageName attribute.

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