Overview

The custom methods exclude filter allows ignoring of specific methods during the build scan and extends the functionality offered by the files excluded filesexcluded and packages excluded packagesexcluded filter parameters as used by the Sealights build scanner.

Methods can be excluded according to custom patterns. The custom methods filter is applied after the files filter.

A pattern may include a method name or even a method signature.

For build scanner command and parameter usage refer to SeaLights Java agent - Command Reference.

Method Ignore rules and syntax

The customer filter will be provided as an external file in JSON format (see the example below). 

The filter contains a list of rules, grouped by associated class names. 

The rules group may include the following properties set according to Filter patterns notation:

• classNames - a list of comma-separated class-names patterns according to Class name pattern notation. If the property is omitted or empty, the rules will be applied to any class.

• excludesExact - a comma-separated list of method signatures according to Exact method signature notation, that should be excluded

• excludesRegex - a list of method signatures regex patterns according to Method signature regex pattern notation that should be excluded.

• includesExact - a comma-separated list of method signatures according to Exact method signature notation that should not be excluded. 

• includesRegex - a list of method signatures regex patterns according to Method signature regex pattern notation that should not be excluded.

Filter patterns notation

Class name pattern notation

1. May be an exact value or a regular expression

2. A sign '$' in the nested class pattern will not be handled as a regex special character, but as a part of the name

3. A pattern should not contain a file extension

Example:

Apply for class MyClass and any nested class of MyClass:

"classNames": [".*MyClass", ".*MyClass$.*"]

Exact method signature notation

An exact method signature should include the following verbs separated by single space: method access, return type, method name and parameter types in brackets.

Examples:

public static Map groupById(List)
void calculate(int, boolean, List)
private String asString()

The exact method signature is used as is for full equity.

Method signature regex pattern notation

The method signature regex should be defined according to Java regex notation, but the method arguments enclosing parentheses will not be handled as a regex special character.

Examples:

public .* get[A-Z]*()
*calculate(int, boolean, List)
* run(.*)

Filter handling

1. The custom methods filter is applied after the files filter: it is applied to files and packages that were included.

2. Include rules are intended to add “exceptions” to exclude rules and are checked first. If a particular method matches any include rule, it will not be excluded

If the same pattern appears in includes and excludes, the include rule always overwrites the exclude and the appropriate method will not be excluded.

Example:

"includesRegex": [
       "protected void create_.*(boolean, String, int)",
       "protected void create_.*()",
    ],
"excludesRegex": [
       ".*create_.*",
       "public .* validate[A-Z]*()"
     ]

The pattern with method name create_.*  appears in both excludesRegex and includeRegex. The filter will work as following:

• Methods with signatures matching to the include patterns will be included, for example:

  • protected void create_table()

  • protected void create_table(boolean, String, int)

  • protected void create_list()

• Any other method with the name prefix  create_.* and signature, not matching to the inclusion, will be excluded, for example:

  • public void create_table()

  • protected void create_table(boolean)

  • protected List create_list()

Full file example

{
  "rules": [
    {
      "comments": "Any method of class of HashedMethodData and nested classes should be excluded",
      "classNames": [".*MethodData", ".*MethodData$.*"],
      "excludesRegex": [
        ".*"
      ]
    },
    {
      "classNames": [".*tests.samples.CustomExcludeSample.*"],
      "includesRegex": [
        "public.*foo()"
      ],
      "excludesRegex": [
        "public .* get[A-Z]*()",
        ".*foo.*(int, boolean)"
      ]
    },
    {
      "classNames": [".*GroupingCollectors"],
      "excludesExact": [
        "public static Map groupById(List)"
      ],
      "excludesRegex": [
        ".*lambda.*"
      ]
    }
  ]
}

Custom filter settings

Build Scanner CLI

A custom filter file may be provided to the build scanner CLI -scan command:

• as an input argument of the scan mode -customFilterFile <path/to/filter.json>

• as a system property sl.customFilterFile

• if both values are provided, the argument value overrides the system property

Sealights plugins configuration

A custom filter file may be provided as a system property sl.customFilterFile inside sealightsJvmParams section.

The pom file fragment example:

<sealightsJvmParams>
      <sl.customFilterFile>config/CustomFilter.json</sl.customFilterFile>
</sealightsJvmParams>