Creating Pattern-Based Filters

Pattern-based filters are filters that you define without changing your application code. You add JVM-wide filters in properties files or application-specific filters on the java command line.

A pattern-based filter is a sequence of patterns. Each pattern is matched against the name of a class in the stream or a resource limit. Class-based and resource limit patterns can be combined in one filter string, with each pattern separated by a semicolon (;).

Pattern-based Filter Syntax

When you create a filter that is composed of patterns, use the following guidelines:

Separate patterns by semicolons. For example:
```
pattern1.*;pattern2.*
```
White space is significant and is considered part of the pattern.
Put the limits first in the string. They are evaluated first regardless of where they are in the string, so putting them first reinforces the ordering. Otherwise, patterns are evaluated from left to right.
A class name that matches a pattern that is preceded by ! is rejected. A class name that matches a pattern without ! is allowed. The following filter rejects pattern1.MyClass but allows pattern2.MyClass:
```
!pattern1.*;pattern2.*
```
Use the wildcard symbol (*) to represent unspecified class names in a pattern as shown in the following examples:
- To match every class name, use *
- To match every class name in mypackage, use mypackage.*
- To match every class name in mypackage and its subpackages, use mypackage.**
- To match every class name that starts with text, use text*

If a class name doesn’t match any filter, then it is allowed. If you want to allow only certain class names, then your filter must reject everything that doesn’t match. To reject all class names other than those specified, include !* as the last pattern in a class filter.

For a complete description of the syntax for the patterns, see JEP 290.

Pattern-Based Filter Limitations

The following are some of the limitations of pattern-based filters:

Patterns can’t allow different sizes of arrays based on the class name.
Patterns can’t match classes based on the supertype or interfaces of the class name.
Patterns have no state and can’t make choices depending on the class instances deserialized earlier in the stream.

Note:

A pattern-based filter doesn't check interfaces that are implemented by classes being deserialized. The filter is invoked for interfaces explicitly referenced in the stream; it isn't invoked for interfaces implemented by classes for objects being deserialized.

Define a Pattern-Based Filter for One Application

You can define a pattern-based filter as a system property for one application. A system property supersedes a Security Property value.

To create a filter that only applies to one application, and only to a single invocation of Java, define the jdk.serialFilter system property in the command line.

The following example shows how to limit resource usage for an individual application:

java -Djdk.serialFilter=maxarray=100000;maxdepth=20;maxrefs=500 com.example.test.Application

Define a Pattern-Based Filter for All Applications

You can define a pattern-based, JVM-wide filter that affects every application run with a Java runtime from $JAVA_HOME by specifying it as a Security Property. (Note that a system property supersedes a Security Property value.) Edit the file $JAVA_HOME/conf/security/java.security and add the pattern-based filter to the jdk.serialFilter Security Property.

Define a Class Filter

You can create a pattern-based class filter that is applied globally. For example, the pattern might be a class name or a package with wildcard.

In the following example, the filter rejects one class name from a package (!example.somepackage.SomeClass), and allows all other class names in the package:

jdk.serialFilter=!example.somepackage.SomeClass;example.somepackage.*;

The previous example filter allows all other class names, not just those in example.somepackage.*. To reject all other class names, add !*:

jdk.serialFilter=!example.somepackage.SomeClass;example.somepackage.*;!*

Define a Resource Limit Filter

A resource filter limits graph complexity and size. You can create filters for the following parameters to control the resource usage for each application:

Maximum allowed array size. For example: maxarray=100000;
Maximum depth of a graph. For example: maxdepth=20;
Maximum references in a graph between objects. For example: maxrefs=500;
Maximum number of bytes in a stream. For example: maxbytes=500000;