| Home | Products | Issue Tracker | Service Providers | FAQ | Twitter | Download

# MS RFC 8: Pluggable External Feature Layer Providers

Date

  2005/10/26

Author

  Jani Averbach

Contact

  javerbach at extendthereach.com

Status

  adopted

Version

  MapServer 4.8

## Purpose

The purpose of this proposal is provide a way to user actually plug-in external third party feature layer providers to the MapServer at run time.

## Abstract Solution

Provide a way to user to tell via map-file which library to load for layer, then load this library on demand and cache it for later use and bind it to the running MapServer by layer’s virtual table.

## Technical Solution

- New `CONFIG` option `MS_PLUGIN_DIR` which, if set, tells the base path for plugins

- New MAP-file keyword `PLUGIN` with string argument. This keywords tells which library dynamically to load for this layer.

  The plugins are loaded based on the following algorithm:

  - If plugin string is missing `.so` or `.dll` extension, append it to the plugin string

  - If `MS_PLUGIN_DIR` is set and plugin string is not an absolute path, prefix plugin string with `MS_PLUGIN_DIR`

  - otherwise use plugin string directly

  In general, the dynamic library loader will use system paths to seek appropriate plugin to load, if the path is not absolute.

- New connection type `PLUGIN`

- New field `char* plugin_library` in layerObj structure, this is the name of library to load for this layer.

- Function to get virtual table for requested layer. If the library isn’t already loaded, it will be loaded on demand.

      static const layerVTableObj *
      getCustomLayerVirtualTable(layerObj *layer)

  where `layerVTableObj` is the virtual table and layer is a custom layer. In case of error, function will return `NULL`.

- Function to get a function pointer from dynamic loaded library. This function will also load the library.

      msGetDynamicLibrarySymbol(const char *Library,
                                const char *SymbolName)

  This is implemented by GDAL project, and I have planned to use their implementation of this (`CPLGetSymbol`).

- Cache structure for already loaded libraries. This cache structure will consist of a full name/path of the library (provided by user via mapfile), and a function pointer to the virtual table initialization function. The size of cache will be fixed and will be same as the maximum amount of layers (200 at the moment). This is the maximum number of different custom layers for MapServer which could be loaded at the same time. This cache implementation is internal, so if it has to be make dynamically allocated, it is possible to do later without breaking interface.

- New lock item (`TLOCK_LAYER_VTABLE`) to protect library cache structure.

## Files and objects affected

This proposal will affect at least following files and objects:

- `map.h`

  - `layerObj` will contain a new field, `char *plugin_library`.

- New lock token `TLOCK_LAYER_VTABLE`

- New files and objects for custom layer handling.

## Backwards compatibility issues

This change is binary incompatible, but mapfile backward compatible. It will add a new keyword which is unknown for old MapServers.

## Implementation Issues

None

## Bug ID

Bug 1477

## Voting history

Vote proposed by Jani Averbach on 10/26/2005, the initial result was +3 and after amending RFC, got +4 (3 non-voting members).

Voting +1: Frank Warmerdam, Steve Lime, Yewondwossen Assefa, Daniel Morissette

Proposal passed and will move forward.

## Open questions

None

## Working Notes

Plugin library has to implement function `PluginInitializeVirtualTable`

    int (*pfnPluginInitVTable)(layerVTableObj *,
                               layerObj *);

which is called during library loading. This function is responsible to populate `layerVTableObj *` virtual table. If this function leaves some function pointers to `NULL` in this virtual table, then default actions are used for these missing functions. The defaults are visible in function `maplayer.c: populateVirtualTable(...)`. The function must not populate directly `layerObj->vtable`, it have to use `layerVTableObj *` argument for this. The MapServer is holding `TLOCK_LAYER_VTABLE` lock during this function call.