ObjectInputFilter.Config (Java SE 21 & JDK 21)
Description: declaration: module: java.base, package: java.io, interface: ObjectInputFilter, class: Config
Keywords: java.io.ObjectInputFilter.Config class

Module java.base
Package java.io

# Class ObjectInputFilter.Config

java.lang.Object
java.io.ObjectInputFilter.Config

Enclosing interface:
  `ObjectInputFilter`

public static final class ObjectInputFilter.Config extends Object
A utility class to set and get the JVM-wide deserialization filter factory, the static JVM-wide filter, or to create a filter from a pattern string. The static filter factory and the static filter apply to the whole Java runtime, or "JVM-wide", there is only one of each. For a complete description of the function and use refer to `ObjectInputFilter`.

The JVM-wide deserialization filter factory and the static JVM-wide filter can be configured from system properties during the initialization of the `ObjectInputFilter.Config` class.

If the Java virtual machine is started with the system property `jdk.serialFilter`, its value is used to configure the filter. If the system property is not defined, and the `Security` property `jdk.serialFilter` is defined then it is used to configure the filter. The filter is created as if `createFilter` is called, if the filter string is invalid the initialization fails and subsequent attempts to get the filter, set a filter, or create an ObjectInputStream throw `IllegalStateException`. Deserialization is not possible with an invalid serial filter. If the system property `jdk.serialFilter` or the `Security` property `jdk.serialFilter` is not set the filter can be set with `Config.setSerialFilter`. Setting the `jdk.serialFilter` with `System.setProperty` does not set the filter. The syntax for the property value is the same as for the `createFilter` method.

If the Java virtual machine is started with the system property `jdk.serialFilterFactory` or the `Security` property of the same name, its value names the class to configure the JVM-wide deserialization filter factory. If the system property is not defined, and the `Security` property `jdk.serialFilterFactory` is defined then it is used to configure the filter factory. If it remains unset, the filter factory is a builtin filter factory compatible with previous versions.

The class must be public, must have a public zero-argument constructor, implement the `BinaryOperator<ObjectInputFilter>` interface, provide its implementation and be accessible via the application class loader. If the filter factory constructor is not invoked successfully subsequent attempts to get the factory, set the factory, or create an `ObjectInputStream` throw `IllegalStateException`. Deserialization is not possible with an invalid serial filter factory. The filter factory configured using the system or security property during initialization can NOT be replaced with `Config.setSerialFilterFactory`. This ensures that a filter factory set on the command line is not overridden accidentally or intentionally by the application.

Setting the `jdk.serialFilterFactory` with `System.setProperty` does not set the filter factory. The syntax for the system property value and security property value is the fully qualified class name of the deserialization filter factory.

