Package io.kroxylicious.proxy.filter

Interface FilterFactory<C,I>

Type Parameters:
C - the type of configuration used to create the Filter. Use Void if the Filter is not configurable.
I - The type of the initialization data
public interface FilterFactory<C,I>

A pluggable source of Filter instances.

FilterFactories are:

  • service implementations provided by filter authors
  • called by the proxy runtime to create filter instances

Lifecycle scope

FilterFactory instances are scoped per virtual cluster: each virtual cluster that references a filter definition gets its own FilterFactory instance with its own initialize/close pair. The same filter type used by two virtual clusters produces two independent instances with independent initialization data — there is no cross-virtual-cluster sharing. Within a single virtual cluster, a filter definition referenced multiple times in the chain (e.g. an audit filter applied before and after a transformation) is initialized once and its initialization data is shared across all positions in that virtual cluster's chain.

Per virtual cluster, the proxy runtime guarantees that:

  1. instances will be initialized before any attempt to create filter instances,
  2. instances will eventually be close(Object) closed} if and only if they were successfully initialized,
  3. no attempts to create filter instances will be made once a FilterFactory instance is closed,
  4. initialize and close are never invoked on a Netty event loop thread — blocking work (e.g. closing an HTTP/KMS client) is safe in either method.

Filter instance creation can happen on a different thread than initialization or cleanup. It is suggested to pass state using via the return value from createFilter(FilterFactoryContext, Object) rather than relying on synchronization within a filter factory implementation.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close(I initializationData)
    Called by the runtime to release any resources associated with the given initializationData.
    Filter
    createFilter(FilterFactoryContext context, I initializationData)
    Creates an instance of the Filter.
    I
    initialize(FilterFactoryContext context, C config)
    Initializes the factory with the specified configuration.

  • Method Details

    • initialize

      @UnknownNullness I initialize(FilterFactoryContext context, @UnknownNullness C config) throws PluginConfigurationException

      Initializes the factory with the specified configuration.

      This method is guaranteed to be called at most once per virtual cluster for each filter definition referenced by that virtual cluster, and before any call to createFilter(FilterFactoryContext, Object) on that virtual cluster. Note that because FilterFactory instances are per-virtual-cluster (see the class javadoc), the same filter type used by multiple virtual clusters will see one initialize call per virtual cluster — each on a different FilterFactory instance with its own initialization data.

      This method may provide extra semantic validation of the config, and returns some object (which may be the config, or some other object) which will be passed to createFilter(FilterFactoryContext, Object).

      Parameters:
      context - context
      config - configuration
      Returns:
      A configuration state object, specific to the given config, which will be passed to the other methods of this interface.
      Throws:
      PluginConfigurationException - when the configuration is invalid

    • createFilter

      Filter createFilter(FilterFactoryContext context, @UnknownNullness I initializationData)
      Creates an instance of the Filter.

      This can be called on a different thread from initialize(FilterFactoryContext, Object) and close(I). Implementors should either use the initializationData to pass state from initialize(FilterFactoryContext, Object) or use appropriate synchronization.

      Parameters:
      context - The runtime context for the filter's creation.
      initializationData - The initialization data that was returned from initialize(FilterFactoryContext, Object).
      Returns:
      the Filter instance.

    • close

      default void close(@UnknownNullness I initializationData)
      Called by the runtime to release any resources associated with the given initializationData. This is guaranteed to eventually be called for each successful call to initialize(FilterFactoryContext, Object). Once this method has been called createFilter(FilterFactoryContext, Object) won't be called again.
      Parameters:
      initializationData - The initialization data that was returned from initialize(FilterFactoryContext, Object).