# Java Plugin Configuration Parameters

This document contains list of parameters available in JSON configuration file which can be used during Sealights integration with maven or gradle built java (or/and kotlin, groovy, scala) projects.

Example, minimal configuration 

```json5
{
  "executionType": "full",
  "createBuildSessionId": true,
  "tokenFile": "./sealights/token.txt",
  "appName": "my-service",
  "branchName": "main",
  "buildName": "build-123",
  "packagesIncluded": "*com.example*"
}
```

## Description of parameters

### Execution Mode

* `executionType`: Controls which components run
  * `full`: Scanner + Test Listener
  * `testsonly`: Test Listener only
  * `scanonly`: Scanner only.

### Basic properties

Set token with a `token` or `tokenFile` with a path to file containing the token obtained from the SeaLights dashboard

* `token`: SeaLights token.
* `tokenFile`: Path to a file containing the SeaLights token.
* `runFunctionalTests`: If set to true informs that project contains functional tests and its sources should not by scanned by scanner
* `isEnabled`: Enable/disable the plugin. Default: true
* `pluginVersion`: Plugin version to use. Usually managed by plugin; set manually if you want to ignore the recommendations for newest version and use pre-downloaded plugin from your repository

### Application and build info

* `appName`: Application name as shown on the dashboard.
* `branchName`: Branch name as shown on the dashboard.
* `buildName`: Build name as shown on the dashboard.

### Build session ID management

When you already have a Build Session ID set by buildSessionId or buildSessionIdFile:

* `buildSessionId`: Use an existing Build Session ID.
* `buildSessionIdFile`: Path to a file containing the existing Build Session ID.
* `createBuildSessionId`: Set to false.

When you want the plugin to create a Build Session ID:

* `createBuildSessionId`: Set to `true`.
* Also provide: `appName`, `branchName`, `buildName`, `packagesIncluded`
* Optional property: `packagesExcluded`.

Pull request build Session ID:

* `createPRBuildSessionId`: Set to `true`.
* `appName`: Application name.
* `branchName`: (optional) Branch name as shown on the dashboard.
* `buildName`: (optional) Build name as shown on the dashboard.
* `targetBranch`: PR target branch (must already be reported to SeaLights).
* `pullRequestNumber`: PR number in source control.
* `latestCommit`: Full SHA of the last PR commit.
* `repositoryUrl`: Repository URL up to the segment before the PR number.
* Optional scope filters: `packagesIncluded`, `packagesExcluded`.

### Scan scope and inputs

* `filesIncluded`: Binary files to scan. Default: `*.class`. Confirm default for non-Maven builds.
* `filesExcluded`: Binary files to exclude. Default: `*test-classes*`. Confirm pattern semantics.
* `packagesIncluded`: Comma-separated packages to include. Use `.*` to include subpackages, e.g., com.example.\*.
* `packagesExcluded`: Comma-separated packages to exclude. Use `.*` for subpackages.
* `classLoadersExcluded`: Class loaders to exclude from scan. Format and typical values.
* `workspacepath`: Path to compiled binaries. Default (Maven): `${project.build.outputDirectory}`. Change only if necessary. Gradle default?
* `recursive`: Recursively scan subdirectories of workspacepath. Default: true.
* Build files discovery (alternative to workspacepath):
  * `buildFilesFolders`: Folders to search for build artifacts.
  * `buildFilesPatterns`: Filename patterns to include.
  * `recursiveOnBuildFilesFolders`: Recurse into folders when discovering artifacts.

### Test configuration

* `testStage`: Name of test stage as shown on the dashboard
* `labId`: Unique ID for tests and tested application binding
* `testProjectId`: Test project identifier which allows to distinguish two test stages with the same name for example "Regression Tests" triggered by two different teams on the same environment
* `targetTestProjectId`: Target test project identifier for PR builds
* `testTasksAndStages`: (not relevant for maven) Mapping between test tasks and SL stages (e.g., Gradle task → stage). The example:

  ```
  "testTasksAndStages": {
    "test":"Unit Tests",
    "junitPlatformTest":"Unit Tests",
    "integrationTest":"Integration Tests"
  },
  ```
* `listenerConfigFile`: Path to test listener JSON config. See separate Test Listener config documentation.

### Metadata (CI/CD)

* `metadata`: Free-form key-value map with CI data.
  * Common keys:
    * `jobName`: Build job name (e.g., `${JOB_NAME}`).
    * `logsUrl`: Link to build logs (e.g., `${BUILD_URL}/console`).

### Agent Distribution and Overrides

The plugin downloads recommended agents at start. To pre-download and provide explicit paths:

* `scannerJar`: Path to scanner JAR, e.g., `./sl-build-scanner.jar`.
* `listenerJar`: Path to listener JAR, e.g., `./sl-test-listener.jar`.

Overrides:

* `overrideTestListenerPath`: Override the test listener executable/path. Expected type and usage.
* `overrideMetaJsonPath`: Provide a path to override metadata JSON. Expected schema.

### JVM and process parameters

* `sealightsJvmParams`: JVM params for the SeaLights agent; expected JSON map, e.g., `{"key":"value"}`.
* `buildScannerParams`: Additional params for the build scanner. Format (map vs list).
* `testListenerJvmParams`: JVM params for the test listener process. Provide example.
* `javaAgentExtraJvmParams`: Extra JVM args to attach to the process starting with Java agent. This parameter currently applies only to JVM configuration within Gradle plugin integration.
* Maven-specific convenience (if using Maven Surefire/Failsafe):
  * `surefireArgLine`, `failsafeArgLine`: Extra JVM args injected into Surefire/Failsafe.

