Interface PulsarClientBuilder


public interface PulsarClientBuilder
Builder for configuring and creating a PulsarClient.
  • 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 PulsarClient instance
      Throws:
      PulsarClientException - if the client cannot be created (e.g., invalid configuration or connection failure)
      IllegalStateException - if the PulsarTlsFactory set with tlsFactory(PulsarTlsFactory) was already taken by an earlier build() — 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 catching PulsarClientException should be made to handle
    • serviceUrl

      PulsarClientBuilder serviceUrl(String serviceUrl)
      Set the Pulsar service URL — the broker's binary-protocol endpoint.

      Must use pulsar:// or pulsar+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 - if serviceUrl is null, blank, or does not use pulsar:// / pulsar+ssl://
    • authentication

      PulsarClientBuilder authentication(Authentication 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 reflective authentication(String, String) path). The built client adopts the instance: it drives initializeAsync(...) before first use and Authentication.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 plugin
      authParamsString - 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

      PulsarClientBuilder operationTimeout(Duration timeout)
      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

      PulsarClientBuilder connectionPolicy(ConnectionPolicy policy)
      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

      PulsarClientBuilder transactionPolicy(TransactionPolicy policy)
      Set the transaction policy.
      Parameters:
      policy - the transaction policy controlling transaction behavior and timeouts
      Returns:
      this builder instance for chaining
    • tlsPolicy

      PulsarClientBuilder tlsPolicy(org.apache.pulsar.tls.TlsPolicy policy)
      Configure TLS for the client connection (PIP-478), using the neutral TlsPolicy value 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.pem(String, String, String)
      • TlsPolicy.keyStore(String, String, String, String, String)
      • TlsPolicy.insecure()
    • tlsPolicy

      PulsarClientBuilder tlsPolicy(org.apache.pulsar.tls.TlsPurpose purpose, org.apache.pulsar.tls.TlsPolicy policy)
      Configure TLS for a specific TlsPurpose (PIP-478). Most users call tlsPolicy(TlsPolicy), which binds the policy to TlsPurpose.CLIENT_DEFAULT; this overload additionally lets a user configure a distinct trust domain — for example TlsPurpose.CLIENT_OAUTH2 for the identity provider — with its own material.
      Parameters:
      purpose - the client TLS purpose the policy applies to
      policy - the TLS policy to apply
      Returns:
      this builder instance for chaining
    • tlsFactory

      PulsarClientBuilder tlsFactory(org.apache.pulsar.tls.PulsarTlsFactory factory)
      Provide a custom PulsarTlsFactory implementation (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 calls initialize exactly 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 - if factory is null
    • openTelemetry

      PulsarClientBuilder openTelemetry(io.opentelemetry.api.OpenTelemetry openTelemetry)
      Provide a custom OpenTelemetry instance 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 MeterProvider and TracerProvider it contains. This means:

      • To keep metrics only (no tracing), configure the instance with a MeterProvider and leave the TracerProvider as no-op.
      • To enable distributed tracing, configure the instance with both a MeterProvider and a TracerProvider.
      • To disable all telemetry, pass OpenTelemetry.noop().
      Parameters:
      openTelemetry - the OpenTelemetry instance to use
      Returns:
      this builder instance for chaining
    • memoryLimit

      PulsarClientBuilder memoryLimit(MemorySize size)
      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

      PulsarClientBuilder listenerName(String name)
      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

      PulsarClientBuilder description(String 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