Working with Transformers

Overview

Transformers are utility objects used to transform a set of standard DDF components into a desired format such as into PDF, HTML, XML, or any other format. For instance a transformer can be used to convert a set of query results into an easy-to-read HTML format (HTML Transformer) or convert a set of results into a RSS feed that can be easily published to a URL for RSS feed subscription. A major benefit of transformers though is they can be registered in the OSGi Service Registry so that any other developer can access them based on their standard interface and self-assigned identifier, referred to as its "shortname." Transformers are often used by Endpoints for data conversion in a system standard way. Multiple endpoints can use the same transformer, a different transformer, or their own published transformer.

Usage

The ddf.catalog.transform package includes the InputTransformer, MetacardTransformer, and QueryResponseTransformer interfaces. All implementations can be accessed using the Catalog Framework or OSGi Service Registry as long as the implementations have been registered with the Service Registry.

Catalog Framework

The CatalogFramework provides convenience methods to transform Metacards and QueryResponses using a reference to the CatalogFramework. See Working with the Catalog Framework for more details on the method signatures.

It is easy to execute the convenience transform methods on the CatalogFramework instance.

Query Response Transform Example

1  // inject CatalogFramework instance or retrieve an instance  
2  private CatalogFramework catalogFramework;  
3 
4  public RSSEndpoint(CatalogFramework catalogFramework)
5  {
6     this.catalogFramework = catalogFramework ;
7     // implementation
8  }
9
10 // Other implementation details ...
11 
12 private void convert(QueryResponse queryResponse ) {
13    // ...
14    String transformerId = "rss"; 
15 
16    BinaryContent content = catalogFramework.transform(queryResponse, transformerId, null);
17    
18    // ... 
19 
20 }

Line #	Action
4	`CatalogFramework` is injected, possibly by dependency injection framework.
16	`queryResponse` is transformed into the RSS format, which is stored in the `BinaryContent` instance

Dependency Injection

Using Blueprint or another injection framework, transformers can be injected from the OSGi Service Registry. See Working with OSGi for more details on how to use injected instances.

Blueprint Service Reference

<reference id="[[Reference Id]]" interface="ddf.catalog.transform.[[Transformer Interface Name]]" filter="(shortname=[[Transformer Identifier]])" />

Each transformer has one or more transform methods that can be used to get the desired output.

Input Transformer Example

ddf.catalog.transform.InputTransformer inputTransformer = retrieveInjectedInstance() ;
 
Metacard entry = inputTransformer.transform(messageInputStream);

Metacard Transformer Example

ddf.catalog.transform.MetacardTransformer metacardTransformer = retrieveInjectedInstance() ;

BinaryContent content = metacardTransformer.transform(metacard, arguments);

Query Response Transformer Example

ddf.catalog.transform.QueryResponseTransformer queryResponseTransformer = retrieveInjectedInstance() ;

BinaryContent content = queryResponseTransformer.transform(sourceSesponse, arguments);

See Working with OSGi - Service Registry for more details.

OSGi Service Registry

In the vast majority of cases, working with the OSGi Service Reference directly should be avoided. Instead, dependencies should be injected via a dependency injection framework like Blueprint.

Transformers are registered with the OSGi Service Registry. Using a BundleContext and a filter, references to a registered service can be retrieved.

OSGi Service Registry Reference Example

ServiceReference[] refs = 
    bundleContext.getServiceReferences(ddf.catalog.transform.InputTransformer.class.getName(),"(shortname=" + transformerId + ")");
InputTransformer inputTransformer = (InputTransformer) context.getService(refs[0]); 
Metacard entry = inputTransformer.transform(messageInputStream);