Difference between revisions of "SMILA/Development Guidelines/How to write a ProcessingService"

Revision as of 07:30, 24 April 2009

This page describes how to implement and configure your own processing service in case you wish to add functionality to SMILA.

What are processing services?

In contrast to pipelets processing services are not instantiated and configured by the workflow engine, but are started as OSGi services (preferably by declarative services) independently from the workflow engine. They can read their configuration from wherever they want. Their service registration must have a property named smila.processing.service.name that specifies the name with which the service is referenced by the workflow engine. For more information take a look at Pipelets and ProcessingServices.

Implementation (as DeclarativeService)

Follow these instructions to implement a processing service in SMILA:

• Create a class that implements the interface org.eclipse.smila.processing.ProcessingService. Note that your processing service is free to implement additional interfaces.

• Follow the instructions and rules for implementing DeclarativeService.

• Implement Id[] process(BlackboardService blackboard, Id[] recordIds). Here you have to place the "business logic" of your processing service. In most cases the result is the same as the input recordIDs, so just return it. But it is possible to return another list of IDs as result.

• As with regular DeclarativeServices, you have to specify the service component description(s) in META-INF/MANIFEST.MF.

• Add the property smila.processing.service.name to your service registration file.

• Consider thread-safeness. As processing services are often accessed by multiple threads make sure that the access to member variables (e.g. the configuration) is read-only. For best practices, use local variables instead of member variables if possible.

Configuration

If your processing service needs configurable settings, you are free to use any configuration you like (XML configuration files, property files, etc.) A good place to read configuration settings is the activate() method. But it is also possible to read the configuration in the process() method. Configuration files are usually located within the global configuration folder in a subfolder that equals the name of your bundle (e.g. org.eclipse.smila.mypackage). If your processing service only needs some simple configuration settings it is possible to use the same format used by pipelets but put the configuration inside a separate configuration file. Therefore you can use org.eclipse.smila.utils.config.ConfigUtils and org.eclipse.smila.processing.configuration.PipeletConfigurationLoader.

Here is a code sample showing how to use it in your processing service:

  private PipeletConfiguration readConfiguration(String bundleName, String configFileName) throws Exception {
    InputStream configurationFileStream = null;
    try {
      configurationFileStream = ConfigUtils.getConfigStream(bundleName, configFileName);
      final Unmarshaller unmarshaller = PipeletConfigurationLoader.createPipeletConfigurationUnmarshaller();
      return = (PipeletConfiguration) unmarshaller.unmarshal(configurationFileStream);
    } catch (final Exception ex) {
      throw new Exception("Could not read configuration property file " + configFileName, ex);
    } finally {
      IOUtils.closeQuietly(configurationFileStream);
    }
  }

Example

A template for a MyService class:

package org.eclipse.smila.mypackage

import org.eclipse.smila.blackboard.BlackboardService;
import org.eclipse.smila.datamodel.id.Id;
import org.eclipse.smila.processing.ProcessingException;
import org.eclipse.smila.processing.ProcessingService;
import org.osgi.service.component.ComponentContext;
 
public class MyService implements ProcessingService {
 
  protected void activate(ComponentContext) {
    // add any initialization code here
    // e.g. reading of configuration files
  }
 
  protected void deactivate(ComponentContext) {
    // add any clean up code here
  }
 
  public Id[] process(BlackboardService blackboard, Id[] recordIds) throws ProcessingException {
    // process the recordIds and create a result
  }
}

Register the DS component description in the bundle manifest:

...
Service-Component: OSGI-INF/myservice.xml
...

A template for the component description:

<?xml version="1.0" encoding="UTF-8"?>
<component name="MyService" immediate="true">
    <implementation class="org.eclipse.smila.mypackage.MyService" />
    <service>
         <provide interface="org.eclipse.smila.processing.ProcessingService"/>         
    </service>
    <property name="smila.processing.service.name" value="MyService"/>
</component>

Useful Information

If your service also implements an interface besides org.eclipse.smila.processing.ProcessingService and you want to be able to use the service outside of the workflow in any other class, simply provide another service interface:

...
    <service>
         <provide interface="org.eclipse.smila.processing.ProcessingService"/>         
         <provide interface="org.eclipse.smila.mypackage.MyServiceInterface"/>         
    </service>
...

See org.eclipse.smila.processing.pipelets.aperture.ApertureMimeTypeIdentifier for an example. {info}