This is currently still some complicated manual task, but this stems in part from the goal of allowing a system administrator to effectively constrain the set of available plugins. More effort could make this a lot simpler, but currently this has low priority, as a plugin needs to be configured only once ...

The first step consists of copying the plugins JAR file (and associated library JARs) to the directory which is configured as the plugin directory (see the setting plugin-dir).

Next, an entry has to be made in the file specified in the plugin-config settings. This means to add a property with the name of the FileHandler class and the value containing the name of the plugins JAR file (relative to the plugin directory). In case the JAR contains multiple FileHandlers (which is perfectly legal), an entry has to be made for each one (all pointing to the same JAR file).

By now, the plugin should already be operational and get detected upon startup of the application. In case of classpath issues or dependency problems, an according error message will be logged and the plugin will be ignored.

The plugin should now be listed as an available option for opening files of the MIME types which are listed as supported by the plugin itself. This is normally a sensible default, but a user might desire to open files of other types with the same plugin too. This can be accomplished by adding a mapping to the FileHandler-map specified in the setting file-handler-map. It is possible to either map the MIME type or directly the files extension to a given FileHandler (identified by its class name).

To influence the mapping of file name extensions to MIME types, an entry in the file identified by the setting mimetypes-file can associate that extension to any MIME type. This will subsequently influence the selection of the FileHandler to use, based on the mappings in the file-handler-map.

A complete example might help:

  # it is also possible to place the plugin directory into the users area
  # and thus let each user have her own set of plugins ...
  plugin-dir       = ${app.home}/plugins
  plugin-config    = ${settings.dir}/FileBrowserPlugin.properties
  mimetypes-file   = ${settings.dir}/FileBrowser.mimetypes
  file-handler-map = ${settings.dir}/FileBrowserHandler.properties

  com.foo.bar.MyHandler = sample-filehandler.jar
  # more mappings ...

  # map the extensions '.sample' and '.custom' to the given MIME type:
  application/vnd-custom   sample custom
  # more mappings ...

  # the fallback in case nothing else matches: use the File Info Viewer:
  default = net.boarderzone.gui.widget.FileHandlerViewFileInfo

  # map files without extension to the Text Viewer plugin:
  default."" = net.boarderzone.plugins.filehandler.textviewer.TextViewerHandler

  # map all 'application/*' MIME types to the given handler:
  default.application = some.other.plugin.PreviewHandler

  # map the custom handler to its defined MIME type:
  default.application/vnd-custom = com.foo.bar.MyHandler

  # map the extension '.foo' directly to the custom handler too:
  default.foo = com.foo.bar.MyHandler

  # more mappings ...