### Logging and diagnostics

* `logEnabled`: Enable SeaLights logging.
* `logLevel`: Log level (e.g., INFO, DEBUG).
* `logDestination`: Where to send logs: set one of two available values:
  * `console`
  * `file`
* `logFolder`: Folder for log files.
* `logToFile`: Write logs to file.
* `logToConsole`: Write logs to console.
* `logPluginMinimal`: Minimize plugin-side logs. Exact effect and scope.

Resources embedding

* `includeResources`: Include `sltoken.txt` and `buildSessionId.txt` files in build resources (default is `true`).
* `includeTokenResource`: If includeResources is true, exclude token file when set to false (default is `true`).
* `includeConfigLambdaResource`: When set to true plugin will create sealights-configuration.json file and pack it into created artifact. When you deploy your AWS Lambda Function artifact, it will be unpacked and this file will be automatically pick-up-ed by sl-test-listener (if Sealights Lambda layer will be configured for AWS Lambda function)
* `collectorUrl`: Collector endpoint URL. Use when you want embedd `collectorUrl` into AWS config json created when `includeConfigLambdaResource` is set to true

### Networking and proxy

* `proxy`: Proxy configuration. Structure (URL string vs object with host/port/user/pass).

### Gradle-specific Project Configuration

* `repoConfig`: Repository configuration snippet to insert into a repositories block. The value is injected as-is. Use with care.
* `gradleProjectConfig`: Composite Gradle project configuration:
  * `gradleProjectConfig.excludedProjects`: List of project paths to exclude.
  * `gradleProjectConfig.includedProjects`: List of project paths to include.
  * `gradleProjectConfig.useOnlyProjectRepoSection`: Use only the project-level repositories section.
* `useGradleCache`: Set to true if Gradle build cache is used and some of the modules can be used from cache.
* `buildScanTaskName`: Task name to run build scanning. Default per-language.
* `scannerTask`: Scanner task name. Relation to buildScanTaskName.

### Android-specific - relevant only for Sealights-android-gradle-plugin

* `androidProductFlavor`: Product flavor for Android builds. Specify if flavors are defined in project. Only the variant with this flavor will be statically instrumented with Android Test Listener
* `androidBuildType`: Build type for Android builds (e.g., debug, release). Default value: debug. Only the variant with this build type will be statically instrumented with Android Test Listener

### Examples

### Example of execution type "scanonly"

Full example with executionType: `"scanonly"`:

```json
{
  "executionType": "scanonly",
  "tokenFile": "sltoken.txt",
  "createBuildSessionId": true,
  "appName": "${JOB_NAME}",
  "branchName": "${GIT_BRANCH}",
  "buildName": "${BUILD_NUMBER}",
  "packagesIncluded": "*com.example.*,*com.other.package.*",
  "packagesExcluded": "com.example.excluded.*",
  "filesIncluded": "*.class",
  "filesExcluded": "*test-classes*",
  "recursive": true,
  "includeResources": true,
  "logEnabled": true,
  "logDestination": "console",
  "logLevel": "warn",
  "logFolder": "/tmp",
  "sealightsJvmParams": {}
}
```

### Example of execution type "full"

Full example with executionType: `"full"`:

```json
{
  "executionType": "full",
  "tokenFile": "sltoken.txt",
  "createBuildSessionId": true,
  "appName": "${System.getenv('JOB_NAME')}",
  "branchName": "master",
  "buildName": "${System.getenv('BUILD_NUMBER')}",
  "packagesIncluded": "*com.example.*",
  "packagesExcluded": "",
  "filesIncluded": "*.class",
  "filesExcluded": "*test-classes*",
  "recursive": true,
  "includeResources": true,
  "testTasksAndStages": {"test":"Unit Tests", "junitPlatformTest":"Unit Tests", "integrationTest":"Integration Tests"},
  "logEnabled": false,
  "logLevel": "off",
  "gradleProjectConfig": {
    "excludedProjects": ["subProject1", "subProject2"],
    "repoConfig": "mavenLocal()"
  }
}
```

### Example of execution of runFunctionalTests

Full example with `runFunctionalTests`: `true`:

```json
{
  "tokenFile": "./sealights/token.txt",
  "createBuildSessionId": false,
  "labId": "integ_stage_2b5b_bstore",
  "runFunctionalTests": true,
  "testStage": "E2E",
  "logEnabled": true,
  "logLevel": "INFO",
  "logToConsole": true,
  "sealightsJvmParams": {
    "sl.fixSurefireOutput" : true
  }
}
```

### Example of execution of runFunctionalTests

Full example with a PR Build Session:

```json
{
  "isEnabled": true,
  "tokenFile": "./sealights/token.txt",
  "appName": "storefront",
  "executionType": "full",
  "createPRBuildSessionId": true,
  "targetBranch": "main",
  "pullRequestNumber": 42,
  "latestCommit": "9b1fcdf3a0b94f6c8e2b5da3e7d3e8e7b5c1a2d3",
  "repositoryUrl": "https://example.com/org/repo/pull/",
  "packagesIncluded": "com.example.*",
  "packagesExcluded": "com.example.excluded.*",
  "testStage": "integration",
  "metadata": {
    "jobName": "ci/storefront-pr/42",
    "logsUrl": "https://ci.example.com/builds/123/console"
  },
  "logEnabled": true,
  "logLevel": "INFO",
  "logToConsole": true
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sealights.io/knowledgebase/phased-onboarding/java-agent-parameter-reference/java-agent-configuration-parameters/java-plugin-configuration-parameters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.