/
Developing an Input Transformer

Developing an Input Transformer

Owned by Shaun Morris
Last updated: Jun 28, 2013 by Jeff VettrainoVersion comment

Prerequisites

  1. Understand the desired component for development as described in the DDF Catalog section.
    • Review existing implementations in the source code and application documentation.
  2. Have an IDE and the ability to create OSGi bundles.
  3. Understand the Use of the Whiteboard Design Pattern section and how to publish services to the OSGi service registry.

Overview

An InputTransformer is used to transform data from an InputStream into a Metacard.  Input Transformers can be requested from the OSGi Service Registry by Endpoints or any other bundle.  See Included Input Transformers for examples.

Creating an InputTransformer Using Java

  1. Create a new Java class that implements ddf.catalog.transform.InputTransformer.

    public class SampleInputTransformer implements ddf.catalog.transform.InputTransformer

  2. Implement the transform methods.

    public Metacard transform(InputStream input) throws IOException, CatalogTransformerException 
public Metacard transform(InputStream input, String id) throws IOException, CatalogTransformerException

  3. Import the DDF interface packages to the bundle manifest (in addition to any other required packages).

    Import-Package: ddf.catalog,ddf.catalog.transform

  4. Create an OSGi descriptor file to communicate with the OSGi Service Registry (described in the Working with OSGi section). Export the service to the OSGi Registry and declare service properties.

    Blueprint descriptor example
    ...
<service ref="[[SampleInputTransformer]]" interface="ddf.catalog.transform.InputTransformer">
    <service-properties>
        <entry key="shortname" value="[[sampletransform]]" />
        <entry key="title" value="[[Sample Input Transformer]]" />
        <entry key="description" value="[[A new transformer for metacard input.]]" />
    </service-properties>
</service>
...

  5. Deploy OSGi Bundle to OSGi runtime.

     

Variable Descriptions

Blueprint Service properties
KeyDescription of ValueExample
shortname(Required) An abbreviation for the return-type of the BinaryContent being sent to the user.atom
title(Optional) A user-readable title that describes (in greater detail than the shortname) the service.Atom Entry Transformer Service
description(Optional) A short, human-readable description that describes the functionality of the service and the output.This service converts a single metacard xml document to an atom entry element.

Creating an Input Transformer Using Apache Camel

Alternatively, make an Apache Camel route in a blueprint file and deploy it, either via a feature file or via hot deploy.

Design Pattern

From

When using from catalog:inputtransformer?id=text/xml then an Input Transformer will be created and registered in the OSGi registry with an id of text/xml.

To

When using to catalog:inputtransformer?id=text/xml then an Input Transformer with an id matching text/xml will be discovered from the OSGi registry and invoked.

Message Formats

InputTransformer

Exchange TypeFieldType
Request (comes from <from> in the route)bodyjava.io.InputStream
Response (returned after called via <to> in the route)bodyddf.catalog.data.Metacard

Examples

InputTransformer Creation
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
        <route>
            <from uri="catalog:inputtransformer?mimeType=RAW(id=text/xml;id=vehicle)"/>
            <to uri="xslt:vehicle.xslt" /> <!-- must be on classpath for this bundle -->
            <to uri="catalog:inputtransformer?mimeType=RAW(id=text/xml;id=ddms20)" />
        </route>
    </camelContext>
</blueprint>

Its always a good idea to wrap the mimeType value with the RAW parameter as shown in the example above. This will ensure that the value is taken exactly as is, and is especially useful when you are using special characters.

Line

Number

Description
1Defines this as an Apache Aries blueprint file
2Defines the Apache Camel context that contains the route
3Defines start of an Apache Camel route
4

Defines the endpoint/consumer for the route. In this case it is the DDF custom catalog component that is an InputTransformer registered with

an id of text/xml;id=vehicle meaning it can transform an InputStream of vehicle data into a Metacard.

Note that the specified XSL stylesheet must be on the classpath of the bundle that this blueprint file is packaged in.

5Defines the XSLT to be used to transform the vehicle input into DDMS format using the Apache Camel provided XSLT component.
6

Defines the route node that accepts DDMS formatted input and transforms it into a Metacard, using the DDF custom catalog component

that is an InputTransformer registered with an id of text/xml;id=ddms20

An example of using an Apache Camel route to define an InputTransformer in a blueprint file and deploying it as a bundle to an OSGi container can be found in the DDF SDK examples at ddf/sdk/sample-transformers/xslt-identity-input-transformer

Additional Reading