Apache Pulsar support for Spring

Apache Pulsar support for Spring makes it easier to build Apache Pulsar applications with Spring. It provides PulsarTemplate for publishing messages, @PulsarListener and @PulsarReader for consuming them, a Spring Boot starter with auto-configuration and a Spring Cloud Stream binder.

Getting started

Most applications use Spring Boot with the pulsar-spring-boot-starter dependency. The Quick Tour shows what to add to a Maven or Gradle build, and a complete application that publishes and consumes a message.

If you don't use Spring Boot, see Getting Dependencies without Spring Boot.

Migrating from Spring for Apache Pulsar

This project is the successor to Spring for Apache Pulsar. The Maven coordinates and Java packages have changed. See Migration from Spring's Pulsar support for the changes to make in your application.

Documentation

See the reference documentation. You can also build it locally with the command in Building.

Background

This project is the successor to Spring for Apache Pulsar. It brings together code that was previously maintained in three repositories:

Previous repository	Code
spring-projects/spring-pulsar	Core library and test utilities
spring-projects/spring-boot	Spring Boot auto-configuration and starters
spring-cloud/spring-cloud-stream	Spring Cloud Stream binder

Further development happens under the Apache Pulsar project in this repository.

Modules

All artifacts use the org.apache.pulsar group ID.

Artifact	Description
pulsar-spring	Core library
pulsar-spring-boot-autoconfigure	Spring Boot auto-configuration
pulsar-spring-boot-starter	Starter for Spring Boot applications
pulsar-spring-boot-starter-test	Starter for testing Spring Boot applications
pulsar-spring-cloud-stream-binder	Spring Cloud Stream binder
pulsar-spring-test	Test utilities
pulsar-spring-bom	Bill of materials

Sample applications are in pulsar-spring-sample-apps.

Building

The build uses the included Gradle wrapper and a Java 25 toolchain. Docker is required for the tests.

# Full build, including tests
./gradlew build

# Also run the sample application tests
./gradlew build -PsampleTests

# Run the sample application tests against published artifacts in a local repository
./gradlew publishAllPublicationsToLocalRepository
(cd pulsar-spring-sample-apps && ../gradlew runAllSampleTests -PsampleTests -PpulsarSpringRepository=../build/publications/repos)

# Run the tests with another Pulsar image
PULSAR_TEST_IMAGE=registry.example.com/pulsar:5.0.1 ./gradlew :pulsar-spring-cloud-stream-binder:test

# Also test the AOT support in a native image, which requires GraalVM for JDK 25
(cd pulsar-spring-sample-apps && ../gradlew :sample-native-image:nativeSmokeTest -PpulsarSpringRepository=../build/publications/repos)

# Reference documentation, generated in pulsar-spring-docs/build/site
./gradlew :pulsar-spring-docs:antora

Publishing

Artifacts are published to the Apache repository. publishArtifacts uses the snapshot repository for -SNAPSHOT versions and a staging repository for other versions, which must be signed. It refuses to publish a version to the wrong repository.

Pass your ASF credentials as environment variables so that they aren't stored in gradle.properties, and start the command with a space to keep the password out of your shell history:

# Snapshot
 ORG_GRADLE_PROJECT_apacheSnapshotsUsername=<ASF ID> \
 ORG_GRADLE_PROJECT_apacheSnapshotsPassword=<password> \
 ./gradlew publishArtifacts

# Release or milestone, with -Psigning.gnupg.keyName=<key ID> to choose a key other than the default
 ORG_GRADLE_PROJECT_apacheReleasesUsername=<ASF ID> \
 ORG_GRADLE_PROJECT_apacheReleasesPassword=<password> \
 ./gradlew publishArtifacts -PuseGpgCmd=true

Set -PapacheSnapshotsRepoUrl and -PapacheReleasesRepoUrl to file:// URLs to test the publication without uploading anything.

A private fork can publish with its own group ID by changing group in gradle.properties.

Source release

sourceRelease creates the source release for an ASF release vote in build/source-release: an archive of the committed tree, with a SHA-512 checksum and a detached signature.

./gradlew sourceRelease -PuseGpgCmd=true

For a non-snapshot version, it fails if there are uncommitted changes, if the committed gradle.properties has a different version, or if signing isn't configured. The reference documentation is skipped when building from the archive because Antora needs a git repository, so build the site from a clone.

Contributing

See CONTRIBUTING.md for how to contribute, set up your IDE and follow the code conventions.

Security

Don't report vulnerabilities in public issues. See SECURITY.md for how to report them.

License

Licensed under the Apache License, Version 2.0.