# Integrating PVS\-Studio Java into the Maven build system

PVS\-Studio Java static analyzer consists of two main components: [the core](https://pvs-studio.com/en/docs/manual/6703/) that performs analysis, the plugins for integrating the analyzer into build systems \(Maven and [Gradle](https://pvs-studio.com/en/docs/manual/6706/)\), and IDEs \([PVS\-Studio for IntelliJ IDEA and Android Studio](https://pvs-studio.com/en/docs/manual/6704/)\)\.

With the plugins, you can: 

* run and configure the analyzer in a user\-friendly interface; 
* deploy the analyzer core in the system;
* collect and transfer the project structure data \(the set of source files and the classpath\) to the analyzer core\.

## How to integrate the PVS\-Studio plugin into Maven

To integrate the plugin, add the following code to the `pom.xml` file:

```cpp
<pluginRepositories>
  <pluginRepository>
    <id>pvsstudio-maven-repo</id>
    <url>https://wcdn.pvs-studio.com/java/pvsstudio-maven-repository/</url>
  </pluginRepository>
</pluginRepositories>
<build>
  <plugins>
    <plugin>
      <groupId>com.pvsstudio</groupId>
      <artifactId>pvsstudio-maven-plugin</artifactId>
      <version>{{FULL_VERSION_PVS_JAVA}}</version>
      <configuration>
        <analyzer>
          <outputType>text</outputType>
          <outputFile>.PVS-Studio/report.txt</outputFile>
          <analysisMode>GA,OWASP</analysisMode>
        </analyzer>
      </configuration>
    </plugin>
  </plugins>
</build>
```

## How to run the analysis

> Before running the analysis, enter the PVS\-Studio license\. To learn how to do this, please consult the [documentation](https://pvs-studio.com/en/docs/manual/0046/#PvsStudioJava)\.

To run the analysis, execute the following command:

```cpp
mvn pvsstudio:pvsAnalyze
```

In addition, you can incorporate the analysis into the project build cycle by adding the `<execution>` element:

```cpp
<plugin>
  <groupId>com.pvsstudio</groupId>
  <artifactId>pvsstudio-maven-plugin</artifactId>
  <version>{{FULL_VERSION_PVS_JAVA}}</version>
  <executions>
    <execution>
      <phase>compile</phase>
      <goals>
        <goal>pvsAnalyze</goal>
      </goals>
    </execution>
  </executions>
</plugin>
```

**Note\.** When analyzing a project, the plugin runs the [Java analyzer core](https://pvs-studio.com/en/docs/manual/6703/), which uses the Java version from the `PATH` environment variable by default\. You can set a different version by configuring the `javaPath` plugin\. The **Configuration** section below describes this in detail\.

## How to run the analysis without network access

For the plugin to work, you need to download its dependencies\. If you work with the plugin on a system that does not have network access, create a local repository of the plugin dependencies\. To do that, you may use [_maven\-dependency\-plugin_](https://maven.apache.org/plugins/maven-dependency-plugin/go-offline-mojo.html)\. 

Use this command to download the dependencies and prepare them for offline use:

```cpp
mvn dependency:go-offline
```

Run this command from the directory that contains the `pom.xml` file \(the project root directory\)\. In this case, all the dependencies needed to build and analyze the project will be saved in the default local repository folder: `%userprofile%/.m2/repository` on Windows or `~/.m2/repository` on Linux/macOS\.

To save the offline repository to a different folder, use the `maven.repo.local` parameter\. In this case, the command would look like as follows:

```cpp
mvn dependency:go-offline -Dmaven.repo.local=/custom/path
```

To download the dependencies, you need to have a network connection while running this command\. Internet access is no longer required to continue working\.

The system must be installed the same Java core version as the plugin\. You can learn how to install the Java analyzer core in [this documentation](https://pvs-studio.com/en/docs/manual/6703/#java_core_install)\. 

Using the analyzer in this case is no different from its normal use\. To prevent _maven_ from downloading dependencies use the `--offline` \(`-o`\) flag\. An example of a command to run an offline analysis using a user local repository:

```cpp
mvn -o pvsstudio:pvsAnalyze -Dmaven.repo.local=/custom/path
```

## Configuration

The `<analyzer>` block is used to configure the analyzer\. The following is a list of analysis settings:

* `<additionalWarnings>VXXXX, ....</additionalWarnings>` specifies a list of diagnostic rules that will be added to the analysis\. It has a higher priority than `<enabledWarnings>`, `<disabledWarnings>`, and `<analysisMode>`\. Default value: not set\.
* `<analysisMode>GA, ....</analysisMode>` specifies a list of enabled diagnostic rule groups\. The `<enabledWarnings>`, `<disabledWarnings>`, and `<additionalWarnings>` settings have a higher priority than this setting\. In other words, you can use these settings to enable or disable individual diagnostic rules based on whether the diagnostic rule group is disabled or enabled\. Default value: `GA`\. Available groups are: 
  * `[GA](https://pvs-studio.com/en/docs/warnings/#GeneralAnalysisJAVA)` \(general analysis diagnostic rules\);
  * `[OWASP](https://pvs-studio.com/en/pvs-studio/sast/owasp/#java)` \(rules based on [OWASP Top Ten](https://pvs-studio.com/en/pvs-studio/sast/owasptopten/) and [OWASP ASVS](https://pvs-studio.com/en/pvs-studio/sast/owasp/)\)\.
* `<analyzeOnly>PATH, ....</analyzeOnly>` specifies a list of files and/or directories for the analysis\. Relative \(will be expanded relative to the working directory\) and absolute paths are supported\. Files and/or directories passed in this argument are merged into a list with files and/or directories from the `<analyzeOnlyList>` argument\. If no value is provided for this setting, all files are analyzed\. The setting has a lower priority than `<exclude>`\. Default value: not set\.
* `<analyzeOnlyList>PATH</analyzeOnlyList>` specifies a path to a text file that contains a list of paths to files and/or directories for the analysis\. Each entry must be on a separate line\. Relative \(will be expanded relative to the working directory\) and absolute paths are supported\. Files and/or directories read from the file specified in this argument are merged into a list with values from the `<analyzeOnly>` argument\. The setting has a lower priority than `<exclude>`\. Default value: not set\.
* `<disableCache>BOOLEAN</disableCache>` disables caching of the program metamodel\. When caching is disabled, the project model is not cached and is rebuilt each run\. Disabling caching also disables the [incremental analysis mode](https://pvs-studio.com/en/docs/manual/0024/), even if the `<incremental>` parameter is specified\. Default value: `false`\.
* `<disabledWarnings>VXXXX, ....</disabledWarnings>` specifies a list of diagnostic rules that will not be applied during the analysis\. If this setting is not specified, all diagnostic rules are enabled\. The setting has a higher priority than the `<enabledWarnings>` and `<analysisMode>` settings, but it has a lower priority than `<additionalWarnings>`\. Default value: not set\.
* `<enabledWarnings>VXXXX, ....</enabledWarnings>` specifies a list of enabled diagnostic rules\. Only the listed ones will be enabled during the analysis\. The setting has a lower priority than `<disabledWarnings>` and `<additionalWarnings>`, but it has a higher priority than `<analysisMode>`\. Default value: not set\.
* `<exclude>PATH, ....</exclude>` specifies a list of files and/or directories to be excluded from analysis\. Relative \(will be expanded relative to the working directory\) and absolute paths are supported\. The setting has a higher priority than `<analyzeOnly>` and `<analyzeOnlyList>`\. Default value: not set\.
* `<failOnWarnings>BOOLEAN</failOnWarnings>` returns a non\-zero exit code if the analyzer issues at least one warning for the project code\. This behavior can be useful when [integrating into CI/CD](https://pvs-studio.com/en/docs/#IDF1BF21914C)\. Default value: `false`\.
* `<forceRebuild>BOOLEAN</forceRebuild>` forces a full rebuild of the cached program metamodel\. Enabling this flag disables the [incremental analysis mode](https://pvs-studio.com/en/docs/manual/0024/), even if the `<incremental>` parameter is specified\. Default value: `false`\.
* `<incremental>BOOLEAN</incremental>` enables [incremental](https://pvs-studio.com/en/docs/manual/0024/) analysis\. In this mode, the analyzer checks only modified files\. Default value: `false`\.
* `<javaPath>PATH</javaPath>` specifies a path to the `java` executable file that is used to run the analyzer core\. This setting can be configured system\-wide in the [`global.json`](https://pvs-studio.com/en/docs/manual/6703/#java_global_json_file) file\. If `java-path` is not used, PVS\-Studio attempts to use the path from the `PATH` environment variable\.
* `<jvmArguments>FLAG, ....</jvmArguments>` specifies additional JVM flags for running the analyzer core\. They enable the configuration of the JVM that will run the Java core of the analyzer\. This setting can also be configured system\-wide in the [`global.json`](https://pvs-studio.com/en/docs/manual/6703/#java_global_json_file) file\. Default value: `["-Xss64m"]`\.
* `<licensePath>PATH</licensePath>` specifies a path to the license file\. Supported file extensions are `.xml` and `.lic`\. Default value: `%APPDATA%/PVS-Studio/Settings.xml` \(Windows\) or `~/.config/PVS-Studio/PVS-Studio.lic` \(macOS and Linux\)\.
* `<logging>LEVEL</logging>` specifies the logging level when starting the analysis\. When enabled, log files are created for the current run in the `.PVS-Studio/logs` subdirectory relative to the directory where the Java analyzer is currently running\. If an invalid value is passed, logging is disabled\. Default value: `OFF`\. Available values are:
  * `OFF`
  * `ERROR`
  * `WARN`
  * `INFO`
  * `DEBUG`
  * `TRACE`
  * `ALL`\. 
* `<outputFile>PATH</outputFile>` specifies a path to the analyzer report file\. The report format does not depend on the file extension specified in the parameter\. Default value: `./PVS-Studio` \+ the format extension defined by `--output-type`\. To generate a report in `.fullhtml` format, specify the directory where the `fullhtml` subdirectory containing the analyzer report file \(`index.html`\) will be created\. Default value: `./fullhtml`\. **Note**\. It is recommend to use the [PlogConverter \(Windows\)](https://pvs-studio.com/en/docs/manual/0038/#PlogConverter) and [plog\-converter \(Linux and macOS\)](https://pvs-studio.com/en/docs/manual/0038/#plog-converter) instead of `<outputFile>`\. They enable converting the analyzer report to more formats \(for example, SARIF\)\. The utilities provide additional features: filtering warnings from reports, converting paths in reports from absolute to relative \(and vice versa\), comparing reports, and more\.
* `<outputType>TYPE</outputType>` specifies the analyzer report format\. Default value: `json`\. Available values are:
  * `text`
  * `log`
  * `json`
  * `xml`
  * `tasklist`
  * `html`
  * `fullhtml`
  * `errorfile`\. 
* `<securityRelatedIssues>BOOLEAN</securityRelatedIssues>` tags warnings related to potential security issues with an additional mark up in the `SAST` field\. Default value: `false`;
* `<sourceTreeRoot>PATH</sourceTreeRoot>` specifies a root part of the path that the [analyzer uses](https://pvs-studio.com/en/docs/manual/0027/) to generate relative paths in the report for warnings\. Default value: not set\.
* `<suppressBase>PATH</suppressBase>` specifies a path to the [suppress file](https://pvs-studio.com/en/docs/manual/0032/) that contains suppressed analyzer warnings\. These warnings are excluded from future analysis reports\. Default value: `${basedir}/.PVS-Studio/suppress_base.json`\.
* `<threadsNum>NUMBER</threadsNum>` specifies the number of analysis threads\. This setting can also be configured system\-wide in the [`global.json`](https://pvs-studio.com/en/docs/manual/6703/#java_global_json_file) file\. Default value: the _number of available logical processors_\.
* `<timeout>NUMBER</timeout>` specifies the timeout for analyzing one file \(in minutes\)\. This setting can be configured system\-wide in the [`global.json`](https://pvs-studio.com/en/docs/manual/6703/#java_global_json_file) file\. Default value: `10`\.
* `<compatibility>BOOLEAN</compatibility>` enables the [V6078](https://pvs-studio.com/en/docs/warnings/v6078/) diagnostic rule, which detects potential API compatibility issues between selected Java SE versions\. Default value: `false`\.
* `<excludePackages>"PACK", ....</excludePackages>` specifies packages to be excluded from the compatibility analysis\. The [V6078](https://pvs-studio.com/en/docs/warnings/v6078/) diagnostic rule uses this setting if the `<compatibility>` setting is enabled\.
* `<sourceJava>NUMBER</sourceJava>` specifies the Java SE version used to develop the application analyzed\. The [V6078](https://pvs-studio.com/en/docs/warnings/v6078/) diagnostic rule uses this setting if the `<compatibility>` setting is enabled\. Minimum value: `8`\. Maximum value: `14`\.
* `<targetJava>NUMBER</targetJava>` specifies the Java SE version against which the API used by the analyzed application \(`<sourceJava>`\) is checked for compatibility\. The [V6078](https://pvs-studio.com/en/docs/warnings/v6078/) diagnostic rule uses this setting if the `<compatibility>` setting is enabled\. Minimum value: `8`\. Maximum value: `14`\.

The definition format:

```cpp
-Dpvsstudio.<nameSingleParam>=value 
-Dpvsstudio.<nameMultipleParam>=value1;value2;value3
```

The example:

```cpp
mvn pvsstudio:pvsAnalyze -Dpvsstudio.outputType=text
                         -Dpvsstudio.outputFile=.PVS-Studio/report.txt
                         -Dpvsstudio.disabledWarnings=V6001;V6002;V6003
```

**Please note** that parameters explicitly passed via the command line have the highest priority\.

### How to change the Java version to run the analyzer

By default, the analyzer starts the core with Java from the `PATH` environment variable\. If you need to run the analysis with some other version, you can set it manually\. To do this, specify the path to Java from the JDK in the `<javaPath>` analyzer setting\. The version of this JDK will be used when analyzing the project source code:

```cpp
....
<javaPath>C:/Program Files/Java/jdk19.0.5/bin/java</javaPath>
....
```

## How to update PVS\-Studio Java

To update [_pvsstudio\-maven\-plugin_](https://mvnrepository.com/artifact/com.pvsstudio/pvsstudio-maven-plugin), change the version of the plugin in the _pom\.xml_ file\.

### Using a proxy

When using a proxy, it is necessary to enter your login and password to correctly load the analyzer core\. 

To do this, you can use the following arguments: 

* `-Dhttp.proxyUser`, `-Dhttp.proxyPassword`;
* `-Dhttps.proxyUser`, `-Dhttps.proxyPassword`;
* `-Djava.net.socks.username`, `-Djava.net.socks.password`;
* `-Dftp.proxyUser`, `-Dftp.proxyPassword`\.

You can use this command to run the analysis via the plugin for Maven that uses a proxy:

```cpp
mvn pvsstudio:pvsAnalyze "-Dhttp.proxyUser=USER" "-Dhttp.proxyPassword=PASS"
```