Package io.camunda.zeebe.client.api.worker

Interface JobClient

All Known Subinterfaces:
ZeebeClient
All Known Implementing Classes:
JobClientImpl, ZeebeClientImpl
public interface JobClient
A client with access to all job-related operation:
  • complete a job
  • mark a job as failed
  • update the retries of a job

    • Method Details

      • newCompleteCommand

        CompleteJobCommandStep1 newCompleteCommand(long jobKey)
        Command to complete a job. 
         long jobKey = ..;

 jobClient
  .newCompleteCommand(jobKey)
  .variables(json)
  .send();

        If the job is linked to a process instance then this command will complete the related activity and continue the flow.

        Parameters:
        jobKey - the key which identifies the job
        Returns:
        a builder for the command

      • newCompleteCommand

        CompleteJobCommandStep1 newCompleteCommand(ActivatedJob job)
        Command to complete a job. 
         ActivatedJob job = ..;

 jobClient
  .newCompleteCommand(job)
  .variables(json)
  .send();

        If the job is linked to a process instance then this command will complete the related activity and continue the flow.

        Parameters:
        job - the activated job
        Returns:
        a builder for the command

      • newFailCommand

        FailJobCommandStep1 newFailCommand(long jobKey)
        Command to mark a job as failed. 
         long jobKey = ..;

 jobClient
  .newFailCommand(jobKey)
  .retries(3)
  .send();

        If the given retries are greater than zero then this job will be picked up again by a job subscription. Otherwise, an incident is created for this job.

        Parameters:
        jobKey - the key which identifies the job
        Returns:
        a builder for the command

      • newFailCommand

        FailJobCommandStep1 newFailCommand(ActivatedJob job)
        Command to mark a job as failed. 
         ActivatedJob job = ..;

 jobClient
  .newFailCommand(job)
  .retries(3)
  .send();

        If the given retries are greater than zero then this job will be picked up again by a job subscription. Otherwise, an incident is created for this job.

        Parameters:
        job - the activated job
        Returns:
        a builder for the command

      • newThrowErrorCommand

        ThrowErrorCommandStep1 newThrowErrorCommand(long jobKey)
        Command to report a business error (i.e. non-technical) that occurs while processing a job. 
         long jobKey = ...;
 String code = ...;

 jobClient
  .newThrowErrorCommand(jobKey)
  .errorCode(code)
  .send();

        The error is handled in the process by an error catch event. If there is no error catch event with the specified errorCode then an incident will be raised instead.

        Parameters:
        jobKey - the key which identifies the job
        Returns:
        a builder for the command

      • newThrowErrorCommand

        ThrowErrorCommandStep1 newThrowErrorCommand(ActivatedJob job)
        Command to report a business error (i.e. non-technical) that occurs while processing a job. 
         ActivatedJob job = ...;
 String code = ...;

 jobClient
  .newThrowErrorCommand(job)
  .errorCode(code)
  .send();

        The error is handled in the process by an error catch event. If there is no error catch event with the specified errorCode then an incident will be raised instead.

        Parameters:
        job - the activated job
        Returns:
        a builder for the command

      • newActivateJobsCommand

        ActivateJobsCommandStep1 newActivateJobsCommand()
        Command to activate multiple jobs of a given type. 
         jobClient
  .newActivateJobsCommand()
  .jobType("payment")
  .maxJobsToActivate(10)
  .workerName("paymentWorker")
  .timeout(Duration.ofMinutes(10))
  .send();

        The command will try to use maxJobsToActivate for given jobType. If less then the requested maxJobsToActivate jobs of the jobType are available for activation the returned list will have fewer elements.

        Returns:
        a builder for the command

      • newStreamJobsCommand

        @ExperimentalApi("https://github.com/camunda/zeebe/issues/11231") StreamJobsCommandStep1 newStreamJobsCommand()
        Activates and streams jobs of a specific type. 
        
 final Consumer<ActivatedJob> consumer = ...; // do something with the consumed job
 final ZeebeFuture<StreamJobsResponse> stream = jobClient
  .newStreamJobsCommand()
  .jobType("payment")
  .consumer(consumer)
  .workerName("paymentWorker")
  .timeout(Duration.ofMinutes(10))
  .send();

  stream.whenComplete((ok, error) -> {
    // recreate stream if necessary
    // be careful if you've cancelled the stream explicitly to not recreate it if shutting down
  });

  // You can later terminate the stream by cancelling the future
  stream.cancel(true);

        Stream or Activate?

        As opposed to newActivateJobsCommand(), which polls each partition until it has activated enough jobs or a timeout has elapsed, this command opens a long living stream onto which activated jobs are pushed. This typically results in lower latency, as jobs are activated and pushed out immediately, instead of waiting to be polled.

        Limitations

        This feature is still under development; as such, there is currently no way to rate limit how many jobs are streamed over a single call. This can be mitigated by opening more streams of the same type, which will ensure work is fairly load balanced.

        Additionally, only jobs which are created, retried, or timed out after the command has been registered will be streamed out. For older jobs, you must still use the newActivateJobsCommand(). It's generally recommended that you use the JobWorker API to avoid having to coordinate both calls.

        Activation

        Jobs activated via this command will use the given worker name, activation time out, and fetch variables parameters in the same way as the newActivateJobsCommand().

        Termination

        The stream can be explicitly cancelled by performing one of the following:

        NOTE: streams can be closed for various reasons - for example, the server is restarting. As such, it's recommended to add listeners to the resulting future to handle such cases and reopen streams if necessary.
        Returns:
        a builder for the command