Developing a Resource Reader

Overview

A ResourceReader is a class that retrieves a Resource or product from a native/external source and returns it to DDF. A simple example is that of a File ResourceReader. It takes a file from the local file system and passes it back to DDF.  New implementations can be created in order to support obtaining Resources from various Resource data stores.  See the Working with Resources section of the Developer's Guide for more information. 

Creating A New ResourceReader

Creating a ResourceReader consists of 2 main steps:

1. Create a Java class that implements the ddf.catalog.resource.ResourceReader interface.
2. Deploy the OSGi bundled packaged service to the DDFrun-time.
   • Check the Working with OSGi - Bundles section.

Implementing the ResourceReader interface

public class TestResourceReader implements ddf.catalog.resource.ResourceReader

ResourceReader has a couple key methods where most of the work is performed.

retrieveResource

 public ResourceResponse retrieveResource( URI uri, Map<String, Serializable> arguments ) throws IOException, ResourceNotFoundException, ResourceNotSupportedException;

This method is the main entry to the ResourceReader. It is used to retrieve a Resource and send it back to the caller (generally the CatalogFramework). Information needed to obtain the entry is contained in the URI reference. The URI Scheme will need to match a scheme specified in the getSupportedSchemes method. This is how the CatalogFramework determines which ResourceReader implementation to use.  If there are multiple ResourceReaders supporting the same scheme, these ResourceReaders will be invoked iteratively.  Invocation of the ResourceReaders stops once one of them returns a Resource.

Arguments are also passed in. These can be used by the ResourceReader to perform additional operations on the resource.

An example of how URLResourceReader (located in the source code at /trunk/ddf/catalog/resource/URLResourceReader.java) implements the getResource method. This ResourceReader simply reads a file from a URI.

Implementing retrieveResource()

1. Define supported schemes (e.g. file, http, etc)
2. Check if the incoming URI matches a supported scheme, if not throw ResourceNotSupportedException.

3. For example:

    if ( !uri.getScheme().equals("http") )
    {
      throw new ResourceNotSupportedException("Unsupported scheme received, was expecting http")
    }

4. Implement the business logic.

5. For example the URLResourceReader will obtain the resource through a connection:

    URL url = uri.toURL();
    URLConnection conn = url.openConnection();
    String mimeType = conn.getContentType();
    if ( mimeType == null ) {
       mimeType = URLConnection.guessContentTypeFromName( url.getFile() );
    }
    InputStream is = conn.getInputStream();

   The Resource needs to be accessible from the DDF installation.  This includes being able to find a file locally, or reach out to a remote URI.  This may require internet access, and DDF may need to be configured to use a proxy (http.proxyHost and http.proxyPort can be added to the system properties on the command line script)

6. Return Resource in ResourceResponse

7. For example:

   return ResourceResponseImpl( new ResourceImpl( new BufferedInputStream( is ), new MimeType( mimeType ), url.getFile() ) );

8. If the Resource cannot be found, throw a ResourceNotFoundException.  

getSupportedSchemes

public Set<String> getSupportedSchemes();

This method lets the ResourceReader inform the CatalogFramework about the type of URI scheme that it accepts / should be passed. For single-use ResourceReaders (like a URLResourceReader) there may only be one scheme that it can accept while for others they may understand more than one. A ResourceReader must, at minimum, accept one qualifier.  As mentioned before, this method is used by the CatalogFramework to determine which ResourceReader to invoke. 

Export to OSGi Service Registry

In order for the ResourceReader to be used by the CatalogFramework, it should be exported to the OSGi Service Registry as a ddf.catalog.resource.ResourceReader.

See the XML below for an example:

<bean id="[[customResourceReaderId]]" class="[[example.resource.reader.impl.CustomResourceReader]]" />
<service ref="[[customResourceReaderId]]" interface="ddf.catalog.source.ResourceReader" />