gradle-plugin-common

https://github.com/zaproxy/gradle-plugin-common
Admin
A Gradle plugin that provides common ZAP build-related configurations and tasks for Java projects.
Tokens:2,931
Snippets:30
Trust Score:8
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Java Code Formatting with Spotless

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

This example shows the difference in Java code before and after applying spotlessApply, demonstrating the addition of a license header and correct indentation.

```java
// Before spotlessApply — missing license header, wrong indent
package org.zaproxy.example;
public class Example {
  public static void main(String[] args) { System.out.println("hello"); }
}

// After spotlessApply
/*
 * Zed Attack Proxy (ZAP) and its related class files.
 *
 * ZAP is an HTTP/HTTPS proxy for assessing web application security.
 *
 * Copyright 2025 The ZAP Development Team
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * ...
 */
package org.zaproxy.example;

public class Example {
    public static void main(String[] args) {
        System.out.println("hello");
    }
}
```

--------------------------------

### Properties File Formatting Example

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Demonstrates the input and output of the properties file formatting. Keys are sorted alphabetically, separators are normalized to ' = ', multiline values are flattened, and Unicode escapes are decoded.

```properties
# Input (unformatted.properties):
# spaces.before.separator     = value
# no.spaces.separator=value
# colon.separator: value
# space.separator value
# multiline.value = line1 \
#   line2
# unicode.encoded = \u0928\u0930\u0938\u094d\u0924\u0947

# Output (formatted.properties — keys sorted, separators normalised):
# colon.separator = value
# multiline.value = line1 line2
# no.spaces.separator = value
# space.separator = value
# spaces.before.separator = value
# unicode.encoded = नमस्ते
```

--------------------------------

### Spotless Properties File Formatting Error Cases

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Shows examples of error cases for properties file formatting, including duplicate keys and keys with leading spaces, which will cause the build to fail.

```bash
# Error case — duplicate key:
# $ ./gradlew spotlessPropertiesCheck
# > Invalid properties:
# > DUPLICATE: [my.key]
# BUILD FAILED

# Error case — leading space in key:
# > Invalid properties:
# > LEADING_SPACE_IN_NAME: [my.key]
```

--------------------------------

### Configure Spotless for Java Formatting and License Header

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Apply this configuration in your build.gradle.kts file to enable Java formatting using Google Java Format and prepend the ZAP Apache 2.0 license header. Use './gradlew spotlessCheck' to check formatting and './gradlew spotlessApply' to apply it.

```kotlin
plugins {
    `java-library`
    id("com.diffplug.spotless")
    id("org.zaproxy.common") version "0.5.0"
}

repositories {
    mavenCentral()
}
```

--------------------------------

### Apply Spotless Formatting

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Apply Spotless formatting rules to all sources in the repository. This ensures consistent code style.

```bash
./gradlew spotlessApply
```

--------------------------------

### CI Build Matrix with Java Versions

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Iterate through different Java versions (17, 21, 22) to build and verify the project. This mirrors the CI workflow.

```bash
for JAVA in 17 21 22; do
  sdk use java ${JAVA}-tem
  ./gradlew assemble check
done
```

--------------------------------

### Apply `org.zaproxy.common.settings` Plugin to Settings

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Apply this plugin in `settings.gradle.kts` to register Maven Central as the default dependency repository for all projects in the build.

```kotlin
settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
    }
}

plugins {
    id("org.zaproxy.common.settings") version "0.5.0"
}

rootProject.name = "my-zap-addon"
include("core", "api")

// Effect: dependencyResolutionManagement.repositories { mavenCentral() }
// is automatically applied to all included projects.
```

--------------------------------

### Run All Verification Tasks with Gradle

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Execute all verification tasks, including unit tests, functional tests, and spotless checks. This is typically used for CI builds.

```bash
./gradlew check
```

--------------------------------

### Run Unit Tests with Gradle

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Execute only the unit tests defined in the 'test' source set. Ensure you have the Gradle wrapper script available.

```bash
./gradlew test
```

--------------------------------

### Internal Logic for `CommonPlugin.apply(Project)`

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Illustrative internal logic showing how the `CommonPlugin` registers formatters and configures Java compilation. No user action is required for this part.

```java
// Equivalent internal logic (illustrative — no user action required):
public void apply(Project target) {
    // 1. Register properties formatter unconditionally
    var spotless = target.getExtensions().findByType(SpotlessExtension.class);
    if (spotless != null) {
        spotless.format("properties", format -> {
            format.target("**/*.properties");
            format.targetExclude(
                "**/Messages_*_*.properties",
                "**/gradle.properties",
                "**/gradle-wrapper.properties");
            format.addStep(FormatPropertiesStep.create());
        });
    }
    // 2. Configure Java compiler + Spotless Java only when java plugin present
    target.getPlugins().withType(JavaPlugin.class, jp -> configureJavaPlugin(target));
}
```

