Java SDK

TaskDaemon java sdk guide

Java SDK

The Java SDK for writing TaskDaemon handlers.

Installation

Add io.github.jona62:handler:0.1.2 from Maven Central to your application. The SDK requires Java 17 or later; Java package imports remain com.taskdaemon.

Maven

<dependency>
    <groupId>io.github.jona62</groupId>
    <artifactId>handler</artifactId>
    <version>0.1.2</version>
</dependency>

Gradle

plugins {
    id 'java'
}

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.github.jona62:handler:0.1.2'
}

Source build alternative

For a local source build from the same release:

git clone --branch v0.1.2 --depth 1 https://github.com/jona62/TaskDaemon-Handlers.git vendor/TaskDaemon-Handlers
mvn -B -f vendor/TaskDaemon-Handlers/java/pom.xml clean install

Gradle users choosing this local source build must add mavenLocal() before mavenCentral() in repositories.

For source-based Docker builds, install this pinned SDK in the builder before packaging your application.

Keep diagnostic logs on stderr; the handler protocol uses stdout for one response per task. A request starts with attempt: 1; retries require a valid retryable error and remaining stored budget.

Basic Usage

import com.taskdaemon.Handler;
import com.taskdaemon.Handler.*;
import java.util.Map;

public class MyHandler {
    public static void main(String[] args) throws Exception {
        Handler.run(task -> {
            String name = (String) task.task_data().getOrDefault("name", "World");
            return new Success(Map.of("message", "Hello, " + name + "!"));
        });
    }
}

Task Record

public record Task(
    String task_id,
    String task_type,
    Map<String, Object> task_data,
    int attempt  // Current attempt (starts at 1)
) {}

Result Types

// Sealed interface for type safety
public sealed interface Result permits Success, Error {}

// Success with result
public record Success(Object result) implements Result {}

// Error with message and retryable flag
public record Error(String error, boolean retryable) implements Result {}

Usage:

// Success
return new Success(Map.of("processed", true));

// Non-retryable error
return new Handler.Error("Invalid input", false);

// Retryable error
return new Handler.Error("Service unavailable", true);

Complete Example

import com.taskdaemon.Handler;
import com.taskdaemon.Handler.*;
import java.util.Map;
import java.util.Arrays;

public class WordCountHandler {
    public static void main(String[] args) throws Exception {
        Handler.run(task -> {
            String text = (String) task.task_data().getOrDefault("text", "");

            // Count words
            long words = Arrays.stream(text.split("\\s+"))
                .filter(s -> !s.isEmpty())
                .count();

            // Count characters (excluding spaces)
            long chars = text.chars()
                .filter(c -> !Character.isWhitespace(c))
                .count();

            // Count lines
            long lines = text.lines().count();

            return new Success(Map.of(
                "words", words,
                "characters", chars,
                "lines", lines
            ));
        });
    }
}

Error Handling

Exceptions are automatically caught and converted to non-retryable errors:

Handler.run(task -> {
    // If this throws, it becomes Error(exception.getMessage(), false)
    String required = (String) task.task_data().get("required");
    if (required == null) {
        throw new IllegalArgumentException("Missing required field");
    }
    return new Success(Map.of("value", required));
});

For explicit error handling:

Handler.run(task -> {
    if (!task.task_data().containsKey("required")) {
        return new Handler.Error("Missing required field", false);
    }

    try {
        var result = externalApiCall();
        return new Success(result);
    } catch (IOException e) {
        return new Handler.Error("API unavailable: " + e.getMessage(), true);
    }
});

Dockerfile

Save the complete example as src/main/java/WordCountHandler.java. Use this application pom.xml to compile for Java 17:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>taskdaemon-app</artifactId>
    <version>1.0.0</version>
    <properties>
        <maven.compiler.release>17</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
    <dependencies>
        <dependency>
            <groupId>io.github.jona62</groupId>
            <artifactId>handler</artifactId>
            <version>0.1.2</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.14.1</version>
            </plugin>
        </plugins>
    </build>
</project>

The Dockerfile runs WordCountHandler with the SDK and its runtime dependencies from Maven Central:

FROM maven:3.9-eclipse-temurin-21 AS builder
WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN mvn -q package dependency:copy-dependencies -DincludeScope=runtime -DskipTests

FROM eclipse-temurin:21-jre
COPY --from=builder /app/target/classes /app/classes
COPY --from=builder /app/target/dependency /app/lib
CMD ["java", "-cp", "/app/classes:/app/lib/*", "WordCountHandler"]

Change the main class to match your application, including its package name. GraalVM native builds require application-specific build configuration and Jackson reflection metadata; validate that build before substituting a native executable.

Handler Configuration

[handlers.wordcount]
image = "java-handler:latest"
instances = 4
timeout = 30

Requirements

• Java 17+ (uses records and sealed interfaces)
• Jackson for JSON serialization (included in SDK)