Skip to main content

DBOS Client

DBOSClient provides a programmatic way to interact with your DBOS application from external code.

DBOSClient​

DBOSClient(String url, String user, String password)
DBOSClient(String url, String user, String password, String schema)
DBOSClient(DataSource dataSource)
DBOSClient(DataSource dataSource, String schema)

Construct the DBOSClient.

Parameters:

  • url: The JDBC URL for your system database.
  • user: Your Postgres username or role.
  • password: The password for your Postgres user or role.
  • schema: The schema the DBOS System Database tables are stored in. Defaults to dbos if not provided.
  • dataSource: System Database data source. A HikariDataSource is created if not provided.

Workflow Interaction Methods​

enqueueWorkflow​

<T, E extends Exception> WorkflowHandle<T, E> enqueueWorkflow(
      EnqueueOptions options, Object[] args)

Enqueue a workflow and return a handle to it.

Parameters:

  • options: Configuration for the enqueued workflow, as defined below.
  • args: An array of the workflow's arguments. These will be serialized and passed into the workflow when it is dequeued.

Example Syntax:

This code enqueues workflow exampleWorkflow in class com.example.ExampleImpl on queue example-queue with arguments argumentOne and argumentTwo.

var client = new DBOSClient(dbUrl, dbUser, dbPassword);
var options =
    new DBOSClient.EnqueueOptions(
        "com.example.ExampleImpl", "exampleWorkflow", "example-queue");
var handle = client.enqueueWorkflow(options, new Object[]{"argumentOne", "argumentTwo"});

EnqueueOptions​

EnqueueOptions is a with-based configuration record for parameterizing client.enqueueWorkflow.

Constructors:

public EnqueueOptions(String className, String workflowName, String queueName)

Specify the name and class name of the workflow to enqueue and the name of the queue on which it is to be enqueued.

Methods:

  • withInstanceName(String name): The enqueued workflow should run on this particular named class instance.
  • withWorkflowId(String workflowId): Specify the idempotency ID to assign to the enqueued workflow.
  • withAppVersion(String appVersion): The version of your application that should process this workflow. If left undefined, it will be updated to the current version when the workflow is first dequeued.
  • withTimeout(Duration timeout): Set a timeout for the enqueued workflow. When the timeout expires, the workflow and all its children are cancelled. The timeout does not begin until the workflow is dequeued and starts execution.
  • withDeadline(Instant deadline): Set a deadline for the enqueued workflow. If the workflow is executing when the deadline arrives, the workflow and all its children are cancelled.
info

Timeout and deadline cannot both be set

  • withDeduplicationId(String deduplicationId): At any given time, only one workflow with a specific deduplication ID can be enqueued in the specified queue. If a workflow with a deduplication ID is currently enqueued or actively executing (status ENQUEUED or PENDING), subsequent workflow enqueue attempt with the same deduplication ID in the same queue will raise an exception.
  • withPriority(Integer priority): The priority of the enqueued workflow in the specified queue. Workflows with the same priority are dequeued in FIFO (first in, first out) order. Priority values can range from 1 to 2,147,483,647, where a low number indicates a higher priority. Workflows without assigned priorities have the highest priority and are dequeued before workflows with assigned priorities.
  • withQueuePartitionKey(String partitionKey): Set a queue partition key for the workflow. Use if and only if the queue is partitioned (created with withPartitionedEnabled). In partitioned queues, all flow control (including concurrency and rate limits) is applied to individual partitions instead of the queue as a whole.
info
  • Partition keys are required when enqueueing to a partitioned queue.
  • Partition keys cannot be used with non-partitioned queues.
  • Partition keys and deduplication IDs cannot be used together.

send​

send(String destinationId, Object message, String topic, String idempotencyKey)

Similar to DBOS.send.

getEvent​

Object getEvent(String targetId, String key, Duration timeoutSeconds)

Similar to DBOS.getEvent.

Workflow Management Methods​

retrieveWorkflow​

WorkflowHandle<T, E> retrieveWorkflow(String workflowId)

Similar to DBOS.retrieveWorkflow.

getWorkflowStatus​

Optional<WorkflowStatus> getWorkflowStatus(String workflowId)

Retrieve the WorkflowStatus of a workflow.

listWorkflows​

List<WorkflowStatus> listWorkflows(ListWorkflowsInput input)

Similar to DBOS.listWorkflows.

listWorkflowSteps​

List<StepInfo> listWorkflowSteps(String workflowId)

Similar to DBOS.listWorkflowSteps.

cancelWorkflow​

void cancelWorkflow(String workflowId)

Similar to DBOS.cancelWorkflow.

resumeWorkflow​

<T, E extends Exception> WorkflowHandle<T, E> resumeWorkflow(String workflowId)

Similar to DBOS.resumeWorkflow.

forkWorkflow​

<T, E extends Exception> WorkflowHandle<T, E> forkWorkflow(
      String originalWorkflowId, int startStep, ForkOptions options)

Similar to DBOS.forkWorkflow.