Overview 

This page describes how to create and deploy Kettle step plugins using Java annotations: @org.pentaho.di.core.annotations.Step.

The @Step annotation is contained inside the kettle-engine.jar file.

In certain situations we wants to be able to deploy many plug-ins at the same time, In this document we describe a system that allows you to create a set of step plug-ins that can be loaded from a single JAR file.  The steps are described using Java annotations.

@Step

In version 3.0.0RC1 or later you can annotate steps with the @Step PDI annotation.  For an example, we look at the "Row Generator" step in the source code:

@Step(name="RowGenerator",image="ui/images/GEN.png",tooltip="BaseStep.TypeTooltipDesc.GenerateRows",description="BaseStep.TypeLongDesc.GenerateRows", category=StepCategory.CATEGORY_INPUT)
public class RowGeneratorMeta extends BaseStepMeta implements StepMetaInterface
{
...
}

Here are the different options for the @Step annotation:

Internationalization (i18n)

 By default, the i18n keys referenced in the @Step annotation are looked up the standard messages packages in "org.pentaho.di.trans.step".  However, if i18nPackageName is set, that package is used.
If that default location fails to reveal a translation, the package that contains the annotated step is used. 

Typically, in the default configuration, "org.pentaho.di.trans.step" does not contain the translation for your plugin so the easiest way to provide translations is to put your properties files in a messages/ package in the package that contains the annotated plugin.

Plug-in scans

 Because it would take too much time during start-up to scan all packages (in all jar files!) for annotated plugins, we only scan the following packages by default:

• org.pentaho.di.trans
• plugin

For OEM purposes, this is configurable in the file kettle-config.xml:

<!--  This adds classes annotated with the @Step annotation as a Kettle step -->
    <config id="steps-annotation-config">
        <config-class>
            org.pentaho.di.core.config.AnnotatedStepsConfigManager
        </config-class>
        <!-- the packages to scan for the annotation.  Even though this is not required, it is advisable to enter a value here to
        avoid full classpath scanning.  Different packages can be separated by commas. Lastly, the scan IS RECURSIVE. -->
        <property name="packages" value="org.pentaho.di.trans,plugin" />
    </config>

 
That basically means that if you put your plug-in in a package called "plugin.org.foo.com" it will be loaded if you put a jar in the PDI classpath.  (for example if you simply put it in the libext/ directory)

If you already wrote the plug-in and you don't want to change the name of the packages, you can also set an environment variable

KETTLE_PLUGIN_PACKAGES

If you set this environment variable on your system, the Spoon, Pan and Kitchen utilities will pick up this comma (,) delimited package list.  These packages will then also be scanned for annotated plug-ins.

Deployment

1. Simply put the JAR file containing the annotated plug-ins and the required extra libraries in the libext/ directory (or in your class path).
2. Optionally set environment variable KETTLE_PLUGIN_PACKAGES or change kettle-config.xml to make sure your plugins our found.