|Java Interface|| |
|Base class|| |
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
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.
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.
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
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
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
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
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
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:
| ||A globally unique ID for the step|
| ||The resource location for the png icon image of the step|
| ||A short label for the step|
| ||A longer description for the step|
| ||The category the step should appear under in the PDI step tree. For example Input, Output, Transform, etc.|
| ||If the |
Please refer to the Sample Step Plugin for a complete implementation example.