Pulsar Java client
You can use a Pulsar Java client to create Pulsar producers, consumers, and readers in Java and perform administrative tasks. Share a client instance across your producers and consumers.
Java client SDKs
The names v4 and v5 identify Java API generations, not dependency or server release versions. The v4 client remains supported with Pulsar 5 and later. Pulsar provides both APIs:
| v4 client | v5 client | |
|---|---|---|
| Package | org.apache.pulsar.client.api | org.apache.pulsar.client.api.v5 |
| Topics | Regular partitioned and non-partitioned topics | Scalable topics and regular persistent topics |
| Consumption | Exclusive / Failover / Shared / Key_Shared subscriptions | Stream / Queue / Checkpoint consumers |
| Minimum Java with the combined artifacts | 17 | 17 |
The v4 client is the existing supported client used by applications with regular topics. The Get started and Advanced use guides describe this API.
The v5 client supports scalable topics and also works against regular persistent topics. See Java client (v5). It requires Pulsar 5.x brokers with scalableTopicsEnabled=true, even for regular topics. Use the v4 API for older brokers, non-persistent topics, or features outside the v5 API.
Use pulsar-client-v5-all by default to obtain the v4 client, v5 client, and admin implementations through unshaded dependencies. If unshaded dependency conflicts cannot be resolved, pulsar-client-v5-shaded is a fallback with relocated implementations. Follow Java client setup for release selection, external dependencies, and classpath exclusions. Both APIs can run side by side in one application; adopting a combined dependency and migrating source code to v5 are separate choices. Existing v4 applications using regular topics do not need to change their API or dependencies for a broker upgrade.
Get started
Please refer to Java client Performance considerations for more information on how to improve the performance of the Java client and tune the Java JVM options to avoid java.lang.OutOfMemoryError: Direct buffer memory errors in high-throughput applications.
What's next?
- Work with clients
- Work with producers
- Work with consumers
- Work with readers
- Work with TableView
- Configure cluster-level failover
Reference doc
API reference
The following table outlines the API packages and reference docs for Pulsar Java clients.
| Package | Description | Recommended dependency |
|---|---|---|
org.apache.pulsar.client.api | v4 Java client API | pulsar-client-v5-all |
org.apache.pulsar.client.api.v5 | v5 Java client API | pulsar-client-v5-all |
org.apache.pulsar.client.admin | Java admin API | pulsar-client-v5-all |
All three APIs are also available with the shaded fallback. See Java client setup for the dependency graph; an aggregate artifact name does not introduce a separate API package.