Catalog Plug-in Services

The Catalog plugin provides the following services:

  • The concept of Handles to actual Resources
  • Discovery of additional resources using Search facilities
  • Programmatic Management of geospatial resources

The Catalog plugin supports several formats right out of the box and is easily extended for custom content.

EXT: To extend catalog for additional formats you will need to make an implementation of IService, IGeoResource and a WizardPage for your new content.

Background Information

We are going to launch right into technical details here – if you require additional background information please consider the following references:

  • Contributing to Eclipse (nice explanation of IResource, and Iadaptable)
  • Eclipse FAQ
  • Eclipse House Rules

The above references do no cover any additional ground beyond what is needed for normal eclipse plug-in development. Most of the above documentation is writen from the perspective of IDE development. The only additional restriction to watch out for is limit yourself to plug-ins available using a Rich Client Platform application.

Common mistakes:

  • Rich Client Platform: Please do not depend on IResource, it will not be available at runtime as it is part of the Eclipse IDE
  • Eclipse House Rules: You may only depend on public API packages (example net.refractions.udig.catalog)

Overview of the CatalogPlugin

CatalogPlugin provides the following (from AbstractUIPlugin):

  • getDialogSettings() - used to hold persistent state data for wizards and plug-ins
  • getImageRegistry() - images that are shared for frequently used within the plugin
  • getPreferenceStore() - used to hold persistent user or internal settings

CatalogPlugin explicitly provides for the following:

  • ID – convenience field, this is the same value used by plugin extention point, can be used to locate Platform resources associated with the CatalogPlugin
  • getDefault() - the single instance of the CatalogPlugin
  • addListener( .. ) – listen to resource change notification
  • removeListener( .. ) – stop listening for change notification
  • getCatalogs() - known catalogs, including registered web catalogs
  • getLocalCatalog() - catalog of known resources
  • getServiceFactory() - used to create new content from a URL

Code Example – Use of ID and Log

public void static countCatalog(){
    CatalogPlugin catalog = CatalogPlugin.getDefault();
    try {
        return catalog.getCatalogs().length;
    }
    catch( Throwable t ){
        catalog.getLog(
            new Status( IStatus.WARNING, CatalogPlugin.ID, IStatus.OK, null, t)
        );
        return 0;
    }
}

The above example makes use of CatalogPlugin, any problems are reported using the CatalogPlugin ID to the logging system.

Overview of IResolve

Catalog uses the model of a “handle� to allow access to spatial resources. The handle idea is captured by the IResolve class, this has the same design as the normal Eclipse IResource class.

It makes use of the following design element:

  • Acts as a Proxy for remote content, the associated resource considered remote* Acts as an “Extensible Interfaceâ€?, you can turn IResolve into the object you really want

With this in mind let us explore the core responsibilities of IResolve:

  • IResolve.getIdentifier() is a unique URL used to identify this resource
  • IResolve.canResolve( Class type ) is a non blocking check to see a type of resource is available
  • IResolve.resolve( Class type, IProgressMonitor monitor ) will aquire the request resource

IResolve handles can form a tree using following methods:

  • members( IResolve parent, IProgressMonitor )
  • parent( IProgressMonitor )

Finally, just because a handle exists does not mean the real resource resources exists or is working. A service may be down, or a shapefile may not be created yet.

Here is how to check on the status of a IResolve:

  • IResolve.getStatus(), one of CONNECTED, NOTCONNECTED or BROKEN

Note: Methods that are blocking make use of a IProgressMonitor, and throw an IOException in the event of a problem. This allows for both feedback during the operation, and strongly indicates to calling code that blocking input/output will occur.

Lets quickly work with an example (to make this real)

Code Example – Use of canResolve and resolve methods

public count shapes( File shapefile ){
    CatalogPlugin catalog = CatalogPlugin.getDefault();
    IServiceFactory factory = catalog.getServiceFactory();
    for( IResolve resolve : factory.aquire( shapefile.toUrl() ) ){
       if( resolve.canResolve( DataStore.class ) ){
           DataStore shape = resolve.resolve( DataStore.class );
           String typeName = shape.getTypeNames()[0];
           return shape.getFeatureSource( typeName ).count();
       }
    }
    return 0;
}

Note: Remember this is Java 5, there is less casting then you may expect

Comparison with IResource

IResolve offers the following advantages over normal Eclipse IResource:

  • IResolve explicitly represents a handle for an remote resource
  • IResolve blocking behavior is explicit at the API level
  • IResolve is available for RCP applications, normal IResource is part of the Eclipse IDE and cannot be used in a RCP application
  • IResolve uses Java 5 enums, type narrowing and Templates for a simplified API

IDE: Your instance of IResolve could also implement IAdaptable (we ensured that no method names would conflict). Implementing Iadaptable, and providing an adapter for IResource allows for seemless integration with the Eclipse IDE. This is out of scope for our current development effort – however the implementation is straight forward and would allow integration of the GISPlatform with the wider Eclipse community. The Eclipse workbench is already checks for the classes supporting IAdaptable, and will automatically integrate any class that responds to isAdaptable( IResource.class ).

Catalog API

Now that the role and use of IResolve is known we can begin to describe the uDig Catalog API in some detail.

The Catalog API is split between three abstractions:

  • ICatalog – catalog of spatial resources, both local and remote catalogs are available
  • IService – represents an external service such as a Web Feature Service or Shapefile
  • IGeoResource – actual spatial information such as a Web Map Server layer or shapefile contents

It is also time to introduce an additional design element:

  • Acts as a Bridge – you can navigate from your handle to information about the real resource

IGeoResource Overview

Lets start with the most specific, and the most useful member of the Catalog API. IGeoResource represents real information, the kind you can display on screen or work with.

Here are a few examples to get us started with:

  • A Table or View in a database
  • A FeatureCollection made available through a Web Feature Server (WFS)
  • A Web Map Server (WMS) Layer
  • The contents of a shapefile
  • A GridCoverage contained in an ArcGrid file

The IGeoResource implementation does not place any restrictions on the interface used to represent the external resource. That said here are our top contenders for most popular interface:

  1. Geotools FeatureSource used to represent Feature information available in a File, Database or Web Feature Server
  2. Geotools FeatureStore used to represent Feature information that allows modification.
  3. Geotools WMS Layer, represents a externalized rendering service advertised by a WMS
  4. GeoAPI GridCoverage, represents raster information such as GeoTIFF or ArcGRID content

EXT: This API is designed to be extended with your own content, CAD file formats, feature content from other toolkits , and dynamically generated content are exciting possibilities.

IGeoResource and IGeoResourceInfo

IGeoResource has the following extensions to IResolve:

  • parent is an IService
  • getInfo is a IGeoResourceInfo

Resolution Manager (Pending)

Just because we know how to do a few tricks with Shapefiles, turn them into a FeatureSource does not mean you are left out of the game. You can teach the uDig catalog system new tricks.

The ResolutionManager processes an extention point binding IResolve to new classes, you can use this facility to integrate your own functionality with the uDig application.


resolve.gif (image/gif)
resolvemanager.png (image/png)
[view] [edit]
(c) Copyright (c) 2004,2005 Refractions Research Inc. and others.