Interface PulsarClientBuilder
PulsarClient.-
Method Summary
Modifier and TypeMethodDescriptionauthentication(String authPluginClassName, String authParamsString) Set authentication by plugin class name and parameter string.authentication(Authentication authentication) Set the authentication provider from an instance supplied programmatically.build()Build and return the configured client.connectionPolicy(ConnectionPolicy policy) Configure connection-level settings such as timeouts, pool size, threading, keep-alive, and proxy configuration.description(String description) A human-readable description of this client (for logging and debugging).listenerName(String name) Set the listener name for multi-listener brokers.memoryLimit(MemorySize size) Maximum amount of memory the client may hold in pending messages, across all of its producers and consumers.openTelemetry(io.opentelemetry.api.OpenTelemetry openTelemetry) Provide a customOpenTelemetryinstance for metrics and tracing.operationTimeout(Duration timeout) Timeout for client operations (e.g., creating producers/consumers).serviceUrl(String serviceUrl) Set the Pulsar service URL — the broker's binary-protocol endpoint.tlsFactory(org.apache.pulsar.tls.PulsarTlsFactory factory) Provide a customPulsarTlsFactoryimplementation (PIP-478), for advanced deployments that source TLS material from something other than files (a KMS, an HSM-backed key manager, a per-destination workload identity).tlsPolicy(org.apache.pulsar.tls.TlsPolicy policy) Configure TLS for the client connection (PIP-478), using the neutralTlsPolicyvalue shared by the client builder and the server components.tlsPolicy(org.apache.pulsar.tls.TlsPurpose purpose, org.apache.pulsar.tls.TlsPolicy policy) Configure TLS for a specificTlsPurpose(PIP-478).transactionPolicy(TransactionPolicy policy) Set the transaction policy.
-
Method Details
-
build
Build and return the configured client. A builder may be reused to build further clients; each one takes its own copy of the configuration.- Returns:
- the configured
PulsarClientinstance - Throws:
PulsarClientException- if the client cannot be created (e.g., invalid configuration or connection failure)IllegalStateException- if thePulsarTlsFactoryset withtlsFactory(PulsarTlsFactory)was already taken by an earlierbuild()— taking it is what initializes it, so it is spent whether or not that build went on to produce a client, and it cannot be handed over a second time. Deliberately unchecked: it reports a programming error in how the builder is used, not a failure to reach or configure a cluster, so it is not something a caller catchingPulsarClientExceptionshould be made to handle
-
serviceUrl
Set the Pulsar service URL — the broker's binary-protocol endpoint.Must use
pulsar://orpulsar+ssl://. The admin/web service URL (http://.../https://...) is NOT accepted.- Parameters:
serviceUrl- the Pulsar broker service URL to connect to, e.g.pulsar://localhost:6650- Returns:
- this builder instance for chaining
- Throws:
IllegalArgumentException- ifserviceUrlis null, blank, or does not usepulsar:///pulsar+ssl://
-
authentication
Set the authentication provider from an instance supplied programmatically.Programmatic-path contract. The instance is presumed already configured — the framework does NOT call
Authentication.configure(java.util.Map)on it (that step runs only for the reflectiveauthentication(String, String)path). The built client adopts the instance: it drivesinitializeAsync(...)before first use andAuthentication.close()when the client is closed, so callers must not close the instance themselves or share one instance across clients with differing lifetimes.- Parameters:
authentication- the authentication provider to use for connecting to the broker; must already be configured- Returns:
- this builder instance for chaining
-
authentication
PulsarClientBuilder authentication(String authPluginClassName, String authParamsString) throws PulsarClientException Set authentication by plugin class name and parameter string.- Parameters:
authPluginClassName- the fully qualified class name of the authentication pluginauthParamsString- the authentication parameters as a serialized string- Returns:
- this builder instance for chaining
- Throws:
PulsarClientException- if the authentication plugin cannot be loaded or configured
-
operationTimeout
Timeout for client operations (e.g., creating producers/consumers).- Parameters:
timeout- the maximum duration to wait for an operation to complete- Returns:
- this builder instance for chaining
-
connectionPolicy
Configure connection-level settings such as timeouts, pool size, threading, keep-alive, and proxy configuration.The reconnection backoff's initial and max intervals are applied. A backoff whose multiplier is not 2, or whose jitter is not
BackoffPolicy.DEFAULT_JITTER_PERCENT, is rejected rather than ignored. The client doubles the delay on each attempt.- Parameters:
policy- the connection policy- Returns:
- this builder instance for chaining
- See Also:
-
transactionPolicy
Set the transaction policy.- Parameters:
policy- the transaction policy controlling transaction behavior and timeouts- Returns:
- this builder instance for chaining
-
tlsPolicy
Configure TLS for the client connection (PIP-478), using the neutralTlsPolicyvalue shared by the client builder and the server components. The policy is bound to the default client purposes.- Parameters:
policy- the TLS policy to apply to broker connections- Returns:
- this builder instance for chaining
- See Also:
-
tlsPolicy
PulsarClientBuilder tlsPolicy(org.apache.pulsar.tls.TlsPurpose purpose, org.apache.pulsar.tls.TlsPolicy policy) Configure TLS for a specificTlsPurpose(PIP-478). Most users calltlsPolicy(TlsPolicy), which binds the policy toTlsPurpose.CLIENT_DEFAULT; this overload additionally lets a user configure a distinct trust domain — for exampleTlsPurpose.CLIENT_OAUTH2for the identity provider — with its own material.- Parameters:
purpose- the client TLS purpose the policy applies topolicy- the TLS policy to apply- Returns:
- this builder instance for chaining
-
tlsFactory
Provide a customPulsarTlsFactoryimplementation (PIP-478), for advanced deployments that source TLS material from something other than files (a KMS, an HSM-backed key manager, a per-destination workload identity). The supplied factory is adopted: the client initializes it and closes it when the client closes.Adoption is a hand-over rather than a share, so an instance passed here belongs to one build. A builder otherwise builds as many clients as you like, but
build()rejects a second one while this slot still holds a factory an earlier build already took — pass a fresh instance to build again.What matters for a retry is whether the build got as far as the factory, not whether it succeeded. A build that failed before that — a missing
serviceUrl(String), say — has not touched the instance, and the same one can be used to build again. Once the client has taken it the instance is spent, whether the build then succeeded or not: taking it is what initializes it, and the SPI callsinitializeexactly once. A build that took it and then failed closes it on the way out, so that factory is released rather than left half-open — but it still cannot be offered to a second client. (One that succeeded keeps it, and closes it with the client, as above.)Everything configured through
tlsPolicy(TlsPolicy)is unaffected: a policy is a value, and each client composes its own factory from it.- Parameters:
factory- the TLS factory to adopt- Returns:
- this builder instance for chaining
- Throws:
IllegalArgumentException- iffactoryis null
-
openTelemetry
Provide a customOpenTelemetryinstance for metrics and tracing.If not set, the client creates its own internal instance that exports metrics (via a Prometheus-compatible endpoint) with tracing disabled.
When a custom instance is provided, the client uses whatever
MeterProviderandTracerProviderit contains. This means:- To keep metrics only (no tracing), configure the instance with a
MeterProviderand leave theTracerProvideras no-op. - To enable distributed tracing, configure the instance with both a
MeterProviderand aTracerProvider. - To disable all telemetry, pass
OpenTelemetry.noop().
- Parameters:
openTelemetry- the OpenTelemetry instance to use- Returns:
- this builder instance for chaining
- To keep metrics only (no tracing), configure the instance with a
-
memoryLimit
Maximum amount of memory the client may hold in pending messages, across all of its producers and consumers.A message a producer has accepted is charged its payload size plus a fixed allowance for the per-message bookkeeping, until the send completes, so the limit bounds how many messages can be pending as well as how many bytes. It is the only bound on a producer's pending messages: see
ProducerBuilder.blockIfQueueFull(boolean)for what a send does when it is reached.- Parameters:
size- the memory limit for pending messages- Returns:
- this builder instance for chaining
- See Also:
-
listenerName
Set the listener name for multi-listener brokers.- Parameters:
name- the listener name to use when connecting to brokers that advertise multiple listener endpoints- Returns:
- this builder instance for chaining
-
description
A human-readable description of this client (for logging and debugging).- Parameters:
description- a descriptive label for this client instance- Returns:
- this builder instance for chaining
-