net.sf.okapi.common.filters

## Interface IFilterConfigurationMapper

- All Superinterfaces:
    IParametersEditorMapper
  All Known Implementing Classes:
    FilterConfigurationMapper

      public interface IFilterConfigurationMapper
      extends IParametersEditorMapper

  Common set of methods to manage filter configurations.

  This interface allows you to add and remove filter configurations from a central place. You can instantiate the filter corresponding to a given configuration, as well as manipulate its parameters.

  Classes that implements this interface should consider overriding the methods related to custom configurations to provide application-specific storage mechanism and naming convention. The methods related to custom configurations are, for example: `createCustomConfiguration(FilterConfiguration)`, `deleteCustomParameters(FilterConfiguration)`, `getCustomParameters(FilterConfiguration)`, `getCustomParameters(FilterConfiguration, IFilter)`, and `saveCustomParameters(FilterConfiguration, IParameters)`.

- - ### 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` | `addEditor(java.lang.String editorClass, java.lang.String parametersClass)` Adds a new editor mapping to this mapper.
    `void` | `clearConfigurations(boolean customOnly)` Removes configuration mappings from this mapper.
    `void` | `clearEditors()` Removes all editor mappings for 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.
    `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).
    `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` | `removeEditor(java.lang.String editorClass)` Removes a given editor from this mapper.
    `void` | `saveCustomParameters(FilterConfiguration config, IParameters params)` Saves the parameters of a custom configuration.

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

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

- - ### Method Detail

    - #### addConfiguration

          void addConfiguration(FilterConfiguration config)

      Adds a new configuration to this mapper.
      Parameters:
        `config` - the configuration to add.

    - #### removeConfiguration

          void removeConfiguration(java.lang.String configId)

      Removes a given configuration from this mapper.
      Parameters:
        `configId` - the identifier of the configuration to remove.

    - #### addConfigurations

          void addConfigurations(java.lang.String filterClass)

      Adds all the predefined configurations of a given filter to this mapper.
      Parameters:
        `filterClass` - the class name of the filter to lookup.

    - #### removeConfigurations

          void removeConfigurations(java.lang.String filterClass)

      Removes all the configurations (predefined and custom) of a given filter from this mapper.
      Parameters:
        `filterClass` - the class name of the filter to lookup.

    - #### clearConfigurations

          void clearConfigurations(boolean customOnly)

      Removes configuration mappings from this mapper.
      Parameters:
        `customOnly` - true to clear only the custom configurations, false to clear all the configurations from this mapper.

    - #### addEditor

          void addEditor(java.lang.String editorClass,
                       java.lang.String parametersClass)

      Adds a new editor mapping to this mapper.
      Specified by:
        `addEditor` in interface `IParametersEditorMapper`
      Parameters:
        `editorClass` - the class name of the editor to add.
        `parametersClass` - the class name of the parameters this editor can edit.

    - #### removeEditor

          void removeEditor(java.lang.String editorClass)

      Removes a given editor from this mapper.
      Specified by:
        `removeEditor` in interface `IParametersEditorMapper`
      Parameters:
        `editorClass` - the class name of the editor to remove.

    - #### clearEditors

          void clearEditors()

      Removes all editor mappings for this mapper.
      Specified by:
        `clearEditors` in interface `IParametersEditorMapper`

    - #### createFilter

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

      Creates an instance of the filter for a given configuration identifier and loads its corresponding parameters.
      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.
      Throws:
        `OkapiFilterCreationException` - if the filter could not be created.

    - #### createFilter

          IFilter createFilter(java.lang.String configId)

      Creates an instance of the filter for a given configuration identifier and loads its corresponding parameters.
      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.
      Throws:
        `OkapiFilterCreationException` - if the filter could not be created.

    - #### createConfigurationEditor

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

      Creates an instance of the filter's parameters editor for a given configuration identifier.
      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.
      Throws:
        `OkapiFilterCreationException` - if a filter needed to be created and could not.
        `OkapiEditorCreationException` - if the editor could not be created.

    - #### createConfigurationEditor

          IParametersEditor createConfigurationEditor(java.lang.String configId)

      Creates an instance of the filter's parameters editor for a given configuration identifier.
      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.
      Throws:
        `OkapiFilterCreationException` - if a filter needed to be created and could not.
        `OkapiEditorCreationException` - if the editor could not be created.

    - #### getConfiguration

          FilterConfiguration getConfiguration(java.lang.String configId)

      Gets the FilterConfiguration object for a given configuration identifier.
      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.

    - #### getDefaultConfiguration

          FilterConfiguration getDefaultConfiguration(java.lang.String mimeType)

      Gets the first filter configuration for a given MIME type.
      Parameters:
        `mimeType` - MIME type to search for.
      Returns:
        the filter configuration for the given MIME type, or null if none is found.

    - #### getDefaultConfigurationFromExtension

          FilterConfiguration getDefaultConfigurationFromExtension(java.lang.String ext)

      Gets the first filter configuration for a given extension.
      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.

    - #### getFiltersInfo

          java.util.List<FilterInfo> getFiltersInfo()

      Gets a list of information on all filters in this mapper.
      Returns:
        a list of information on all filters in this mapper.

    - #### getAllConfigurations

          java.util.Iterator<FilterConfiguration> getAllConfigurations()

      Gets an iterator on all configurations objects for this mapper.
      Returns:
        an iterator on all configurations for this mapper.

    - #### getMimeConfigurations

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

      Gets a list of all FilterConfiguration objects for a given MIME type.
      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

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

      Gets a list of all FilterConfiguration objects for a given filter class.
      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).

    - #### getParameters

          IParameters getParameters(FilterConfiguration config)

      Gets the parameters for a given configuration (predefined or custom).
      Parameters:
        `config` - the configuration for which the parameters are requested.
      Returns:
        the parameters object for the given configuration.
      See Also:
        `getCustomParameters(FilterConfiguration)`

    - #### getParameters

          IParameters getParameters(FilterConfiguration config,
                                  IFilter existingFilter)

      Gets the parameters for a given configuration (predefined or custom).
      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.

    - #### createCustomConfiguration

          FilterConfiguration createCustomConfiguration(FilterConfiguration baseConfig)

      Creates a custom configuration object based on a give one. The new configuration is not added to the current list.
      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.

    - #### getCustomParameters

          IParameters getCustomParameters(FilterConfiguration config,
                                        IFilter existingFilter)

      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.
      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.
      Throws:
        `OkapiFilterCreationException` - if the filter of the given configuration could not be created to load the parameters.

    - #### getCustomParameters

          IParameters getCustomParameters(FilterConfiguration config)

      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.
      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.
      Throws:
        `OkapiFilterCreationException` - if the filter of the given configuration could not be created to load the parameters.
      See Also:
        `getParameters(FilterConfiguration)`

    - #### saveCustomParameters

          void saveCustomParameters(FilterConfiguration config,
                                  IParameters params)

      Saves the parameters of a custom configuration. This method provides a way for this mapper to implements how it stores custom filter parameters.
      Parameters:
        `config` - the custom configuration for which to save the parameters.
        `params` - the parameters to save.

    - #### deleteCustomParameters

          void deleteCustomParameters(FilterConfiguration config)

      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 `removeConfiguration(String)`.
      Parameters:
        `config` - the custom configuration for which to delete the parameters.