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

Revision as of 06:27, 26 September 2008

What are ProcessingServices

In contrast to "Pipelets" ProcessingService 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 references by the workflow engine.

Implementation (as DeclarativeService)

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

• Follow the rules for implementing DeclarativeServices: SMILA/Development Guidelines/Declarative Services

• Implement Id[] process(BlackboardService blackboard, Id[] recordIds). Here you have to place the "business logic" of your ProcessingService. 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 property "smila.processing.service.name" to your service registration file

• Thread-safe: as ProcessingServices are often accessed by multiple threads make sure that access to member variables (e.g. the configuration) is read only.
  • Best Practice: use local variables instead of memeber variables if possible

Configuration

If your ProcessingService needs configurable settings you are free to use any configuration you like (XML config 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 thee name of your bundle (e.g. org.eclipse.smila.mypackage). If your ProcessingService only needs some simple configuration settings it is possible to use the same format used by Pipelets but put the configuration inside a seperate configuration file. Therfore you can use org.eclipse.smila.utils.config.ConfigUtils and org.eclipse.smila.processing.configuration.PipeletConfigurationLoader.

Here is a code sample of how to use it in your ProcessingService:

  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, just 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}