net.sf.okapi.common.filters

## Class FilterConfigurationMapper

- java.lang.Object
- - net.sf.okapi.common.ParametersEditorMapper
  - - net.sf.okapi.common.filters.FilterConfigurationMapper

- All Implemented Interfaces:
    IFilterConfigurationMapper, IParametersEditorMapper

      public class FilterConfigurationMapper
      extends ParametersEditorMapper
      implements IFilterConfigurationMapper

  Default implementation of the `IFilterConfigurationMapper` interface. In this implementation the custom configurations are stored as simple files in the file system of the machine and the value for `FilterConfiguration.parametersLocation` for a custom configuration is filename of the parameters file. The directory where the files are located is defined with the `setCustomConfigurationsDirectory(String)`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `CONFIGFILE_EXT` Extension of the custom configuration files of this mapper.
    `static char` | `CONFIGFILE_SEPARATOR` Character used to separate the filter name from the custom configuration name in a custom configuration identifier for this mapper.

    - ### Fields inherited from class net.sf.okapi.common.ParametersEditorMapper

      `descMap, editorMap`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FilterConfigurationMapper()` Creates a new FilterConfigurationMapper object with no mappings and the custom configuration directory set to the current directory.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addConfiguration(FilterConfiguration config)` Adds a new configuration to this mapper.
    `void` | `addConfigurations(java.lang.String filterClass)` Adds all the predefined configurations of a given filter to this mapper.
    `void` | `addCustomConfiguration(java.lang.String configId)`
    `void` | `addCustomConfiguration(java.lang.String configId, IParameters parameters)`
    `void` | `addFromPlugins(PluginsManager pm)`
    `void` | `clearConfigurations(boolean customOnly)` Removes configuration mappings from this mapper.
    `IParametersEditor` | `createConfigurationEditor(java.lang.String configId)` Creates an instance of the filter's parameters editor for a given configuration identifier.
    `IParametersEditor` | `createConfigurationEditor(java.lang.String configId, IFilter existingFilter)` Creates an instance of the filter's parameters editor for a given configuration identifier.
    `FilterConfiguration` | `createCustomConfiguration(FilterConfiguration baseConfig)` Creates a custom configuration object based on a give one.
    `IFilter` | `createFilter(java.lang.String configId)` Creates an instance of the filter for a given configuration identifier and loads its corresponding parameters.
    `IFilter` | `createFilter(java.lang.String configId, IFilter existingFilter)` Creates an instance of the filter for a given configuration identifier and loads its corresponding parameters.
    `void` | `deleteCustomParameters(FilterConfiguration config)` Deletes the parameters of a custom configuration.
    `java.util.Iterator<FilterConfiguration>` | `getAllConfigurations()` Gets an iterator on all configurations objects for this mapper.
    `FilterConfiguration` | `getConfiguration(java.lang.String configId)` Gets the FilterConfiguration object for a given configuration identifier.
    `java.lang.String` | `getCustomConfigurationsDirectory()` Gets the directory where the custom configuration files are stored.
    `IParameters` | `getCustomParameters(FilterConfiguration config)` Gets the parameters for a given custom filter configuration.
    `IParameters` | `getCustomParameters(FilterConfiguration config, IFilter existingFilter)` Gets the parameters for a given custom filter configuration.
    `FilterConfiguration` | `getDefaultConfiguration(java.lang.String mimeType)` Gets the first filter configuration for a given MIME type.
    `FilterConfiguration` | `getDefaultConfigurationFromExtension(java.lang.String ext)` Gets the first filter configuration for a given extension.
    `java.util.List<FilterConfiguration>` | `getFilterConfigurations(java.lang.String filterClass)` Gets a list of all FilterConfiguration objects for a given filter class.
    `java.util.List<FilterInfo>` | `getFiltersInfo()` Gets a list of information on all filters in this mapper.
    `java.util.List<FilterConfiguration>` | `getMimeConfigurations(java.lang.String mimeType)` Gets a list of all FilterConfiguration objects for a given MIME type.
    `IParameters` | `getParameters(FilterConfiguration config)` Gets the parameters for a given configuration (predefined or custom).
    `IParameters` | `getParameters(FilterConfiguration config, IFilter existingFilter)` Gets the parameters for a given configuration (predefined or custom).
    `protected IFilter` | `instantiateFilter(FilterConfiguration config, IFilter existingFilter)` Instantiate a filter from a given configuration, trying to re-use an existing one.
    `void` | `removeConfiguration(java.lang.String configId)` Removes a given configuration from this mapper.
    `void` | `removeConfigurations(java.lang.String filterClass)` Removes all the configurations (predefined and custom) of a given filter from this mapper.
    `void` | `saveCustomParameters(FilterConfiguration config, IParameters params)` Saves the parameters of a custom configuration.
    `void` | `setCustomConfigurationsDirectory(java.lang.String dir)` Sets the directory where the custom configuration files are stored.
    `static java.lang.String[]` | `splitFilterFromConfiguration(java.lang.String configId)` Splits a configuration identifier into a filter identifier and the parameters info.
    `void` | `updateCustomConfigurations()` Updates the custom configurations for this mapper.

    - ### Methods inherited from class net.sf.okapi.common.ParametersEditorMapper

      `addDescriptionProvider, addDescriptionProvider, addEditor, addEditor, clearDescriptionProviders, clearEditors, createParametersEditor, getDescriptionProvider, removeDescriptionProvider, removeEditor`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface net.sf.okapi.common.filters.IFilterConfigurationMapper

      `addEditor, clearEditors, removeEditor`

    - ### Methods inherited from interface net.sf.okapi.common.IParametersEditorMapper

      `addDescriptionProvider, addDescriptionProvider, addEditor, clearDescriptionProviders, createParametersEditor, getDescriptionProvider, removeDescriptionProvider`

