Exclude Methods from Build Scan

The custom methods exclude filter allows ignoring of specific methods during the build scan and extends the functionality offered by the filter parameters used by the Sealights build scanner, like files excluded filesexcluded and packages excluded packagesexcluded. 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.

• Methods can be excluded according to custom patterns. A pattern may include a method name or even a method signature.

Applying the Custom Filter to the Scan command

Build Scanner CLI

A custom filter file should be provided as an additional input argument to the scan command of the Java Agent

java -jar sl-build-scanner.jar -scan -tokenfile /path/to/sltoken.txt -buildsessionidfile buildSessionId.txt -workspacepath "/path/to/war/files" -fi "*.war" -customFilterFile /path/to/customfilter.json

The custom filter may also be passed as a sl.customFilterFile system property and if if both values are provided, the argument value overrides the system property

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

Sealights plugins configuration

A custom filter file may be provided as a system property sl.customFilterFile inside the sealightsJvmParams section in the JSON file for the Maven or Gradle plugins. Here is a relevant JSON file fragment example:

"sealightsJvmParams": {
    "sl.customFilterFile": "config/CustomFilter.json"
}

• This parameter is only relevant to an executionType that executes the scanner like full, or scanonly. It does not apply to testonly.

• You can declare this system property into a buildScannerParams section rather than the generic sealightsJvmParams. This way it will not be passed to java commands other than the build scanner during the Maven execution.

Custom Filter Sample file

{
  "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.*"
      ]
    }
  ]
}

Ignore Rules Syntax

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.

Regular Expression are following the Java Regex Standard Notation.

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 exclusion 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()