--------------------------------

### Apply `org.zaproxy.common` Plugin to a Project

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Apply this plugin to a Gradle project that uses the `java` or `java-library` plugin. It configures Spotless formatting and Java compilation settings.

```kotlin
plugins {
    `java-library`
    id("com.diffplug.spotless")       // must be applied before org.zaproxy.common
    id("org.zaproxy.common") version "0.5.0"
}

repositories {
    mavenCentral()
}

// No further configuration required — the plugin sets up:
//  • Spotless Java: Google Java Format 1.25.2 (AOSP style) + ZAP license header
//  • Spotless properties: sorted keys, normalised separators, duplicate-key detection
//  • JavaCompile: encoding=UTF-8, -Xlint:all, -Werror, -parameters
```

--------------------------------

### Run Functional Tests with Gradle

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Execute only the functional (integration) tests defined in the 'functionalTest' source set. This requires the Gradle wrapper.

```bash
./gradlew functionalTest
```

--------------------------------

### Configure Spotless for Properties File Formatting

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Use this direct API usage in your Spotless configuration to format Java .properties files. It sorts keys, normalizes separators, flattens multiline values, decodes Unicode escapes, and ensures a trailing newline. It throws InvalidPropertiesException for invalid input.

```java
import com.diffplug.gradle.spotless.SpotlessExtension;
import org.zaproxy.gradle.common.spotless.FormatPropertiesStep;

spotless {
    format("properties", format -> {
        format.target("src/**/*.properties");
        format.addStep(FormatPropertiesStep.create());
    });
}
```

--------------------------------

### Configure Common Settings Plugin for Dependency Management

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Apply the common settings plugin in settings.gradle.kts to automatically add Maven Central to dependencyResolutionManagement.repositories. This eliminates the need for individual sub-projects to declare repositories.

```kotlin
plugins {
    id("org.zaproxy.common.settings") version "0.5.0"
}

rootProject.name = "my-zap-project"
include("plugin-a", "plugin-b")
```

--------------------------------

### Assemble JARs without Running Tests

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Build the project's JAR files without executing any tests. Useful for creating distributable artifacts.

```bash
./gradlew assemble
```

--------------------------------

### Java Compilation Configuration by `CommonPlugin`

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

Shows the effective compiler settings applied by the plugin, including encoding, compiler arguments, and Error Prone checks. This configuration is automatically applied when the `java` or `java-library` plugin is present.

```kotlin
// Effective compiler settings injected by the plugin — shown for clarity:
tasks.withType<JavaCompile>().configureEach {
    options.encoding = "UTF-8"
    options.compilerArgs = listOf("-Xlint:all", "-Werror", "-parameters")
    // Error Prone (configured at root):
    options.errorprone {
        disableAllChecks.set(true)
        error("MissingOverride", "WildcardImport")
    }
}

// Example: a class with an unchecked cast triggers a build failure
// src/main/java/org/example/Foo.java
public class Foo {
    public static void main(String[] args) {
        java.util.List l = new java.util.ArrayList<Number>(); // raw-type warning
        java.util.List<String> ls = l;                        // unchecked warning → ERROR
    }
}
// $ ./gradlew compileJava
// > error: warnings found and -Werror specified
// BUILD FAILED
```

--------------------------------

### Handle InvalidPropertiesException in Unit Tests

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

This unit-test-style usage demonstrates how to catch and assert the specific messages for `DUPLICATE` and `LEADING_SPACE_IN_NAME` exceptions thrown by `FormatPropertiesStep.format()`.

```java
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import org.zaproxy.gradle.common.spotless.FormatPropertiesStep;

// DUPLICATE
assertThatThrownBy(() ->
    FormatPropertiesStep.format("my.key = v1\nmy.key = v2\n"))
    .isInstanceOf(FormatPropertiesStep.InvalidPropertiesException.class)
    .hasMessage("Invalid properties:\nDUPLICATE: [my.key]\n");

// LEADING_SPACE_IN_NAME
assertThatThrownBy(() ->
    FormatPropertiesStep.format(" bad.key = value"))
    .isInstanceOf(FormatPropertiesStep.InvalidPropertiesException.class)
    .hasMessage("Invalid properties:\nLEADING_SPACE_IN_NAME: [bad.key]\n");
```

--------------------------------

### Sub-project Dependency Declaration without Repositories

Source: https://context7.com/zaproxy/gradle-plugin-common/llms.txt

In a sub-project's build.gradle.kts, dependencies can be declared directly without a repositories block because Maven Central is already registered globally by the common settings plugin.

```kotlin
plugins {
    `java-library`
    id("com.diffplug.spotless")
    id("org.zaproxy.common") version "0.5.0"
}
dependencies {
    // No repositories{} block needed — Maven Central is already registered
    implementation("com.google.guava:guava:33.0.0-jre")
}
```
Tokens:
Raw