2. ArmoniK Java SDK — Client

2.1. Role of the Client SDK

The client SDK provides a language-friendly interface to interact with ArmoniK’s control plane. It allows you to:

• Create and manage sessions.

• Define and submit tasks, optionally with dependencies.

• Create and manage input and output blobs.

• Monitor task progress and retrieve results.

• Use optional asynchronous callback mechanisms.

• Ensure consistent workflow semantics: retries, error propagation, idempotency.

---

2.2. Entry Point: ArmoniKClient

The main entry point is ArmoniKClient, configured via ArmoniKConfig which describes:

• Endpoints

• TLS configuration

• Retry policy

Use try-with-resources for automatic cleanup:

try (ArmoniKClient client = new ArmoniKClient(config)) {
    // ...
}

Available operations on ArmoniKClient:

• Create a new Session

• Retrieve an existing Session

• Cancel a Session

• Close a Session

---

2.3. Session Creation

Define a session with SessionDefinition, then submit it to get a SessionHandle.

SessionDefinition components:

Component	Description
Partition IDs	Where tasks can execute
TaskConfiguration	Default configuration for all tasks
BlobCompletionListener	Callback when an output blob is COMPLETED or ABORTED

---

2.4. Blob Completion Listener

BlobCompletionListener is a callback interface for async result notifications. Register it in SessionDefinition to enable event-driven result handling.

BlobCompletionListener listener = new BlobCompletionListener() {
    @Override
    public void onBlobSuccess(Blob blob) { /* blob is ready */ }

    @Override
    public void onBlobError(BlobError error) { /* handle error */ }
};

---

2.5. Working with Blobs

Type	Description
InputBlobDefinition	Data sent to workers
OutputBlobDefinition	Placeholder for expected results
BlobHandle	Reference to an already uploaded/downloaded blob

Input data can come from:

• In-memory byte array

• File

• Custom source by implementing the BlobData interface

SessionHandle can also create session-scoped blobs directly.

---

2.6. Task Submission

Create a TaskDefinition specifying:

• Inputs: InputBlobDefinition or BlobHandle

• Outputs: OutputBlobDefinition

• Optional: override TaskConfiguration

• Optional: WorkerLibrary for dynamic loading

Submit it to SessionHandle. This is non-blocking and returns a TaskHandle immediately.

---

2.7. WorkerLibrary (Dynamic Loading)

WorkerLibrary describes a dynamically loaded worker library for task execution. It has three components:

Field	Description	Example
path	Path to the artifact inside the zip	"MyWorker.jar"
symbol	Fully qualified class name	"com.example.MyProcessor"
libraryHandle	BlobHandle referencing the uploaded library zip	—

---

2.8. Typical Workflow

1. Create ArmoniKClient with config
2. Create SessionDefinition (with partitions, TaskConfiguration, listener)
3. Open SessionHandle
4. Define InputBlobDefinition and OutputBlobDefinition
5. Create and submit TaskDefinition
6. Wait for completion or react to BlobCompletionListener callbacks
7. Read output blobs
8. Close session and client

---

2.9. Task Submission Flow (General)

1. The client creates a session to group related tasks.

2. Input data is uploaded as blobs.

3. The client defines one or more task definitions, each referencing:

   • input blobs (data dependencies)

   • expected output blobs

   • optional task configuration

4. Tasks are submitted to the control plane.

5. Workers execute tasks, read inputs, and produce outputs.

6. The control plane signals task completion.

7. The client retrieves output blobs or submits new tasks to continue the workflow.