- - ### Field Detail

    - #### CONFIGFILE_EXT

          public static final java.lang.String CONFIGFILE_EXT

      Extension of the custom configuration files of this mapper.
      See Also:
        Constant Field Values

    - #### CONFIGFILE_SEPARATOR

          public static final char CONFIGFILE_SEPARATOR

      Character used to separate the filter name from the custom configuration name in a custom configuration identifier for this mapper.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### FilterConfigurationMapper

          public FilterConfigurationMapper()

      Creates a new FilterConfigurationMapper object with no mappings and the custom configuration directory set to the current directory.

  - ### Method Detail

    - #### splitFilterFromConfiguration

          public static java.lang.String[] splitFilterFromConfiguration(java.lang.String configId)

      Splits a configuration identifier into a filter identifier and the parameters info.
      Parameters:
        `configId` - the configuration identifier to split.
      Returns:
        an array of two strings: 0=filter (e.g. "okf_xml", 1=parameter info (or null).

    - #### addFromPlugins

          public void addFromPlugins(PluginsManager pm)

    - #### addConfigurations

          public void addConfigurations(java.lang.String filterClass)

      Description copied from interface: `IFilterConfigurationMapper`
      Adds all the predefined configurations of a given filter to this mapper.
      Specified by:
        `addConfigurations` in interface `IFilterConfigurationMapper`
      Parameters:
        `filterClass` - the class name of the filter to lookup.

    - #### addConfiguration

          public void addConfiguration(FilterConfiguration config)

      Description copied from interface: `IFilterConfigurationMapper`
      Adds a new configuration to this mapper.
      Specified by:
        `addConfiguration` in interface `IFilterConfigurationMapper`
      Parameters:
        `config` - the configuration to add.

    - #### createFilter

          public IFilter createFilter(java.lang.String configId)

      Description copied from interface: `IFilterConfigurationMapper`
      Creates an instance of the filter for a given configuration identifier and loads its corresponding parameters.
      Specified by:
        `createFilter` in interface `IFilterConfigurationMapper`
      Parameters:
        `configId` - the configuration identifier to use for look-up.
      Returns:
        a new `IFilter` object (with its parameters loaded) for the given configuration identifier, or null if the object could not be created.

    - #### createFilter

          public IFilter createFilter(java.lang.String configId,
                             IFilter existingFilter)

      Description copied from interface: `IFilterConfigurationMapper`
      Creates an instance of the filter for a given configuration identifier and loads its corresponding parameters.
      Specified by:
        `createFilter` in interface `IFilterConfigurationMapper`
      Parameters:
        `configId` - the configuration identifier to use for look-up.
        `existingFilter` - an optional existing instance of a filter. This argument can be null. If this argument is not null, it is checked against the requested filter and re-use if the requested filter and the provided instance are the same. If the provided instance is re-used, its parameters are always re-loaded. Providing an existing instance of the requested filter may allow for better efficiency.
      Returns:
        a new `IFilter` object (with its parameters loaded) for the given configuration identifier, or null if the object could not be created.

    - #### getParameters

          public IParameters getParameters(FilterConfiguration config)

      Description copied from interface: `IFilterConfigurationMapper`
      Gets the parameters for a given configuration (predefined or custom).
      Specified by:
        `getParameters` in interface `IFilterConfigurationMapper`
      Parameters:
        `config` - the configuration for which the parameters are requested.
      Returns:
        the parameters object for the given configuration.
      See Also:
        `IFilterConfigurationMapper.getCustomParameters(FilterConfiguration)`

    - #### getParameters

          public IParameters getParameters(FilterConfiguration config,
                                  IFilter existingFilter)

      Description copied from interface: `IFilterConfigurationMapper`
      Gets the parameters for a given configuration (predefined or custom).
      Specified by:
        `getParameters` in interface `IFilterConfigurationMapper`
      Parameters:
        `config` - the configuration for which the parameters are requested.
        `existingFilter` - optional existing instance of the filter for the given configuration. This argument can be null. If it not null, the provided filter may be used to load the parameters (if it matches the appropriate class). Providing this argument may allow the method to be more efficient by not creating a temporary filter to get an instance of the parameters to load.
      Returns:
        the parameters object for the given configuration.

    - #### createConfigurationEditor

          public IParametersEditor createConfigurationEditor(java.lang.String configId)

      Description copied from interface: `IFilterConfigurationMapper`
      Creates an instance of the filter's parameters editor for a given configuration identifier.
      Specified by:
        `createConfigurationEditor` in interface `IFilterConfigurationMapper`
      Parameters:
        `configId` - the configuration identifier to use for look-up.
      Returns:
        a new IParametersEditor object for the given configuration identifier, or null if no editor is available or if the object could not be created.

    - #### createConfigurationEditor

          public IParametersEditor createConfigurationEditor(java.lang.String configId,
                                                    IFilter existingFilter)

      Description copied from interface: `IFilterConfigurationMapper`
      Creates an instance of the filter's parameters editor for a given configuration identifier.
      Specified by:
        `createConfigurationEditor` in interface `IFilterConfigurationMapper`
      Parameters:
        `configId` - the configuration identifier to use for look-up.
        `existingFilter` - an optional existing instance of a filter. This argument can be null. If this argument is not null and matches the filter of the given configuration it is used instead of a temporay instance, to get an instance of the parameters object for which the editor is requested.
      Returns:
        a new IParametersEditor object for the given configuration identifier, or null if no editor is available or if the object could not be created.

    - #### getConfiguration

          public FilterConfiguration getConfiguration(java.lang.String configId)

      Description copied from interface: `IFilterConfigurationMapper`
      Gets the FilterConfiguration object for a given configuration identifier.
      Specified by:
        `getConfiguration` in interface `IFilterConfigurationMapper`
      Parameters:
        `configId` - the configuration identifier to search for.
      Returns:
        the FilterConfiguration object for the given configuration identifier, or null if a match could not be found.

    - #### getAllConfigurations

          public java.util.Iterator<FilterConfiguration> getAllConfigurations()

      Description copied from interface: `IFilterConfigurationMapper`
      Gets an iterator on all configurations objects for this mapper.
      Specified by:
        `getAllConfigurations` in interface `IFilterConfigurationMapper`
      Returns:
        an iterator on all configurations for this mapper.

    - #### getMimeConfigurations

          public java.util.List<FilterConfiguration> getMimeConfigurations(java.lang.String mimeType)

      Description copied from interface: `IFilterConfigurationMapper`
      Gets a list of all FilterConfiguration objects for a given MIME type.
      Specified by:
        `getMimeConfigurations` in interface `IFilterConfigurationMapper`
      Parameters:
        `mimeType` - mimeType MIME type to search for.
      Returns:
        a list of all FilterConfiguration objects found for the given MIME type (the list may be empty).

    - #### getFilterConfigurations

          public java.util.List<FilterConfiguration> getFilterConfigurations(java.lang.String filterClass)

      Description copied from interface: `IFilterConfigurationMapper`
      Gets a list of all FilterConfiguration objects for a given filter class.
      Specified by:
        `getFilterConfigurations` in interface `IFilterConfigurationMapper`
      Parameters:
        `filterClass` - the class name of the filter to search for.
      Returns:
        a list of all FilterConfiguration objects found for the given filter class name (the list may be empty).

    - #### getDefaultConfiguration

          public FilterConfiguration getDefaultConfiguration(java.lang.String mimeType)

      Description copied from interface: `IFilterConfigurationMapper`
      Gets the first filter configuration for a given MIME type.
      Specified by:
        `getDefaultConfiguration` in interface `IFilterConfigurationMapper`
      Parameters:
        `mimeType` - MIME type to search for.
      Returns:
        the filter configuration for the given MIME type, or null if none is found.

    - #### getDefaultConfigurationFromExtension

          public FilterConfiguration getDefaultConfigurationFromExtension(java.lang.String ext)

      Description copied from interface: `IFilterConfigurationMapper`
      Gets the first filter configuration for a given extension.
      Specified by:
        `getDefaultConfigurationFromExtension` in interface `IFilterConfigurationMapper`
      Parameters:
        `ext` - the extension to search for (must be in the form ".ext" but can be in any case).
      Returns:
        the filter configuration for the given extension, or null if none is found.

    - #### removeConfiguration

          public void removeConfiguration(java.lang.String configId)

      Description copied from interface: `IFilterConfigurationMapper`
      Removes a given configuration from this mapper.
      Specified by:
        `removeConfiguration` in interface `IFilterConfigurationMapper`
      Parameters:
        `configId` - the identifier of the configuration to remove.

    - #### removeConfigurations

          public void removeConfigurations(java.lang.String filterClass)

      Description copied from interface: `IFilterConfigurationMapper`
      Removes all the configurations (predefined and custom) of a given filter from this mapper.
      Specified by:
        `removeConfigurations` in interface `IFilterConfigurationMapper`
      Parameters:
        `filterClass` - the class name of the filter to lookup.

    - #### getCustomParameters

          public IParameters getCustomParameters(FilterConfiguration config)

      Description copied from interface: `IFilterConfigurationMapper`
      Gets the parameters for a given custom filter configuration. This method provides a way for this mapper to implements how it retrieves custom filter parameters.
      Specified by:
        `getCustomParameters` in interface `IFilterConfigurationMapper`
      Parameters:
        `config` - the custom configuration for which the method should return the filter parameters.
      Returns:
        the parameters for the given custom filter configuration, or null if the parameters could not be provided, or if the corresponding filter does not have parameters.
      See Also:
        `IFilterConfigurationMapper.getParameters(FilterConfiguration)`

    - #### getCustomParameters

          public IParameters getCustomParameters(FilterConfiguration config,
                                        IFilter existingFilter)

      Gets the parameters for a given custom filter configuration. This default implementation gets the custom data from a file located in the current directory at the time the method is called.
      Specified by:
        `getCustomParameters` in interface `IFilterConfigurationMapper`
      Parameters:
        `config` - the custom configuration for which the method should return the filter parameters.
        `existingFilter` - optional existing instance of the filter for the given configuration. This argument can be null. If it not null, the provided filter may be used to load the parameters (if it matches the appropriate class). Providing this argument may allow the method to be more efficient by not creating a temporary filter to get an instance of the parameters to load.
      Returns:
        the parameters for the given custom filter configuration, or null if the parameters could not be provided, or if the corresponding filter does not have parameters.

    - #### deleteCustomParameters

          public void deleteCustomParameters(FilterConfiguration config)

      Description copied from interface: `IFilterConfigurationMapper`
      Deletes the parameters of a custom configuration. This method provides a way for this mapper to implements how it permanently delete custom filter parameters. The actual configuration is not removed from this mapper, you must do it by calling `IFilterConfigurationMapper.removeConfiguration(String)`.
      Specified by:
        `deleteCustomParameters` in interface `IFilterConfigurationMapper`
      Parameters:
        `config` - the custom configuration for which to delete the parameters.

    - #### saveCustomParameters

          public void saveCustomParameters(FilterConfiguration config,
                                  IParameters params)

      Description copied from interface: `IFilterConfigurationMapper`
      Saves the parameters of a custom configuration. This method provides a way for this mapper to implements how it stores custom filter parameters.
      Specified by:
        `saveCustomParameters` in interface `IFilterConfigurationMapper`
      Parameters:
        `config` - the custom configuration for which to save the parameters.
        `params` - the parameters to save.

    - #### createCustomConfiguration

          public FilterConfiguration createCustomConfiguration(FilterConfiguration baseConfig)

      Description copied from interface: `IFilterConfigurationMapper`
      Creates a custom configuration object based on a give one. The new configuration is not added to the current list.
      Specified by:
        `createCustomConfiguration` in interface `IFilterConfigurationMapper`
      Parameters:
        `baseConfig` - the base configuration from which to base the new one.
      Returns:
        a new `FilterConfiguration` object set with some default values, or null if the configuration could not be created.

    - #### clearConfigurations

          public void clearConfigurations(boolean customOnly)

      Description copied from interface: `IFilterConfigurationMapper`
      Removes configuration mappings from this mapper.
      Specified by:
        `clearConfigurations` in interface `IFilterConfigurationMapper`
      Parameters:
        `customOnly` - true to clear only the custom configurations, false to clear all the configurations from this mapper.

    - #### getCustomConfigurationsDirectory

          public java.lang.String getCustomConfigurationsDirectory()

      Gets the directory where the custom configuration files are stored.
      Returns:
        the directory where the custom configuration files are stored.

    - #### setCustomConfigurationsDirectory

          public void setCustomConfigurationsDirectory(java.lang.String dir)

      Sets the directory where the custom configuration files are stored. You should call `updateCustomConfigurations()` after this to update the list of the custom configurations in this mapper.
      Parameters:
        `dir` - the new directory where the custom configuration files are stored.

    - #### addCustomConfiguration

          public void addCustomConfiguration(java.lang.String configId,
                                    IParameters parameters)

    - #### addCustomConfiguration

          public void addCustomConfiguration(java.lang.String configId)

    - #### updateCustomConfigurations

          public void updateCustomConfigurations()

      Updates the custom configurations for this mapper. This should be called if the custom configurations directory has changed.

    - #### instantiateFilter

          protected IFilter instantiateFilter(FilterConfiguration config,
                                  IFilter existingFilter)

      Instantiate a filter from a given configuration, trying to re-use an existing one.
      Parameters:
        `config` - the configuration corresponding to the filter to load.
        `existingFilter` - an optional existing filter we can try to reuse.
      Returns:
        the instance of the requested filter, or null if an error occurred.
      Throws:
        `OkapiFilterCreationException` - if the filter could not be instantiated.

    - #### getFiltersInfo

          public java.util.List<FilterInfo> getFiltersInfo()

      Description copied from interface: `IFilterConfigurationMapper`
      Gets a list of information on all filters in this mapper.
      Specified by:
        `getFiltersInfo` in interface `IFilterConfigurationMapper`
      Returns:
        a list of information on all filters in this mapper.