# 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 <a href="#applying-the-custom-filter-to-the-scan-command" id="applying-the-custom-filter-to-the-scan-command"></a>

### Build Scanner CLI <a href="#build-scanner-cli" id="build-scanner-cli"></a>

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

{% code overflow="wrap" lineNumbers="true" %}

```sh
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
```

{% endcode %}

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

{% hint style="info" %}
For build scanner command and parameter usage refer to [SeaLights Java agent - Command Reference](https://sealights.atlassian.net/wiki/spaces/SUP/pages/1933323).
{% endhint %}

### Sealights plugins configuration <a href="#sealights-plugins-configuration" id="sealights-plugins-configuration"></a>

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:

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

{% hint style="info" %}

* 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.
  {% endhint %}

## Custom Filter Sample file <a href="#custom-filter-sample-file" id="custom-filter-sample-file"></a>

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

## Ignore Rules Syntax <a href="#ignore-rules-syntax" id="ignore-rules-syntax"></a>

The rules group may include the following properties set according to [#filter-patterns-notation](#filter-patterns-notation "mention"):

* **classNames** - a list of comma-separated class-names patterns according to [#class-name-pattern-notation](#class-name-pattern-notation "mention"). 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](#exact-method-signature-notation "mention"), that should be excluded
* **excludesRegex** - a list of method signatures regex patterns according to [#method-signature-regex-pattern-notation](#method-signature-regex-pattern-notation "mention") that should be excluded.
* **includesExact** - a comma-separated list of method signatures according to [#exact-method-signature-notation](#exact-method-signature-notation "mention") that **should not be** excluded.&#x20;
* **includesRegex** - a list of method signatures regex patterns according to [#method-signature-regex-pattern-notation](#method-signature-regex-pattern-notation "mention") that **should not be** excluded.

{% hint style="info" %}
Regular Expression are following the Java Regex Standard Notation.
{% endhint %}

### Filter patterns notation <a href="#filter-patterns-notation" id="filter-patterns-notation"></a>

#### Class name pattern notation <a href="#class-name-pattern-notation" id="class-name-pattern-notation"></a>

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:

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

#### Exact method signature notation <a href="#exact-method-signature-notation" id="exact-method-signature-notation"></a>

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:

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

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

#### Method signature regex pattern notation <a href="#method-signature-regex-pattern-notation" id="method-signature-regex-pattern-notation"></a>

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:

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

## Filter handling <a href="#filter-handling" id="filter-handling"></a>

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

{% hint style="warning" %}
If the same pattern appears in includes and excludes, the **include rule always overwrites the exclusion** and the appropriate method will not be excluded.
{% endhint %}

Example:

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

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