0
# Temporal Java SDK
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: temporal-sdk
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**:
10
```xml
11
<dependency>
12
<groupId>io.temporal</groupId>
13
<artifactId>temporal-sdk</artifactId>
14
<version>1.31.0</version>
15
</dependency>
16
```
17
18
## Core Imports
19
20
```java
21
// Workflow client and service interaction
22
import io.temporal.client.WorkflowClient;
23
import io.temporal.client.WorkflowOptions;
24
import io.temporal.servicestubs.WorkflowServiceStubs;
25
26
// Workflow implementation
27
import io.temporal.workflow.Workflow;
28
import io.temporal.workflow.WorkflowInterface;
29
import io.temporal.workflow.WorkflowMethod;
30
import io.temporal.workflow.SignalMethod;
31
import io.temporal.workflow.QueryMethod;
32
33
// Activity implementation
34
import io.temporal.activity.Activity;
35
import io.temporal.activity.ActivityInterface;
36
import io.temporal.activity.ActivityMethod;
37
import io.temporal.activity.ActivityOptions;
38
39
// Worker management
40
import io.temporal.worker.Worker;
41
import io.temporal.worker.WorkerFactory;
42
import io.temporal.worker.WorkerOptions;
43
44
// Common configurations and exceptions
45
import io.temporal.common.RetryOptions;
46
import io.temporal.failure.ApplicationFailure;
47
```
48
49
## Basic Usage
50
51
```java
52
// Define a workflow interface
53
@WorkflowInterface
54
public interface HelloWorkflow {
55
@WorkflowMethod
56
String sayHello(String name);
57
}
58
59
// Define an activity interface
60
@ActivityInterface
61
public interface HelloActivity {
62
@ActivityMethod
63
String getGreeting(String name);
64
}
65
66
// Implement the workflow
67
public class HelloWorkflowImpl implements HelloWorkflow {
68
private final HelloActivity activity = Workflow.newActivityStub(
69
HelloActivity.class,
70
ActivityOptions.newBuilder()
71
.setStartToCloseTimeout(Duration.ofSeconds(30))
72
.build()
73
);
74
75
@Override
76
public String sayHello(String name) {
77
return activity.getGreeting(name);
78
}
79
}
80
81
// Implement the activity
82
public class HelloActivityImpl implements HelloActivity {
83
@Override
84
public String getGreeting(String name) {
85
return "Hello, " + name + "!";
86
}
87
}
88
89
// Start a workflow
90
public class Main {
91
public static void main(String[] args) {
92
// Create workflow client
93
WorkflowServiceStubs service = WorkflowServiceStubs.newLocalServiceStubs();
94
WorkflowClient client = WorkflowClient.newInstance(service);
95
96
// Create worker
97
WorkerFactory factory = WorkerFactory.newInstance(client);
98
Worker worker = factory.newWorker("hello-task-queue");
99
worker.registerWorkflowImplementationTypes(HelloWorkflowImpl.class);
100
worker.registerActivitiesImplementations(new HelloActivityImpl());
101
102
// Start worker
103
factory.start();
104
105
// Execute workflow
106
HelloWorkflow workflow = client.newWorkflowStub(
107
HelloWorkflow.class,
108
WorkflowOptions.newBuilder()
109
.setTaskQueue("hello-task-queue")
110
.setWorkflowId("hello-workflow")
111
.build()
112
);
113
114
String result = workflow.sayHello("World");
115
System.out.println(result); // "Hello, World!"
116
}
117
}
118
```
119
120
## Architecture
121
122
The Temporal Java SDK is built around several key components:
123
124
- **Workflow Client**: Central interface for starting workflows, managing executions, and interacting with the Temporal service
125
- **Workers**: Execute workflow and activity code, polling task queues for work
126
- **Workflow Implementation**: Contains business logic with deterministic execution guarantees
127
- **Activity Implementation**: Handles external service calls and non-deterministic operations
128
- **Type-Safe Stubs**: Generated proxies providing compile-time type safety for workflow and activity invocations
129
- **Failure Handling**: Comprehensive exception hierarchy for retry logic and error propagation
130
- **Data Conversion**: Pluggable serialization system for payload encoding and decoding
131
132
## Capabilities
133
134
### Activity Execution
135
136
Comprehensive APIs for implementing activities that handle external service calls, with built-in retry logic, heartbeat support, and async completion patterns.
137
138
```java { .api }
139
// Core activity execution context
140
public final class Activity {
141
public static ActivityExecutionContext getExecutionContext();
142
public static RuntimeException wrap(Throwable e);
143
}
144
145
// Activity execution context with heartbeat and async completion
146
public interface ActivityExecutionContext {
147
ActivityInfo getInfo();
148
<V> void heartbeat(V details) throws ActivityCompletionException;
149
<V> Optional<V> getHeartbeatDetails(Class<V> detailsClass);
150
ManualActivityCompletionClient useLocalManualCompletion();
151
void doNotCompleteOnReturn();
152
}
153
154
// Activity configuration options
155
public final class ActivityOptions {
156
public static ActivityOptions.Builder newBuilder();
157
// Builder methods for timeouts, retry options, task queue, etc.
158
}
159
```
160
161
[Activity Execution and Configuration](./activities.md)
162
163
### Workflow Implementation
164
165
APIs for implementing workflow logic with deterministic execution, including timers, signals, queries, updates, and child workflows.
166
167
```java { .api }
168
// Central workflow utility class
169
public final class Workflow {
170
public static <T> T newActivityStub(Class<T> activityInterface, ActivityOptions options);
171
public static <T> T newLocalActivityStub(Class<T> activityInterface, LocalActivityOptions options);
172
public static <T> ChildWorkflowStub newChildWorkflowStub(Class<T> workflowInterface, ChildWorkflowOptions options);
173
public static void sleep(Duration duration);
174
public static long currentTimeMillis();
175
public static Random newRandom();
176
public static void continueAsNew(Object... args);
177
}
178
179
// Workflow interface annotations
180
@WorkflowInterface
181
@WorkflowMethod
182
@SignalMethod
183
@QueryMethod
184
@UpdateMethod
185
```
186
187
[Workflow Implementation and Lifecycle](./workflows.md)
188
189
### Service Interaction
190
191
Complete client APIs for workflow lifecycle management, including starting workflows, sending signals, executing queries and updates, and batch operations.
192
193
```java { .api }
194
// Primary workflow client interface
195
public interface WorkflowClient {
196
// Factory methods
197
public static WorkflowClient newInstance(WorkflowServiceStubs service);
198
public static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOptions options);
199
200
// Workflow stub creation
201
public <T> T newWorkflowStub(Class<T> workflowInterface, WorkflowOptions options);
202
public <T> T newWorkflowStub(Class<T> workflowInterface, String workflowId);
203
public WorkflowStub newUntypedWorkflowStub(String workflowType, WorkflowOptions options);
204
205
// Static execution methods
206
public static WorkflowExecution start(Func<R> workflow);
207
public static <R> CompletableFuture<R> execute(Func<R> workflow);
208
}
209
210
// Workflow configuration options
211
public final class WorkflowOptions {
212
public static WorkflowOptions.Builder newBuilder();
213
// Builder methods for timeouts, retry options, task queue, etc.
214
}
215
```
216
217
[WorkflowClient and Service Interaction](./client.md)
218
219
### Worker Management
220
221
APIs for configuring and managing Temporal workers that execute workflow and activity code, with options for concurrency, task routing, and performance tuning.
222
223
```java { .api }
224
// Worker factory for creating and managing workers
225
public interface WorkerFactory {
226
public static WorkerFactory newInstance(WorkflowClient workflowClient);
227
public Worker newWorker(String taskQueue);
228
public Worker newWorker(String taskQueue, WorkerOptions options);
229
public void start();
230
public void shutdown();
231
public void awaitTermination(long timeout, TimeUnit unit);
232
}
233
234
// Individual worker for executing workflows and activities
235
public interface Worker {
236
public void registerWorkflowImplementationTypes(Class<?>... workflowImplementationClasses);
237
public void registerActivitiesImplementations(Object... activityImplementations);
238
public <R> void addWorkflowImplementationFactory(Class<R> workflowInterface, Func<R> factory);
239
}
240
241
// Worker configuration options
242
public final class WorkerOptions {
243
public static WorkerOptions.Builder newBuilder();
244
// Builder methods for concurrency limits, timeouts, tuning options
245
}
246
```
247
248
[Worker Configuration and Management](./workers.md)
249
250
### Exception Handling
251
252
Comprehensive exception hierarchy for handling workflow and activity failures, with support for retries, timeouts, cancellation, and custom application failures.
253
254
```java { .api }
255
// Base exception hierarchy
256
public class TemporalException extends RuntimeException { }
257
public class TemporalFailure extends TemporalException { }
258
259
// Specific failure types
260
public final class ActivityFailure extends TemporalFailure { }
261
public final class ApplicationFailure extends TemporalFailure {
262
public static ApplicationFailure newFailure(String message, String type);
263
public static ApplicationFailure newNonRetryableFailure(String message, String type);
264
}
265
public final class CanceledFailure extends TemporalFailure { }
266
public final class ChildWorkflowFailure extends TemporalFailure { }
267
public final class TimeoutFailure extends TemporalFailure { }
268
public final class TerminatedFailure extends TemporalFailure { }
269
```
270
271
[Exception Hierarchy and Error Handling](./exceptions.md)
272
273
### Data Conversion
274
275
Pluggable payload conversion system for serializing workflow arguments, results, and signals with support for custom codecs and encryption.
276
277
```java { .api }
278
// Core payload conversion interface
279
public interface PayloadConverter {
280
public Optional<Payload> toData(Object value) throws DataConverterException;
281
public <T> T fromData(Payload content, Class<T> valueClass, Type valueType) throws DataConverterException;
282
}
283
284
// Payload codec for encoding/decoding (encryption, compression)
285
public interface PayloadCodec {
286
public List<Payload> encode(List<Payload> payloads);
287
public List<Payload> decode(List<Payload> payloads);
288
}
289
290
// Serialization context for activities
291
public interface ActivitySerializationContext extends SerializationContext {
292
public String getNamespace();
293
public String getTaskQueue();
294
public String getWorkflowId();
295
}
296
```
297
298
[Payload Conversion and Serialization](./data-conversion.md)