tessl/maven-io-temporal--temporal-sdk

Temporal Workflow Java SDK - A framework for authoring Workflows and Activities in Java

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Temporal Java SDK

Name: tessl/maven-io-temporal--temporal-sdk
Author: tessl

The Temporal Java SDK is a comprehensive framework for authoring reliable, scalable workflows and activities in Java. It provides type-safe APIs for building distributed applications that can withstand failures, handle retries, and manage complex business processes across multiple services and time scales.

Package Information

Package Name: temporal-sdk
Package Type: Maven
Language: Java
Installation:
```
<dependency>
    <groupId>io.temporal</groupId>
    <artifactId>temporal-sdk</artifactId>
    <version>1.31.0</version>
</dependency>
```

Core Imports

// Workflow client and service interaction
import io.temporal.client.WorkflowClient;
import io.temporal.client.WorkflowOptions;
import io.temporal.servicestubs.WorkflowServiceStubs;

// Workflow implementation
import io.temporal.workflow.Workflow;
import io.temporal.workflow.WorkflowInterface;
import io.temporal.workflow.WorkflowMethod;
import io.temporal.workflow.SignalMethod;
import io.temporal.workflow.QueryMethod;

// Activity implementation
import io.temporal.activity.Activity;
import io.temporal.activity.ActivityInterface;
import io.temporal.activity.ActivityMethod;
import io.temporal.activity.ActivityOptions;

// Worker management
import io.temporal.worker.Worker;
import io.temporal.worker.WorkerFactory;
import io.temporal.worker.WorkerOptions;

// Common configurations and exceptions
import io.temporal.common.RetryOptions;
import io.temporal.failure.ApplicationFailure;

Basic Usage

// Define a workflow interface
@WorkflowInterface
public interface HelloWorkflow {
    @WorkflowMethod
    String sayHello(String name);
}

// Define an activity interface
@ActivityInterface
public interface HelloActivity {
    @ActivityMethod
    String getGreeting(String name);
}

// Implement the workflow
public class HelloWorkflowImpl implements HelloWorkflow {
    private final HelloActivity activity = Workflow.newActivityStub(
        HelloActivity.class,
        ActivityOptions.newBuilder()
            .setStartToCloseTimeout(Duration.ofSeconds(30))
            .build()
    );

    @Override
    public String sayHello(String name) {
        return activity.getGreeting(name);
    }
}

// Implement the activity
public class HelloActivityImpl implements HelloActivity {
    @Override
    public String getGreeting(String name) {
        return "Hello, " + name + "!";
    }
}

// Start a workflow
public class Main {
    public static void main(String[] args) {
        // Create workflow client
        WorkflowServiceStubs service = WorkflowServiceStubs.newLocalServiceStubs();
        WorkflowClient client = WorkflowClient.newInstance(service);

        // Create worker
        WorkerFactory factory = WorkerFactory.newInstance(client);
        Worker worker = factory.newWorker("hello-task-queue");
        worker.registerWorkflowImplementationTypes(HelloWorkflowImpl.class);
        worker.registerActivitiesImplementations(new HelloActivityImpl());

        // Start worker
        factory.start();

        // Execute workflow
        HelloWorkflow workflow = client.newWorkflowStub(
            HelloWorkflow.class,
            WorkflowOptions.newBuilder()
                .setTaskQueue("hello-task-queue")
                .setWorkflowId("hello-workflow")
                .build()
        );

        String result = workflow.sayHello("World");
        System.out.println(result); // "Hello, World!"
    }
}

Architecture

The Temporal Java SDK is built around several key components:

Workflow Client: Central interface for starting workflows, managing executions, and interacting with the Temporal service
Workers: Execute workflow and activity code, polling task queues for work
Workflow Implementation: Contains business logic with deterministic execution guarantees
Activity Implementation: Handles external service calls and non-deterministic operations
Type-Safe Stubs: Generated proxies providing compile-time type safety for workflow and activity invocations
Failure Handling: Comprehensive exception hierarchy for retry logic and error propagation
Data Conversion: Pluggable serialization system for payload encoding and decoding

Capabilities

Activity Execution

Comprehensive APIs for implementing activities that handle external service calls, with built-in retry logic, heartbeat support, and async completion patterns.

// Core activity execution context
public final class Activity {
    public static ActivityExecutionContext getExecutionContext();
    public static RuntimeException wrap(Throwable e);
}

// Activity execution context with heartbeat and async completion
public interface ActivityExecutionContext {
    ActivityInfo getInfo();
    <V> void heartbeat(V details) throws ActivityCompletionException;
    <V> Optional<V> getHeartbeatDetails(Class<V> detailsClass);
    ManualActivityCompletionClient useLocalManualCompletion();
    void doNotCompleteOnReturn();
}

