Contents

What are pipelets?

Pipelets are not standalone services, but their lifecycle and configuration is managed by the workflow engine. Each occurrence of a pipelet in a workflow uses a different pipelet instance. For more information take a look at Pipelets.

Project template

Before writing your own pipelet we recommend you to take a look at the HelloWorldPipelet.java. This pipelet is an example of a very simple processing pipelet and can be used as a template for your pipelets. You can also get it by importing the bundles from the examples directory of SMILA's repository into your workspace and use them as templates:

In the MANIFEST.MF, add at least these as "Imported Packages" (of course, you will need more to develop your pipelet, depending on what you want to do):

org.eclipse.smila.blackboard

org.eclipse.smila.datamodel

org.eclipse.smila.processing

org.eclipse.smila.utils

org.eclipse.smila.processing.parameters (to use ParameterAccessor)

org.eclipse.smila.processing.util (to use ResultCollector)

Create a class that implements the interface org.eclipse.smila.processing.Pipelet and make sure that the class has a public no-argument constructor (or none at all).

Implement void configure(AnyMap configuration). This method is called prior to process. Here you can read the configuration provided for the pipelet in the pipeline. To share those properties store the whole configuration in a member variable or better check the configuration for validity and completeness and then store the settings in a member variable. You can later access the configuration with the ParameterAccessor (see code sample below). The advantage of using the parameter accessor is that you can also override your configuration with configuration parameters set in the single records (e.g. the task parameters are included in the record by PipelineProcessorWorker, so you could override the pipelets configuration with job parameters as long as you use the ParameterAccessor to access parameters in the process method).

Do not access OSGi Services in configure()
You should not try to use OSGi services in the configure() method, because during startup of SMILA configure() is called immediately during initialization of the BPEL engine, and it is easily possible that the required service has not been activated at that time, and if configure() throws an exception because it cannot lookup the required service, the pipeline will not be deployed and cannot be executed. It's better to lookup the services later in the process() method, because all services should be available then.

Implement String[] process(Blackboard blackboard, String[] recordIds). Here you have to place the "business logic" of your pipelet. In most cases the result is the same as the input recordIDs. But it is possible to return another list of IDs as result. Use the ResultCollector.addResult(...) to collect the ids you want to return and ResultCollector.addFailedResult(...) to control the error handling behaviour of your pipelet. When creating the ResultCollector you have to determine if the Collector should drop the ids that caused errors from the result id list it creates (using resultCollector.getResultIds())or if these ids should still be part of the result id set. The ResultCollector will also control exception handling for you when setting failed record ids (depending on the existence and value of the parameter _failOnError, default is false). If _failOnError is set to true the ResultCollector will throw a ProcessingException, if not, the error will just be logged (on how to use the ResultCollector see the code sample below).

Create a pipelet description json file for your pipelet in the SMILA-INF folder of the providing bundle. The file name is arbitrary but must have ".json" extension and the file content must contain at least the class name of the pipelet ({"class" : "your.class.name.here"}). Then they can be detected by the PipeletTracker service. If you would like to register multiple classes, use one separate description file for each class. Don't forget to add the SMILA-INF folder to the bin.includes entry of the bundle's build.properties file.

Consider thread-safe-ness. Because pipelets may be accessed by multiple threads, make sure that access to member variables (e.g. the configuration) is read-only. For best practices: use local variables instead of member variables if possible.

After that you will find the plugin jar in your destination directory in a plugins folder. Copy the plugin jar to your SMILA installation's plugins folder. After (re-)starting SMILA, you should find your pipelets via REST API: http://localhost:8080/smila/pipelets

The description as well as the parameters section is optional but gives users a hint on which parameters you pipelet uses and what they mean as well as what your pipelet does. The parameters section follows the same restrictions as the workers' parameter descriptions, see SMILA/Documentation/ParameterDefinition for details.

Now add the folder SMILA-INF to the build.properties (or just check it in the Build view of the MANIFEST.MF file in your IDE.

And finally, this is a sample showing how a pipelet is invoked in the BPEL pipeline using an <extensionActivity>. It also shows how the pipelet is configured using a <configuration> section.