Package io.camunda.client.impl.worker

Class JobWorkerBuilderImpl

java.lang.Object

io.camunda.client.impl.worker.JobWorkerBuilderImpl

All Implemented Interfaces:

CommandWithOneOrMoreTenantsStep<JobWorkerBuilderStep1.JobWorkerBuilderStep3>, CommandWithTenantStep<JobWorkerBuilderStep1.JobWorkerBuilderStep3>, JobWorkerBuilderStep1, JobWorkerBuilderStep1.JobWorkerBuilderStep2, JobWorkerBuilderStep1.JobWorkerBuilderStep3

public final class JobWorkerBuilderImpl
extends Object
implements JobWorkerBuilderStep1, JobWorkerBuilderStep1.JobWorkerBuilderStep2, JobWorkerBuilderStep1.JobWorkerBuilderStep3

Nested Class Summary

Nested classes/interfaces inherited from interface io.camunda.client.api.worker.JobWorkerBuilderStep1

JobWorkerBuilderStep1.JobWorkerBuilderStep2, JobWorkerBuilderStep1.JobWorkerBuilderStep3

Field Summary

Fields

Modifier and Type	Field	Description
static final BackoffSupplier	DEFAULT_BACKOFF_SUPPLIER
static final Duration	DEFAULT_STREAM_INACTIVITY_TIMEOUT
static final BackoffSupplier	DEFAULT_STREAM_NO_JOBS_BACKOFF_SUPPLIER
static final Duration	DEFAULT_STREAM_TIMEOUT

Fields inherited from interface io.camunda.client.api.command.CommandWithTenantStep

DEFAULT_TENANT_IDENTIFIER

Constructor Summary

Constructors

Constructor	Description
JobWorkerBuilderImpl(CamundaClientConfiguration configuration, JobClient jobClient, ScheduledExecutorService scheduledExecutor, ExecutorService jobHandlingExecutor, List<Closeable> closeables)

Method Summary

Modifier and Type	Method	Description
JobWorkerBuilderStep1.JobWorkerBuilderStep3	backoffSupplier(BackoffSupplier backoffSupplier)	Sets the backoff supplier.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	fetchVariables(String... fetchVariables)	Set a list of variable names which should be fetched on job activation.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	fetchVariables(List<String> fetchVariables)	Set a list of variable names which should be fetched on job activation.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	handler(JobHandler handler)	Set the handler to process the jobs.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	jobExceptionHandler(JobExceptionHandler jobExceptionHandler)	Sets the job exception handler to use for this worker.
JobWorkerBuilderStep1.JobWorkerBuilderStep2	jobType(String type)	Set the type of jobs to work on.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	maxJobsActive(int maxJobsActive)	Set the maximum number of jobs which will be exclusively activated for this worker at the same time.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	metrics(JobWorkerMetrics metrics)	Sets the job worker metrics implementation to use.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	name(String workerName)	Set the name of the worker owner.
JobWorker	open()	Open the worker and start to work on available tasks.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	pollInterval(Duration pollInterval)	Set the maximal interval between polling for new jobs.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	requestTimeout(Duration requestTimeout)	Set the request timeout for activate job request used to poll for new job.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	streamEnabled(boolean isStreamEnabled)	Opt-in feature flag to enable job streaming.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	streamInactivityTimeout(Duration timeout)	If streaming is enabled, sets the maximum duration the worker will wait without receiving any job on the open stream before cancelling and recreating it.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	streamNoJobsBackoffSupplier(BackoffSupplier streamNoJobsBackoffSupplier)	Sets the job activation backoff supplier to be used when polling yields no jobs, when streaming is enabled.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	streamTimeout(Duration timeout)	If streaming is enabled, sets a maximum lifetime for a given stream.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	tenantFilter(TenantFilter tenantFilter)	The behavior to adopt when filtering jobs during activation by this worker.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	tenantId(String tenantId)	Specifies the tenant that will own any entities (e.g. process definition, process instances, etc.) resulting from this command, or that owns any entities (e.g. jobs) referred to from this command.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	tenantIds(String... tenantIds)	Shorthand method for CommandWithOneOrMoreTenantsStep.tenantIds(List).
JobWorkerBuilderStep1.JobWorkerBuilderStep3	tenantIds(List<String> tenantIds)	Specifies the tenants that may own any entities (e.g. process definition, process instances, etc.) resulting from this command.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	timeout(long timeout)	Set the time for how long a job is exclusively assigned for this worker.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	timeout(Duration timeout)	Set the time for how long a job is exclusively assigned for this worker.
JobWorkerBuilderStep1.JobWorkerBuilderStep3	withLease(boolean withLease)	Activate the jobs polled by this worker with a lease.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_BACKOFF_SUPPLIER

