Skip to main content
The InfiniticClient class is the main entry point for interacting with Infinitic from your application. It allows you to start workflows, retrieve workflow instances, manage workflow execution, and complete delegated tasks.

​
Package

io.infinitic.clients.InfiniticClient

​
Constructor

​
config
InfiniticClientConfigInterface
required
The client configuration including transport settings

​
Creation Methods

The InfiniticClient provides several static factory methods for creating instances:

​
From Builder

val client = InfiniticClient.builder()
  .setTransport(transportConfig)
  .setName("my-client")
  .build()

​
From YAML

​
fromYamlResource
InfiniticClient
Creates a client from YAML files in the resources directoryParameters:
  • resources: String... - Resource paths
Example:
val client = InfiniticClient.fromYamlResource(
  "infinitic.yml"
)
​
fromYamlFile
InfiniticClient
Creates a client from YAML files in the file systemParameters:
  • files: String... - File paths
Example:
val client = InfiniticClient.fromYamlFile(
  "/etc/infinitic/client.yml"
)
​
fromYamlString
InfiniticClient
Creates a client from YAML stringsParameters:
  • yamls: String... - YAML content strings

​
Instance Methods

​
Workflow Management

​
newWorkflow
<T> T
Creates a stub for starting a new workflow instanceParameters:
  • klass: Class<out T> - The workflow interface class
  • tags: Set<String>? - Optional tags for the workflow (default: null)
  • meta: Map<String, ByteArray>? - Optional metadata (default: null)
Returns: A proxy stub for the workflowExample:
val workflow = client.newWorkflow(
  BookingWorkflow::class.java,
  tags = setOf("high-priority"),
  meta = mapOf("region" to "us-east".toByteArray())
)
​
getWorkflowById
<T> T
Gets a stub for an existing workflow by IDParameters:
  • klass: Class<out T> - The workflow interface class
  • id: String - The workflow instance ID
Returns: A proxy stub for the existing workflowExample:
val workflow = client.getWorkflowById(
  BookingWorkflow::class.java,
  "550e8400-e29b-41d4-a716-446655440000"
)
​
getWorkflowByTag
<T> T
Gets a stub for existing workflows by tagParameters:
  • klass: Class<out T> - The workflow interface class
  • tag: String - The workflow tag
Returns: A proxy stub targeting workflows with the given tagExample:
val workflow = client.getWorkflowByTag(
  BookingWorkflow::class.java,
  "booking-12345"
)

​
Starting Workflows

​
startAsync
<R> CompletableFuture<Deferred<R>>
Starts a workflow method asynchronouslyParameters:
  • invoke: () -> R - Lambda invoking the workflow method
Returns: A CompletableFuture containing a Deferred for the resultExample:
val workflow = client.newWorkflow(BookingWorkflow::class.java)
val future = client.startAsync { workflow.processBooking("booking-123") }
val deferred = future.join()
val result = deferred.await()
​
startVoidAsync
CompletableFuture<Deferred<Void>>
Starts a void workflow method asynchronouslyParameters:
  • invoke: () -> Unit - Lambda invoking the workflow method
Returns: A CompletableFuture containing a Deferred<Void>

​
Workflow Control

​
cancelAsync
CompletableFuture<Unit>
Cancels a running workflowParameters:
  • stub: Any - The workflow stub (must be from getWorkflowById or getWorkflowByTag)
Returns: A CompletableFuture that completes when the cancellation is processedExample:
val workflow = client.getWorkflowById(
  BookingWorkflow::class.java,
  workflowId
)
client.cancelAsync(workflow).join()
​
retryWorkflowTaskAsync
CompletableFuture<Unit>
Retries the current workflow taskParameters:
  • stub: Any - The workflow stub
Returns: A CompletableFuture that completes when retry is scheduled
​
retryTasksAsync
CompletableFuture<Unit>
Retries tasks within a workflowOverloads:
  • retryTasksAsync(stub: Any, taskId: String) - Retry specific task by ID
  • retryTasksAsync(stub: Any, taskStatus: DeferredStatus?, taskClass: Class<*>?) - Retry tasks by status and/or class
Parameters:
  • stub: Any - The workflow stub
  • taskId: String - The task ID to retry
  • taskStatus: DeferredStatus? - Filter by task status (FAILED, CANCELED, etc.)
  • taskClass: Class<*>? - Filter by task class
Example:
// Retry all failed payment tasks
client.retryTasksAsync(
  workflow,
  DeferredStatus.FAILED,
  PaymentService::class.java
).join()
​
completeTimersAsync
CompletableFuture<Unit>
Manually completes timers within a workflowParameters:
  • stub: Any - The workflow stub
  • id: String? - Optional workflow method ID to target specific timers
Returns: A CompletableFuture that completes when timers are completed

​
Delegated Tasks

​
completeDelegatedTaskAsync
CompletableFuture<Unit>
Completes a delegated task from an external systemParameters:
  • serviceName: String - The service name
  • taskId: String - The task ID (from Task.taskId)
  • result: Any? - The task result
Returns: A CompletableFuture that completes when the task is marked completeExample:
// In external system after processing
client.completeDelegatedTaskAsync(
  "PaymentService",
  taskId,
  PaymentResult(success = true)
).join()

​
Query Methods

​
getIds
<T> Set<String>
Gets all workflow IDs associated with a tagParameters:
  • stub: T - The workflow stub (must be from getWorkflowByTag)
Returns: Set of workflow IDsExample:
val workflow = client.getWorkflowByTag(
  BookingWorkflow::class.java,
  "customer-12345"
)
val ids = client.getIds(workflow)
println("Found ${ids.size} workflows for customer")

​
Properties

​
lastDeferred
Deferred<*>?
Gets the last Deferred created by calling a stub methodExample:
val workflow = client.newWorkflow(BookingWorkflow::class.java)
workflow.processBooking("booking-123") // Dispatches workflow
val deferred = client.lastDeferred // Get the Deferred
​
getName
String
Gets the client name (used for message routing)

​
Lifecycle

​
close
Unit
Closes the client and releases resourcesExample:
client.use { client ->
  // Use client
} // Automatically closed

​
Usage Example

import io.infinitic.clients.InfiniticClient
import java.time.Duration

fun main() {
  // Create client from configuration
  val client = InfiniticClient.fromYamlResource("infinitic.yml")
  
  try {
    // Start a new workflow
    val workflow = client.newWorkflow(
      BookingWorkflow::class.java,
      tags = setOf("customer-12345")
    )
    
    val deferred = client.startAsync {
      workflow.processBooking("booking-789")
    }.join()
    
    println("Workflow started: ${deferred.id}")
    
    // Wait for result (with timeout)
    val result = deferred.await()
    println("Booking result: $result")
    
    // Query workflows by tag
    val taggedWorkflow = client.getWorkflowByTag(
      BookingWorkflow::class.java,
      "customer-12345"
    )
    val workflowIds = client.getIds(taggedWorkflow)
    println("Customer has ${workflowIds.size} workflows")
    
  } finally {
    client.close()
  }
}

​
Thread Safety

The InfiniticClient is thread-safe and can be shared across multiple threads. It’s recommended to create a single instance and reuse it throughout your application.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us