JobResult Reference
Comprehensive result object capturing all aspects of a job execution. JobResult<T> encapsulates success/failure status, return values, error details, timing information, and custom metadata. It is the primary input for workflow condition evaluation.
Package: run.ratchet.api
Type: class JobResult<T> implements Serializable
Overview
JobResult is created internally by the Ratchet executor after each job execution. You interact with it primarily through workflow conditions:
scheduler.enqueue(() -> analyzeData())
.when(result -> result.isSuccess() && result.getValue() > threshold,
() -> handleHighValue())
.when(result -> result.getExecutionTimeMsOrZero() > 60000,
() -> alertSlowExecution())
.thenOnFailure(() -> notifyAdmins())
.submit();
Factory Methods
success
public static <T> JobResult<T> success(T value)
Creates a successful result with the given return value.
Type Parameters:
T-- the type of the return value.
Parameters:
value-- the return value from the job (may be null for void methods).
Returns: a successful JobResult containing the value.
JobResult<Integer> result = JobResult.success(42);
JobResult<String> result = JobResult.success("completed");
JobResult<Void> result = JobResult.success(null);
failure
public static <T> JobResult<T> failure(String error, Throwable exception)
Creates a failure result with an error message and exception.
Type Parameters:
T-- the type of the return value (not used for failures).
Parameters:
error-- human-readable error message.exception-- the exception that caused the failure.
Returns: a failed JobResult containing the error details.
JobResult<Void> result = JobResult.failure(
"Database connection failed",
new SQLException("Connection refused"));
of
public static <T> JobResult<T> of(
boolean success, T value, String error, Throwable exception,
Long executionTimeMs, Instant startTime, Instant endTime,
Map<String, Object> metadata)
Creates a JobResult with all fields specified. This is the full-control factory used internally by the executor.
Parameters:
success-- whether the job completed successfully.value-- the return value from the job (null for void or failures).error-- human-readable error message (null for successes).exception-- the exception that caused failure (null for successes).executionTimeMs-- total execution time in milliseconds (null if not recorded).startTime-- timestamp when execution began (null if not recorded).endTime-- timestamp when execution completed (null if not recorded).metadata-- extensible key-value pairs (null if none).
Returns: a JobResult with all fields populated.
JobResult<String> result = JobResult.of(
true, "processed", null, null,
1250L, startInstant, endInstant,
Map.of("recordsProcessed", 500));
Status Methods
isSuccess
public boolean isSuccess()
Returns true if the job completed without throwing an exception, regardless of whether it returned a value.
if (result.isSuccess()) {
processValue(result.getValue());
}
isFailure
public boolean isFailure()
Convenience method equivalent to !isSuccess().
if (result.isFailure()) {
log.error("Job failed: " + result.getError());
}
hasValue
public boolean hasValue()
Returns true if the job returned a non-null value. A job can be successful without returning a value (e.g., void methods).
if (result.hasValue()) {
Integer count = (Integer) result.getValue();
}
hasError
public boolean hasError()
Returns true if either an error message or exception is present.
if (result.hasError()) {
log.error("Error: {}", result.getError());
}
Value Access
getValue
public T getValue()
Returns the value produced by the job. May be null for void methods or failed jobs.
Returns: the return value of type T, or null.
Integer count = result.getValue();
getError
public String getError()
Returns the human-readable error message, or null if no error occurred.
String msg = result.getError(); // e.g., "Connection refused"
getException
public Throwable getException()
Returns the exception that caused the failure, or null if no exception occurred. Preserves the full stack trace and cause chain.
Some exception types may not be serializable. When JobResult is serialized (e.g., for persistence), the exception is automatically sanitized to a RuntimeException that preserves the class name, message, and stack trace.
Throwable cause = result.getException();
if (cause instanceof TimeoutException) {
// Handle timeout specifically
}
Timing Methods
getStartTime
public Instant getStartTime()
Returns when job execution began, or null if not recorded.
Instant started = result.getStartTime();
getEndTime
public Instant getEndTime()
Returns when job execution completed, or null if not recorded.
Instant ended = result.getEndTime();
getExecutionTimeMs
public Long getExecutionTimeMs()
Returns the total execution time in milliseconds, or null if not recorded.
Long ms = result.getExecutionTimeMs();
if (ms != null && ms > 30000) {
log.warn("Slow job: {} ms", ms);
}
getExecutionTimeMsOrZero
public long getExecutionTimeMsOrZero()
Returns the execution time in milliseconds, or 0 if not recorded. Safe to use in calculations without null checking.
long duration = result.getExecutionTimeMsOrZero();
metrics.record("job.duration", duration);
Metadata Methods
getMetadata (map)
public Map<String, Object> getMetadata()
Returns the full metadata map, or null if no metadata was attached.
Map<String, Object> meta = result.getMetadata();
getMetadata (by key)
public Object getMetadata(String key)
Returns a single metadata value by key, or null if not found.
Parameters:
key-- the metadata key.
Object count = result.getMetadata("recordsProcessed");
getMetadata (typed with default)
public <V> V getMetadata(String key, V defaultValue)
Returns a typed metadata value with a fallback default. Automatically casts the value.
Type Parameters:
V-- the expected type of the metadata value.
Parameters:
key-- the metadata key.defaultValue-- the value to return if the key is not found.
Returns: the metadata value if present, otherwise the default.
Integer count = result.getMetadata("processedCount", 0);
String status = result.getMetadata("status", "unknown");
Double rate = result.getMetadata("successRate", 1.0);
Using in Workflow Conditions
JobResult is the primary input for workflow branching decisions:
Success/Failure Branching
scheduler.enqueue(() -> processPayment(orderId))
.thenOnSuccess(() -> sendReceipt(orderId))
.thenOnFailure(() -> refundPayment(orderId))
.submit();
Value-Based Branching
scheduler.enqueue(() -> inventoryService.checkStock(itemId))
.whenResult(stock -> stock > 100, () -> placeOrder(itemId))
.whenResult(stock -> stock == 0, () -> notifyOutOfStock(itemId))
.submit();
Complex Condition Branching
scheduler.enqueue(() -> analyzeData())
.when(result -> result.isSuccess()
&& result.getExecutionTimeMsOrZero() > 30000,
() -> alertSlowJob())
.when(result -> result.isSuccess()
&& "critical".equals(result.getMetadata("severity")),
() -> escalateToOps())
.submit();
Serialization
JobResult implements Serializable. During serialization, non-serializable Throwable instances in the exception field are automatically converted to a safe RuntimeException that preserves the original class name, message, and stack trace. This is transparent -- in-memory access via getException() returns the original Throwable.