public static final BackoffSupplier DEFAULT_BACKOFF_SUPPLIER

DEFAULT_STREAM_NO_JOBS_BACKOFF_SUPPLIER

public static final BackoffSupplier DEFAULT_STREAM_NO_JOBS_BACKOFF_SUPPLIER

DEFAULT_STREAM_TIMEOUT

public static final Duration DEFAULT_STREAM_TIMEOUT

DEFAULT_STREAM_INACTIVITY_TIMEOUT

public static final Duration DEFAULT_STREAM_INACTIVITY_TIMEOUT

Constructor Details

JobWorkerBuilderImpl

public JobWorkerBuilderImpl(CamundaClientConfiguration configuration,
 JobClient jobClient,
 ScheduledExecutorService scheduledExecutor,
 ExecutorService jobHandlingExecutor,
 List<Closeable> closeables)

Method Details

jobType

public JobWorkerBuilderStep1.JobWorkerBuilderStep2 jobType(String type)

Description copied from interface: JobWorkerBuilderStep1

Set the type of jobs to work on.

Specified by:

jobType in interface JobWorkerBuilderStep1

Parameters:

type - the type of jobs (e.g. "payment")

Returns:

the builder for this worker

handler

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 handler(JobHandler handler)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep2

Set the handler to process the jobs. At the end of the processing, the handler should complete the job or mark it as failed;

Example JobHandler implementation:

 public final class PaymentHandler implements JobHandler
 {
   @Override
   public void handle(JobClient client, JobEvent jobEvent)
   {
     String json = jobEvent.getVariables();
     // modify variables

     client
      .newCompleteCommand(jobEvent.getKey())
      .variables(json)
      .send();
   }
 };
 

The handler must be thread-safe.

Specified by:

handler in interface JobWorkerBuilderStep1.JobWorkerBuilderStep2

Parameters:

handler - the handle to process the jobs

Returns:

the builder for this worker

timeout

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 timeout(long timeout)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Set the time for how long a job is exclusively assigned for this worker.

In this time, the job can not be assigned by other workers to ensure that only one worker work on the job. When the time is over then the job can be assigned again by this or other worker if it's not completed yet.

If no timeout is set, then the default is used from the configuration.

Specified by:

timeout in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

timeout - the time in milliseconds

Returns:

the builder for this worker

timeout

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 timeout(Duration timeout)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Set the time for how long a job is exclusively assigned for this worker.

In this time, the job can not be assigned by other workers to ensure that only one worker work on the job. When the time is over then the job can be assigned again by this or other worker if it's not completed yet.

If no time is set then the default is used from the configuration.

Specified by:

timeout in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

timeout - the time as duration (e.g. "Duration.ofMinutes(5)")

Returns:

the builder for this worker

name

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 name(String workerName)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Set the name of the worker owner.

This name is used to identify the worker to which a job is exclusively assigned to.

If no name is set then the default is used from the configuration.

Specified by:

name in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

workerName - the name of the worker (e.g. "payment-service")

Returns:

the builder for this worker

maxJobsActive

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 maxJobsActive(int maxJobsActive)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Set the maximum number of jobs which will be exclusively activated for this worker at the same time.

This is used to control the backpressure of the worker. When the maximum is reached then the worker will stop activating new jobs in order to not overwhelm the client and give other workers the chance to work on the jobs. The worker will try to activate new jobs again when jobs are completed (or marked as failed).

If no maximum is set then the default, from the CamundaClientConfiguration, is used.

Considerations:

• A greater value can avoid situations in which the client waits idle for the broker to provide more jobs. This can improve the worker's throughput.
• The memory used by the worker is linear with respect to this value.
• The job's timeout starts to run down as soon as the broker pushes the job. Keep in mind that the following must hold to ensure fluent job handling: time spent in queue + time job handler needs until job completion invalid input: '<' job timeout

Specified by:

maxJobsActive in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

maxJobsActive - the maximum jobs active by this worker

Returns:

the builder for this worker

pollInterval

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 pollInterval(Duration pollInterval)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Set the maximal interval between polling for new jobs.

A job worker will automatically try to always activate new jobs after completing jobs. If no jobs can be activated after completing the worker will periodically poll for new jobs.

If no poll interval is set then the default is used from the CamundaClientConfiguration

Specified by:

pollInterval in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

pollInterval - the maximal interval to check for new jobs

Returns:

the builder for this worker

requestTimeout

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 requestTimeout(Duration requestTimeout)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Set the request timeout for activate job request used to poll for new job.

If no request timeout is set then the default is used from the CamundaClientConfiguration

NOTE: the request time out defined here is only applied to the activate jobs command, i.e. to polling for jobs, and is not applied to the job stream; use JobWorkerBuilderStep1.JobWorkerBuilderStep3.streamTimeout(Duration) for that.

