Package io.camunda.zeebe.client.impl

Class ZeebeClientImpl

java.lang.Object
io.camunda.zeebe.client.impl.ZeebeClientImpl
All Implemented Interfaces:
JobClient, ZeebeClient, AutoCloseable
public final class ZeebeClientImpl extends Object implements ZeebeClient

  • Constructor Details

  • Method Details

    • buildChannel

      public static io.grpc.ManagedChannel buildChannel(ZeebeClientConfiguration config)

    • buildGatewayStub

      public static GatewayGrpc.GatewayStub buildGatewayStub(io.grpc.ManagedChannel channel, ZeebeClientConfiguration config)

    • newTopologyRequest

      public TopologyRequestStep1 newTopologyRequest()
      Description copied from interface: ZeebeClient
      Request the current cluster topology. Can be used to inspect which brokers are available at which endpoint and which broker is the leader of which partition. 
       List<BrokerInfo> brokers = zeebeClient
  .newTopologyRequest()
  .send()
  .join()
  .getBrokers();

  InetSocketAddress address = broker.getSocketAddress();

  List<PartitionInfo> partitions = broker.getPartitions();
      Specified by:
      newTopologyRequest in interface ZeebeClient
      Returns:
      the request where you must call send()

    • getConfiguration

      public ZeebeClientConfiguration getConfiguration()
      Specified by:
      getConfiguration in interface ZeebeClient
      Returns:
      the client's configuration

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface ZeebeClient

    • newDeployCommand

      public DeployProcessCommandStep1 newDeployCommand()
      Description copied from interface: ZeebeClient
      Command to deploy new processes. 
       zeebeClient
  .newDeployCommand()
  .addResourceFile("~/wf/process1.bpmn")
  .addResourceFile("~/wf/process2.bpmn")
  .send();
      Specified by:
      newDeployCommand in interface ZeebeClient
      Returns:
      a builder for the command

    • newDeployResourceCommand

      public DeployResourceCommandStep1 newDeployResourceCommand()
      Description copied from interface: ZeebeClient
      Command to deploy new resources, i.e. BPMN process models and DMN decision models. 
       zeebeClient
  .newDeployCommand()
  .addResourceFile("~/wf/process1.bpmn")
  .addResourceFile("~/wf/process2.bpmn")
  .addResourceFile("~/dmn/decision.dmn")
  .send();
      Specified by:
      newDeployResourceCommand in interface ZeebeClient
      Returns:
      a builder for the command

    • newCreateInstanceCommand

      public CreateProcessInstanceCommandStep1 newCreateInstanceCommand()
      Description copied from interface: ZeebeClient
      Command to create/start a new instance of a process. 
       zeebeClient
  .newCreateInstanceCommand()
  .bpmnProcessId("my-process")
  .latestVersion()
  .variables(json)
  .send();
      Specified by:
      newCreateInstanceCommand in interface ZeebeClient
      Returns:
      a builder for the command

    • newModifyProcessInstanceCommand

      public ModifyProcessInstanceCommandStep1 newModifyProcessInstanceCommand(long processInstanceKey)
      Description copied from interface: ZeebeClient
      Command to modify a process instance. 
         zeebeClient
    .newModifyProcessInstanceCommand(processInstanceKey)
    .activateElement("element1")
    .and()
    .activateElement("element2")
    .withVariables(globalScopedVariables)
    .withVariables(localScopedVariables, "element2")
    .and()
    .terminateElement("element3")
    .send();
      Specified by:
      newModifyProcessInstanceCommand in interface ZeebeClient
      Parameters:
      processInstanceKey - the key which identifies the corresponding process instance
      Returns:
      a builder for the command

    • newMigrateProcessInstanceCommand

      public MigrateProcessInstanceCommandStep1 newMigrateProcessInstanceCommand(long processInstanceKey)
      Description copied from interface: ZeebeClient
      Command to migrate a process instance to a different process definition.

      The migration command contains a migration plan. Migration plan contains targetProcessDefinitionKey to indicate which process definition to use for the migration. Mapping instructions for the migration describe how to map elements from the source process definition to the target process definition.

      For example, let's consider we want to migrate process instance with key 1, target process definition key 2, a source process definition with a service task with id "task1" and the target process definition with a service task with id "task2". The migration command could be: 

      
 {
  "processInstanceKey": 1,
  "migrationPlan": {
   "targetProcessDefinitionKey": 2,
   "mappingInstructions": [
    {
     "sourceElementId": "task1",
     "targetElementId": "task2"
    }
   ]
  }
 }
 
      
 zeebeClient
  .newMigrateProcessInstanceCommand(1L)
  .migrationPlan(2L)
  .addMappingInstruction("element1", "element2")
  .addMappingInstruction("element3", "element4")
  .send();
 
       final MigrationPlan migrationPlan =
         MigrationPlan.newBuilder()
             .withTargetProcessDefinitionKey(2L)
             .addMappingInstruction("element1", "element2")
             .addMappingInstruction("element3", "element4")
             .build();
 zeebeClient
  .newMigrateProcessInstanceCommand(1L)
  .migrationPlan(migrationPlan)
  .send();
      Specified by:
      newMigrateProcessInstanceCommand in interface ZeebeClient
      Parameters:
      processInstanceKey - the key which refers to the process instance to migrate
      Returns:
      a builder for the command

    • newCancelInstanceCommand

      public CancelProcessInstanceCommandStep1 newCancelInstanceCommand(long processInstanceKey)
      Description copied from interface: ZeebeClient
      Command to cancel a process instance. 
       zeebeClient
  .newCancelInstanceCommand(processInstanceKey)
  .send();
      Specified by:
      newCancelInstanceCommand in interface ZeebeClient
      Parameters:
      processInstanceKey - the key which identifies the corresponding process instance
      Returns:
      a builder for the command

    • newSetVariablesCommand

      public SetVariablesCommandStep1 newSetVariablesCommand(long elementInstanceKey)
      Description copied from interface: ZeebeClient
      Command to set and/or update the variables of a given flow element (e.g. process instance, task, etc.) 
       zeebeClient
  .newSetVariablesCommand(elementInstanceKey)
  .variables(json)
  .send();
      Specified by:
      newSetVariablesCommand in interface ZeebeClient
      Parameters:
      elementInstanceKey - the key of the element instance to set/update the variables for
      Returns:
      a builder for the command

    • newEvaluateDecisionCommand

      public EvaluateDecisionCommandStep1 newEvaluateDecisionCommand()
      Description copied from interface: ZeebeClient
      Command to evaluate a decision. 
       zeebeClient
  .newEvaluateDecisionCommand()
  .decisionKey("my-decision")
  .variables(json)
  .send();
      Specified by:
      newEvaluateDecisionCommand in interface ZeebeClient
      Returns:
      a builder for the command

    • newPublishMessageCommand

      public PublishMessageCommandStep1 newPublishMessageCommand()
      Description copied from interface: ZeebeClient
      Command to publish a message which can be correlated to a process instance. 
       zeebeClient
  .newPublishMessageCommand()
  .messageName("order canceled")
  .correlationKey(orderId)
  .variables(json)
  .send();
      Specified by:
      newPublishMessageCommand in interface ZeebeClient
      Returns:
      a builder for the command

    • newBroadcastSignalCommand

      public BroadcastSignalCommandStep1 newBroadcastSignalCommand()
      Description copied from interface: ZeebeClient
      Command to broadcast a signal. 
       zeebeClient
  .newBroadcastSignalCommand()
  .signalName("signal")
  .variables(json)
  .send();
      Specified by:
      newBroadcastSignalCommand in interface ZeebeClient
      Returns:
      a builder for the command

    • newResolveIncidentCommand

      public ResolveIncidentCommandStep1 newResolveIncidentCommand(long incidentKey)
      Description copied from interface: ZeebeClient
      Command to resolve an existing incident. 
       zeebeClient
  .newResolveIncidentCommand(incidentKey)
  .send();
      Specified by:
      newResolveIncidentCommand in interface ZeebeClient
      Parameters:
      incidentKey - the key of the corresponding incident
      Returns:
      the builder for the command

    • newUpdateRetriesCommand

      public UpdateRetriesJobCommandStep1 newUpdateRetriesCommand(long jobKey)
      Description copied from interface: ZeebeClient
      Command to update the retries of a job. 
       long jobKey = ..;

 zeebeClient
  .newUpdateRetriesCommand(jobKey)
  .retries(3)
  .send();

      If the given retries are greater than zero then this job will be picked up again by a job worker. This will not close a related incident, which still has to be marked as resolved with newResolveIncidentCommand(long incidentKey) .

      Specified by:
      newUpdateRetriesCommand in interface ZeebeClient
      Parameters:
      jobKey - the key of the job to update
      Returns:
      a builder for the command

    • newUpdateRetriesCommand

      public UpdateRetriesJobCommandStep1 newUpdateRetriesCommand(ActivatedJob job)
      Description copied from interface: ZeebeClient
      Command to update the retries of a job. 
       ActivatedJob job= ..;

 zeebeClient
  .newUpdateRetriesCommand(job)
  .retries(3)
  .send();

      If the given retries are greater than zero then this job will be picked up again by a job worker. This will not close a related incident, which still has to be marked as resolved with newResolveIncidentCommand(long incidentKey) .

      Specified by:
      newUpdateRetriesCommand in interface ZeebeClient
      Parameters:
      job - the activated job
      Returns:
      a builder for the command

    • newUpdateTimeoutCommand

      public UpdateTimeoutJobCommandStep1 newUpdateTimeoutCommand(long jobKey)
      Description copied from interface: ZeebeClient
      Command to update the timeout of a job. 
       long jobKey = ..;

 zeebeClient
  .newUpdateTimeoutCommand(jobKey)
  .timeout(100)
  .send();

      Timeout value in millis is used to calculate a new job deadline. This will happen when the command to update the timeline is processed. The timeout value will be added to the current time then.

      Specified by:
      newUpdateTimeoutCommand in interface ZeebeClient
      Parameters:
      jobKey - the key of the job to update
      Returns:
      a builder for the command

    • newUpdateTimeoutCommand

      public UpdateTimeoutJobCommandStep1 newUpdateTimeoutCommand(ActivatedJob job)
      Description copied from interface: ZeebeClient
      Command to update the timeout of a job. 
       ActivatedJob job= ..;

 zeebeClient
  .newUpdateTimeoutCommand(job)
  .timeout(100)
  .send();

      Timeout value in millis is used to calculate a new job deadline. This will happen when the command to update the timeline is processed. The timeout value will be added to the current time then.

      Specified by:
      newUpdateTimeoutCommand in interface ZeebeClient
      Parameters:
      job - the activated job
      Returns:
      a builder for the command

    • newWorker

      public JobWorkerBuilderStep1 newWorker()
      Description copied from interface: ZeebeClient
      Registers a new job worker for jobs of a given type.

      After registration, the broker activates available jobs and assigns them to this worker. It then publishes them to the client. The given worker is called for every received job, works on them and eventually completes them. 

       JobWorker worker = zeebeClient
  .newWorker()
  .jobType("payment")
  .handler(paymentHandler)
  .open();

 ...
 worker.close();
      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()
      .event(jobEvent)
      .variables(json)
      .send();
   }
 };
      Specified by:
      newWorker in interface ZeebeClient
      Returns:
      a builder for the worker registration

    • newDeleteResourceCommand

      public DeleteResourceCommandStep1 newDeleteResourceCommand(long resourceKey)
      Description copied from interface: ZeebeClient
      Command to delete a resource. 
       zeebeClient
  .newDeleteResourceCommand(resourceKey)
  .send();
      Specified by:
      newDeleteResourceCommand in interface ZeebeClient
      Parameters:
      resourceKey - the key of the resource
      Returns:
      the builder for the command

    • newUserTaskCompleteCommand

      public CompleteUserTaskCommandStep1 newUserTaskCompleteCommand(long userTaskKey)
      Description copied from interface: ZeebeClient
      Command to complete a user task. 
       long userTaskKey = ..;

 zeebeClient
  .newUserTaskCompleteCommand(userTaskKey)
  .variables(map)
  .send();

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

      This command is only sent via REST over HTTP, not via gRPC

      Experimental: This method is under development, and as such using it may have no effect on the client builder when called. Until this warning is removed, anything described below may not yet have taken effect, and the interface and its description are subject to change.

      Specified by:
      newUserTaskCompleteCommand in interface ZeebeClient
      Parameters:
      userTaskKey - the key of the user task
      Returns:
      a builder for the command

    • newUserTaskAssignCommand

      public AssignUserTaskCommandStep1 newUserTaskAssignCommand(long userTaskKey)
      Description copied from interface: ZeebeClient
      Command to assign a user task. 
       long userTaskKey = ..;

 zeebeClient
  .newUserTaskAssignCommand(userTaskKey)
  .assignee(newAssignee)
  .send();

      This command is only sent via REST over HTTP, not via gRPC

      Experimental: This method is under development, and as such using it may have no effect on the client builder when called. Until this warning is removed, anything described below may not yet have taken effect, and the interface and its description are subject to change.

      Specified by:
      newUserTaskAssignCommand in interface ZeebeClient
      Parameters:
      userTaskKey - the key of the user task
      Returns:
      a builder for the command

    • newUserTaskUpdateCommand

      public UpdateUserTaskCommandStep1 newUserTaskUpdateCommand(long userTaskKey)
      Description copied from interface: ZeebeClient
      Command to update a user task. 
       long userTaskKey = ..;

 zeebeClient
  .newUserTaskUpdateCommand(userTaskKey)
  .candidateGroups(newCandidateGroups)
  .send();

      This command is only sent via REST over HTTP, not via gRPC

      Experimental: This method is under development, and as such using it may have no effect on the client builder when called. Until this warning is removed, anything described below may not yet have taken effect, and the interface and its description are subject to change.

      Specified by:
      newUserTaskUpdateCommand in interface ZeebeClient
      Parameters:
      userTaskKey - the key of the user task
      Returns:
      a builder for the command

    • newUserTaskUnassignCommand

      public UnassignUserTaskCommandStep1 newUserTaskUnassignCommand(long userTaskKey)
      Description copied from interface: ZeebeClient
      Command to unassign a user task. 
       long userTaskKey = ..;

 zeebeClient
  .newUserTaskUnassignCommand(userTaskKey)
  .send();

      This command is only sent via REST over HTTP, not via gRPC

      Experimental: This method is under development, and as such using it may have no effect on the client builder when called. Until this warning is removed, anything described below may not yet have taken effect, and the interface and its description are subject to change.

      Specified by:
      newUserTaskUnassignCommand in interface ZeebeClient
      Parameters:
      userTaskKey - the key of the user task
      Returns:
      a builder for the command

    • newCompleteCommand

      public CompleteJobCommandStep1 newCompleteCommand(long jobKey)
      Description copied from interface: JobClient
      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.

      Specified by:
      newCompleteCommand in interface JobClient
      Parameters:
      jobKey - the key which identifies the job
      Returns:
      a builder for the command

    • newCompleteCommand

      public CompleteJobCommandStep1 newCompleteCommand(ActivatedJob job)
      Description copied from interface: JobClient
      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.

      Specified by:
      newCompleteCommand in interface JobClient
      Parameters:
      job - the activated job
      Returns:
      a builder for the command

    • newFailCommand

      public FailJobCommandStep1 newFailCommand(long jobKey)
      Description copied from interface: JobClient
      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.

      Specified by:
      newFailCommand in interface JobClient
      Parameters:
      jobKey - the key which identifies the job
      Returns:
      a builder for the command

    • newFailCommand

      public FailJobCommandStep1 newFailCommand(ActivatedJob job)
      Description copied from interface: JobClient
      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.

      Specified by:
      newFailCommand in interface JobClient
      Parameters:
      job - the activated job
      Returns:
      a builder for the command

    • newThrowErrorCommand

      public ThrowErrorCommandStep1 newThrowErrorCommand(long jobKey)
      Description copied from interface: JobClient
      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.

      Specified by:
      newThrowErrorCommand in interface JobClient
      Parameters:
      jobKey - the key which identifies the job
      Returns:
      a builder for the command

    • newThrowErrorCommand

      public ThrowErrorCommandStep1 newThrowErrorCommand(ActivatedJob job)
      Description copied from interface: JobClient
      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.

      Specified by:
      newThrowErrorCommand in interface JobClient
      Parameters:
      job - the activated job
      Returns:
      a builder for the command

    • newActivateJobsCommand

      public ActivateJobsCommandStep1 newActivateJobsCommand()
      Description copied from interface: JobClient
      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.

      Specified by:
      newActivateJobsCommand in interface JobClient
      Returns:
      a builder for the command

    • newStreamJobsCommand

      public StreamJobsCommandStep1 newStreamJobsCommand()
      Description copied from interface: JobClient
      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 JobClient.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 JobClient.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 JobClient.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.
      Specified by:
      newStreamJobsCommand in interface JobClient
      Returns:
      a builder for the command