// Activity configuration options
public final class ActivityOptions {
    public static ActivityOptions.Builder newBuilder();
    // Builder methods for timeouts, retry options, task queue, etc.
}

Activity Execution and Configuration

Workflow Implementation

APIs for implementing workflow logic with deterministic execution, including timers, signals, queries, updates, and child workflows.

// Central workflow utility class
public final class Workflow {
    public static <T> T newActivityStub(Class<T> activityInterface, ActivityOptions options);
    public static <T> T newLocalActivityStub(Class<T> activityInterface, LocalActivityOptions options);
    public static <T> ChildWorkflowStub newChildWorkflowStub(Class<T> workflowInterface, ChildWorkflowOptions options);
    public static void sleep(Duration duration);
    public static long currentTimeMillis();
    public static Random newRandom();
    public static void continueAsNew(Object... args);
}

// Workflow interface annotations
@WorkflowInterface
@WorkflowMethod
@SignalMethod
@QueryMethod
@UpdateMethod

Workflow Implementation and Lifecycle

Service Interaction

Complete client APIs for workflow lifecycle management, including starting workflows, sending signals, executing queries and updates, and batch operations.

// Primary workflow client interface
public interface WorkflowClient {
    // Factory methods
    public static WorkflowClient newInstance(WorkflowServiceStubs service);
    public static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOptions options);

    // Workflow stub creation
    public <T> T newWorkflowStub(Class<T> workflowInterface, WorkflowOptions options);
    public <T> T newWorkflowStub(Class<T> workflowInterface, String workflowId);
    public WorkflowStub newUntypedWorkflowStub(String workflowType, WorkflowOptions options);

    // Static execution methods
    public static WorkflowExecution start(Func<R> workflow);
    public static <R> CompletableFuture<R> execute(Func<R> workflow);
}

// Workflow configuration options
public final class WorkflowOptions {
    public static WorkflowOptions.Builder newBuilder();
    // Builder methods for timeouts, retry options, task queue, etc.
}

WorkflowClient and Service Interaction

Worker Management

APIs for configuring and managing Temporal workers that execute workflow and activity code, with options for concurrency, task routing, and performance tuning.

// Worker factory for creating and managing workers
public interface WorkerFactory {
    public static WorkerFactory newInstance(WorkflowClient workflowClient);
    public Worker newWorker(String taskQueue);
    public Worker newWorker(String taskQueue, WorkerOptions options);
    public void start();
    public void shutdown();
    public void awaitTermination(long timeout, TimeUnit unit);
}

// Individual worker for executing workflows and activities
public interface Worker {
    public void registerWorkflowImplementationTypes(Class<?>... workflowImplementationClasses);
    public void registerActivitiesImplementations(Object... activityImplementations);
    public <R> void addWorkflowImplementationFactory(Class<R> workflowInterface, Func<R> factory);
}

// Worker configuration options
public final class WorkerOptions {
    public static WorkerOptions.Builder newBuilder();
    // Builder methods for concurrency limits, timeouts, tuning options
}

Worker Configuration and Management

Exception Handling

Comprehensive exception hierarchy for handling workflow and activity failures, with support for retries, timeouts, cancellation, and custom application failures.

// Base exception hierarchy
public class TemporalException extends RuntimeException { }
public class TemporalFailure extends TemporalException { }

// Specific failure types
public final class ActivityFailure extends TemporalFailure { }
public final class ApplicationFailure extends TemporalFailure {
    public static ApplicationFailure newFailure(String message, String type);
    public static ApplicationFailure newNonRetryableFailure(String message, String type);
}
public final class CanceledFailure extends TemporalFailure { }
public final class ChildWorkflowFailure extends TemporalFailure { }
public final class TimeoutFailure extends TemporalFailure { }
public final class TerminatedFailure extends TemporalFailure { }

Exception Hierarchy and Error Handling

Data Conversion

Pluggable payload conversion system for serializing workflow arguments, results, and signals with support for custom codecs and encryption.

// Core payload conversion interface
public interface PayloadConverter {
    public Optional<Payload> toData(Object value) throws DataConverterException;
    public <T> T fromData(Payload content, Class<T> valueClass, Type valueType) throws DataConverterException;
}

// Payload codec for encoding/decoding (encryption, compression)
public interface PayloadCodec {
    public List<Payload> encode(List<Payload> payloads);
    public List<Payload> decode(List<Payload> payloads);
}

// Serialization context for activities
public interface ActivitySerializationContext extends SerializationContext {
    public String getNamespace();
    public String getTaskQueue();
    public String getWorkflowId();
}

Payload Conversion and Serialization

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 2 months ago
Describes: pkg:maven/io.temporal/temporal-sdk@1.31.x
Publish Source: CLI
Badge