Specified by:

requestTimeout in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

requestTimeout - the request timeout for activate jobs request

Returns:

the builder for this worker

fetchVariables

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 fetchVariables(List<String> fetchVariables)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Set a list of variable names which should be fetched on job activation.

The jobs which are activated by this worker will only contain variables from this list.

This can be used to limit the number of variables of the activated jobs.

Specified by:

fetchVariables in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

fetchVariables - list of variables names to fetch on activation

Returns:

the builder for this worker

fetchVariables

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 fetchVariables(String... fetchVariables)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Set a list of variable names which should be fetched on job activation.

The jobs which are activated by this worker will only contain variables from this list.

This can be used to limit the number of variables of the activated jobs.

Specified by:

fetchVariables in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

fetchVariables - list of variables names to fetch on activation

Returns:

the builder for this worker

withLease

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 withLease(boolean withLease)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Activate the jobs polled by this worker with a lease. When enabled, each activated job is assigned a distinct lease token, fencing the complete, fail, and throw-error commands against a superseded activation of the same job.

Only applies to the polling path. If not set, jobs are activated without a lease.

Specified by:

withLease in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

withLease - whether to activate the jobs with a lease

Returns:

the builder for this worker

backoffSupplier

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 backoffSupplier(BackoffSupplier backoffSupplier)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Sets the backoff supplier. The supplier is called to determine the retry delay after each failed request; the worker then waits until the returned delay has elapsed before sending the next request. Note that this is used only when activating jobs - failures in the JobHandler should be handled there, and retried there if need be.

By default, the supplier uses exponential back off, with an upper bound of 5 seconds. The exponential backoff can be easily configured using BackoffSupplier.newBackoffBuilder().

Specified by:

backoffSupplier in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

backoffSupplier - supplies the retry delay after a failed request

Returns:

the builder for this worker

streamNoJobsBackoffSupplier

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 streamNoJobsBackoffSupplier(BackoffSupplier streamNoJobsBackoffSupplier)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Sets the job activation backoff supplier to be used when polling yields no jobs, when streaming is enabled. The supplier is called to determine the backoff delay after a successful poll request with no activated jobs when job streaming is enabled; the worker then waits until the returned delay has elapsed before sending the next poll request.

Note, this is used only when streaming is enabled.

By default, the supplier uses exponential back off, with an upper bound of 1 minute. The exponential backoff can be easily configured using BackoffSupplier.newBackoffBuilder().

Specified by:

streamNoJobsBackoffSupplier in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

streamNoJobsBackoffSupplier - supplies the backoff delay after a successful poll request

Returns:

the builder for this worker

streamEnabled

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 streamEnabled(boolean isStreamEnabled)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Opt-in feature flag to enable job streaming. If set as enabled, the job worker will use a mix of streaming and polling to activate jobs. A long living stream will be opened onto which jobs will be eagerly pushed, and the polling mechanism will be used strictly to fetch jobs created before any streams were opened.

If the stream is closed, e.g. the server closed the connection, was restarted, etc., it will be immediately recreated as long as the worker is opened.

Specified by:

streamEnabled in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Returns:

the builder for this worker

streamTimeout

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 streamTimeout(Duration timeout)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

If streaming is enabled, sets a maximum lifetime for a given stream. Once this timeout is reached, the stream is closed, such that no more jobs are activated and received. If the worker is still open, then it will immediately open a new stream.

With no timeout, the stream will live as long as the client, or until the server closes the connection.

It's recommended to set a relatively long timeout, to allow for streams to load balance properly across your gateways.

Specified by:

streamTimeout in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

timeout - a timeout, after which the stream is recreated

Returns:

the builder for this worker

streamInactivityTimeout

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 streamInactivityTimeout(Duration timeout)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

If streaming is enabled, sets the maximum duration the worker will wait without receiving any job on the open stream before cancelling and recreating it. The timer is reset every time a job is received.

This acts as an application-level liveness check on top of the transport-level HTTP/2 keepalive: it detects silent stalls where the transport is healthy but the stream is no longer producing jobs (for example, because an intermediary proxy keeps the socket warm while the broker-side handler has stopped pushing).

Must be strictly less than JobWorkerBuilderStep1.JobWorkerBuilderStep3.streamTimeout(Duration) when both are configured. Pass null to disable the inactivity watchdog.

Specified by:

streamInactivityTimeout in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

timeout - duration of inactivity after which the stream is cancelled and recreated, or null to disable

Returns:

the builder for this worker

metrics

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 metrics(JobWorkerMetrics metrics)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Sets the job worker metrics implementation to use. See JobWorkerMetrics for more. Defaults to JobWorkerMetrics.noop(), an implementation which simply does nothing.