Since:
  9

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static ObjectInputFilter`
  `createFilter(String pattern)`
  Returns an ObjectInputFilter from a string of patterns.
  `static ObjectInputFilter`
  `getSerialFilter()`
  Returns the static JVM-wide deserialization filter or `null` if not configured.
  `static BinaryOperator<ObjectInputFilter>`
  `getSerialFilterFactory()`
  Returns the JVM-wide deserialization filter factory.
  `static void`
  `setSerialFilter(ObjectInputFilter filter)`
  Set the static JVM-wide filter if it has not already been configured or set.
  `static void`
  `setSerialFilterFactory(BinaryOperator<ObjectInputFilter> filterFactory)`
  Set the JVM-wide deserialization filter factory.

  ### Methods declared in class java.lang.Object

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

- ## Method Details

  - ### getSerialFilter

    public static ObjectInputFilter getSerialFilter()
    Returns the static JVM-wide deserialization filter or `null` if not configured.
    Returns:
      the static JVM-wide deserialization filter or `null` if not configured
    Throws:
      `IllegalStateException` - if the initialization of the filter from the system property `jdk.serialFilter` or the security property `jdk.serialFilter` fails.

  - ### setSerialFilter

    public static void setSerialFilter(ObjectInputFilter filter)
    Set the static JVM-wide filter if it has not already been configured or set.
    Parameters:
      `filter` - the deserialization filter to set as the JVM-wide filter; not null
    Throws:
      `SecurityException` - if there is security manager and the `SerializablePermission("serialFilter")` is not granted
      `IllegalStateException` - if the filter has already been set or the initialization of the filter from the system property `jdk.serialFilter` or the security property `jdk.serialFilter` fails.

  - ### getSerialFilterFactory

    public static BinaryOperator<ObjectInputFilter> getSerialFilterFactory()
    Returns the JVM-wide deserialization filter factory. If the filter factory has been set it is returned, otherwise, a builtin deserialization filter factory is returned. The filter factory provides a filter for every ObjectInputStream when invoked from ObjectInputStream constructors and when a stream-specific filter is set with `setObjectInputFilter`.
    Implementation Requirements:
      The builtin deserialization filter factory provides the static JVM-wide filter when invoked from ObjectInputStream constructors. When invoked `to set the stream-specific filter` the requested filter replaces the static JVM-wide filter, unless it has already been set. The builtin deserialization filter factory implements the behavior of earlier versions of setting the initial filter in the `ObjectInputStream` constructor and `ObjectInputStream.setObjectInputFilter(java.io.ObjectInputFilter)`.
    Returns:
      the JVM-wide deserialization filter factory; non-null
    Throws:
      `IllegalStateException` - if the filter factory initialization is incomplete
    Since:
      17

  - ### setSerialFilterFactory

    public static void setSerialFilterFactory(BinaryOperator<ObjectInputFilter> filterFactory)
    Set the JVM-wide deserialization filter factory. The filter factory can be configured exactly once with one of: setting the `jdk.serialFilterFactory` property on the command line, setting the `jdk.serialFilterFactory` property in the `Security` file, or using this `setSerialFilterFactory` method. The filter factory can be set only before any `ObjectInputStream` has been created to avoid any inconsistency in which filter factory is being used.

    The JVM-wide filter factory is invoked when an ObjectInputStream is constructed and when the stream-specific filter is set. The parameters are the current filter and a requested filter and it returns the filter to be used for the stream. If the current filter is `non-null`, the filter factory must return a `non-null` filter; this is to prevent unintentional disabling of filtering after it has been enabled. The factory determines the filter to be used for `ObjectInputStream` streams based on its inputs, any other filters, context, or state that is available. The factory may throw runtime exceptions to signal incorrect use or invalid parameters. See the filter models for examples of composition and delegation.

    Parameters:
      `filterFactory` - the deserialization filter factory to set as the JVM-wide filter factory; not null
    Throws:
      `IllegalStateException` - if the builtin deserialization filter factory has already been replaced or any instance of `ObjectInputStream` has been created.
      `SecurityException` - if there is security manager and the `SerializablePermission("serialFilter")` is not granted
    Since:
      17

  - ### createFilter

    public static ObjectInputFilter createFilter(String pattern)
    Returns an ObjectInputFilter from a string of patterns.

    Patterns are separated by ";" (semicolon). Whitespace is significant and is considered part of the pattern. If a pattern includes an equals assignment, "`=`" it sets a limit. If a limit appears more than once the last value is used.

    - maxdepth=`value` - the maximum depth of a graph
    - maxrefs=`value` - the maximum number of internal references
    - maxbytes=`value` - the maximum number of bytes in the input stream
    - maxarray=`value` - the maximum array length allowed

    Other patterns match or reject class or package name as returned from `Class.getName()` and if an optional module name is present `class.getModule().getName()`. Note that for arrays the element type is used in the pattern, not the array type.

    - If the pattern starts with "!", the class is rejected if the remaining pattern is matched; otherwise the class is allowed if the pattern matches.
    - If the pattern contains "/", the non-empty prefix up to the "/" is the module name; if the module name matches the module name of the class then the remaining pattern is matched with the class name. If there is no "/", the module name is not compared.
    - If the pattern ends with ".**" it matches any class in the package and all subpackages.
    - If the pattern ends with ".*" it matches any class in the package.
    - If the pattern ends with "*", it matches any class with the pattern as a prefix.
    - If the pattern is equal to the class name, it matches.
    - Otherwise, the pattern is not matched.

    The resulting filter performs the limit checks and then tries to match the class, if any. If any of the limits are exceeded, the filter returns `Status.REJECTED`. If the class is an array type, the class to be matched is the element type. Arrays of any number of dimensions are treated the same as the element type. For example, a pattern of "`!example.Foo`", rejects creation of any instance or array of `example.Foo`. The first pattern that matches, working from left to right, determines the `Status.ALLOWED` or `Status.REJECTED` result. If the limits are not exceeded and no pattern matches the class, the result is `Status.UNDECIDED`.

    Parameters:
      `pattern` - the pattern string to parse; not null
    Returns:
      a filter to check a class being deserialized; `null` if no patterns
    Throws:
      `IllegalArgumentException` - if the pattern string is illegal or malformed and cannot be parsed. In particular, if any of the following is true:
      - if a limit is missing the name or the name is not one of "maxdepth", "maxrefs", "maxbytes", or "maxarray"
      - if the value of the limit can not be parsed by `Long.parseLong` or is negative
      - if the pattern contains "/" and the module name is missing or the remaining pattern is empty
      - if the package is missing for ".*" and ".**"