Set up Java client

To set up Java client in Pulsar, complete the following steps.

Step 1: Install Java client library

The latest version of the Pulsar Java client library is available via Maven Central. To use the latest version, add the pulsar-client library to your build configuration.

tip

• pulsar-client and pulsar-client-admin shade dependencies via maven-shade-plugin to avoid conflicts of the underlying dependency packages (such as Netty). If you do not want to manage dependency conflicts manually, you can use them.
• pulsar-client-original and pulsar-client-admin-original does not shade dependencies. If you want to manage dependencies manually, you can use them.

Maven

If you use Maven, add the following information to the pom.xml file.

<!-- in your <properties> block -->
<pulsar.version>4.0.0</pulsar.version>

<!-- in your <dependencies> block -->
<dependency>
  <groupId>org.apache.pulsar</groupId>
  <artifactId>pulsar-client</artifactId>
  <version>${pulsar.version}</version>
</dependency>

Gradle

If you use Gradle, add the following information to the build.gradle file.

def pulsarVersion = '4.0.0'

dependencies {
	implementation "org.apache.pulsar:pulsar-client:${pulsarVersion}"
}

Pulsar BOM

While the above dependencies are sufficient to obtain the Pulsar Java client, it is recommended to also use the Pulsar BOM to ensure that all Pulsar dependencies (both direct and transitive) are at the same expected version. In order to use the BOM, the previous directions are modified slightly as follows:

Maven

note

Please notice that when using Spring Boot and the default Maven build, it is necessary to use Spring Boot Maven plugin features to configure the Pulsar version. Please refer to the Spring Boot using Maven section for more details.

If you use Maven, add the following information to the pom.xml file.

<!-- in your <properties> block -->
<pulsar.version>4.0.0</pulsar.version>

<!-- in your <dependencyManagement>/<dependencies> block -->
<dependency>
  <groupId>org.apache.pulsar</groupId>
  <artifactId>pulsar-bom</artifactId>
  <version>${pulsar.version}</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

<!-- in your <dependencies> block -->
<dependency>
  <groupId>org.apache.pulsar</groupId>
  <artifactId>pulsar-client</artifactId>
</dependency>

Gradle

If you use Gradle, add the following information to the build.gradle file.

note

Please notice that when using Spring Boot and the default Gradle build with the Spring Dependency Management plugin (io.spring.dependency-management), it is necessary to use Spring Dependency Management plugin features to configure the Pulsar version. Please refer to the Spring Boot using Gradle section for more details.

def pulsarVersion = '4.0.0'

dependencies {
  implementation enforcedPlatform("org.apache.pulsar:pulsar-bom:${pulsarVersion}")
  implementation 'org.apache.pulsar:pulsar-client'
}

Note that the version is number for the pulsar-client dependency is now omitted as the Pulsar BOM dictates which version is used.

Spring Boot

You can find more information about using Pulsar with Spring Boot in the Spring Boot documentation.

Spring Boot using Maven

The Spring Boot Dependency Version properties define pulsar.version and pulsar-reactive.version for controlling the Pulsar Java client version and Pulsar Reactive client version.

<!-- in your <properties> block -->
<pulsar.version>4.0.0</pulsar.version>

<!-- in your <dependencies> block -->
<!-- The Pulsar Java client will be automatically added to dependencies as a transitive dependency of the spring-boot-starter-pulsar dependency -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-pulsar</artifactId>
</dependency>

Spring Boot using Gradle

Please notice that when using the Spring Dependency Management plugin (io.spring.dependency-management) in Gradle, it is necessary to use Spring Dependency Management plugin features to configure the Pulsar version. The Spring Boot Dependency Version properties define pulsar.version and pulsar-reactive.version for controlling the Pulsar Java client version and Pulsar Reactive client version.

To use a specific Pulsar version for the Pulsar Java client in a Spring Boot application using Gradle, add the following to your build.gradle file in a Spring Boot project:

// Alternatively, you can set the `pulsar.version` property in the `gradle.properties` file.
ext['pulsar.version'] = '4.0.0'

// The Pulsar Java client will be automatically added to dependencies as a transitive dependency of the spring-boot-starter-pulsar dependency
dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-pulsar'
}

Step 2: Connect to Pulsar cluster

To connect to Pulsar using client libraries, you need to specify a Pulsar protocol URL.

You can assign Pulsar protocol URLs to specific clusters and use the pulsar scheme. The following is an example of localhost with the default port 6650:

pulsar://localhost:6650

If you have multiple brokers, separate IP:port by commas:

pulsar://localhost:6550,localhost:6651,localhost:6652

If you use mTLS authentication, add +ssl in the scheme:

pulsar+ssl://pulsar.us-west.example.com:6651

Java client Performance considerations

Increasing the memory limit

For high-throughput applications, you can increase the amount of memory with the Java client builder's memoryLimit configuration option. The default limit is 64MB which is usually too low for high-throughput applications.

By default Java applications have a limit for direct memory allocations. The allocations are limited by the -XX:MaxDirectMemorySize JVM option. In many JVM implementations, this defaults to the maximum heap size unless explicitly set. Allocations happen outside of the Java heap.

Enabling optimized Netty direct memory buffer access

The Pulsar Java client uses Netty under the hood and uses Netty direct buffers for data transport.

Netty has a feature that allows optimized direct memory buffer access. This feature enables Netty to use low level APIs such as sun.misc.Unsafe for direct memory operations, which provides faster allocation and deallocation of direct buffers. The faster deallocation can help avoid direct memory exhaustion and java.lang.OutOfMemoryError: Direct buffer memory errors. These errors can occur when the Netty memory pool and memory allocator cannot release memory back to the operating system quickly enough.

To enable this feature in Java clients since Java 11, you need to add the following JVM options to the application that uses the Java client:

• --add-opens java.base/java.nio=ALL-UNNAMED
• --add-opens java.base/jdk.internal.misc=ALL-UNNAMED

In addition, you need to add one of the following JVM options:

• -Dorg.apache.pulsar.shade.io.netty.tryReflectionSetAccessible=true for the default shaded Pulsar client
• -Dio.netty.tryReflectionSetAccessible=true for the unshaded "original" Pulsar client