Specified by:

metrics in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

metrics - the implementation to use

Returns:

the builder for this worker

jobExceptionHandler

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 jobExceptionHandler(JobExceptionHandler jobExceptionHandler)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Sets the job exception handler to use for this worker. See JobExceptionHandler for more. Defaults to CamundaClientBuilder.defaultJobWorkerExceptionHandler(JobExceptionHandler).

Specified by:

jobExceptionHandler in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

jobExceptionHandler - the retry backoff supplier to use

Returns:

the builder for this worker

tenantFilter

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 tenantFilter(TenantFilter tenantFilter)

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

The behavior to adopt when filtering jobs during activation by this worker. See TenantFilter for possible values. Defaults to

invalid @link

{@link *

io.camunda.client.CamundaClientBuilder#defaultJobWorkerTenantFilter(tenantFilter)}.

Specified by:

tenantFilter in interface CommandWithOneOrMoreTenantsStep<JobWorkerBuilderStep1.JobWorkerBuilderStep3>

Specified by:

tenantFilter in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Parameters:

tenantFilter - the default filter to use for all workers

Returns:

the builder for this command with the tenant filter specified

open

public JobWorker open()

Description copied from interface: JobWorkerBuilderStep1.JobWorkerBuilderStep3

Open the worker and start to work on available tasks.

Specified by:

open in interface JobWorkerBuilderStep1.JobWorkerBuilderStep3

Returns:

the worker

tenantId

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 tenantId(String tenantId)

Description copied from interface: CommandWithOneOrMoreTenantsStep

Specifies the tenant that will own any entities (e.g. process definition, process instances, etc.) resulting from this command, or that owns any entities (e.g. jobs) referred to from this command.

Multi-tenancy

Multiple tenants can share a Camunda cluster. Entities can be assigned to a specific tenant using an identifier. Only that tenant can access these entities.

Any entities created before multi-tenancy has been enabled in the Camunda cluster, are assigned to the CommandWithTenantStep.DEFAULT_TENANT_IDENTIFIER.

If no tenant is explicitly specified, then the command is rejected.

One or more tenants

This method can be called multiple times to specify multiple tenants.

This can be useful when requesting jobs for multiple tenants at once. Each of the activated jobs will be owned by the tenant that owns the corresponding process instance.

Note: when TenantFilter is set to TenantFilter.ASSIGNED the tenant IDs provided via this method are ignored and the tenants assigned to the authenticated principal are resolved dynamically.

Specified by:

tenantId in interface CommandWithOneOrMoreTenantsStep<JobWorkerBuilderStep1.JobWorkerBuilderStep3>

Specified by:

tenantId in interface CommandWithTenantStep<JobWorkerBuilderStep1.JobWorkerBuilderStep3>

Parameters:

tenantId - the identifier of the tenant to specify for this command, e.g. "ACME"

Returns:

the builder for this command with the tenant specified

tenantIds

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 tenantIds(List<String> tenantIds)

Description copied from interface: CommandWithOneOrMoreTenantsStep

Specifies the tenants that may own any entities (e.g. process definition, process instances, etc.) resulting from this command.

One or more tenants

This can be useful when requesting jobs for multiple tenants at once. Each of the activated jobs will be owned by the tenant that owns the corresponding process instance.

Note: when TenantFilter is set to TenantFilter.ASSIGNED the tenant IDs provided via this method are ignored and the tenants assigned to the authenticated principal are resolved dynamically.

Specified by:

tenantIds in interface CommandWithOneOrMoreTenantsStep<JobWorkerBuilderStep1.JobWorkerBuilderStep3>

Parameters:

tenantIds - the identifiers of the tenants to specify for this command, e.g. ["ACME", "OTHER"]

Returns:

the builder for this command with the tenants specified

See Also:

• CommandWithOneOrMoreTenantsStep.tenantId(String)

tenantIds

public JobWorkerBuilderStep1.JobWorkerBuilderStep3 tenantIds(String... tenantIds)

Description copied from interface: CommandWithOneOrMoreTenantsStep

Shorthand method for CommandWithOneOrMoreTenantsStep.tenantIds(List).

Note: when TenantFilter is set to TenantFilter.ASSIGNED the tenant IDs provided via this method are ignored and the tenants assigned to the authenticated principal are resolved dynamically.

Specified by:

tenantIds in interface CommandWithOneOrMoreTenantsStep<JobWorkerBuilderStep1.JobWorkerBuilderStep3>

Parameters:

tenantIds - the identifiers of the tenants to specify for this command, e.g. ["ACME", "OTHER"]

Returns:

the builder for this command with the tenants specified

See Also:

• CommandWithOneOrMoreTenantsStep.tenantIds(List)