Package io.camunda.client

Interface CamundaClientBuilder

All Known Subinterfaces:
CamundaClientCloudBuilderStep1.CamundaClientCloudBuilderStep2.CamundaClientCloudBuilderStep3.CamundaClientCloudBuilderStep4, CamundaClientCloudBuilderStep1.CamundaClientCloudBuilderStep2.CamundaClientCloudBuilderStep3.CamundaClientCloudBuilderStep4.CamundaClientCloudBuilderStep5
All Known Implementing Classes:
CamundaClientBuilderImpl, CamundaClientCloudBuilderImpl
public interface CamundaClientBuilder
A builder to create a CamundaClient.

  • Method Details

    • withProperties

      CamundaClientBuilder withProperties(Properties properties)
      Sets all the properties from a Properties object. Can be used to configure the client from a properties file.

      See ClientProperties for valid property names.

    • withConfiguration

      CamundaClientBuilder withConfiguration(CamundaClientConfiguration configuration)
      Sets the configuration from a CamundaClientConfiguration object. Can be used to configure a client from a base configuration.

    • applyEnvironmentVariableOverrides

      CamundaClientBuilder applyEnvironmentVariableOverrides(boolean applyEnvironmentVariableOverrides)
      Allows to disable the mechanism to override some properties by ENVIRONMENT VARIABLES. This is useful if a client shall be constructed for test cases or in an environment that wants to fully control properties (like Spring Boot).

      The default value is true.

    • restAddress

      CamundaClientBuilder restAddress(URI restAddress)
      Parameters:
      restAddress - the REST API address of a gateway that the client can connect to. The address must be an absolute URL, including the scheme.

      The default value is https://0.0.0.0:8080.

    • grpcAddress

      CamundaClientBuilder grpcAddress(URI grpcAddress)
      Parameters:
      grpcAddress - the gRPC address of a gateway that the client can connect to. The address must be an absolute URL, including the scheme.

      The default value is https://0.0.0.0:26500.

    • defaultTenantId

      CamundaClientBuilder defaultTenantId(String tenantId)
      Parameters:
      tenantId - the tenant identifier which is used for tenant-aware commands when no tenant identifier is set. The default value is CommandWithTenantStep.DEFAULT_TENANT_IDENTIFIER.

    • physicalTenantId

      CamundaClientBuilder physicalTenantId(String physicalTenantId)
      Parameters:
      physicalTenantId - the physical tenant identifier sent as the Camunda-Physical-Tenant gRPC metadata header on every outgoing call. When null the header is omitted and the gateway applies its own default.

    • prefixPhysicalTenantPath

      CamundaClientBuilder prefixPhysicalTenantPath(boolean prefixPhysicalTenantPath)
      Controls whether the client prefixes the REST base path with /physical-tenants/<id> when a physical tenant id is set (default true). Set to false to use the configured REST address verbatim — e.g. when a reverse proxy or a custom path layout already routes to the physical tenant. Has no effect on the gRPC Camunda-Physical-Tenant header, which is always sent when a physical tenant id is set.
      Parameters:
      prefixPhysicalTenantPath - whether to auto-prefix the REST base path per physical tenant

    • defaultJobWorkerTenantIds

      CamundaClientBuilder defaultJobWorkerTenantIds(List<String> tenantIds)
      Parameters:
      tenantIds - the tenant identifiers which are used for job-activation commands when no tenant identifiers are set. The default value contains only CommandWithTenantStep.DEFAULT_TENANT_IDENTIFIER.

    • defaultJobWorkerTenantFilter

      CamundaClientBuilder defaultJobWorkerTenantFilter(TenantFilter tenantFilter)
      The behavior to adopt when filtering jobs during activation by a given worker. See TenantFilter for possible values. The default value is TenantFilter.PROVIDED.
      Parameters:
      TenantFilter - the default filter to use for all workers

    • defaultJobWorkerMaxJobsActive

      CamundaClientBuilder defaultJobWorkerMaxJobsActive(int maxJobsActive)
      Parameters:
      maxJobsActive - Default value for JobWorkerBuilderStep1.JobWorkerBuilderStep3.maxJobsActive(int). Default value is 32.

    • numJobWorkerExecutionThreads

      CamundaClientBuilder numJobWorkerExecutionThreads(int numThreads)
      Parameters:
      numThreads - The number of threads for invocation of job workers. Default value is 1. Setting this value to 0 causes the client to reuse the scheduled executor for job handling (backward compatibility behavior).

    • jobWorkerExecutor

      @Deprecated default CamundaClientBuilder jobWorkerExecutor(ScheduledExecutorService executor)
      Deprecated.
      use jobWorkerSchedulingExecutor(ScheduledExecutorService, boolean) and jobHandlingExecutor(ExecutorService, boolean) instead
      Identical behavior as jobWorkerExecutor(ScheduledExecutorService,boolean), replaced in favor of more fine-grained configuration of job worker executors.

    • jobWorkerExecutor

      @Deprecated CamundaClientBuilder jobWorkerExecutor(ScheduledExecutorService executor, boolean takeOwnership)
      Deprecated.
      use jobWorkerSchedulingExecutor(ScheduledExecutorService, boolean) and jobHandlingExecutor(ExecutorService, boolean) instead
      Identical behavior as jobWorkerSchedulingExecutor(ScheduledExecutorService,boolean). Replaced in favor of more fine-grained configuration of job worker executors.

    • jobWorkerSchedulingExecutor

      default CamundaClientBuilder jobWorkerSchedulingExecutor(ScheduledExecutorService executor)
      Identical behavior as jobWorkerSchedulingExecutor(ScheduledExecutorService,boolean), but taking ownership of the executor by default. This means the given executor is closed when the client is closed.
      Parameters:
      executor - an executor service to use for scheduling job worker tasks
      See Also:

    • jobWorkerSchedulingExecutor

      CamundaClientBuilder jobWorkerSchedulingExecutor(ScheduledExecutorService executor, boolean takeOwnership)
      Allows passing a custom scheduled executor service that will be used for scheduling job worker tasks such as polling for new jobs.

      Note that job handling (i.e. executing the JobHandler) is done on a separate executor configured via jobHandlingExecutor(ExecutorService, boolean).

      If no job handling executor is provided, this scheduling executor will also be used for job handling. If no executor is provided here, a default scheduled executor will be created.

      Parameters:
      executor - an executor service to use for scheduling job worker tasks
      takeOwnership - if true, the executor will be closed when the client is closed otherwise, it's up to the caller to manage its lifecycle
      See Also:

    • jobHandlingExecutor

      default CamundaClientBuilder jobHandlingExecutor(ExecutorService executor)
      Identical behavior as jobHandlingExecutor(ExecutorService,boolean), but taking ownership of the executor by default. This means the given executor is closed when the client is closed.
      Parameters:
      executor - an executor service to use for handling jobs
      See Also:

    • jobHandlingExecutor

      CamundaClientBuilder jobHandlingExecutor(ExecutorService executor, boolean takeOwnership)
      Allows passing a custom executor service that will be used for handling jobs (i.e. executing the JobHandler). This executor is separate from the scheduling executor configured via jobWorkerSchedulingExecutor(ScheduledExecutorService, boolean).

      If no executor is provided here, the scheduling executor will also be used for job handling.

      When non-null, this setting override numJobWorkerExecutionThreads(int).

      Parameters:
      executor - an executor service to use for handling jobs
      takeOwnership - if true, the executor will be closed when the client is closed otherwise, it's up to the caller to manage its lifecycle

    • defaultJobWorkerName

      CamundaClientBuilder defaultJobWorkerName(String workerName)
      The name of the worker which is used when none is set for a job worker. Default is 'default'.

    • defaultJobTimeout

      CamundaClientBuilder defaultJobTimeout(Duration timeout)
      The timeout which is used when none is provided for a job worker. Default is 5 minutes.

    • defaultJobPollInterval

      CamundaClientBuilder defaultJobPollInterval(Duration pollInterval)
      The interval which a job worker is periodically polling for new jobs. Default is 100 milliseconds.

    • defaultMessageTimeToLive

      CamundaClientBuilder defaultMessageTimeToLive(Duration timeToLive)
      The time-to-live which is used when none is provided for a message. Default is 1 hour.

    • defaultRequestTimeout

      CamundaClientBuilder defaultRequestTimeout(Duration requestTimeout)
      The request timeout used if not overridden by the command. Default is 10 seconds.

    • defaultRequestTimeoutOffset

      CamundaClientBuilder defaultRequestTimeoutOffset(Duration requestTimeoutOffset)
      The request timeout client offset is used in commands where the defaultRequestTimeout(Duration) is also passed to the server. This ensures that the client timeout does not occur before the server timeout.

      The client-side timeout for these commands is calculated as the sum of defaultRequestTimeout and defaultRequestTimeoutOffset.

      Default is 1 second.

    • caCertificatePath

      CamundaClientBuilder caCertificatePath(String certificatePath)
      Path to a root CA certificate to be used instead of the certificate in the default default store.

    • credentialsProvider

      CamundaClientBuilder credentialsProvider(CredentialsProvider credentialsProvider)
      A custom CredentialsProvider which will be used to apply authentication credentials to requests.

    • keepAlive

      CamundaClientBuilder keepAlive(Duration keepAlive)
      Time interval between keep alive messages sent to the gateway. The default is 45 seconds.

    • withInterceptors

      CamundaClientBuilder withInterceptors(io.grpc.ClientInterceptor... interceptor)
      Custom implementations of the gRPC ClientInterceptor middleware API. The interceptors will be applied to every gRPC call that the client makes. More details can be found at invalid input: '{@link <a href="https://grpc.io/docs/guides/interceptors/">grpc.io</a>'}.

    • withChainHandlers

      CamundaClientBuilder withChainHandlers(org.apache.hc.client5.http.async.AsyncExecChainHandler... chainHandler)
      Custom implementations of the Apache HttpClient AsyncExecChainHandler middleware API. The middleware implementations will be called on every REST API call that the client makes.

    • withJsonMapper

      CamundaClientBuilder withJsonMapper(JsonMapper jsonMapper)

    • overrideAuthority

      CamundaClientBuilder overrideAuthority(String authority)
      Overrides the authority used with TLS virtual hosting. Specifically, to override hostname verification in the TLS handshake. It does not change what host is actually connected to.

      This method is intended for testing, but may safely be used outside of tests as an alternative to DNS overrides.

      This setting does nothing if a plaintext connection is used.

      Parameters:
      authority - The alternative authority to use, commonly in the form host or host:port

    • maxMessageSize

      CamundaClientBuilder maxMessageSize(int maxSize)
      A custom maxMessageSize allows the client to receive larger or smaller responses from Camunda. Technically, it specifies the maxInboundMessageSize of the gRPC channel. The default is 5242880 = 5MB.

    • maxMetadataSize

      CamundaClientBuilder maxMetadataSize(int maxSize)
      A custom maxMetadataSize allows the client to receive larger or smaller response headers from Camunda. Technically, it specifies the maxInboundMetadataSize of the gRPC channel. The default is 16384 = 16KB .

    • defaultJobWorkerStreamEnabled

      CamundaClientBuilder defaultJobWorkerStreamEnabled(boolean streamEnabled)
      A custom streamEnabled allows the client to use job stream instead of job poll. The default value is set as enabled.

    • useDefaultRetryPolicy

      CamundaClientBuilder useDefaultRetryPolicy(boolean useDefaultRetryPolicy)
      If enabled, the client will make use of the default retry policy defined. False by default.

      NOTE: the default retry policy is taken from the gateway-service-config.json in the io.camunda:zeebe-gateway-protocol-impl JAR.

    • preferRestOverGrpc

      CamundaClientBuilder preferRestOverGrpc(boolean preferRestOverGrpc)
      If true, will prefer to use REST over gRPC for calls which can be done over both REST and gRPC. The default value is true (REST is preferred).

      NOTE: job streaming is only supported via gRPC

      Parameters:
      preferRestOverGrpc - if true, the client will use REST instead of gRPC whenever possible

    • useClientSideLoadBalancing

      CamundaClientBuilder useClientSideLoadBalancing(boolean useClientSideLoadBalancing)
      If enabled, the client will use DNS-based name resolution and balance across all addresses. This allows the client to distribute requests across multiple gateway instances resolved by DNS without requiring an external load balancer.

      Default is false.

      Parameters:
      useClientSideLoadBalancing - if true, enables DNS resolution and randomized load balancing

    • maxHttpConnections

      CamundaClientBuilder maxHttpConnections(int maxConnections)
      Sets the maximum number of concurrent HTTP connections the client can open.

    • defaultJobWorkerExceptionHandler

      CamundaClientBuilder defaultJobWorkerExceptionHandler(JobExceptionHandler jobExceptionHandler)
      A custom retryBackoffSupplier allows the client to determine the default retry backoff strategy that every job worker will apply unless configured otherwise. By default, a static retry backoff of PT0S is used.
      Parameters:
      jobExceptionHandler - the retry backoff supplier to retrieve the retry backoff for every fail job command
      Returns:
      this builder for chaining

    • build

      CamundaClient build()
      Returns:
      a new CamundaClient with the provided configuration options.