Providing configuration options for a plugin

Plugins should be designed to be reusable that reads configuration options set within the data source or results page.

Plugins support two types of configuration:

Configuration supplied via configuration keys

Configuration keys can be defined within data source or results page configuration, which are available to the plugin via a Java map. These configuration keys are key-value pairs the are stored with the other configuration for the data source or results page and are service the configuration needs of the majority of plugins.

Configuration supplied via a configuration file

A plugin-specific configuration file can be defined to capture complex configuration for a plugin. This is appropriate when plugin configuration requirements are not satisfied by simple key-value pairs, e.g. if you need a set of keys to define a single rule that the plugin uses.

Configuration files can be defined in two formats - plain text and JSON.

Supplying configuration to a plugin

Access to plugin configuration is via the plugin context object that is associated with the interface that you are implementing.

Configuration keys

Configuration keys defined in the data source or results page configuration can be accessed using a variety of methods that return single or multiple configuration keys.

Please refer to the Plugin shared Javadoc documentation for the interface that you are implementing for the specific methods available. The methods below vary depending on the requirements of the interface.

For example, the gather and index interfaces provide the following methods for accessing configuration keys:

  • Map<String, List<String>> getConfigKeysMatchingPattern(String pattern): Provides config settings which match the given key pattern.

  • Set<String> getConfigKeysWithPrefix(String prefix): Provides a list of configuration setting keys which have a common prefix.

  • String getConfigSetting(String key): Provides access to configurations settings from the current Funnelback installation and data source/results page.

Configuration files

Access to a plugin-specific configuration file is provided using a method in the plugin context object for the interface that you are implementing.

Please refer to the Plugin shared Javadoc documentation for the interface that you are implementing for the specific methods available. The methods below vary depending on the requirements of the interface.

For example, the gather and index interfaces provide the following methods for accessing configuration files:

  • Optional<String> pluginConfigurationFile(String filename): Reads a configuration file for the currently running plugin as a UTF-8 String.

  • Optional<byte[]> pluginConfigurationFileAsBytes(String filename): Reads a configuration file for the currently running plugin as binary data.

Reading a configuration key and falling back to a default value

/*
Note: this will require you to add an import to the top of your java file.

import java.util.Optional;
*/


/*
  For boolean values

  Example: Read the plugin.example-gatherer.debug configuration key
   from the data source configuration, and set to false if it's not set.
*/
Boolean debug = Optional.ofNullable(context.getConfigSetting("plugin.example-gatherer.debug")).map(Boolean::parseBoolean).orElse(false)

/*
  For boolean values

  Example: Read the plugin.example-gatherer.debug configuration key
   from the data source configuration, and set to false if it's not set.
*/

String example = Optional.ofNullable(context.getConfigSetting("plugin.example-gatherer.")).orElse("default value")