Skip to content

Working with the Code

Jump to bottom
Chris Bono edited this page Mar 18, 2024 · 11 revisions

See the CONTRIBUTING guide for information on how to contribute issues and code changes to the project.

Building from Source

Spring Pulsar source can be built from the command line using Gradle. We include Gradle’s wrapper scripts (./gradlew or gradlew.bat) that you can run rather than needing to install Gradle locally.

The project requires Java 17 and can be built from the root directory using the standard Gradle command:

./gradlew build

Tests Requiring Docker

Some integration tests that run as part of the Spring Pulsar build rely on a Docker daemon to test against live services using Testcontainers. These tests will be skipped if a local Docker daemon is not available.

Using an IDE

Importing into IntelliJ IDEA

If you have performed a checkout of this repository already, use “File” → “Open” and then select the root build.gradle file to import the code.

Note

If you encounter an error around invalid source release: 17 make sure that Gradle is using Java 17.

  • Select “IntelliJ IDEA” → “Preferences” → “Build, Execution, Deployment”

  • Select “Build Tools” → “Gradle”

  • Set "Gradle JVM" to point to valid Java 17 location

Install the Spring Formatter plugin

The formatter plugin will allow you to format your code from within IDEA.

  • Download the latest IntelliJ IDEA plugin jar.

  • Select “IntelliJ IDEA” → “Preferences”.

  • Select “Plugins”.

  • Select the wheel and “Install Plugin from Disk…​”.

  • Select the jar file you’ve downloaded.

Import additional code style

The formatter does not cover all rules (such as order of imports) and an additional file needs to be added.

  • Select “IntelliJ IDEA” → “Preferences”.

  • Select “Editor” → “Code Style”.

  • Select the wheel and “Import Scheme” → “IntelliJ IDEA code style XML”.

  • Select idea/codeStyleConfig.xml from this repository.

Install the Checkstyle IDEA plugin

While not strictly required, the CheckStyle-IDEA plugin hooks in the formatter rules and your local checkstyles so that any checkstyle related operations in IDEA use the rules you expect.

  • Download the latest CheckStyle-IDEA plugin.

  • Select “IntelliJ IDEA” → “Preferences”.

  • Select “Plugins”.

  • Select the wheel and “Install Plugin from Disk…​”.

  • Select the zip file you’ve downloaded.

Import additional check style

  • Download the latest spring-javaformat-checkstyle jar

  • Download the latest spring-javaformat-config jar

  • Select “IntelliJ IDEA” → “Preferences” → “Tools” → “Checkstyle”.

  • Specify the appropriate Checkstyle version (currently 9.3)

  • Add the downloaded spring-javaformat-checkstyle-0.0.35.jar and spring-javaformat-config-0.0.35.jar to the “Third-Party Checks”

  • Select “+” on “Configuration File” to add configuration file

    • Use Description: "Spring Pulsar checkstyle"

    • Select "Use a local checkstyle file" and navigate to "src/checkstyle/checkstyle.xml"

    • Enter "config_loc" of "src/checkstyle" if prompted

    • Select "Next"

Importing into Eclipse

TODO

Importing into Other IDEs

Gradle is well supported by most Java IDEs. Refer to your vendor documentation.

Updating the Reference Documentation

The reference documentation is stored in this repository, see spring-pulsar-docs/src/main/antora/modules/ROOT/pages. We use Asciidoc and you can build the documentation locally using this command:

./gradlew spring-pulsar-docs:build
Note
 The generated HTML documentation is available from spring-pulsar-docs/build/site/index.html.

Troubleshooting

Formatting violations

After changing some code you may encounter formatting violations during a build. These errors generally look like the following exmample:

$ ./gradlew build -x test
> Task :spring-pulsar:checkFormatMain FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':spring-pulsar:checkFormatMain'.
> Formatting violations found in the following files:
* src/main/java/org/springframework/pulsar/core/PulsarTemplate.java

  Run `format` to fix.

As the error message suggests, you can run the following command to automatically fix most of these violations:

./gradlew format

If there are still violations after running format then you must manually fix the reported issue(s).

More information on formatting can be found in the CONTRIBUTING guide.

Classpath Conflict

After adding new dependencies you may encounter prohibited dependency violations during a build. These errors generally look like the following example:

$ ./gradlew build -x test
> Task :spring-pulsar-docs:checkCompileClasspathForProhibitedDependencies FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':spring-pulsar-docs:checkCompileClasspathForProhibitedDependencies'.
> Found prohibited dependencies:
javax.activation:javax.activation-api

The build ensures that the classpaths do not contain any "prohibited" dependencies. In the above example, it flagged javax.activation:javax.activation-api as the culprit.

Understand the violation

You can use the Gradle dependency insight report to identify the origin of the violator. For example:

$ ./gradlew spring-pulsar:dependencyInsight --dependency javax.activation:javax.activation-api

> Task :spring-pulsar:dependencyInsight
javax.activation:javax.activation-api:1.2.0
   variant "compile" [
      org.gradle.status              = release (not requested)
      org.gradle.usage               = java-api
      org.gradle.libraryelements     = jar (compatible with: classes)
      org.gradle.category            = library

      Requested attributes not found in the selected variant:
         org.gradle.dependency.bundling = external
         org.gradle.jvm.environment     = standard-jvm
         org.gradle.jvm.version         = 17
   ]

javax.activation:javax.activation-api:1.2.0
\--- javax.xml.bind:jaxb-api:2.3.1
     +--- compileClasspath
     \--- org.apache.pulsar:pulsar-client-admin:2.10.1
          +--- compileClasspath (requested org.apache.pulsar:pulsar-client-admin)
          \--- project :spring-pulsar-dependencies
               \--- compileClasspath

(*) - dependencies omitted (listed previously)

In this case, we can see that the javax.xml.bind:jaxb-api:2.3.1 is transitively bringing in the dependency. Most likely this is the recently added dependency that is causing the violation.

Fix the violation

The typical solution is to exclude the transitive violator such as:

api ('javax.xml.bind:jaxb-api:2.3.1') {
    exclude group: 'javax.activation', module: 'javax.activation-api'
}

Override the violation

If the dependency in question should actually be allowed, then LenientCheckClasspathForProhibitedDependencies can be modified accordingly.

Cloning the git repository on Windows

Some files in the git repository may exceed the Windows maximum file path (260 characters), depending on where you clone the repository. If you get Filename too long errors, set the core.longPaths=true git option:

git clone -c core.longPaths=true https://github.com/spring-projects-experimental/spring-pulsar

Pages

Development Process

Clone this wiki locally