implements TaskEntity {
+
+ /**
+ * The current state of the entity. Subclasses may read and write this field directly
+ * in their operation methods.
+ */
+ protected TState state;
+
+ /**
+ * The current entity context, providing access to entity metadata such as the entity ID
+ * and the ability to signal other entities.
+ *
+ * This property is automatically set before each operation dispatch and is available for use
+ * in operation methods. This mirrors the .NET SDK's {@code TaskEntity.Context} property.
+ */
+ protected TaskEntityContext context;
+
+ /**
+ * Controls whether operations can be dispatched to methods on the state object.
+ * When {@code true}, if no matching method is found on the entity class itself,
+ * the framework will look for a matching method on the state object.
+ * When {@code false} (the default), only methods on the entity class are considered.
+ *
+ * This matches the .NET SDK default where {@code AllowStateDispatch} is {@code false}.
+ */
+ private boolean allowStateDispatch = false;
+
+ // Per-class cache for resolved methods, keyed by operation name (lowercased).
+ // Uses ClassValue to scope the cache per entity class, matching the .NET model
+ // where MethodInfo caching is per-type. GC can collect entries when classes are unloaded.
+ private static final ClassValue>> methodCache =
+ new ClassValue>>() {
+ @Override
+ protected Map> computeValue(Class type) {
+ return new ConcurrentHashMap<>();
+ }
+ };
+
+ /**
+ * Creates a new {@code TaskEntity} instance.
+ */
+ protected AbstractTaskEntity() {
+ }
+
+ /**
+ * Gets whether state dispatch is allowed.
+ *
+ * @return {@code true} if operations can be dispatched to state object methods
+ */
+ protected boolean getAllowStateDispatch() {
+ return this.allowStateDispatch;
+ }
+
+ /**
+ * Sets whether operations can be dispatched to methods on the state object.
+ *
+ * When {@code true}, if no matching method is found on the entity class itself,
+ * the framework will look for a matching method on the state object.
+ * When {@code false} (the default), only methods on the entity class are considered.
+ *
+ * @param allowStateDispatch {@code true} to allow state dispatch, {@code false} to disable
+ */
+ protected void setAllowStateDispatch(boolean allowStateDispatch) {
+ this.allowStateDispatch = allowStateDispatch;
+ }
+
+ /**
+ * Called to initialize the entity state when no prior state exists.
+ *
+ * The default implementation attempts to create a new instance of {@code TState} using
+ * its no-arg constructor via reflection. Override this method to provide custom initialization.
+ *
+ * @param operation the operation that triggered state initialization
+ * @return the initial state value
+ */
+ @SuppressWarnings("unchecked")
+ protected TState initializeState(TaskEntityOperation operation) {
+ Class stateType = getStateType();
+ if (stateType == null) {
+ return null;
+ }
+ try {
+ return stateType.getDeclaredConstructor().newInstance();
+ } catch (Exception e) {
+ throw new RuntimeException(
+ "Failed to initialize entity state of type " + stateType.getName() +
+ ". Override initializeState() to provide custom initialization.", e);
+ }
+ }
+
+ /**
+ * Gets the runtime class of the state type parameter. Override this method in concrete
+ * entity classes to provide the state type class, which is needed for deserialization.
+ *
+ * @return the state type class, or {@code null} if not applicable
+ */
+ @Nullable
+ protected abstract Class getStateType();
+
+ @Override
+ public Object run(TaskEntityOperation operation) throws Exception {
+ // Set the context before dispatch so subclass methods can access it
+ this.context = operation.getContext();
+ this.implicitDeleteHandled = false;
+
+ // Step 1: Load or initialize state
+ Class stateType = getStateType();
+ if (stateType != null) {
+ this.state = operation.getState().getState(stateType);
+ if (this.state == null) {
+ this.state = initializeState(operation);
+ }
+ }
+
+ Object result;
+
+ // Step 2: Try reflection dispatch on this entity class
+ Method method = findMethod(this.getClass(), operation.getName());
+ if (method != null) {
+ result = invokeMethod(method, this, operation);
+ } else if (this.allowStateDispatch && this.state != null) {
+ // Step 3: Try state dispatch (only if allowStateDispatch is true)
+ Method stateMethod = findMethod(this.state.getClass(), operation.getName());
+ if (stateMethod != null) {
+ result = invokeMethod(stateMethod, this.state, operation);
+ } else {
+ // Step 4: Implicit delete
+ result = handleImplicitOperations(operation);
+ }
+ } else {
+ // Step 4: Implicit delete (no state loaded)
+ result = handleImplicitOperations(operation);
+ }
+
+ // Step 5: Save state back only on success (the executor handles rollback on failure).
+ // Skip if the operation was an implicit delete, which already called deleteState().
+ if (stateType != null && !implicitDeleteHandled) {
+ operation.getState().setState(this.state);
+ }
+
+ return result;
+ }
+
+ private boolean implicitDeleteHandled;
+
+ private Object handleImplicitOperations(TaskEntityOperation operation) {
+ if ("delete".equalsIgnoreCase(operation.getName())) {
+ operation.getState().deleteState();
+ this.state = null;
+ this.implicitDeleteHandled = true;
+ return null;
+ }
+ throw new UnsupportedOperationException(
+ "Entity '" + this.getClass().getSimpleName() + "' does not support operation '" +
+ operation.getName() + "'.");
+ }
+
+ // region Re-entrant self-dispatch
+
+ /**
+ * Dispatches an operation to this entity instance synchronously (re-entrant self-call).
+ *
+ * This allows one entity operation to invoke another operation on the same entity,
+ * reusing the same state and context. The dispatched operation executes inline — state
+ * mutations are visible immediately to the caller.
+ *
+ * The operation is resolved using the same case-insensitive reflection dispatch as external
+ * operations: entity class methods are tried first, then state object methods (if
+ * {@linkplain #setAllowStateDispatch state dispatch} is enabled), then implicit operations.
+ *
+ *
Example:
+ *
{@code
+ * public class BankAccount extends TaskEntity {
+ * public void deposit(int amount) {
+ * this.state.balance += amount;
+ * }
+ *
+ * public void depositWithBonus(int amount) {
+ * dispatch("deposit", amount); // re-entrant call
+ * dispatch("deposit", amount / 10); // 10% bonus
+ * }
+ * }
+ * }
+ *
+ * @param operationName the name of the operation to dispatch (case-insensitive)
+ * @return the operation result, or {@code null} for void operations
+ * @throws IllegalStateException if called outside of entity execution
+ * @throws UnsupportedOperationException if no matching operation is found
+ */
+ protected Object dispatch(String operationName) {
+ return dispatch(operationName, null);
+ }
+
+ /**
+ * Dispatches an operation with input to this entity instance synchronously (re-entrant self-call).
+ *
+ * @param operationName the name of the operation to dispatch (case-insensitive)
+ * @param input the input value to pass to the operation, or {@code null}
+ * @return the operation result, or {@code null} for void operations
+ * @throws IllegalStateException if called outside of entity execution
+ * @throws UnsupportedOperationException if no matching operation is found
+ * @see #dispatch(String)
+ */
+ protected Object dispatch(String operationName, Object input) {
+ if (this.context == null) {
+ throw new IllegalStateException(
+ "dispatch() can only be called during entity operation execution.");
+ }
+
+ Method method = findMethod(this.getClass(), operationName);
+ Object target = this;
+
+ if (method == null && this.allowStateDispatch && this.state != null) {
+ method = findMethod(this.state.getClass(), operationName);
+ target = this.state;
+ }
+
+ if (method == null) {
+ if ("delete".equalsIgnoreCase(operationName)) {
+ this.state = null;
+ return null;
+ }
+ throw new UnsupportedOperationException(
+ "Entity '" + this.getClass().getSimpleName() +
+ "' does not support operation '" + operationName + "'.");
+ }
+
+ return invokeMethodDirect(method, target, input, this.context);
+ }
+
+ /**
+ * Dispatches an operation with input and a typed return value (re-entrant self-call).
+ *
+ * @param operationName the name of the operation to dispatch (case-insensitive)
+ * @param input the input value to pass to the operation, or {@code null}
+ * @param returnType the expected return type
+ * @param the return type
+ * @return the operation result cast to {@code V}
+ * @throws IllegalStateException if called outside of entity execution
+ * @throws UnsupportedOperationException if no matching operation is found
+ * @throws ClassCastException if the result cannot be cast to {@code returnType}
+ * @see #dispatch(String, Object)
+ */
+ @SuppressWarnings("unchecked")
+ protected V dispatch(String operationName, Object input, Class returnType) {
+ Object result = dispatch(operationName, input);
+ if (result == null) {
+ return null;
+ }
+ // Primitive types (int.class, etc.) cannot use Class.cast() with boxed values,
+ // so we let the unchecked cast handle primitive-to-wrapper conversion.
+ if (returnType.isPrimitive()) {
+ return (V) result;
+ }
+ return returnType.cast(result);
+ }
+
+ /**
+ * Invokes a method with a direct (already-deserialized) input value, without requiring
+ * a {@link TaskEntityOperation}. Used by {@link #dispatch} for re-entrant self-calls.
+ */
+ private static Object invokeMethodDirect(
+ Method method, Object target, Object input, TaskEntityContext context) {
+ Class[] paramTypes = method.getParameterTypes();
+ Object[] args = new Object[paramTypes.length];
+
+ for (int i = 0; i < paramTypes.length; i++) {
+ if (TaskEntityContext.class.isAssignableFrom(paramTypes[i])) {
+ args[i] = context;
+ } else if (TaskEntityOperation.class.isAssignableFrom(paramTypes[i])) {
+ throw new UnsupportedOperationException(
+ "Cannot dispatch to method '" + method.getName() +
+ "' that accepts TaskEntityOperation. Use a simpler signature for " +
+ "operations that support re-entrant dispatch.");
+ } else {
+ args[i] = input;
+ }
+ }
+
+ try {
+ return method.invoke(target, args);
+ } catch (InvocationTargetException e) {
+ Throwable cause = e.getTargetException();
+ if (cause instanceof RuntimeException) {
+ throw (RuntimeException) cause;
+ }
+ if (cause instanceof Error) {
+ throw (Error) cause;
+ }
+ throw new RuntimeException(cause);
+ } catch (IllegalAccessException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ // endregion
+
+ /**
+ * Finds a public method on the target class matching the operation name (case-insensitive).
+ * Methods inherited from {@code Object} and from {@code TaskEntity} itself are excluded.
+ */
+ @Nullable
+ private static Method findMethod(Class targetClass, String operationName) {
+ Map> classCache = methodCache.get(targetClass);
+ String key = operationName.toLowerCase();
+ return classCache.computeIfAbsent(key, k -> findMethodUncached(targetClass, k)).orElse(null);
+ }
+
+ private static Optional findMethodUncached(Class targetClass, String operationName) {
+ List matches = new ArrayList<>();
+ for (Method m : targetClass.getMethods()) {
+ // Skip static methods — only instance methods should be dispatchable
+ if (Modifier.isStatic(m.getModifiers())) {
+ continue;
+ }
+ // Skip methods from Object
+ if (m.getDeclaringClass() == Object.class) {
+ continue;
+ }
+ // Skip methods from TaskEntity base class itself
+ if (m.getDeclaringClass() == AbstractTaskEntity.class) {
+ continue;
+ }
+ // Skip methods from TaskEntity interface
+ if (m.getDeclaringClass() == TaskEntity.class) {
+ continue;
+ }
+ // Skip methods from JDK packages to prevent unintended state dispatch
+ // (e.g., Integer.intValue(), String.length()) when state type is a JDK class
+ Package pkg = m.getDeclaringClass().getPackage();
+ String declaringPackage = pkg != null ? pkg.getName() : "";
+ if (declaringPackage.startsWith("java.") || declaringPackage.startsWith("javax.")) {
+ continue;
+ }
+ if (m.getName().equalsIgnoreCase(operationName)) {
+ matches.add(m);
+ }
+ }
+ if (matches.size() > 1) {
+ throw new IllegalStateException(
+ "Ambiguous match: multiple methods named '" + operationName + "' found on " +
+ targetClass.getName() + ". Entity operation methods must have unique names.");
+ }
+ return matches.isEmpty() ? Optional.empty() : Optional.of(matches.get(0));
+ }
+
+ /**
+ * Invokes the resolved method with appropriate parameter binding.
+ *
+ * Supports 0–2 parameters among:
+ *
+ * - The operation input (deserialized to the parameter type)
+ * - {@link TaskEntityContext}
+ *
+ */
+ private static Object invokeMethod(Method method, Object target, TaskEntityOperation operation)
+ throws Exception {
+ Class[] paramTypes = method.getParameterTypes();
+ Object[] args = new Object[paramTypes.length];
+
+ for (int i = 0; i < paramTypes.length; i++) {
+ if (TaskEntityContext.class.isAssignableFrom(paramTypes[i])) {
+ args[i] = operation.getContext();
+ } else if (TaskEntityOperation.class.isAssignableFrom(paramTypes[i])) {
+ args[i] = operation;
+ } else {
+ // Assume this is the input parameter
+ args[i] = operation.getInput(paramTypes[i]);
+ }
+ }
+
+ try {
+ return method.invoke(target, args);
+ } catch (InvocationTargetException e) {
+ // Unwrap the target exception
+ Throwable cause = e.getTargetException();
+ if (cause instanceof Exception) {
+ throw (Exception) cause;
+ }
+ throw new RuntimeException(cause);
+ }
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/CallEntityOptions.java b/client/src/main/java/com/microsoft/durabletask/CallEntityOptions.java
new file mode 100644
index 00000000..3b92ff32
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/CallEntityOptions.java
@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+import java.time.Duration;
+
+/**
+ * Options for calling a durable entity and waiting for a response.
+ */
+public final class CallEntityOptions {
+ private Duration timeout;
+
+ /**
+ * Creates a new {@code CallEntityOptions} with default settings.
+ */
+ public CallEntityOptions() {
+ }
+
+ /**
+ * Sets the timeout for the entity call. If the entity does not respond within this duration,
+ * the call will fail with a timeout exception.
+ *
+ * @param timeout the maximum duration to wait for a response
+ * @return this {@code CallEntityOptions} object for chaining
+ */
+ public CallEntityOptions setTimeout(@Nullable Duration timeout) {
+ this.timeout = timeout;
+ return this;
+ }
+
+ /**
+ * Gets the timeout for the entity call, or {@code null} if no timeout is configured.
+ *
+ * @return the timeout duration, or {@code null}
+ */
+ @Nullable
+ public Duration getTimeout() {
+ return this.timeout;
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/CleanEntityStorageRequest.java b/client/src/main/java/com/microsoft/durabletask/CleanEntityStorageRequest.java
new file mode 100644
index 00000000..fdeed40e
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/CleanEntityStorageRequest.java
@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+
+/**
+ * Represents a request to clean up entity storage by removing empty entities and/or releasing orphaned locks.
+ *
+ * Use the builder-style setters to configure the request, then pass it to
+ * {@link DurableEntityClient#cleanEntityStorage(CleanEntityStorageRequest)}.
+ */
+public final class CleanEntityStorageRequest {
+ private String continuationToken;
+ private boolean removeEmptyEntities = true;
+ private boolean releaseOrphanedLocks = true;
+ private boolean continueUntilComplete = false;
+
+ /**
+ * Creates a new {@code CleanEntityStorageRequest} with default settings.
+ * By default, both {@code removeEmptyEntities} and {@code releaseOrphanedLocks} are {@code true}.
+ */
+ public CleanEntityStorageRequest() {
+ }
+
+ /**
+ * Sets the continuation token for resuming a previous clean operation.
+ *
+ * @param continuationToken the continuation token, or {@code null} to start from the beginning
+ * @return this {@code CleanEntityStorageRequest} for chaining
+ */
+ public CleanEntityStorageRequest setContinuationToken(@Nullable String continuationToken) {
+ this.continuationToken = continuationToken;
+ return this;
+ }
+
+ /**
+ * Gets the continuation token for resuming a previous clean operation.
+ *
+ * @return the continuation token, or {@code null}
+ */
+ @Nullable
+ public String getContinuationToken() {
+ return this.continuationToken;
+ }
+
+ /**
+ * Sets whether to remove entities that have no state and no pending operations.
+ *
+ * @param removeEmptyEntities {@code true} to remove empty entities
+ * @return this {@code CleanEntityStorageRequest} for chaining
+ */
+ public CleanEntityStorageRequest setRemoveEmptyEntities(boolean removeEmptyEntities) {
+ this.removeEmptyEntities = removeEmptyEntities;
+ return this;
+ }
+
+ /**
+ * Gets whether empty entities should be removed.
+ *
+ * @return {@code true} if empty entities will be removed
+ */
+ public boolean isRemoveEmptyEntities() {
+ return this.removeEmptyEntities;
+ }
+
+ /**
+ * Sets whether to release locks held by orchestrations that no longer exist.
+ *
+ * @param releaseOrphanedLocks {@code true} to release orphaned locks
+ * @return this {@code CleanEntityStorageRequest} for chaining
+ */
+ public CleanEntityStorageRequest setReleaseOrphanedLocks(boolean releaseOrphanedLocks) {
+ this.releaseOrphanedLocks = releaseOrphanedLocks;
+ return this;
+ }
+
+ /**
+ * Gets whether orphaned locks should be released.
+ *
+ * @return {@code true} if orphaned locks will be released
+ */
+ public boolean isReleaseOrphanedLocks() {
+ return this.releaseOrphanedLocks;
+ }
+
+ /**
+ * Sets whether the client should automatically continue cleaning with continuation tokens
+ * until all entities have been processed. When {@code true}, the client will loop internally,
+ * accumulating results across multiple pages.
+ *
+ * @param continueUntilComplete {@code true} to automatically continue until complete
+ * @return this {@code CleanEntityStorageRequest} for chaining
+ */
+ public CleanEntityStorageRequest setContinueUntilComplete(boolean continueUntilComplete) {
+ this.continueUntilComplete = continueUntilComplete;
+ return this;
+ }
+
+ /**
+ * Gets whether the client should automatically continue cleaning until all entities are processed.
+ *
+ * @return {@code true} if the client will automatically continue until complete
+ */
+ public boolean isContinueUntilComplete() {
+ return this.continueUntilComplete;
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/CleanEntityStorageResult.java b/client/src/main/java/com/microsoft/durabletask/CleanEntityStorageResult.java
new file mode 100644
index 00000000..f5ad588d
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/CleanEntityStorageResult.java
@@ -0,0 +1,59 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+
+/**
+ * Represents the result of a {@link DurableEntityClient#cleanEntityStorage(CleanEntityStorageRequest)} operation.
+ */
+public final class CleanEntityStorageResult {
+ private final String continuationToken;
+ private final int emptyEntitiesRemoved;
+ private final int orphanedLocksReleased;
+
+ /**
+ * Creates a new {@code CleanEntityStorageResult}.
+ *
+ * @param continuationToken the continuation token for resuming the clean operation, or {@code null} if complete
+ * @param emptyEntitiesRemoved the number of empty entities removed in this batch
+ * @param orphanedLocksReleased the number of orphaned locks released in this batch
+ */
+ CleanEntityStorageResult(
+ @Nullable String continuationToken,
+ int emptyEntitiesRemoved,
+ int orphanedLocksReleased) {
+ this.continuationToken = continuationToken;
+ this.emptyEntitiesRemoved = emptyEntitiesRemoved;
+ this.orphanedLocksReleased = orphanedLocksReleased;
+ }
+
+ /**
+ * Gets the continuation token for resuming the clean operation.
+ * If {@code null}, the clean operation has processed all entities.
+ *
+ * @return the continuation token, or {@code null} if the operation is complete
+ */
+ @Nullable
+ public String getContinuationToken() {
+ return this.continuationToken;
+ }
+
+ /**
+ * Gets the number of empty entities that were removed in this batch.
+ *
+ * @return the count of empty entities removed
+ */
+ public int getEmptyEntitiesRemoved() {
+ return this.emptyEntitiesRemoved;
+ }
+
+ /**
+ * Gets the number of orphaned locks that were released in this batch.
+ *
+ * @return the count of orphaned locks released
+ */
+ public int getOrphanedLocksReleased() {
+ return this.orphanedLocksReleased;
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/DurableEntityClient.java b/client/src/main/java/com/microsoft/durabletask/DurableEntityClient.java
new file mode 100644
index 00000000..61fcba6c
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/DurableEntityClient.java
@@ -0,0 +1,225 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+
+/**
+ * Client for interacting with durable entities.
+ *
+ * This class provides operations for signaling entities, querying entity metadata,
+ * and performing entity storage maintenance. Instances are obtained from
+ * {@link DurableTaskClient#getEntities()}.
+ *
+ * This design mirrors the .NET SDK's {@code DurableEntityClient} which is accessed
+ * via the {@code DurableTaskClient.Entities} property.
+ */
+public abstract class DurableEntityClient {
+
+ private final String name;
+
+ /**
+ * Creates a new {@code DurableEntityClient} instance.
+ *
+ * @param name the name of the client
+ */
+ protected DurableEntityClient(String name) {
+ this.name = name;
+ }
+
+ /**
+ * Gets the name of this client.
+ *
+ * @return the client name
+ */
+ public String getName() {
+ return this.name;
+ }
+
+ /**
+ * Sends a signal to a durable entity instance without waiting for a response.
+ *
+ * If the target entity does not exist, it will be created automatically when it receives the signal.
+ *
+ * @param entityId the target entity's instance ID
+ * @param operationName the name of the operation to invoke on the entity
+ */
+ public void signalEntity(EntityInstanceId entityId, String operationName) {
+ this.signalEntity(entityId, operationName, null, null);
+ }
+
+ /**
+ * Sends a signal with input to a durable entity instance without waiting for a response.
+ *
+ * If the target entity does not exist, it will be created automatically when it receives the signal.
+ *
+ * @param entityId the target entity's instance ID
+ * @param operationName the name of the operation to invoke on the entity
+ * @param input the serializable input for the operation, or {@code null}
+ */
+ public void signalEntity(EntityInstanceId entityId, String operationName, @Nullable Object input) {
+ this.signalEntity(entityId, operationName, input, null);
+ }
+
+ /**
+ * Sends a signal with input and options to a durable entity instance without waiting for a response.
+ *
+ * If the target entity does not exist, it will be created automatically when it receives the signal.
+ * Use {@link SignalEntityOptions#setScheduledTime(java.time.Instant)} to schedule the signal for
+ * delivery at a future time.
+ *
+ * @param entityId the target entity's instance ID
+ * @param operationName the name of the operation to invoke on the entity
+ * @param input the serializable input for the operation, or {@code null}
+ * @param options additional options for the signal, or {@code null}
+ */
+ public abstract void signalEntity(
+ EntityInstanceId entityId,
+ String operationName,
+ @Nullable Object input,
+ @Nullable SignalEntityOptions options);
+
+ /**
+ * Fetches the metadata for a durable entity instance, including its state by default.
+ *
+ * This matches the .NET SDK behavior where {@code includeState} defaults to {@code true}.
+ *
+ * @param entityId the entity instance ID to query
+ * @return the entity metadata, or {@code null} if the entity does not exist
+ */
+ @Nullable
+ public EntityMetadata getEntityMetadata(EntityInstanceId entityId) {
+ return this.getEntityMetadata(entityId, true);
+ }
+
+ /**
+ * Fetches the metadata for a durable entity instance, optionally including its state.
+ *
+ * @param entityId the entity instance ID to query
+ * @param includeState {@code true} to include the entity's serialized state in the result
+ * @return the entity metadata, or {@code null} if the entity does not exist
+ */
+ @Nullable
+ public abstract EntityMetadata getEntityMetadata(EntityInstanceId entityId, boolean includeState);
+
+ /**
+ * Fetches the metadata for a durable entity instance with typed state access.
+ *
+ * This always includes state in the result, matching the .NET SDK's
+ * {@code GetEntityAsync()} pattern. The returned {@link TypedEntityMetadata} provides
+ * a {@link TypedEntityMetadata#getState()} method for direct typed state access.
+ *
+ * {@code
+ * TypedEntityMetadata metadata = client.getEntities()
+ * .getEntityMetadata(entityId, Integer.class);
+ * if (metadata != null) {
+ * Integer state = metadata.getState();
+ * System.out.println("Counter value: " + state);
+ * }
+ * }
+ *
+ * @param entityId the entity instance ID to query
+ * @param stateType the class to deserialize the entity's state into
+ * @param the entity state type
+ * @return the typed entity metadata with state, or {@code null} if the entity does not exist
+ */
+ @Nullable
+ public TypedEntityMetadata getEntityMetadata(EntityInstanceId entityId, Class stateType) {
+ EntityMetadata metadata = this.getEntityMetadata(entityId, true);
+ if (metadata == null) {
+ return null;
+ }
+ return new TypedEntityMetadata<>(metadata, stateType);
+ }
+
+ /**
+ * Queries the durable store for entity instances matching the specified filter criteria.
+ *
+ * @param query the query filter criteria
+ * @return the query result containing matching entities and an optional continuation token
+ */
+ public abstract EntityQueryResult queryEntities(EntityQuery query);
+
+ /**
+ * Returns an auto-paginating iterable over entity instances matching the specified filter criteria.
+ *
+ * This method automatically handles pagination when iterating over results. It fetches pages
+ * from the store on demand, making it convenient when you want to process all matching entities
+ * without manually managing continuation tokens.
+ *
+ * You can iterate over individual items:
+ *
{@code
+ * for (EntityMetadata entity : client.getEntities().getAllEntities(query)) {
+ * System.out.println(entity.getEntityInstanceId());
+ * }
+ * }
+ *
+ * Or iterate page by page for more control:
+ *
{@code
+ * for (EntityQueryResult page : client.getEntities().getAllEntities(query).byPage()) {
+ * for (EntityMetadata entity : page.getEntities()) {
+ * System.out.println(entity.getEntityInstanceId());
+ * }
+ * }
+ * }
+ *
+ * @param query the query filter criteria
+ * @return a pageable iterable over all matching entities
+ */
+ public EntityQueryPageable getAllEntities(EntityQuery query) {
+ return new EntityQueryPageable(query, this::queryEntities);
+ }
+
+ /**
+ * Returns an auto-paginating iterable over all entity instances.
+ *
+ * This is a convenience overload equivalent to {@code getAllEntities(new EntityQuery())}.
+ *
+ * @return a pageable iterable over all entities
+ */
+ public EntityQueryPageable getAllEntities() {
+ return getAllEntities(new EntityQuery());
+ }
+
+ /**
+ * Returns an auto-paginating iterable over entity instances matching the specified filter criteria,
+ * with typed state access.
+ *
+ * This mirrors the .NET SDK's {@code GetAllEntitiesAsync()} pattern. Entity state is always
+ * included in the results and eagerly deserialized into the specified type. Each item is a
+ * {@link TypedEntityMetadata} with a {@link TypedEntityMetadata#getState()} accessor.
+ *
+ * Note: A copy of the query is made with {@code includeState} set to {@code true} so the
+ * original query is not modified.
+ *
+ *
{@code
+ * EntityQuery query = new EntityQuery().setInstanceIdStartsWith("counter");
+ * for (TypedEntityMetadata entity : client.getEntities().getAllEntities(query, Integer.class)) {
+ * Integer state = entity.getState();
+ * System.out.println("Counter value: " + state);
+ * }
+ * }
+ *
+ * @param query the query filter criteria
+ * @param stateType the class to deserialize each entity's state into
+ * @param the entity state type
+ * @return a pageable iterable over all matching entities with typed state
+ */
+ public TypedEntityQueryPageable getAllEntities(EntityQuery query, Class stateType) {
+ // Create a copy with includeState=true so we don't mutate the caller's query
+ EntityQuery typedQuery = query.copy().setIncludeState(true);
+ EntityQueryPageable inner = new EntityQueryPageable(typedQuery, this::queryEntities);
+ return new TypedEntityQueryPageable<>(inner, stateType);
+ }
+
+ /**
+ * Cleans up entity storage by removing empty entities and/or releasing orphaned locks.
+ *
+ * This is an administrative operation that can be used to reclaim storage space and fix
+ * entity state inconsistencies.
+ *
+ * @param request the clean storage request specifying what to clean
+ * @return the result of the clean operation, including counts of removed entities and released locks
+ */
+ public abstract CleanEntityStorageResult cleanEntityStorage(CleanEntityStorageRequest request);
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/DurableTaskClient.java b/client/src/main/java/com/microsoft/durabletask/DurableTaskClient.java
index 1e1b3cb0..117f9d69 100644
--- a/client/src/main/java/com/microsoft/durabletask/DurableTaskClient.java
+++ b/client/src/main/java/com/microsoft/durabletask/DurableTaskClient.java
@@ -356,4 +356,142 @@ public void resumeInstance(String instanceId) {
* @param reason the reason for resuming the orchestration instance
*/
public abstract void resumeInstance(String instanceId, @Nullable String reason);
-}
\ No newline at end of file
+
+ // region Entity APIs
+
+ /**
+ * Gets the entity client for interacting with durable entities.
+ *
+ * This mirrors the .NET SDK's {@code DurableTaskClient.Entities} property, providing a
+ * dedicated client for entity operations such as signaling, querying, and storage management.
+ *
+ * @return the {@link DurableEntityClient} for this client
+ * @throws UnsupportedOperationException if the current client implementation does not support entities
+ */
+ public DurableEntityClient getEntities() {
+ throw new UnsupportedOperationException("Entity operations are not supported by this client implementation.");
+ }
+
+ /**
+ * Sends a signal to a durable entity instance without waiting for a response.
+ *
+ * If the target entity does not exist, it will be created automatically when it receives the signal.
+ *
+ * @param entityId the target entity's instance ID
+ * @param operationName the name of the operation to invoke on the entity
+ * @deprecated Use {@code getEntities().signalEntity(entityId, operationName)} instead.
+ */
+ @Deprecated
+ public void signalEntity(EntityInstanceId entityId, String operationName) {
+ this.getEntities().signalEntity(entityId, operationName);
+ }
+
+ /**
+ * Sends a signal with input to a durable entity instance without waiting for a response.
+ *
+ * If the target entity does not exist, it will be created automatically when it receives the signal.
+ *
+ * @param entityId the target entity's instance ID
+ * @param operationName the name of the operation to invoke on the entity
+ * @param input the serializable input for the operation, or {@code null}
+ * @deprecated Use {@code getEntities().signalEntity(entityId, operationName, input)} instead.
+ */
+ @Deprecated
+ public void signalEntity(EntityInstanceId entityId, String operationName, @Nullable Object input) {
+ this.getEntities().signalEntity(entityId, operationName, input);
+ }
+
+ /**
+ * Sends a signal with input and options to a durable entity instance without waiting for a response.
+ *
+ * @param entityId the target entity's instance ID
+ * @param operationName the name of the operation to invoke on the entity
+ * @param input the serializable input for the operation, or {@code null}
+ * @param options additional options for the signal, or {@code null}
+ * @deprecated Use {@code getEntities().signalEntity(entityId, operationName, input, options)} instead.
+ */
+ @Deprecated
+ public void signalEntity(
+ EntityInstanceId entityId,
+ String operationName,
+ @Nullable Object input,
+ @Nullable SignalEntityOptions options) {
+ this.getEntities().signalEntity(entityId, operationName, input, options);
+ }
+
+ /**
+ * Fetches the metadata for a durable entity instance, including its state.
+ *
+ * @param entityId the entity instance ID to query
+ * @return the entity metadata, or {@code null} if the entity does not exist
+ * @deprecated Use {@code getEntities().getEntityMetadata(entityId)} instead.
+ */
+ @Deprecated
+ @Nullable
+ public EntityMetadata getEntityMetadata(EntityInstanceId entityId) {
+ return this.getEntities().getEntityMetadata(entityId);
+ }
+
+ /**
+ * Fetches the metadata for a durable entity instance, optionally including its state.
+ *
+ * @param entityId the entity instance ID to query
+ * @param includeState {@code true} to include the entity's serialized state in the result
+ * @return the entity metadata, or {@code null} if the entity does not exist
+ * @deprecated Use {@code getEntities().getEntityMetadata(entityId, includeState)} instead.
+ */
+ @Deprecated
+ @Nullable
+ public EntityMetadata getEntityMetadata(EntityInstanceId entityId, boolean includeState) {
+ return this.getEntities().getEntityMetadata(entityId, includeState);
+ }
+
+ /**
+ * Queries the durable store for entity instances matching the specified filter criteria.
+ *
+ * @param query the query filter criteria
+ * @return the query result containing matching entities and an optional continuation token
+ * @deprecated Use {@code getEntities().queryEntities(query)} instead.
+ */
+ @Deprecated
+ public EntityQueryResult queryEntities(EntityQuery query) {
+ return this.getEntities().queryEntities(query);
+ }
+
+ /**
+ * Returns an auto-paginating iterable over entity instances matching the specified filter criteria.
+ *
+ * @param query the query filter criteria
+ * @return a pageable iterable over all matching entities
+ * @deprecated Use {@code getEntities().getAllEntities(query)} instead.
+ */
+ @Deprecated
+ public EntityQueryPageable getAllEntities(EntityQuery query) {
+ return this.getEntities().getAllEntities(query);
+ }
+
+ /**
+ * Returns an auto-paginating iterable over all entity instances.
+ *
+ * @return a pageable iterable over all entities
+ * @deprecated Use {@code getEntities().getAllEntities()} instead.
+ */
+ @Deprecated
+ public EntityQueryPageable getAllEntities() {
+ return this.getEntities().getAllEntities();
+ }
+
+ /**
+ * Cleans up entity storage by removing empty entities and/or releasing orphaned locks.
+ *
+ * @param request the clean storage request specifying what to clean
+ * @return the result of the clean operation, including counts of removed entities and released locks
+ * @deprecated Use {@code getEntities().cleanEntityStorage(request)} instead.
+ */
+ @Deprecated
+ public CleanEntityStorageResult cleanEntityStorage(CleanEntityStorageRequest request) {
+ return this.getEntities().cleanEntityStorage(request);
+ }
+
+ // endregion
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcClient.java b/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcClient.java
index 14955120..8778252a 100644
--- a/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcClient.java
+++ b/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcClient.java
@@ -32,6 +32,7 @@ public final class DurableTaskGrpcClient extends DurableTaskClient {
private final ManagedChannel managedSidecarChannel;
private final TaskHubSidecarServiceBlockingStub sidecarClient;
private final String defaultVersion;
+ private final GrpcDurableEntityClient entityClient;
DurableTaskGrpcClient(DurableTaskGrpcClientBuilder builder) {
this.dataConverter = builder.dataConverter != null ? builder.dataConverter : new JacksonDataConverter();
@@ -58,6 +59,7 @@ public final class DurableTaskGrpcClient extends DurableTaskClient {
}
this.sidecarClient = TaskHubSidecarServiceGrpc.newBlockingStub(sidecarGrpcChannel);
+ this.entityClient = new GrpcDurableEntityClient("GrpcDurableEntityClient", this.sidecarClient, this.dataConverter);
}
DurableTaskGrpcClient(int port, String defaultVersion) {
@@ -70,6 +72,7 @@ public final class DurableTaskGrpcClient extends DurableTaskClient {
.usePlaintext()
.build();
this.sidecarClient = TaskHubSidecarServiceGrpc.newBlockingStub(this.managedSidecarChannel);
+ this.entityClient = new GrpcDurableEntityClient("GrpcDurableEntityClient", this.sidecarClient, this.dataConverter);
}
/**
@@ -399,4 +402,13 @@ public String restartInstance(String instanceId, boolean restartWithNewInstanceI
private PurgeResult toPurgeResult(PurgeInstancesResponse response){
return new PurgeResult(response.getDeletedInstanceCount());
}
+
+ // region Entity APIs
+
+ @Override
+ public DurableEntityClient getEntities() {
+ return this.entityClient;
+ }
+
+ // endregion
}
diff --git a/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcWorker.java b/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcWorker.java
index 284b7090..7e42025d 100644
--- a/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcWorker.java
+++ b/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcWorker.java
@@ -19,7 +19,11 @@
import java.time.Duration;
import java.time.Instant;
import java.util.*;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.SynchronousQueue;
+import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.util.stream.Stream;
@@ -29,22 +33,29 @@
*/
public final class DurableTaskGrpcWorker implements AutoCloseable {
private static final int DEFAULT_PORT = 4001;
+ static final int DEFAULT_MAX_WORK_ITEM_THREADS = 100;
private static final Logger logger = Logger.getLogger(DurableTaskGrpcWorker.class.getPackage().getName());
+ private static final AtomicInteger THREAD_COUNTER = new AtomicInteger(0);
private static final Duration DEFAULT_MAXIMUM_TIMER_INTERVAL = Duration.ofDays(3);
private final HashMap orchestrationFactories = new HashMap<>();
private final HashMap activityFactories = new HashMap<>();
+ private final HashMap entityFactories = new HashMap<>();
private final ManagedChannel managedSidecarChannel;
private final DataConverter dataConverter;
private final Duration maximumTimerInterval;
private final DurableTaskGrpcWorkerVersioningOptions versioningOptions;
+ private final int maxConcurrentEntityWorkItems;
+ private final ExecutorService workItemExecutor;
private final TaskHubSidecarServiceBlockingStub sidecarClient;
DurableTaskGrpcWorker(DurableTaskGrpcWorkerBuilder builder) {
this.orchestrationFactories.putAll(builder.orchestrationFactories);
this.activityFactories.putAll(builder.activityFactories);
+ this.entityFactories.putAll(builder.entityFactories);
+ this.maxConcurrentEntityWorkItems = builder.maxConcurrentEntityWorkItems;
Channel sidecarGrpcChannel;
if (builder.channel != null) {
@@ -70,6 +81,17 @@ public final class DurableTaskGrpcWorker implements AutoCloseable {
this.dataConverter = builder.dataConverter != null ? builder.dataConverter : new JacksonDataConverter();
this.maximumTimerInterval = builder.maximumTimerInterval != null ? builder.maximumTimerInterval : DEFAULT_MAXIMUM_TIMER_INTERVAL;
this.versioningOptions = builder.versioningOptions;
+ int maxThreads = builder.maxWorkItemThreads > 0 ? builder.maxWorkItemThreads : DEFAULT_MAX_WORK_ITEM_THREADS;
+ this.workItemExecutor = new ThreadPoolExecutor(
+ 0, maxThreads,
+ 60L, TimeUnit.SECONDS,
+ new SynchronousQueue<>(),
+ r -> {
+ Thread t = new Thread(r, "durabletask-worker-" + THREAD_COUNTER.incrementAndGet());
+ t.setDaemon(true);
+ return t;
+ },
+ new ThreadPoolExecutor.CallerRunsPolicy());
}
/**
@@ -90,13 +112,21 @@ public void start() {
* configured.
*/
public void close() {
+ this.workItemExecutor.shutdown();
+ try {
+ if (!this.workItemExecutor.awaitTermination(10, TimeUnit.SECONDS)) {
+ this.workItemExecutor.shutdownNow();
+ }
+ } catch (InterruptedException e) {
+ this.workItemExecutor.shutdownNow();
+ Thread.currentThread().interrupt();
+ }
+
if (this.managedSidecarChannel != null) {
try {
this.managedSidecarChannel.shutdownNow().awaitTermination(5, TimeUnit.SECONDS);
} catch (InterruptedException e) {
- // Best effort. Also note that AutoClose documentation recommends NOT having
- // close() methods throw InterruptedException:
- // https://docs.oracle.com/javase/7/docs/api/java/lang/AutoCloseable.html
+ Thread.currentThread().interrupt();
}
}
}
@@ -123,16 +153,26 @@ public void startAndBlock() {
this.dataConverter,
this.maximumTimerInterval,
logger,
- this.versioningOptions);
+ this.versioningOptions,
+ true);
TaskActivityExecutor taskActivityExecutor = new TaskActivityExecutor(
this.activityFactories,
this.dataConverter,
logger);
+ TaskEntityExecutor taskEntityExecutor = new TaskEntityExecutor(
+ this.entityFactories,
+ this.dataConverter,
+ logger);
// TODO: How do we interrupt manually?
while (true) {
try {
- GetWorkItemsRequest getWorkItemsRequest = GetWorkItemsRequest.newBuilder().build();
+ GetWorkItemsRequest.Builder requestBuilder = GetWorkItemsRequest.newBuilder();
+ if (!this.entityFactories.isEmpty()) {
+ // Signal to the sidecar that this worker can handle entity work items
+ requestBuilder.setMaxConcurrentEntityWorkItems(this.maxConcurrentEntityWorkItems);
+ }
+ GetWorkItemsRequest getWorkItemsRequest = requestBuilder.build();
Iterator workItemStream = this.sidecarClient.getWorkItems(getWorkItemsRequest);
while (workItemStream.hasNext()) {
WorkItem workItem = workItemStream.next();
@@ -340,7 +380,6 @@ public void startAndBlock() {
spanAttributes);
Scope activityScope = activitySpan.makeCurrent();
- // TODO: Run this on a worker pool thread: https://www.baeldung.com/thread-pool-java-and-guava
String output = null;
TaskFailureDetails failureDetails = null;
Throwable activityError = null;
@@ -375,7 +414,113 @@ public void startAndBlock() {
}
this.sidecarClient.completeActivityTask(responseBuilder.build());
- }
+ } else if (requestType == RequestCase.ENTITYREQUEST) {
+ EntityBatchRequest entityRequest = workItem.getEntityRequest();
+ this.workItemExecutor.submit(() -> {
+ try {
+ EntityBatchResult result = taskEntityExecutor.execute(entityRequest);
+ EntityBatchResult responseWithToken = result.toBuilder()
+ .setCompletionToken(workItem.getCompletionToken())
+ .build();
+ this.sidecarClient.completeEntityTask(responseWithToken);
+ } catch (Exception e) {
+ logger.log(Level.WARNING,
+ String.format("Failed to execute entity batch for '%s'. Abandoning work item.",
+ entityRequest.getInstanceId()),
+ e);
+ this.sidecarClient.abandonTaskEntityWorkItem(
+ AbandonEntityTaskRequest.newBuilder()
+ .setCompletionToken(workItem.getCompletionToken())
+ .build());
+ }
+ });
+ } else if (requestType == RequestCase.ENTITYREQUESTV2) {
+ EntityRequest entityRequestV2 = workItem.getEntityRequestV2();
+ this.workItemExecutor.submit(() -> {
+ try {
+ // Convert V2 (history-based) format to V1 (flat) format
+ EntityBatchRequest.Builder batchBuilder = EntityBatchRequest.newBuilder()
+ .setInstanceId(entityRequestV2.getInstanceId());
+ if (entityRequestV2.hasEntityState()) {
+ batchBuilder.setEntityState(entityRequestV2.getEntityState());
+ }
+
+ List operationInfos = new ArrayList<>();
+ for (HistoryEvent event : entityRequestV2.getOperationRequestsList()) {
+ if (event.hasEntityOperationSignaled()) {
+ EntityOperationSignaledEvent signaled = event.getEntityOperationSignaled();
+ OperationRequest.Builder opBuilder = OperationRequest.newBuilder()
+ .setRequestId(signaled.getRequestId())
+ .setOperation(signaled.getOperation());
+ if (signaled.hasInput()) {
+ opBuilder.setInput(signaled.getInput());
+ }
+ batchBuilder.addOperations(opBuilder.build());
+ // Fire-and-forget: no response destination
+ operationInfos.add(OperationInfo.newBuilder()
+ .setRequestId(signaled.getRequestId())
+ .build());
+ } else if (event.hasEntityOperationCalled()) {
+ EntityOperationCalledEvent called = event.getEntityOperationCalled();
+ OperationRequest.Builder opBuilder = OperationRequest.newBuilder()
+ .setRequestId(called.getRequestId())
+ .setOperation(called.getOperation());
+ if (called.hasInput()) {
+ opBuilder.setInput(called.getInput());
+ }
+ batchBuilder.addOperations(opBuilder.build());
+ // Two-way call: include response destination
+ OperationInfo.Builder infoBuilder = OperationInfo.newBuilder()
+ .setRequestId(called.getRequestId());
+ if (called.hasParentInstanceId()) {
+ OrchestrationInstance.Builder destBuilder = OrchestrationInstance.newBuilder()
+ .setInstanceId(called.getParentInstanceId().getValue());
+ if (called.hasParentExecutionId()) {
+ destBuilder.setExecutionId(StringValue.of(called.getParentExecutionId().getValue()));
+ }
+ infoBuilder.setResponseDestination(destBuilder.build());
+ }
+ operationInfos.add(infoBuilder.build());
+ } else {
+ logger.log(Level.WARNING,
+ "Skipping unsupported history event type in ENTITYREQUESTV2: {0}",
+ event.getEventTypeCase());
+ }
+ }
+
+ EntityBatchRequest batchRequest = batchBuilder.build();
+ EntityBatchResult result = taskEntityExecutor.execute(batchRequest);
+
+ // Attach completion token and operation infos for response routing
+ EntityBatchResult.Builder responseBuilder = result.toBuilder()
+ .setCompletionToken(workItem.getCompletionToken());
+ // Trim operationInfos to match actual result count
+ int resultCount = result.getResultsCount();
+ if (operationInfos.size() != resultCount) {
+ logger.log(Level.WARNING,
+ String.format("Entity '%s': operationInfos size (%d) does not match result count (%d). Trimming.",
+ entityRequestV2.getInstanceId(),
+ operationInfos.size(),
+ resultCount));
+ }
+ if (operationInfos.size() > resultCount) {
+ responseBuilder.addAllOperationInfos(operationInfos.subList(0, resultCount));
+ } else {
+ responseBuilder.addAllOperationInfos(operationInfos);
+ }
+ this.sidecarClient.completeEntityTask(responseBuilder.build());
+ } catch (Exception e) {
+ logger.log(Level.WARNING,
+ String.format("Failed to execute V2 entity batch for '%s'. Abandoning work item.",
+ entityRequestV2.getInstanceId()),
+ e);
+ this.sidecarClient.abandonTaskEntityWorkItem(
+ AbandonEntityTaskRequest.newBuilder()
+ .setCompletionToken(workItem.getCompletionToken())
+ .build());
+ }
+ });
+ }
else if (requestType == RequestCase.HEALTHPING)
{
// No-op
@@ -408,4 +553,4 @@ else if (requestType == RequestCase.HEALTHPING)
public void stop() {
this.close();
}
-}
\ No newline at end of file
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcWorkerBuilder.java b/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcWorkerBuilder.java
index ec39fee2..00cc0586 100644
--- a/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcWorkerBuilder.java
+++ b/client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcWorkerBuilder.java
@@ -4,8 +4,10 @@
import io.grpc.Channel;
+import java.lang.reflect.InvocationTargetException;
import java.time.Duration;
import java.util.HashMap;
+import java.util.Locale;
/**
* Builder object for constructing customized {@link DurableTaskGrpcWorker} instances.
@@ -13,11 +15,14 @@
public final class DurableTaskGrpcWorkerBuilder {
final HashMap orchestrationFactories = new HashMap<>();
final HashMap activityFactories = new HashMap<>();
+ final HashMap entityFactories = new HashMap<>();
int port;
Channel channel;
DataConverter dataConverter;
Duration maximumTimerInterval;
DurableTaskGrpcWorkerVersioningOptions versioningOptions;
+ int maxConcurrentEntityWorkItems = 1;
+ int maxWorkItemThreads;
/**
* Adds an orchestration factory to be used by the constructed {@link DurableTaskGrpcWorker}.
@@ -62,6 +67,127 @@ public DurableTaskGrpcWorkerBuilder addActivity(TaskActivityFactory factory) {
return this;
}
+ /**
+ * Adds an entity factory to be used by the constructed {@link DurableTaskGrpcWorker}.
+ *
+ * @param name the name of the entity type
+ * @param factory the factory that creates instances of the entity
+ * @return this builder object
+ */
+ public DurableTaskGrpcWorkerBuilder addEntity(String name, TaskEntityFactory factory) {
+ if (name == null || name.isEmpty()) {
+ throw new IllegalArgumentException("A non-empty entity name is required.");
+ }
+ if (factory == null) {
+ throw new IllegalArgumentException("An entity factory is required.");
+ }
+
+ String key = name.toLowerCase(Locale.ROOT);
+ if (this.entityFactories.containsKey(key)) {
+ throw new IllegalArgumentException(
+ String.format("An entity factory named %s is already registered.", name));
+ }
+
+ this.entityFactories.put(key, factory);
+ return this;
+ }
+
+ /**
+ * Registers an entity type for the constructed {@link DurableTaskGrpcWorker}.
+ *
+ * The entity class must implement {@link TaskEntity} and have a public no-argument constructor.
+ * A new instance of the entity is created for each operation batch using reflection.
+ *
+ * The entity name is derived from the simple class name of the provided type.
+ *
+ * @param entityClass the entity class to register; must implement {@link TaskEntity}
+ * @return this builder object
+ * @throws IllegalArgumentException if the class does not implement {@link TaskEntity}
+ */
+ public DurableTaskGrpcWorkerBuilder addEntity(Class entityClass) {
+ if (entityClass == null) {
+ throw new IllegalArgumentException("entityClass must not be null.");
+ }
+ String name = entityClass.getSimpleName();
+ return this.addEntity(name, entityClass);
+ }
+
+ /**
+ * Registers an entity type with a specific name for the constructed {@link DurableTaskGrpcWorker}.
+ *
+ * The entity class must implement {@link TaskEntity} and have a public no-argument constructor.
+ * A new instance of the entity is created for each operation batch using reflection.
+ *
+ * @param name the name of the entity type
+ * @param entityClass the entity class to register; must implement {@link TaskEntity}
+ * @return this builder object
+ * @throws IllegalArgumentException if the class does not implement {@link TaskEntity}
+ */
+ public DurableTaskGrpcWorkerBuilder addEntity(String name, Class entityClass) {
+ if (entityClass == null) {
+ throw new IllegalArgumentException("entityClass must not be null.");
+ }
+ if (!TaskEntity.class.isAssignableFrom(entityClass)) {
+ throw new IllegalArgumentException(
+ String.format("Type %s does not implement TaskEntity.", entityClass.getName()));
+ }
+ return this.addEntity(name, () -> {
+ try {
+ return entityClass.getDeclaredConstructor().newInstance();
+ } catch (InstantiationException | IllegalAccessException | InvocationTargetException | NoSuchMethodException e) {
+ throw new RuntimeException(
+ String.format("Failed to create instance of entity type %s. Ensure it has a public no-argument constructor.", entityClass.getName()), e);
+ }
+ });
+ }
+
+ /**
+ * Registers an entity singleton for the constructed {@link DurableTaskGrpcWorker}.
+ *
+ * The same entity instance is reused for every operation batch. This is useful for stateless entities
+ * or entities that manage their own lifecycle.
+ *
+ * The entity name is derived from the simple class name of the provided entity instance.
+ *
+ * Thread safety warning: Because the same instance handles all operation batches,
+ * the entity implementation must be thread-safe if concurrent entity work items are enabled.
+ * Implementations that extend {@link AbstractTaskEntity} store mutable state in instance fields and
+ * are not safe for singleton registration. Use {@link #addEntity(Class)} or
+ * {@link #addEntity(String, Class)} instead to create a new instance per batch.
+ *
+ * @param entity the entity instance to register
+ * @return this builder object
+ */
+ public DurableTaskGrpcWorkerBuilder addEntity(TaskEntity entity) {
+ if (entity == null) {
+ throw new IllegalArgumentException("entity must not be null.");
+ }
+ String name = entity.getClass().getSimpleName();
+ return this.addEntity(name, () -> entity);
+ }
+
+ /**
+ * Registers an entity singleton with a specific name for the constructed {@link DurableTaskGrpcWorker}.
+ *
+ * The same entity instance is reused for every operation batch.
+ *
+ * Thread safety warning: Because the same instance handles all operation batches,
+ * the entity implementation must be thread-safe if concurrent entity work items are enabled.
+ * Implementations that extend {@link AbstractTaskEntity} store mutable state in instance fields and
+ * are not safe for singleton registration. Use {@link #addEntity(String, Class)} instead
+ * to create a new instance per batch.
+ *
+ * @param name the name of the entity type
+ * @param entity the entity instance to register
+ * @return this builder object
+ */
+ public DurableTaskGrpcWorkerBuilder addEntity(String name, TaskEntity entity) {
+ if (entity == null) {
+ throw new IllegalArgumentException("entity must not be null.");
+ }
+ return this.addEntity(name, () -> entity);
+ }
+
/**
* Sets the gRPC channel to use for communicating with the sidecar process.
*
@@ -114,6 +240,42 @@ public DurableTaskGrpcWorkerBuilder maximumTimerInterval(Duration maximumTimerIn
return this;
}
+ /**
+ * Sets the maximum number of entity work items that can be processed concurrently by this worker.
+ *
+ * Each entity instance is always single-threaded (serial execution), but this setting controls
+ * how many different entity instances can process work items in parallel. The default value is 1.
+ *
+ * @param maxConcurrentEntityWorkItems the maximum number of concurrent entity work items (must be at least 1)
+ * @return this builder object
+ * @throws IllegalArgumentException if the value is less than 1
+ */
+ public DurableTaskGrpcWorkerBuilder maxConcurrentEntityWorkItems(int maxConcurrentEntityWorkItems) {
+ if (maxConcurrentEntityWorkItems < 1) {
+ throw new IllegalArgumentException("maxConcurrentEntityWorkItems must be at least 1.");
+ }
+ this.maxConcurrentEntityWorkItems = maxConcurrentEntityWorkItems;
+ return this;
+ }
+
+ /**
+ * Sets the maximum number of threads used for processing entity work items.
+ *
+ * The default value is {@value DurableTaskGrpcWorker#DEFAULT_MAX_WORK_ITEM_THREADS}.
+ * Threads are created on demand and idle threads are reclaimed after 60 seconds.
+ *
+ * @param maxWorkItemThreads the maximum number of work item threads (must be at least 1)
+ * @return this builder object
+ * @throws IllegalArgumentException if the value is less than 1
+ */
+ public DurableTaskGrpcWorkerBuilder maxWorkItemThreads(int maxWorkItemThreads) {
+ if (maxWorkItemThreads < 1) {
+ throw new IllegalArgumentException("maxWorkItemThreads must be at least 1.");
+ }
+ this.maxWorkItemThreads = maxWorkItemThreads;
+ return this;
+ }
+
/**
* Sets the versioning options for this worker.
*
diff --git a/client/src/main/java/com/microsoft/durabletask/EntityInstanceId.java b/client/src/main/java/com/microsoft/durabletask/EntityInstanceId.java
new file mode 100644
index 00000000..ad8153d8
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/EntityInstanceId.java
@@ -0,0 +1,119 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nonnull;
+import java.util.Locale;
+import java.util.Objects;
+
+/**
+ * Immutable identifier for a durable entity instance, consisting of a name and key pair.
+ *
+ * The name typically corresponds to the entity class/type name, and the key identifies the specific
+ * entity instance (e.g., a user ID or account number).
+ */
+public final class EntityInstanceId implements Comparable {
+ private final String name;
+ private final String key;
+
+ /**
+ * Creates a new {@code EntityInstanceId} with the specified name and key.
+ *
+ * @param name the entity name (type), must not be null
+ * @param key the entity key (instance identifier), must not be null
+ * @throws IllegalArgumentException if name or key is null or empty
+ */
+ public EntityInstanceId(@Nonnull String name, @Nonnull String key) {
+ if (name == null || name.isEmpty()) {
+ throw new IllegalArgumentException("Entity name must not be null or empty.");
+ }
+ if (name.contains("@")) {
+ throw new IllegalArgumentException("Entity name must not contain '@'.");
+ }
+ if (key == null || key.isEmpty()) {
+ throw new IllegalArgumentException("Entity key must not be null or empty.");
+ }
+ this.name = name.toLowerCase(Locale.ROOT);
+ this.key = key;
+ }
+
+ /**
+ * Gets the entity name (type).
+ *
+ * @return the entity name
+ */
+ @Nonnull
+ public String getName() {
+ return this.name;
+ }
+
+ /**
+ * Gets the entity key (instance identifier).
+ *
+ * @return the entity key
+ */
+ @Nonnull
+ public String getKey() {
+ return this.key;
+ }
+
+ /**
+ * Parses an {@code EntityInstanceId} from its string representation.
+ *
+ * The expected format is {@code @{name}@{key}}, matching the .NET {@code EntityId.ToString()} format.
+ *
+ * @param value the string to parse
+ * @return the parsed {@code EntityInstanceId}
+ * @throws IllegalArgumentException if the string is not in the expected format
+ */
+ @Nonnull
+ public static EntityInstanceId fromString(@Nonnull String value) {
+ if (value == null || value.isEmpty()) {
+ throw new IllegalArgumentException("Value must not be null or empty.");
+ }
+ if (!value.startsWith("@")) {
+ throw new IllegalArgumentException(
+ "Invalid EntityInstanceId format. Expected '@{name}@{key}', got: " + value);
+ }
+ int secondAt = value.indexOf('@', 1);
+ if (secondAt < 0) {
+ throw new IllegalArgumentException(
+ "Invalid EntityInstanceId format. Expected '@{name}@{key}', got: " + value);
+ }
+ String name = value.substring(1, secondAt);
+ String key = value.substring(secondAt + 1);
+ return new EntityInstanceId(name, key);
+ }
+
+ /**
+ * Returns the string representation in the format {@code @{name}@{key}}.
+ *
+ * @return the string representation of this entity instance ID
+ */
+ @Override
+ public String toString() {
+ return "@" + this.name + "@" + this.key;
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o) return true;
+ if (o == null || getClass() != o.getClass()) return false;
+ EntityInstanceId that = (EntityInstanceId) o;
+ return this.name.equals(that.name) && this.key.equals(that.key);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.name, this.key);
+ }
+
+ @Override
+ public int compareTo(@Nonnull EntityInstanceId other) {
+ int nameCompare = this.name.compareTo(other.name);
+ if (nameCompare != 0) {
+ return nameCompare;
+ }
+ return this.key.compareTo(other.key);
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/EntityMetadata.java b/client/src/main/java/com/microsoft/durabletask/EntityMetadata.java
new file mode 100644
index 00000000..c6d00070
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/EntityMetadata.java
@@ -0,0 +1,152 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+import java.time.Instant;
+
+/**
+ * Represents metadata about a durable entity instance, including its identity, state, and lock status.
+ *
+ * For typed state access, see {@link TypedEntityMetadata} which provides a {@code getState()} method
+ * that returns the deserialized state as a specific type.
+ *
+ * @see TypedEntityMetadata
+ */
+public class EntityMetadata {
+ private final String instanceId;
+ private final Instant lastModifiedTime;
+ private final int backlogQueueSize;
+ private final String lockedBy;
+ private final String serializedState;
+ private final boolean includesState;
+ private final DataConverter dataConverter;
+ private volatile EntityInstanceId cachedEntityInstanceId;
+
+ /**
+ * Creates a new {@code EntityMetadata} instance.
+ *
+ * @param instanceId the entity instance ID string (in {@code @name@key} format)
+ * @param lastModifiedTime the time the entity was last modified
+ * @param backlogQueueSize the number of operations waiting in the entity's backlog queue
+ * @param lockedBy the orchestration instance ID that currently holds a lock on this entity, or {@code null}
+ * @param serializedState the serialized entity state, or {@code null} if state was not fetched
+ * @param includesState {@code true} if the state was requested and is included in this metadata
+ * @param dataConverter the data converter used to deserialize state
+ */
+ EntityMetadata(
+ String instanceId,
+ Instant lastModifiedTime,
+ int backlogQueueSize,
+ @Nullable String lockedBy,
+ @Nullable String serializedState,
+ boolean includesState,
+ DataConverter dataConverter) {
+ this.instanceId = instanceId;
+ this.lastModifiedTime = lastModifiedTime;
+ this.backlogQueueSize = backlogQueueSize;
+ this.lockedBy = lockedBy;
+ this.serializedState = serializedState;
+ this.includesState = includesState;
+ this.dataConverter = dataConverter;
+ }
+
+ /**
+ * Gets the entity instance ID string.
+ *
+ * @return the instance ID
+ */
+ public String getInstanceId() {
+ return this.instanceId;
+ }
+
+ /**
+ * Gets the parsed {@link EntityInstanceId} from the instance ID string.
+ *
+ * @return the parsed entity instance ID
+ */
+ public EntityInstanceId getEntityInstanceId() {
+ if (this.cachedEntityInstanceId == null) {
+ this.cachedEntityInstanceId = EntityInstanceId.fromString(this.instanceId);
+ }
+ return this.cachedEntityInstanceId;
+ }
+
+ /**
+ * Gets the time the entity was last modified.
+ *
+ * @return the last modified time
+ */
+ public Instant getLastModifiedTime() {
+ return this.lastModifiedTime;
+ }
+
+ /**
+ * Gets the number of operations waiting in the entity's backlog queue.
+ *
+ * @return the backlog queue size
+ */
+ public int getBacklogQueueSize() {
+ return this.backlogQueueSize;
+ }
+
+ /**
+ * Gets the orchestration instance ID that currently holds a lock on this entity,
+ * or {@code null} if the entity is not locked.
+ *
+ * @return the locking orchestration instance ID, or {@code null}
+ */
+ @Nullable
+ public String getLockedBy() {
+ return this.lockedBy;
+ }
+
+ /**
+ * Gets the raw serialized entity state, or {@code null} if state was not fetched.
+ *
+ * @return the serialized state string, or {@code null}
+ */
+ @Nullable
+ public String getSerializedState() {
+ return this.serializedState;
+ }
+
+ /**
+ * Gets whether this metadata response includes the entity state.
+ *
+ * Queries can exclude the state of the entity from the metadata that is retrieved.
+ * When this returns {@code false}, {@link #getSerializedState()} and {@link #readStateAs(Class)}
+ * will return {@code null}.
+ *
+ * @return {@code true} if state was requested and included in this metadata
+ */
+ public boolean isIncludesState() {
+ return this.includesState;
+ }
+
+ /**
+ * Gets the data converter used for state deserialization.
+ *
+ * This is package-private to allow {@link TypedEntityMetadata} to pass it to the superclass constructor.
+ *
+ * @return the data converter
+ */
+ DataConverter getDataConverter() {
+ return this.dataConverter;
+ }
+
+ /**
+ * Deserializes the entity state into an object of the specified type.
+ *
+ * @param stateType the class to deserialize the state into
+ * @param the target type
+ * @return the deserialized state, or {@code null} if no state is available
+ */
+ @Nullable
+ public T readStateAs(Class stateType) {
+ if (this.serializedState == null) {
+ return null;
+ }
+ return this.dataConverter.deserialize(this.serializedState, stateType);
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/EntityOperationFailedException.java b/client/src/main/java/com/microsoft/durabletask/EntityOperationFailedException.java
new file mode 100644
index 00000000..d34071af
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/EntityOperationFailedException.java
@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * Exception thrown when a two-way entity call fails because the entity operation threw an exception.
+ *
+ * This is analogous to {@link TaskFailedException} but specific to entity operations invoked
+ * via {@code callEntity}. The {@link #getFailureDetails()} method provides detailed information
+ * about the failure.
+ */
+public class EntityOperationFailedException extends RuntimeException {
+ private final EntityInstanceId entityId;
+ private final String operationName;
+ private final FailureDetails failureDetails;
+
+ /**
+ * Creates a new {@code EntityOperationFailedException}.
+ *
+ * @param entityId the ID of the entity that failed
+ * @param operationName the name of the operation that failed
+ * @param failureDetails the details of the failure
+ */
+ public EntityOperationFailedException(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nonnull FailureDetails failureDetails) {
+ super(String.format(
+ "Entity operation '%s' on entity '%s' failed: %s",
+ operationName,
+ entityId.toString(),
+ failureDetails.getErrorMessage()));
+ this.entityId = entityId;
+ this.operationName = operationName;
+ this.failureDetails = failureDetails;
+ }
+
+ /**
+ * Gets the ID of the entity that failed.
+ *
+ * @return the entity instance ID
+ */
+ @Nonnull
+ public EntityInstanceId getEntityId() {
+ return this.entityId;
+ }
+
+ /**
+ * Gets the name of the operation that failed.
+ *
+ * @return the operation name
+ */
+ @Nonnull
+ public String getOperationName() {
+ return this.operationName;
+ }
+
+ /**
+ * Gets the failure details, including the error type, message, and stack trace.
+ *
+ * @return the failure details
+ */
+ @Nonnull
+ public FailureDetails getFailureDetails() {
+ return this.failureDetails;
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/EntityProxy.java b/client/src/main/java/com/microsoft/durabletask/EntityProxy.java
new file mode 100644
index 00000000..9e49e770
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/EntityProxy.java
@@ -0,0 +1,192 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nonnull;
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Proxy;
+import java.lang.reflect.Type;
+
+/**
+ * Creates type-safe proxies for interacting with durable entities from orchestrations.
+ *
+ * A typed entity proxy is a JDK dynamic proxy that implements a user-defined interface.
+ * Method calls on the proxy are translated into entity operations:
+ *
+ * - {@code void} methods become fire-and-forget signals via
+ * {@link TaskOrchestrationContext#signalEntity}
+ * - Methods returning {@link Task}{@code } become two-way calls via
+ * {@link TaskOrchestrationContext#callEntity}
+ *
+ *
+ * The method name is used as the entity operation name (case-insensitive matching on the
+ * entity side). Methods must accept 0 or 1 parameters; the single parameter is passed as
+ * the operation input.
+ *
+ *
Example:
+ *
{@code
+ * // Define entity operations as an interface
+ * public interface ICounter {
+ * void add(int amount); // fire-and-forget signal
+ * void reset(); // fire-and-forget signal
+ * Task get(); // two-way call returning a result
+ * }
+ *
+ * // Use in an orchestration
+ * ICounter counter = ctx.createEntityProxy(entityId, ICounter.class);
+ * counter.add(5);
+ * counter.reset();
+ * int value = counter.get().await();
+ * }
+ *
+ * @see TaskOrchestrationContext#createEntityProxy(EntityInstanceId, Class)
+ * @see TaskOrchestrationEntityFeature#createProxy(EntityInstanceId, Class)
+ */
+public final class EntityProxy {
+
+ private EntityProxy() {
+ // Utility class — not instantiable
+ }
+
+ /**
+ * Creates a typed entity proxy for the given entity instance.
+ *
+ * @param ctx the orchestration context (used to send signals and calls)
+ * @param entityId the target entity's instance ID
+ * @param proxyInterface the interface whose methods map to entity operations
+ * @param the proxy interface type
+ * @return a proxy instance that implements {@code proxyInterface}
+ * @throws IllegalArgumentException if {@code proxyInterface} is not an interface
+ */
+ @SuppressWarnings("unchecked")
+ public static T create(
+ @Nonnull TaskOrchestrationContext ctx,
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull Class proxyInterface) {
+ if (ctx == null) {
+ throw new IllegalArgumentException("ctx must not be null");
+ }
+ if (entityId == null) {
+ throw new IllegalArgumentException("entityId must not be null");
+ }
+ if (proxyInterface == null) {
+ throw new IllegalArgumentException("proxyInterface must not be null");
+ }
+ if (!proxyInterface.isInterface()) {
+ throw new IllegalArgumentException(
+ "proxyInterface must be an interface, got: " + proxyInterface.getName());
+ }
+
+ return (T) Proxy.newProxyInstance(
+ proxyInterface.getClassLoader(),
+ new Class[]{ proxyInterface },
+ new EntityInvocationHandler(ctx, entityId));
+ }
+
+ /**
+ * Invocation handler that translates interface method calls into entity operations.
+ */
+ private static final class EntityInvocationHandler implements InvocationHandler {
+ private final TaskOrchestrationContext ctx;
+ private final EntityInstanceId entityId;
+
+ EntityInvocationHandler(TaskOrchestrationContext ctx, EntityInstanceId entityId) {
+ this.ctx = ctx;
+ this.entityId = entityId;
+ }
+
+ @Override
+ public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
+ // Handle java.lang.Object methods
+ if (method.getDeclaringClass() == Object.class) {
+ switch (method.getName()) {
+ case "toString":
+ return "EntityProxy[" + entityId + "]";
+ case "hashCode":
+ return entityId.hashCode();
+ case "equals":
+ if (args == null || args.length == 0) {
+ return false;
+ }
+ if (args[0] == proxy) {
+ return true;
+ }
+ if (args[0] == null || !Proxy.isProxyClass(args[0].getClass())) {
+ return false;
+ }
+ InvocationHandler otherHandler = Proxy.getInvocationHandler(args[0]);
+ if (otherHandler instanceof EntityInvocationHandler) {
+ return entityId.equals(((EntityInvocationHandler) otherHandler).entityId);
+ }
+ return false;
+ default:
+ return method.invoke(this, args);
+ }
+ }
+
+ String operationName = method.getName();
+
+ if (args != null && args.length > 1) {
+ throw new UnsupportedOperationException(
+ "Entity proxy methods must have 0 or 1 parameters. " +
+ "Method '" + operationName + "' has " + args.length + " parameters. " +
+ "Use a single wrapper object to pass multiple values.");
+ }
+
+ Object input = (args != null && args.length == 1) ? args[0] : null;
+
+ Class returnType = method.getReturnType();
+
+ if (returnType == void.class) {
+ // Fire-and-forget signal
+ ctx.signalEntity(entityId, operationName, input);
+ return null;
+ } else if (Task.class.isAssignableFrom(returnType)) {
+ // Two-way entity call — extract the Task type parameter
+ Class resultType = extractTaskTypeParameter(method);
+ return ctx.callEntity(entityId, operationName, input, resultType);
+ } else {
+ throw new UnsupportedOperationException(
+ "Entity proxy methods must return void (for signals) or Task (for calls). " +
+ "Method '" + operationName + "' returns " + returnType.getName() + ".");
+ }
+ }
+
+ /**
+ * Extracts the generic type parameter from a method returning {@code Task}.
+ * Falls back to {@code Void.class} if the type cannot be determined.
+ */
+ private static Class extractTaskTypeParameter(Method method) {
+ Type genericReturnType = method.getGenericReturnType();
+ if (genericReturnType instanceof ParameterizedType) {
+ ParameterizedType pt = (ParameterizedType) genericReturnType;
+ Type[] typeArgs = pt.getActualTypeArguments();
+ if (typeArgs.length > 0) {
+ return getRawClass(typeArgs[0]);
+ }
+ }
+ return Void.class;
+ }
+
+ /**
+ * Resolves a {@link Type} to its raw {@link Class}, handling parameterized types
+ * and wildcard types.
+ */
+ private static Class getRawClass(Type type) {
+ if (type instanceof Class) {
+ return (Class) type;
+ } else if (type instanceof ParameterizedType) {
+ return getRawClass(((ParameterizedType) type).getRawType());
+ } else if (type instanceof java.lang.reflect.WildcardType) {
+ java.lang.reflect.WildcardType wt = (java.lang.reflect.WildcardType) type;
+ Type[] upperBounds = wt.getUpperBounds();
+ if (upperBounds.length > 0) {
+ return getRawClass(upperBounds[0]);
+ }
+ }
+ return Object.class;
+ }
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/EntityQuery.java b/client/src/main/java/com/microsoft/durabletask/EntityQuery.java
new file mode 100644
index 00000000..0cf652fb
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/EntityQuery.java
@@ -0,0 +1,218 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+import java.time.Instant;
+import java.util.Locale;
+
+/**
+ * Represents a query filter for fetching durable entity metadata from the store.
+ *
+ * Use the builder-style setters to configure the query parameters, then pass this object to
+ * {@link DurableEntityClient#queryEntities(EntityQuery)}.
+ */
+public final class EntityQuery {
+
+ /**
+ * The default page size for entity queries ({@value}).
+ * This matches the .NET SDK's {@code EntityQuery.DefaultPageSize}.
+ */
+ public static final int DEFAULT_PAGE_SIZE = 100;
+
+ private String instanceIdStartsWith;
+ private Instant lastModifiedFrom;
+ private Instant lastModifiedTo;
+ private boolean includeState = true;
+ private boolean includeTransient;
+ private Integer pageSize;
+ private String continuationToken;
+
+ /**
+ * Creates a new {@code EntityQuery} with default settings.
+ */
+ public EntityQuery() {
+ }
+
+ /**
+ * Sets a prefix filter on entity instance IDs.
+ *
+ * If the value does not start with {@code @}, it is treated as a raw entity name and will be
+ * normalized to the internal format {@code @entityname} (lowercased) to match how entity
+ * instance IDs are stored.
+ *
+ * @param instanceIdStartsWith the instance ID prefix to filter by, or {@code null} for no filter
+ * @return this {@code EntityQuery} for chaining
+ */
+ public EntityQuery setInstanceIdStartsWith(@Nullable String instanceIdStartsWith) {
+ if (instanceIdStartsWith != null && !instanceIdStartsWith.startsWith("@")) {
+ // Normalize: treat as raw entity name, prepend '@' and lowercase
+ instanceIdStartsWith = "@" + instanceIdStartsWith.toLowerCase(Locale.ROOT);
+ } else if (instanceIdStartsWith != null) {
+ // Already in @name format, but ensure the entity name portion is lowercased
+ // Format is @entityName or @entityName@key
+ int secondAt = instanceIdStartsWith.indexOf('@', 1);
+ if (secondAt > 0) {
+ // Has key part: lowercase only the name between first and second @
+ instanceIdStartsWith = "@" + instanceIdStartsWith.substring(1, secondAt).toLowerCase(Locale.ROOT)
+ + instanceIdStartsWith.substring(secondAt);
+ } else {
+ // Only @name, lowercase the name portion
+ instanceIdStartsWith = "@" + instanceIdStartsWith.substring(1).toLowerCase(Locale.ROOT);
+ }
+ }
+ this.instanceIdStartsWith = instanceIdStartsWith;
+ return this;
+ }
+
+ /**
+ * Gets the instance ID prefix filter.
+ *
+ * @return the instance ID prefix, or {@code null}
+ */
+ @Nullable
+ public String getInstanceIdStartsWith() {
+ return this.instanceIdStartsWith;
+ }
+
+ /**
+ * Sets the minimum last-modified time filter (inclusive).
+ *
+ * @param lastModifiedFrom the minimum last-modified time, or {@code null} for no lower bound
+ * @return this {@code EntityQuery} for chaining
+ */
+ public EntityQuery setLastModifiedFrom(@Nullable Instant lastModifiedFrom) {
+ this.lastModifiedFrom = lastModifiedFrom;
+ return this;
+ }
+
+ /**
+ * Gets the minimum last-modified time filter.
+ *
+ * @return the minimum last-modified time, or {@code null}
+ */
+ @Nullable
+ public Instant getLastModifiedFrom() {
+ return this.lastModifiedFrom;
+ }
+
+ /**
+ * Sets the maximum last-modified time filter (inclusive).
+ *
+ * @param lastModifiedTo the maximum last-modified time, or {@code null} for no upper bound
+ * @return this {@code EntityQuery} for chaining
+ */
+ public EntityQuery setLastModifiedTo(@Nullable Instant lastModifiedTo) {
+ this.lastModifiedTo = lastModifiedTo;
+ return this;
+ }
+
+ /**
+ * Gets the maximum last-modified time filter.
+ *
+ * @return the maximum last-modified time, or {@code null}
+ */
+ @Nullable
+ public Instant getLastModifiedTo() {
+ return this.lastModifiedTo;
+ }
+
+ /**
+ * Sets whether to include entity state in the query results.
+ *
+ * @param includeState {@code true} to include state, {@code false} to omit it
+ * @return this {@code EntityQuery} for chaining
+ */
+ public EntityQuery setIncludeState(boolean includeState) {
+ this.includeState = includeState;
+ return this;
+ }
+
+ /**
+ * Gets whether entity state is included in query results.
+ *
+ * @return {@code true} if state is included
+ */
+ public boolean isIncludeState() {
+ return this.includeState;
+ }
+
+ /**
+ * Sets whether to include transient (not yet persisted) entities in the results.
+ *
+ * @param includeTransient {@code true} to include transient entities
+ * @return this {@code EntityQuery} for chaining
+ */
+ public EntityQuery setIncludeTransient(boolean includeTransient) {
+ this.includeTransient = includeTransient;
+ return this;
+ }
+
+ /**
+ * Gets whether transient entities are included in query results.
+ *
+ * @return {@code true} if transient entities are included
+ */
+ public boolean isIncludeTransient() {
+ return this.includeTransient;
+ }
+
+ /**
+ * Sets the maximum number of results to return per page.
+ *
+ * @param pageSize the page size, or {@code null} for the server default
+ * @return this {@code EntityQuery} for chaining
+ */
+ public EntityQuery setPageSize(@Nullable Integer pageSize) {
+ this.pageSize = pageSize;
+ return this;
+ }
+
+ /**
+ * Gets the maximum number of results per page.
+ *
+ * @return the page size, or {@code null} for the server default
+ */
+ @Nullable
+ public Integer getPageSize() {
+ return this.pageSize;
+ }
+
+ /**
+ * Sets the continuation token for fetching the next page of results.
+ *
+ * @param continuationToken the continuation token from a previous query, or {@code null} to start from the beginning
+ * @return this {@code EntityQuery} for chaining
+ */
+ public EntityQuery setContinuationToken(@Nullable String continuationToken) {
+ this.continuationToken = continuationToken;
+ return this;
+ }
+
+ /**
+ * Gets the continuation token for pagination.
+ *
+ * @return the continuation token, or {@code null}
+ */
+ @Nullable
+ public String getContinuationToken() {
+ return this.continuationToken;
+ }
+
+ /**
+ * Creates a shallow copy of this query.
+ *
+ * @return a new {@code EntityQuery} with the same field values
+ */
+ public EntityQuery copy() {
+ EntityQuery copy = new EntityQuery();
+ copy.instanceIdStartsWith = this.instanceIdStartsWith;
+ copy.lastModifiedFrom = this.lastModifiedFrom;
+ copy.lastModifiedTo = this.lastModifiedTo;
+ copy.includeState = this.includeState;
+ copy.includeTransient = this.includeTransient;
+ copy.pageSize = this.pageSize;
+ copy.continuationToken = this.continuationToken;
+ return copy;
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/EntityQueryPageable.java b/client/src/main/java/com/microsoft/durabletask/EntityQueryPageable.java
new file mode 100644
index 00000000..fcf07ab1
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/EntityQueryPageable.java
@@ -0,0 +1,165 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+import java.util.Iterator;
+import java.util.List;
+import java.util.NoSuchElementException;
+import java.util.function.Function;
+
+/**
+ * An auto-paginating iterable over entity query results.
+ *
+ * This class automatically handles pagination when iterating over entity metadata results.
+ * It fetches pages from the store on demand and yields individual {@link EntityMetadata}
+ * items to the caller.
+ *
+ * Use {@link DurableEntityClient#getAllEntities(EntityQuery)} to obtain an instance of this class.
+ *
+ *
Example: iterate over all entities
+ * {@code
+ * EntityQuery query = new EntityQuery()
+ * .setInstanceIdStartsWith("counter")
+ * .setIncludeState(true);
+ *
+ * for (EntityMetadata entity : client.getEntities().getAllEntities(query)) {
+ * System.out.println(entity.getEntityInstanceId());
+ * }
+ * }
+ *
+ * Example: iterate page by page
+ * {@code
+ * for (EntityQueryResult page : client.getEntities().getAllEntities(query).byPage()) {
+ * System.out.println("Got " + page.getEntities().size() + " entities");
+ * for (EntityMetadata entity : page.getEntities()) {
+ * System.out.println(entity.getEntityInstanceId());
+ * }
+ * }
+ * }
+ */
+public final class EntityQueryPageable implements Iterable {
+ private final EntityQuery baseQuery;
+ private final Function queryExecutor;
+
+ /**
+ * Creates a new {@code EntityQueryPageable}.
+ *
+ * @param baseQuery the base query parameters
+ * @param queryExecutor the function that executes a single page query
+ */
+ EntityQueryPageable(EntityQuery baseQuery, Function queryExecutor) {
+ this.baseQuery = baseQuery;
+ this.queryExecutor = queryExecutor;
+ }
+
+ /**
+ * Returns an iterator over individual {@link EntityMetadata} items, automatically
+ * fetching subsequent pages as needed.
+ *
+ * @return an iterator over all matching entities
+ */
+ @Override
+ public Iterator iterator() {
+ return new EntityItemIterator();
+ }
+
+ /**
+ * Returns an iterable over pages of results, where each page is an {@link EntityQueryResult}
+ * containing a list of entities and an optional continuation token.
+ *
+ * @return an iterable over result pages
+ */
+ public Iterable byPage() {
+ return PageIterable::new;
+ }
+
+ private class EntityItemIterator implements Iterator {
+ private String continuationToken = baseQuery.getContinuationToken();
+ private Iterator currentPageIterator;
+ private boolean finished;
+
+ EntityItemIterator() {
+ fetchNextPage();
+ }
+
+ @Override
+ public boolean hasNext() {
+ while (true) {
+ if (currentPageIterator != null && currentPageIterator.hasNext()) {
+ return true;
+ }
+ if (finished) {
+ return false;
+ }
+ fetchNextPage();
+ }
+ }
+
+ @Override
+ public EntityMetadata next() {
+ if (!hasNext()) {
+ throw new NoSuchElementException();
+ }
+ return currentPageIterator.next();
+ }
+
+ private void fetchNextPage() {
+ if (finished) {
+ return;
+ }
+
+ EntityQuery pageQuery = baseQuery.copy();
+ pageQuery.setContinuationToken(continuationToken);
+
+ EntityQueryResult result = queryExecutor.apply(pageQuery);
+ List entities = result.getEntities();
+
+ if (entities == null || entities.isEmpty()) {
+ finished = true;
+ currentPageIterator = null;
+ return;
+ }
+
+ currentPageIterator = entities.iterator();
+ continuationToken = result.getContinuationToken();
+
+ if (continuationToken == null || continuationToken.isEmpty()) {
+ finished = true;
+ }
+ }
+ }
+
+ private class PageIterable implements Iterator {
+ private String continuationToken = baseQuery.getContinuationToken();
+ private boolean finished;
+ private boolean firstPage = true;
+
+ @Override
+ public boolean hasNext() {
+ return !finished;
+ }
+
+ @Override
+ public EntityQueryResult next() {
+ if (finished) {
+ throw new NoSuchElementException();
+ }
+
+ EntityQuery pageQuery = baseQuery.copy();
+ if (!firstPage) {
+ pageQuery.setContinuationToken(continuationToken);
+ }
+ firstPage = false;
+
+ EntityQueryResult result = queryExecutor.apply(pageQuery);
+ continuationToken = result.getContinuationToken();
+
+ if (continuationToken == null || continuationToken.isEmpty()) {
+ finished = true;
+ }
+
+ return result;
+ }
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/EntityQueryResult.java b/client/src/main/java/com/microsoft/durabletask/EntityQueryResult.java
new file mode 100644
index 00000000..078ab4ba
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/EntityQueryResult.java
@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Represents the result of an entity query operation, including the matching entities and
+ * an optional continuation token for pagination.
+ */
+public final class EntityQueryResult {
+ private final List entities;
+ private final String continuationToken;
+
+ /**
+ * Creates a new {@code EntityQueryResult}.
+ *
+ * @param entities the list of entity metadata records matching the query
+ * @param continuationToken the continuation token for fetching the next page, or {@code null} if no more results
+ */
+ EntityQueryResult(List entities, @Nullable String continuationToken) {
+ this.entities = entities != null ? Collections.unmodifiableList(entities) : Collections.emptyList();
+ this.continuationToken = continuationToken;
+ }
+
+ /**
+ * Gets the list of entity metadata records matching the query.
+ *
+ * @return the list of entity metadata
+ */
+ public List getEntities() {
+ return this.entities;
+ }
+
+ /**
+ * Gets the continuation token for fetching the next page of results.
+ *
+ * @return the continuation token, or {@code null} if there are no more results
+ */
+ @Nullable
+ public String getContinuationToken() {
+ return this.continuationToken;
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/EntityRunner.java b/client/src/main/java/com/microsoft/durabletask/EntityRunner.java
new file mode 100644
index 00000000..680cced2
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/EntityRunner.java
@@ -0,0 +1,132 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import com.google.protobuf.InvalidProtocolBufferException;
+import com.microsoft.durabletask.implementation.protobuf.OrchestratorService.EntityBatchRequest;
+import com.microsoft.durabletask.implementation.protobuf.OrchestratorService.EntityBatchResult;
+
+import java.util.Base64;
+import java.util.HashMap;
+import java.util.logging.Logger;
+
+/**
+ * Helper class for invoking entity operations directly, without constructing a {@link DurableTaskGrpcWorker} object.
+ *
+ * This static class can be used to execute entity logic directly. In order to use it for this purpose, the
+ * caller must provide entity state as serialized protobuf bytes. This is the entity equivalent of
+ * {@link OrchestrationRunner}.
+ *
+ * Typical usage in an Azure Functions entity trigger:
+ *
+ * {@literal @}FunctionName("Counter")
+ * public String counterEntity(
+ * {@literal @}DurableEntityTrigger(name = "req") String req) {
+ * return EntityRunner.loadAndRun(req, () -> new CounterEntity());
+ * }
+ *
+ */
+public final class EntityRunner {
+ private static final Logger logger = Logger.getLogger(EntityRunner.class.getPackage().getName());
+
+ private EntityRunner() {
+ }
+
+ /**
+ * Loads an entity batch request from {@code base64EncodedEntityRequest} and uses it to execute
+ * entity operations using the entity created by {@code entityFactory}.
+ *
+ * @param base64EncodedEntityRequest the base64-encoded protobuf payload representing an entity batch request
+ * @param entityFactory a factory that creates the entity instance to handle operations
+ * @return a base64-encoded protobuf payload of the entity batch result
+ * @throws IllegalArgumentException if either parameter is {@code null} or if {@code base64EncodedEntityRequest}
+ * is not valid base64-encoded protobuf
+ */
+ public static String loadAndRun(String base64EncodedEntityRequest, TaskEntityFactory entityFactory) {
+ byte[] decodedBytes = Base64.getDecoder().decode(base64EncodedEntityRequest);
+ byte[] resultBytes = loadAndRun(decodedBytes, entityFactory);
+ return Base64.getEncoder().encodeToString(resultBytes);
+ }
+
+ /**
+ * Loads an entity batch request from {@code entityRequestBytes} and uses it to execute
+ * entity operations using the entity created by {@code entityFactory}.
+ *
+ * @param entityRequestBytes the protobuf payload representing an entity batch request
+ * @param entityFactory a factory that creates the entity instance to handle operations
+ * @return a protobuf-encoded payload of the entity batch result
+ * @throws IllegalArgumentException if either parameter is {@code null} or if {@code entityRequestBytes}
+ * is not valid protobuf
+ */
+ public static byte[] loadAndRun(byte[] entityRequestBytes, TaskEntityFactory entityFactory) {
+ if (entityRequestBytes == null || entityRequestBytes.length == 0) {
+ throw new IllegalArgumentException("entityRequestBytes must not be null or empty");
+ }
+
+ if (entityFactory == null) {
+ throw new IllegalArgumentException("entityFactory must not be null");
+ }
+
+ EntityBatchRequest request;
+ try {
+ request = EntityBatchRequest.parseFrom(entityRequestBytes);
+ } catch (InvalidProtocolBufferException e) {
+ throw new IllegalArgumentException("entityRequestBytes was not valid protobuf", e);
+ }
+
+ // Parse entity name from the instance ID so the executor can look it up
+ String instanceId = request.getInstanceId();
+ String entityName;
+ try {
+ entityName = EntityInstanceId.fromString(instanceId).getName();
+ } catch (Exception e) {
+ throw new IllegalArgumentException(
+ "Failed to parse entity instance ID '" + instanceId + "'", e);
+ }
+
+ HashMap factories = new HashMap<>();
+ factories.put(entityName, entityFactory);
+
+ TaskEntityExecutor executor = new TaskEntityExecutor(
+ factories,
+ new JacksonDataConverter(),
+ logger);
+
+ EntityBatchResult result = executor.execute(request);
+ return result.toByteArray();
+ }
+
+ /**
+ * Loads an entity batch request from {@code base64EncodedEntityRequest} and uses it to execute
+ * entity operations using the provided {@code entity} instance.
+ *
+ * @param base64EncodedEntityRequest the base64-encoded protobuf payload representing an entity batch request
+ * @param entity the entity instance to handle operations
+ * @return a base64-encoded protobuf payload of the entity batch result
+ * @throws IllegalArgumentException if either parameter is {@code null} or if {@code base64EncodedEntityRequest}
+ * is not valid base64-encoded protobuf
+ */
+ public static String loadAndRun(String base64EncodedEntityRequest, TaskEntity entity) {
+ if (entity == null) {
+ throw new IllegalArgumentException("entity must not be null");
+ }
+ return loadAndRun(base64EncodedEntityRequest, () -> entity);
+ }
+
+ /**
+ * Loads an entity batch request from {@code entityRequestBytes} and uses it to execute
+ * entity operations using the provided {@code entity} instance.
+ *
+ * @param entityRequestBytes the protobuf payload representing an entity batch request
+ * @param entity the entity instance to handle operations
+ * @return a protobuf-encoded payload of the entity batch result
+ * @throws IllegalArgumentException if either parameter is {@code null} or if {@code entityRequestBytes}
+ * is not valid protobuf
+ */
+ public static byte[] loadAndRun(byte[] entityRequestBytes, TaskEntity entity) {
+ if (entity == null) {
+ throw new IllegalArgumentException("entity must not be null");
+ }
+ return loadAndRun(entityRequestBytes, () -> entity);
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/GrpcDurableEntityClient.java b/client/src/main/java/com/microsoft/durabletask/GrpcDurableEntityClient.java
new file mode 100644
index 00000000..538eb3e2
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/GrpcDurableEntityClient.java
@@ -0,0 +1,176 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import com.google.protobuf.StringValue;
+import com.google.protobuf.Timestamp;
+import com.microsoft.durabletask.implementation.protobuf.OrchestratorService.*;
+import com.microsoft.durabletask.implementation.protobuf.TaskHubSidecarServiceGrpc.TaskHubSidecarServiceBlockingStub;
+
+import javax.annotation.Nullable;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * gRPC-based implementation of {@link DurableEntityClient}.
+ */
+final class GrpcDurableEntityClient extends DurableEntityClient {
+
+ private final TaskHubSidecarServiceBlockingStub sidecarClient;
+ private final DataConverter dataConverter;
+
+ GrpcDurableEntityClient(
+ String name,
+ TaskHubSidecarServiceBlockingStub sidecarClient,
+ DataConverter dataConverter) {
+ super(name);
+ this.sidecarClient = sidecarClient;
+ this.dataConverter = dataConverter;
+ }
+
+ @Override
+ public void signalEntity(
+ EntityInstanceId entityId,
+ String operationName,
+ @Nullable Object input,
+ @Nullable SignalEntityOptions options) {
+ Helpers.throwIfArgumentNull(entityId, "entityId");
+ Helpers.throwIfArgumentNull(operationName, "operationName");
+
+ SignalEntityRequest.Builder builder = SignalEntityRequest.newBuilder()
+ .setInstanceId(entityId.toString())
+ .setName(operationName)
+ .setRequestId(UUID.randomUUID().toString());
+
+ if (input != null) {
+ String serializedInput = this.dataConverter.serialize(input);
+ if (serializedInput != null) {
+ builder.setInput(StringValue.of(serializedInput));
+ }
+ }
+
+ if (options != null && options.getScheduledTime() != null) {
+ Timestamp ts = DataConverter.getTimestampFromInstant(options.getScheduledTime());
+ builder.setScheduledTime(ts);
+ }
+
+ this.sidecarClient.signalEntity(builder.build());
+ }
+
+ @Override
+ @Nullable
+ public EntityMetadata getEntityMetadata(EntityInstanceId entityId, boolean includeState) {
+ Helpers.throwIfArgumentNull(entityId, "entityId");
+
+ GetEntityRequest request = GetEntityRequest.newBuilder()
+ .setInstanceId(entityId.toString())
+ .setIncludeState(includeState)
+ .build();
+
+ GetEntityResponse response = this.sidecarClient.getEntity(request);
+ if (!response.getExists()) {
+ return null;
+ }
+
+ return toEntityMetadata(response.getEntity(), includeState);
+ }
+
+ @Override
+ public EntityQueryResult queryEntities(EntityQuery query) {
+ Helpers.throwIfArgumentNull(query, "query");
+
+ com.microsoft.durabletask.implementation.protobuf.OrchestratorService.EntityQuery.Builder queryBuilder =
+ com.microsoft.durabletask.implementation.protobuf.OrchestratorService.EntityQuery.newBuilder();
+
+ if (query.getInstanceIdStartsWith() != null) {
+ queryBuilder.setInstanceIdStartsWith(StringValue.of(query.getInstanceIdStartsWith()));
+ }
+ if (query.getLastModifiedFrom() != null) {
+ queryBuilder.setLastModifiedFrom(DataConverter.getTimestampFromInstant(query.getLastModifiedFrom()));
+ }
+ if (query.getLastModifiedTo() != null) {
+ queryBuilder.setLastModifiedTo(DataConverter.getTimestampFromInstant(query.getLastModifiedTo()));
+ }
+ queryBuilder.setIncludeState(query.isIncludeState());
+ queryBuilder.setIncludeTransient(query.isIncludeTransient());
+ if (query.getPageSize() != null) {
+ queryBuilder.setPageSize(com.google.protobuf.Int32Value.of(query.getPageSize()));
+ }
+ if (query.getContinuationToken() != null) {
+ queryBuilder.setContinuationToken(StringValue.of(query.getContinuationToken()));
+ }
+
+ QueryEntitiesRequest request = QueryEntitiesRequest.newBuilder()
+ .setQuery(queryBuilder)
+ .build();
+
+ QueryEntitiesResponse response = this.sidecarClient.queryEntities(request);
+
+ List entities = new ArrayList<>();
+ for (com.microsoft.durabletask.implementation.protobuf.OrchestratorService.EntityMetadata protoEntity
+ : response.getEntitiesList()) {
+ entities.add(toEntityMetadata(protoEntity, query.isIncludeState()));
+ }
+
+ String continuationToken = response.hasContinuationToken()
+ ? response.getContinuationToken().getValue()
+ : null;
+
+ return new EntityQueryResult(entities, continuationToken);
+ }
+
+ @Override
+ public CleanEntityStorageResult cleanEntityStorage(CleanEntityStorageRequest request) {
+ Helpers.throwIfArgumentNull(request, "request");
+
+ int totalEmptyEntitiesRemoved = 0;
+ int totalOrphanedLocksReleased = 0;
+ String continuationToken = request.getContinuationToken();
+
+ do {
+ com.microsoft.durabletask.implementation.protobuf.OrchestratorService.CleanEntityStorageRequest.Builder builder =
+ com.microsoft.durabletask.implementation.protobuf.OrchestratorService.CleanEntityStorageRequest.newBuilder()
+ .setRemoveEmptyEntities(request.isRemoveEmptyEntities())
+ .setReleaseOrphanedLocks(request.isReleaseOrphanedLocks());
+
+ if (continuationToken != null) {
+ builder.setContinuationToken(StringValue.of(continuationToken));
+ }
+
+ CleanEntityStorageResponse response = this.sidecarClient.cleanEntityStorage(builder.build());
+
+ totalEmptyEntitiesRemoved += response.getEmptyEntitiesRemoved();
+ totalOrphanedLocksReleased += response.getOrphanedLocksReleased();
+
+ continuationToken = response.hasContinuationToken()
+ ? response.getContinuationToken().getValue()
+ : null;
+ } while (request.isContinueUntilComplete() && continuationToken != null);
+
+ return new CleanEntityStorageResult(
+ continuationToken,
+ totalEmptyEntitiesRemoved,
+ totalOrphanedLocksReleased);
+ }
+
+ private EntityMetadata toEntityMetadata(
+ com.microsoft.durabletask.implementation.protobuf.OrchestratorService.EntityMetadata protoEntity,
+ boolean includeState) {
+ Instant lastModifiedTime = DataConverter.getInstantFromTimestamp(protoEntity.getLastModifiedTime());
+ String lockedBy = protoEntity.hasLockedBy() ? protoEntity.getLockedBy().getValue() : null;
+ String serializedState = protoEntity.hasSerializedState()
+ ? protoEntity.getSerializedState().getValue()
+ : null;
+
+ return new EntityMetadata(
+ protoEntity.getInstanceId(),
+ lastModifiedTime,
+ protoEntity.getBacklogQueueSize(),
+ lockedBy,
+ serializedState,
+ includeState,
+ this.dataConverter);
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/SignalEntityOptions.java b/client/src/main/java/com/microsoft/durabletask/SignalEntityOptions.java
new file mode 100644
index 00000000..1c3a91ed
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/SignalEntityOptions.java
@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+import java.time.Instant;
+
+/**
+ * Options for signaling a durable entity.
+ */
+public final class SignalEntityOptions {
+ private Instant scheduledTime;
+
+ /**
+ * Creates a new {@code SignalEntityOptions} with default settings.
+ */
+ public SignalEntityOptions() {
+ }
+
+ /**
+ * Sets the scheduled time for the signal. If set, the signal will be delivered at the specified time
+ * rather than immediately.
+ *
+ * @param scheduledTime the time at which the signal should be delivered
+ * @return this {@code SignalEntityOptions} object for chaining
+ */
+ public SignalEntityOptions setScheduledTime(@Nullable Instant scheduledTime) {
+ this.scheduledTime = scheduledTime;
+ return this;
+ }
+
+ /**
+ * Gets the scheduled time for the signal, or {@code null} if the signal should be delivered immediately.
+ *
+ * @return the scheduled time, or {@code null}
+ */
+ @Nullable
+ public Instant getScheduledTime() {
+ return this.scheduledTime;
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/TaskEntity.java b/client/src/main/java/com/microsoft/durabletask/TaskEntity.java
new file mode 100644
index 00000000..e78bc1ae
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/TaskEntity.java
@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+/**
+ * Common interface for durable entity implementations.
+ *
+ * Entities are stateful, single-threaded actors identified by a name+key pair
+ * ({@link EntityInstanceId}). The durable task runtime manages state persistence,
+ * message routing, and concurrency control.
+ *
+ * Implement this interface directly for full control over entity behavior, or extend
+ * {@link AbstractTaskEntity} for a higher-level programming model with automatic reflection-based
+ * operation dispatch.
+ *
+ * @see AbstractTaskEntity
+ */
+@FunctionalInterface
+public interface TaskEntity {
+ /**
+ * Executes the entity logic for a single operation.
+ *
+ * @param operation the operation to execute, including the operation name, input, state, and context
+ * @return the result of the operation, which will be serialized and returned to the caller
+ * (for two-way calls). May be {@code null} for void operations.
+ * @throws Exception if the operation fails
+ */
+ Object run(TaskEntityOperation operation) throws Exception;
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/TaskEntityContext.java b/client/src/main/java/com/microsoft/durabletask/TaskEntityContext.java
new file mode 100644
index 00000000..5661fe4f
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/TaskEntityContext.java
@@ -0,0 +1,94 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * Provides contextual information and side-effecting capabilities to a durable entity during operation execution.
+ *
+ * The context allows entities to:
+ *
+ * - Get their own entity instance ID
+ * - Signal other entities (fire-and-forget)
+ * - Start new orchestration instances
+ *
+ *
+ * Actions performed through the context (signals and orchestration starts) are collected and
+ * submitted as part of the entity batch result. They support transactional semantics:
+ * if an operation fails, any actions enqueued during that operation are rolled back.
+ */
+public abstract class TaskEntityContext {
+ /**
+ * Gets the instance ID of the currently executing entity.
+ *
+ * @return the entity instance ID
+ */
+ @Nonnull
+ public abstract EntityInstanceId getId();
+
+ /**
+ * Sends a fire-and-forget signal to another entity.
+ *
+ * @param entityId the target entity's instance ID
+ * @param operationName the name of the operation to invoke on the target entity
+ */
+ public void signalEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName) {
+ this.signalEntity(entityId, operationName, null, null);
+ }
+
+ /**
+ * Sends a fire-and-forget signal to another entity with input data.
+ *
+ * @param entityId the target entity's instance ID
+ * @param operationName the name of the operation to invoke on the target entity
+ * @param input the input data for the operation, or {@code null}
+ */
+ public void signalEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nullable Object input) {
+ this.signalEntity(entityId, operationName, input, null);
+ }
+
+ /**
+ * Sends a fire-and-forget signal to another entity with input data and options.
+ *
+ * @param entityId the target entity's instance ID
+ * @param operationName the name of the operation to invoke on the target entity
+ * @param input the input data for the operation, or {@code null}
+ * @param options signal options (e.g., scheduled time), or {@code null}
+ */
+ public abstract void signalEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nullable Object input,
+ @Nullable SignalEntityOptions options);
+
+ /**
+ * Starts a new orchestration instance.
+ *
+ * @param name the name of the orchestration to start
+ * @param input the input for the orchestration, or {@code null}
+ * @return the instance ID of the newly started orchestration
+ */
+ @Nonnull
+ public String startNewOrchestration(@Nonnull String name, @Nullable Object input) {
+ return this.startNewOrchestration(name, input, null);
+ }
+
+ /**
+ * Starts a new orchestration instance with options.
+ *
+ * @param name the name of the orchestration to start
+ * @param input the input for the orchestration, or {@code null}
+ * @param options the orchestration start options (e.g., instance ID), or {@code null}
+ * @return the instance ID of the newly started orchestration
+ */
+ @Nonnull
+ public abstract String startNewOrchestration(
+ @Nonnull String name,
+ @Nullable Object input,
+ @Nullable NewOrchestrationInstanceOptions options);
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/TaskEntityExecutor.java b/client/src/main/java/com/microsoft/durabletask/TaskEntityExecutor.java
new file mode 100644
index 00000000..e2352da2
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/TaskEntityExecutor.java
@@ -0,0 +1,365 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import com.google.protobuf.StringValue;
+import com.google.protobuf.Timestamp;
+import com.microsoft.durabletask.implementation.protobuf.OrchestratorService.*;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.time.Instant;
+import java.util.*;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * Executes entity batch requests by dispatching operations to registered entity factories.
+ *
+ * Each operation in the batch is executed independently with transactional semantics:
+ * successful operations commit their state and actions, while failed operations roll back
+ * to the previous committed state and discard any actions enqueued during the failed operation.
+ */
+final class TaskEntityExecutor {
+ private final HashMap entityFactories;
+ private final DataConverter dataConverter;
+ private final Logger logger;
+
+ TaskEntityExecutor(
+ HashMap entityFactories,
+ DataConverter dataConverter,
+ Logger logger) {
+ this.entityFactories = entityFactories;
+ this.dataConverter = dataConverter;
+ this.logger = logger;
+ }
+
+ /**
+ * Executes a batch of entity operations from an {@code EntityBatchRequest}.
+ *
+ * @param request the entity batch request from the sidecar
+ * @return the entity batch result to send back to the sidecar
+ */
+ @Nonnull
+ EntityBatchResult execute(@Nonnull EntityBatchRequest request) {
+ String instanceId = request.getInstanceId();
+ EntityInstanceId entityId = EntityInstanceId.fromString(instanceId);
+ String entityName = entityId.getName();
+
+ logger.log(Level.FINE, "Executing entity batch for '{0}' with {1} operation(s).",
+ new Object[]{instanceId, request.getOperationsCount()});
+
+ // Look up the entity factory
+ TaskEntityFactory factory = this.entityFactories.get(entityName);
+ if (factory == null) {
+ // Try case-insensitive lookup
+ for (Map.Entry entry : this.entityFactories.entrySet()) {
+ if (entry.getKey().equalsIgnoreCase(entityName)) {
+ factory = entry.getValue();
+ break;
+ }
+ }
+ }
+
+ if (factory == null) {
+ String errorMessage = String.format("No entity named '%s' is registered.", entityName);
+ logger.log(Level.WARNING, errorMessage);
+ TaskFailureDetails failureDetails = TaskFailureDetails.newBuilder()
+ .setErrorType(IllegalStateException.class.getName())
+ .setErrorMessage(errorMessage)
+ .build();
+ return EntityBatchResult.newBuilder()
+ .setFailureDetails(failureDetails)
+ .build();
+ }
+
+ // Initialize state from the request
+ String initialState = request.hasEntityState()
+ ? request.getEntityState().getValue()
+ : null;
+ TaskEntityState entityState = new TaskEntityState(this.dataConverter, initialState);
+
+ // Create the concrete context that collects actions
+ TaskEntityContextImpl context = new TaskEntityContextImpl(entityId, this.dataConverter);
+
+ // Process each operation
+ List results = new ArrayList<>();
+
+ // Create a single entity instance for the entire batch
+ TaskEntity entity;
+ try {
+ entity = factory.create();
+ if (entity == null) {
+ String errorMsg = String.format("The entity factory for '%s' returned a null entity.", entityName);
+ logger.log(Level.WARNING, errorMsg);
+ TaskFailureDetails failureDetails = TaskFailureDetails.newBuilder()
+ .setErrorType(IllegalStateException.class.getName())
+ .setErrorMessage(errorMsg)
+ .build();
+ return EntityBatchResult.newBuilder()
+ .setFailureDetails(failureDetails)
+ .build();
+ }
+ } catch (Exception e) {
+ String errorMsg = String.format("Failed to create entity instance for '%s': %s", entityName, e.getMessage());
+ logger.log(Level.WARNING, errorMsg, e);
+ TaskFailureDetails failureDetails = TaskFailureDetails.newBuilder()
+ .setErrorType(e.getClass().getName())
+ .setErrorMessage(e.getMessage() != null ? e.getMessage() : "")
+ .setStackTrace(StringValue.of(FailureDetails.getFullStackTrace(e)))
+ .build();
+ return EntityBatchResult.newBuilder()
+ .setFailureDetails(failureDetails)
+ .build();
+ }
+
+ for (OperationRequest opRequest : request.getOperationsList()) {
+ String operationName = opRequest.getOperation();
+ String requestId = opRequest.getRequestId();
+ String serializedInput = opRequest.hasInput() ? opRequest.getInput().getValue() : null;
+
+ logger.log(Level.FINE, "Executing operation '{0}' (requestId={1}) on entity '{2}'.",
+ new Object[]{operationName, requestId, instanceId});
+
+ // Snapshot state and actions before each operation (for rollback on failure)
+ entityState.commit();
+ context.commit();
+
+ Instant startTime = Instant.now();
+
+ try {
+ // Build the operation
+ TaskEntityOperation operation = new TaskEntityOperation(
+ operationName, serializedInput, context, entityState, this.dataConverter);
+
+ // Execute
+ Object result = entity.run(operation);
+
+ Instant endTime = Instant.now();
+
+ // Build success result
+ OperationResultSuccess.Builder successBuilder = OperationResultSuccess.newBuilder()
+ .setStartTimeUtc(toTimestamp(startTime))
+ .setEndTimeUtc(toTimestamp(endTime));
+
+ if (result != null) {
+ String serializedResult = this.dataConverter.serialize(result);
+ if (serializedResult != null) {
+ successBuilder.setResult(StringValue.of(serializedResult));
+ }
+ }
+
+ results.add(OperationResult.newBuilder()
+ .setSuccess(successBuilder.build())
+ .build());
+
+ // Commit state and actions on success
+ entityState.commit();
+ context.commit();
+
+ logger.log(Level.FINE, "Operation '{0}' on entity '{1}' completed successfully.",
+ new Object[]{operationName, instanceId});
+
+ } catch (Exception e) {
+ Instant endTime = Instant.now();
+
+ logger.log(Level.WARNING,
+ String.format("Operation '%s' on entity '%s' failed: %s",
+ operationName, instanceId, e.getMessage()),
+ e);
+
+ // Build failure result
+ TaskFailureDetails failureDetails = TaskFailureDetails.newBuilder()
+ .setErrorType(e.getClass().getName())
+ .setErrorMessage(e.getMessage() != null ? e.getMessage() : "")
+ .setStackTrace(StringValue.of(FailureDetails.getFullStackTrace(e)))
+ .build();
+
+ OperationResultFailure failure = OperationResultFailure.newBuilder()
+ .setFailureDetails(failureDetails)
+ .setStartTimeUtc(toTimestamp(startTime))
+ .setEndTimeUtc(toTimestamp(endTime))
+ .build();
+
+ results.add(OperationResult.newBuilder()
+ .setFailure(failure)
+ .build());
+
+ // Rollback state and actions on failure
+ entityState.rollback();
+ context.rollback();
+ }
+ }
+
+ // Build the final result
+ EntityBatchResult.Builder resultBuilder = EntityBatchResult.newBuilder()
+ .addAllResults(results)
+ .addAllActions(context.getCommittedActions(0));
+
+ // Set the final entity state
+ String finalState = entityState.getSerializedState();
+ if (finalState != null) {
+ resultBuilder.setEntityState(StringValue.of(finalState));
+ }
+
+ return resultBuilder.build();
+ }
+
+ private static Timestamp toTimestamp(Instant instant) {
+ return Timestamp.newBuilder()
+ .setSeconds(instant.getEpochSecond())
+ .setNanos(instant.getNano())
+ .build();
+ }
+
+ /**
+ * Concrete implementation of {@link TaskEntityContext} that collects {@link OperationAction} protos
+ * during entity operation execution.
+ */
+ private static class TaskEntityContextImpl extends TaskEntityContext {
+ private final EntityInstanceId entityId;
+ private final DataConverter dataConverter;
+ private final List pendingActions = new ArrayList<>();
+ private int committedActionCount = 0;
+
+ TaskEntityContextImpl(EntityInstanceId entityId, DataConverter dataConverter) {
+ this.entityId = entityId;
+ this.dataConverter = dataConverter;
+ }
+
+ @Nonnull
+ @Override
+ public EntityInstanceId getId() {
+ return this.entityId;
+ }
+
+ @Override
+ public void signalEntity(
+ @Nonnull EntityInstanceId targetEntityId,
+ @Nonnull String operationName,
+ @Nullable Object input,
+ @Nullable SignalEntityOptions options) {
+ Objects.requireNonNull(targetEntityId, "targetEntityId must not be null");
+ Objects.requireNonNull(operationName, "operationName must not be null");
+
+ SendSignalAction.Builder signalBuilder = SendSignalAction.newBuilder()
+ .setInstanceId(targetEntityId.toString())
+ .setName(operationName);
+
+ if (input != null) {
+ String serializedInput = this.dataConverter.serialize(input);
+ if (serializedInput != null) {
+ signalBuilder.setInput(StringValue.of(serializedInput));
+ }
+ }
+
+ if (options != null && options.getScheduledTime() != null) {
+ Instant scheduledTime = options.getScheduledTime();
+ signalBuilder.setScheduledTime(Timestamp.newBuilder()
+ .setSeconds(scheduledTime.getEpochSecond())
+ .setNanos(scheduledTime.getNano())
+ .build());
+ }
+
+ this.pendingActions.add(new PendingAction(PendingAction.Type.SEND_SIGNAL, signalBuilder.build(), null));
+ }
+
+ @Nonnull
+ @Override
+ public String startNewOrchestration(
+ @Nonnull String name,
+ @Nullable Object input,
+ @Nullable NewOrchestrationInstanceOptions options) {
+ Objects.requireNonNull(name, "orchestration name must not be null");
+
+ String instanceId = (options != null && options.getInstanceId() != null)
+ ? options.getInstanceId()
+ : UUID.randomUUID().toString();
+
+ StartNewOrchestrationAction.Builder orchBuilder = StartNewOrchestrationAction.newBuilder()
+ .setInstanceId(instanceId)
+ .setName(name);
+
+ if (input != null) {
+ String serializedInput = this.dataConverter.serialize(input);
+ if (serializedInput != null) {
+ orchBuilder.setInput(StringValue.of(serializedInput));
+ }
+ }
+
+ if (options != null) {
+ if (options.getVersion() != null) {
+ orchBuilder.setVersion(StringValue.of(options.getVersion()));
+ }
+ if (options.getStartTime() != null) {
+ Instant startTime = options.getStartTime();
+ orchBuilder.setScheduledTime(Timestamp.newBuilder()
+ .setSeconds(startTime.getEpochSecond())
+ .setNanos(startTime.getNano())
+ .build());
+ }
+ }
+
+ this.pendingActions.add(new PendingAction(
+ PendingAction.Type.START_NEW_ORCHESTRATION, null, orchBuilder.build()));
+
+ return instanceId;
+ }
+
+ /**
+ * Marks the current set of pending actions as committed (snapshot for rollback).
+ */
+ void commit() {
+ this.committedActionCount = this.pendingActions.size();
+ }
+
+ /**
+ * Rolls back any uncommitted actions (discards actions added since last commit).
+ */
+ void rollback() {
+ while (this.pendingActions.size() > this.committedActionCount) {
+ this.pendingActions.remove(this.pendingActions.size() - 1);
+ }
+ }
+
+ /**
+ * Returns all committed actions as proto {@link OperationAction} objects.
+ *
+ * @param startId the starting ID for action numbering
+ * @return the list of committed operation actions
+ */
+ List getCommittedActions(int startId) {
+ List actions = new ArrayList<>();
+ int id = startId;
+ for (int i = 0; i < this.committedActionCount; i++) {
+ PendingAction pending = this.pendingActions.get(i);
+ OperationAction.Builder actionBuilder = OperationAction.newBuilder()
+ .setId(id++);
+ if (pending.type == PendingAction.Type.SEND_SIGNAL) {
+ actionBuilder.setSendSignal(pending.sendSignal);
+ } else {
+ actionBuilder.setStartNewOrchestration(pending.startNewOrchestration);
+ }
+ actions.add(actionBuilder.build());
+ }
+ return actions;
+ }
+
+ /**
+ * Represents a pending action (signal or orchestration start) collected during entity execution.
+ */
+ private static class PendingAction {
+ enum Type { SEND_SIGNAL, START_NEW_ORCHESTRATION }
+
+ final Type type;
+ final SendSignalAction sendSignal;
+ final StartNewOrchestrationAction startNewOrchestration;
+
+ PendingAction(Type type, SendSignalAction sendSignal, StartNewOrchestrationAction startNewOrchestration) {
+ this.type = type;
+ this.sendSignal = sendSignal;
+ this.startNewOrchestration = startNewOrchestration;
+ }
+ }
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/TaskEntityFactory.java b/client/src/main/java/com/microsoft/durabletask/TaskEntityFactory.java
new file mode 100644
index 00000000..e5c18d0d
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/TaskEntityFactory.java
@@ -0,0 +1,19 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+/**
+ * Functional interface for creating {@link TaskEntity} instances.
+ *
+ * Entity factories are registered with the {@link DurableTaskGrpcWorkerBuilder} and are used to create
+ * new entity instances when entity work items are received from the sidecar.
+ */
+@FunctionalInterface
+public interface TaskEntityFactory {
+ /**
+ * Creates a new instance of {@link TaskEntity}.
+ *
+ * @return a new entity instance
+ */
+ TaskEntity create();
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/TaskEntityOperation.java b/client/src/main/java/com/microsoft/durabletask/TaskEntityOperation.java
new file mode 100644
index 00000000..7d6fd519
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/TaskEntityOperation.java
@@ -0,0 +1,104 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * Represents a single operation to be executed against a durable entity.
+ *
+ * An operation includes:
+ *
+ * - The operation name (e.g., "add", "get", "delete")
+ * - Optional input data
+ * - Access to the entity's state via {@link TaskEntityState}
+ * - Access to the entity's context via {@link TaskEntityContext}
+ *
+ */
+public class TaskEntityOperation {
+ private final String name;
+ private final String serializedInput;
+ private final TaskEntityContext context;
+ private final TaskEntityState state;
+ private final DataConverter dataConverter;
+
+ /**
+ * Creates a new {@code TaskEntityOperation}.
+ *
+ * @param name the operation name
+ * @param serializedInput the serialized input data, or {@code null} if no input
+ * @param context the entity context
+ * @param state the entity state
+ * @param dataConverter the data converter for deserializing input
+ */
+ TaskEntityOperation(
+ @Nonnull String name,
+ @Nullable String serializedInput,
+ @Nonnull TaskEntityContext context,
+ @Nonnull TaskEntityState state,
+ @Nonnull DataConverter dataConverter) {
+ if (name == null || name.isEmpty()) {
+ throw new IllegalArgumentException("Operation name must not be null or empty.");
+ }
+ this.name = name;
+ this.serializedInput = serializedInput;
+ this.context = context;
+ this.state = state;
+ this.dataConverter = dataConverter;
+ }
+
+ /**
+ * Gets the name of this operation.
+ *
+ * @return the operation name
+ */
+ @Nonnull
+ public String getName() {
+ return this.name;
+ }
+
+ /**
+ * Deserializes and returns the input data for this operation.
+ *
+ * @param inputType the class to deserialize the input into
+ * @param the expected type of the input
+ * @return the deserialized input, or {@code null} if no input was provided
+ */
+ @Nullable
+ public T getInput(@Nonnull Class inputType) {
+ if (this.serializedInput == null) {
+ return null;
+ }
+ return this.dataConverter.deserialize(this.serializedInput, inputType);
+ }
+
+ /**
+ * Returns whether this operation has input data.
+ *
+ * @return {@code true} if input data was provided, {@code false} otherwise
+ */
+ public boolean hasInput() {
+ return this.serializedInput != null;
+ }
+
+ /**
+ * Gets the context for the currently executing entity.
+ *
+ * @return the entity context
+ */
+ @Nonnull
+ public TaskEntityContext getContext() {
+ return this.context;
+ }
+
+ /**
+ * Gets the state accessor for the currently executing entity.
+ *
+ * @return the entity state
+ */
+ @Nonnull
+ public TaskEntityState getState() {
+ return this.state;
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/TaskEntityState.java b/client/src/main/java/com/microsoft/durabletask/TaskEntityState.java
new file mode 100644
index 00000000..f1bba59b
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/TaskEntityState.java
@@ -0,0 +1,116 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+
+/**
+ * Provides access to the state of a durable entity during operation execution.
+ *
+ * Entity state is automatically persisted by the durable task runtime after each successfully
+ * committed operation. The state supports transactional semantics: if an operation fails,
+ * the state is rolled back to the last committed snapshot.
+ */
+public class TaskEntityState {
+ private final DataConverter dataConverter;
+ private String serializedState;
+ private boolean stateExists;
+
+ // Transactional rollback support
+ private String committedSerializedState;
+ private boolean committedStateExists;
+
+ /**
+ * Creates a new {@code TaskEntityState} instance.
+ *
+ * @param dataConverter the data converter used for serialization/deserialization
+ * @param serializedState the initial serialized state, or {@code null} if no state exists
+ */
+ TaskEntityState(DataConverter dataConverter, @Nullable String serializedState) {
+ this.dataConverter = dataConverter;
+ this.serializedState = serializedState;
+ this.stateExists = serializedState != null;
+ // Initialize committed state to match initial state
+ this.committedSerializedState = serializedState;
+ this.committedStateExists = this.stateExists;
+ }
+
+ /**
+ * Gets the current entity state, deserialized to the specified type.
+ *
+ * @param stateType the class to deserialize the state into
+ * @param the type of the state
+ * @return the deserialized state, or {@code null} if no state exists
+ */
+ @Nullable
+ public T getState(Class stateType) {
+ if (!this.stateExists || this.serializedState == null) {
+ return null;
+ }
+ return this.dataConverter.deserialize(this.serializedState, stateType);
+ }
+
+ /**
+ * Sets the entity state. The state will be serialized using the configured {@link DataConverter}.
+ *
+ * @param state the state value to set
+ */
+ public void setState(@Nullable Object state) {
+ if (state == null) {
+ deleteState();
+ } else {
+ this.serializedState = this.dataConverter.serialize(state);
+ if (this.serializedState == null) {
+ throw new IllegalStateException(
+ "DataConverter.serialize() returned null for a non-null state object of type "
+ + state.getClass().getName() + ". This indicates a broken DataConverter implementation.");
+ }
+ this.stateExists = true;
+ }
+ }
+
+ /**
+ * Returns whether the entity currently has state.
+ *
+ * @return {@code true} if the entity has state, {@code false} otherwise
+ */
+ public boolean hasState() {
+ return this.stateExists;
+ }
+
+ /**
+ * Deletes the entity state. After calling this method, {@link #hasState()} will return {@code false}.
+ */
+ public void deleteState() {
+ this.serializedState = null;
+ this.stateExists = false;
+ }
+
+ /**
+ * Gets the serialized (raw) state string.
+ *
+ * @return the serialized state, or {@code null} if no state exists
+ */
+ @Nullable
+ String getSerializedState() {
+ return this.serializedState;
+ }
+
+ /**
+ * Takes a snapshot of the current state as a rollback point.
+ * Called before each operation in a batch to support transactional semantics.
+ */
+ void commit() {
+ this.committedSerializedState = this.serializedState;
+ this.committedStateExists = this.stateExists;
+ }
+
+ /**
+ * Reverts the state to the last committed snapshot.
+ * Called when an operation fails to maintain transactional semantics.
+ */
+ void rollback() {
+ this.serializedState = this.committedSerializedState;
+ this.stateExists = this.committedStateExists;
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationContext.java b/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationContext.java
index 6886d874..e94acde4 100644
--- a/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationContext.java
+++ b/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationContext.java
@@ -11,6 +11,7 @@
import java.util.List;
import java.util.Map;
import java.util.UUID;
+import javax.annotation.Nonnull;
/**
* Used by orchestrators to perform actions such as scheduling tasks, durable timers, waiting for external events,
@@ -560,6 +561,221 @@ default Task waitForExternalEvent(String name, Class dataType) {
}
}
+ /**
+ * Creates a typed entity proxy that maps interface method calls to entity operations.
+ *
+ * This is a convenience method equivalent to calling
+ * {@code EntityProxy.create(this, entityId, proxyInterface)}.
+ *
+ * @param entityId the target entity's instance ID
+ * @param proxyInterface the interface whose methods map to entity operations;
+ * {@code void} methods become signals, {@code Task} methods become calls
+ * @param the proxy interface type
+ * @return a proxy instance that implements {@code proxyInterface}
+ * @throws IllegalArgumentException if {@code proxyInterface} is not an interface
+ * @see EntityProxy#create(TaskOrchestrationContext, EntityInstanceId, Class)
+ */
+ default T createEntityProxy(@Nonnull EntityInstanceId entityId, @Nonnull Class proxyInterface) {
+ return EntityProxy.create(this, entityId, proxyInterface);
+ }
+
+ /**
+ * Gets the durable entity feature for this orchestration context.
+ *
+ * This mirrors the .NET SDK's {@code TaskOrchestrationContext.Entities} surface,
+ * adapted to Java as a method-based accessor.
+ *
+ * @return the entity feature for this orchestration context
+ */
+ default TaskOrchestrationEntityFeature getEntities() {
+ return new ContextBackedTaskOrchestrationEntityFeature(this);
+ }
+
+ /**
+ * Gets the durable entity feature for this orchestration context.
+ *
+ * This is an alias of {@link #getEntities()}.
+ *
+ * @return the entity feature for this orchestration context
+ */
+ default TaskOrchestrationEntityFeature entities() {
+ return this.getEntities();
+ }
+
+ // region Entity integration methods
+
+ /**
+ * Sends a fire-and-forget signal to a durable entity.
+ *
+ * Signals are one-way messages that do not return a result. The target entity will execute the specified
+ * operation asynchronously. If the entity does not exist, it will be created automatically.
+ *
+ * @param entityId the unique identifier of the target entity
+ * @param operationName the name of the operation to invoke on the entity
+ */
+ default void signalEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName) {
+ this.signalEntity(entityId, operationName, null, null);
+ }
+
+ /**
+ * Sends a fire-and-forget signal to a durable entity with the specified input.
+ *
+ * Signals are one-way messages that do not return a result. The target entity will execute the specified
+ * operation asynchronously. If the entity does not exist, it will be created automatically.
+ *
+ * @param entityId the unique identifier of the target entity
+ * @param operationName the name of the operation to invoke on the entity
+ * @param input the serializable input to pass to the entity operation, or {@code null}
+ */
+ default void signalEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName, @Nullable Object input) {
+ this.signalEntity(entityId, operationName, input, null);
+ }
+
+ /**
+ * Sends a fire-and-forget signal to a durable entity with the specified input and options.
+ *
+ * Signals are one-way messages that do not return a result. The target entity will execute the specified
+ * operation asynchronously. If the entity does not exist, it will be created automatically.
+ *
+ * @param entityId the unique identifier of the target entity
+ * @param operationName the name of the operation to invoke on the entity
+ * @param input the serializable input to pass to the entity operation, or {@code null}
+ * @param options signal options such as scheduled delivery time, or {@code null}
+ */
+ void signalEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName, @Nullable Object input, @Nullable SignalEntityOptions options);
+
+ /**
+ * Calls an operation on a durable entity and waits for the result.
+ *
+ * Unlike {@link #signalEntity}, this method is a two-way call that returns a result. The calling orchestration
+ * will block until the entity operation completes and returns a response.
+ *
+ * @param entityId the unique identifier of the target entity
+ * @param operationName the name of the operation to invoke on the entity
+ * @param input the serializable input to pass to the entity operation, or {@code null}
+ * @param returnType the expected class type of the entity operation output
+ * @param the expected type of the entity operation output
+ * @return a {@link Task} that completes when the entity operation completes
+ */
+ Task callEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName, @Nullable Object input, @Nonnull Class returnType);
+
+ /**
+ * Calls an operation on a durable entity and waits for the result, with options.
+ *
+ * Unlike {@link #signalEntity}, this method is a two-way call that returns a result. The calling orchestration
+ * will block until the entity operation completes and returns a response.
+ *
+ * @param entityId the unique identifier of the target entity
+ * @param operationName the name of the operation to invoke on the entity
+ * @param input the serializable input to pass to the entity operation, or {@code null}
+ * @param returnType the expected class type of the entity operation output
+ * @param options call options such as timeout, or {@code null}
+ * @param the expected type of the entity operation output
+ * @return a {@link Task} that completes when the entity operation completes
+ */
+ Task callEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName, @Nullable Object input, @Nonnull Class returnType, @Nullable CallEntityOptions options);
+
+ /**
+ * Calls an operation on a durable entity and waits for it to complete (no return value).
+ *
+ * @param entityId the unique identifier of the target entity
+ * @param operationName the name of the operation to invoke on the entity
+ * @return a {@link Task} that completes when the entity operation completes
+ */
+ default Task callEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName) {
+ return this.callEntity(entityId, operationName, null, Void.class);
+ }
+
+ /**
+ * Calls an operation on a durable entity and waits for the result (no input).
+ *
+ * @param entityId the unique identifier of the target entity
+ * @param operationName the name of the operation to invoke on the entity
+ * @param returnType the expected class type of the entity operation output
+ * @param the expected type of the entity operation output
+ * @return a {@link Task} that completes when the entity operation completes
+ */
+ default Task callEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName, @Nonnull Class returnType) {
+ return this.callEntity(entityId, operationName, null, returnType);
+ }
+
+ /**
+ * Calls an operation on a durable entity with options and waits for the result (no input).
+ *
+ * @param entityId the unique identifier of the target entity
+ * @param operationName the name of the operation to invoke on the entity
+ * @param returnType the expected class type of the entity operation output
+ * @param options call options such as timeout, or {@code null}
+ * @param the expected type of the entity operation output
+ * @return a {@link Task} that completes when the entity operation completes
+ */
+ default Task callEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName, @Nonnull Class returnType, @Nullable CallEntityOptions options) {
+ return this.callEntity(entityId, operationName, null, returnType, options);
+ }
+
+ /**
+ * Calls an operation on a durable entity with options and waits for it to complete (no input, no return value).
+ *
+ * @param entityId the unique identifier of the target entity
+ * @param operationName the name of the operation to invoke on the entity
+ * @param options call options such as timeout, or {@code null}
+ * @return a {@link Task} that completes when the entity operation completes
+ */
+ default Task callEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName, @Nullable CallEntityOptions options) {
+ return this.callEntity(entityId, operationName, null, Void.class, options);
+ }
+
+ /**
+ * Acquires one or more entity locks for the duration of a critical section.
+ *
+ * Entity locks are used to coordinate access and prevent conflicts when multiple orchestrations need
+ * to access the same entities. The returned {@link AutoCloseable} must be closed to release the locks.
+ *
+ * Entity IDs are sorted deterministically before acquiring locks to prevent deadlocks.
+ * Nesting of lock calls is not supported and will throw an {@link IllegalStateException}.
+ *
+ * Example usage:
+ *
{@code
+ * try (AutoCloseable lock = ctx.lockEntities(entityIds).await()) {
+ * // Perform operations on the locked entities
+ * ctx.callEntity(entityId, "transfer", amount).await();
+ * }
+ * }
+ *
+ * @param entityIds the list of entity instance IDs to lock; must not be empty
+ * @return a {@link Task} that completes with an {@link AutoCloseable} when all locks are acquired
+ */
+ Task lockEntities(@Nonnull List entityIds);
+
+ /**
+ * Acquires one or more entity locks for the duration of a critical section (varargs overload).
+ *
+ * @param entityIds the entity instance IDs to lock; must not be empty
+ * @return a {@link Task} that completes with an {@link AutoCloseable} when all locks are acquired
+ */
+ default Task lockEntities(@Nonnull EntityInstanceId... entityIds) {
+ return this.lockEntities(Arrays.asList(entityIds));
+ }
+
+ /**
+ * Gets a value indicating whether this orchestration is currently executing inside a critical section
+ * that was created by {@link #lockEntities}.
+ *
+ * @return {@code true} if the orchestration is inside a critical section, otherwise {@code false}
+ */
+ boolean isInCriticalSection();
+
+ /**
+ * Gets the list of entity instance IDs that are currently locked by this orchestration.
+ *
+ * Returns an empty list if the orchestration is not inside a critical section.
+ *
+ * @return an unmodifiable list of locked entity instance IDs
+ */
+ List getLockedEntities();
+
+ // endregion
+
/**
* Assigns a custom status value to the current orchestration.
*
diff --git a/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationEntityFeature.java b/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationEntityFeature.java
new file mode 100644
index 00000000..0c011533
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationEntityFeature.java
@@ -0,0 +1,253 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Feature for interacting with durable entities from an orchestration.
+ *
+ * This mirrors the .NET SDK's {@code TaskOrchestrationContext.Entities} shape, adapted to Java.
+ */
+public abstract class TaskOrchestrationEntityFeature {
+
+ /**
+ * Calls an operation on an entity and waits for it to complete.
+ *
+ * @param entityId the target entity
+ * @param operationName the name of the operation
+ * @param input the operation input, or {@code null}
+ * @param returnType the expected return type
+ * @param the result type
+ * @return a task that completes with the operation result
+ */
+ public abstract Task callEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nullable Object input,
+ @Nonnull Class returnType);
+
+ /**
+ * Calls an operation on an entity and waits for it to complete, with options.
+ *
+ * @param entityId the target entity
+ * @param operationName the name of the operation
+ * @param input the operation input, or {@code null}
+ * @param returnType the expected return type
+ * @param options the call options, or {@code null}
+ * @param the result type
+ * @return a task that completes with the operation result
+ */
+ public abstract Task callEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nullable Object input,
+ @Nonnull Class returnType,
+ @Nullable CallEntityOptions options);
+
+ /**
+ * Calls an operation on an entity and waits for it to complete.
+ *
+ * @param entityId the target entity
+ * @param operationName the name of the operation
+ * @param the result type
+ * @return a task that completes with the operation result
+ */
+ public Task callEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nonnull Class returnType) {
+ return this.callEntity(entityId, operationName, null, returnType, null);
+ }
+
+ /**
+ * Calls an operation on an entity and waits for it to complete (no input, no return value).
+ *
+ * @param entityId the target entity
+ * @param operationName the name of the operation
+ * @return a task that completes when the operation completes
+ */
+ public Task callEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName) {
+ return this.callEntity(entityId, operationName, null, Void.class, null);
+ }
+
+ /**
+ * Calls an operation on an entity with options and waits for the result (no input).
+ *
+ * @param entityId the target entity
+ * @param operationName the name of the operation
+ * @param returnType the expected return type
+ * @param options the call options, or {@code null}
+ * @param the result type
+ * @return a task that completes with the operation result
+ */
+ public Task callEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nonnull Class returnType,
+ @Nullable CallEntityOptions options) {
+ return this.callEntity(entityId, operationName, null, returnType, options);
+ }
+
+ /**
+ * Calls an operation on an entity with options and waits for it to complete (no input, no return value).
+ *
+ * @param entityId the target entity
+ * @param operationName the name of the operation
+ * @param options the call options, or {@code null}
+ * @return a task that completes when the operation completes
+ */
+ public Task callEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nullable CallEntityOptions options) {
+ return this.callEntity(entityId, operationName, null, Void.class, options);
+ }
+
+ /**
+ * Signals an entity operation without waiting for completion.
+ *
+ * @param entityId the target entity
+ * @param operationName the operation name
+ * @param input the operation input, or {@code null}
+ * @param options signal options, or {@code null}
+ */
+ public abstract void signalEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nullable Object input,
+ @Nullable SignalEntityOptions options);
+
+ /**
+ * Signals an entity operation without waiting for completion.
+ *
+ * @param entityId the target entity
+ * @param operationName the operation name
+ */
+ public void signalEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName) {
+ this.signalEntity(entityId, operationName, null, null);
+ }
+
+ /**
+ * Signals an entity operation without waiting for completion.
+ *
+ * @param entityId the target entity
+ * @param operationName the operation name
+ * @param input the operation input, or {@code null}
+ */
+ public void signalEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nullable Object input) {
+ this.signalEntity(entityId, operationName, input, null);
+ }
+
+ /**
+ * Acquires one or more entity locks.
+ *
+ * @param entityIds the entity IDs to lock
+ * @return a task that completes with an {@link AutoCloseable} used to release locks
+ */
+ public abstract Task lockEntities(@Nonnull List entityIds);
+
+ /**
+ * Acquires one or more entity locks.
+ *
+ * @param entityIds the entity IDs to lock
+ * @return a task that completes with an {@link AutoCloseable} used to release locks
+ */
+ public Task lockEntities(@Nonnull EntityInstanceId... entityIds) {
+ return this.lockEntities(Arrays.asList(entityIds));
+ }
+
+ /**
+ * Gets whether this orchestration is currently inside a critical section.
+ *
+ * @return {@code true} if inside a critical section, otherwise {@code false}
+ */
+ public abstract boolean isInCriticalSection();
+
+ /**
+ * Gets the currently locked entity IDs.
+ *
+ * @return the list of currently locked entities, or an empty list
+ */
+ public abstract List getLockedEntities();
+
+ /**
+ * Creates a typed entity proxy that maps interface method calls to entity operations.
+ *
+ * This is the feature-based equivalent of
+ * {@link TaskOrchestrationContext#createEntityProxy(EntityInstanceId, Class)}.
+ *
+ * @param entityId the target entity's instance ID
+ * @param proxyInterface the interface whose methods map to entity operations;
+ * {@code void} methods become signals, {@code Task} methods become calls
+ * @param the proxy interface type
+ * @return a proxy instance that implements {@code proxyInterface}
+ * @throws IllegalArgumentException if {@code proxyInterface} is not an interface
+ * @see EntityProxy#create(TaskOrchestrationContext, EntityInstanceId, Class)
+ */
+ public abstract T createProxy(@Nonnull EntityInstanceId entityId, @Nonnull Class proxyInterface);
+}
+
+final class ContextBackedTaskOrchestrationEntityFeature extends TaskOrchestrationEntityFeature {
+ private final TaskOrchestrationContext context;
+
+ ContextBackedTaskOrchestrationEntityFeature(TaskOrchestrationContext context) {
+ this.context = context;
+ }
+
+ @Override
+ public Task callEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nullable Object input,
+ @Nonnull Class returnType) {
+ return this.context.callEntity(entityId, operationName, input, returnType);
+ }
+
+ @Override
+ public Task callEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nullable Object input,
+ @Nonnull Class returnType,
+ @Nullable CallEntityOptions options) {
+ return this.context.callEntity(entityId, operationName, input, returnType, options);
+ }
+
+ @Override
+ public void signalEntity(
+ @Nonnull EntityInstanceId entityId,
+ @Nonnull String operationName,
+ @Nullable Object input,
+ @Nullable SignalEntityOptions options) {
+ this.context.signalEntity(entityId, operationName, input, options);
+ }
+
+ @Override
+ public Task lockEntities(@Nonnull List entityIds) {
+ return this.context.lockEntities(entityIds);
+ }
+
+ @Override
+ public boolean isInCriticalSection() {
+ return this.context.isInCriticalSection();
+ }
+
+ @Override
+ public List getLockedEntities() {
+ return this.context.getLockedEntities();
+ }
+
+ @Override
+ public T createProxy(@Nonnull EntityInstanceId entityId, @Nonnull Class proxyInterface) {
+ return EntityProxy.create(this.context, entityId, proxyInterface);
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationExecutor.java b/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationExecutor.java
index 00e48a8f..db744531 100644
--- a/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationExecutor.java
+++ b/client/src/main/java/com/microsoft/durabletask/TaskOrchestrationExecutor.java
@@ -2,6 +2,10 @@
// Licensed under the MIT License.
package com.microsoft.durabletask;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
import com.google.protobuf.StringValue;
import com.google.protobuf.Timestamp;
import com.microsoft.durabletask.interruption.ContinueAsNewInterruption;
@@ -26,11 +30,14 @@
final class TaskOrchestrationExecutor {
private static final String EMPTY_STRING = "";
+ // ObjectMapper for parsing DTFx entity ResponseMessage JSON wrappers in the trigger binding code path
+ private static final ObjectMapper JSON_MAPPER = new ObjectMapper();
private final HashMap orchestrationFactories;
private final DataConverter dataConverter;
private final Logger logger;
private final Duration maximumTimerInterval;
private final DurableTaskGrpcWorkerVersioningOptions versioningOptions;
+ private final boolean useNativeEntityActions;
public TaskOrchestrationExecutor(
HashMap orchestrationFactories,
@@ -38,11 +45,22 @@ public TaskOrchestrationExecutor(
Duration maximumTimerInterval,
Logger logger,
DurableTaskGrpcWorkerVersioningOptions versioningOptions) {
+ this(orchestrationFactories, dataConverter, maximumTimerInterval, logger, versioningOptions, false);
+ }
+
+ public TaskOrchestrationExecutor(
+ HashMap orchestrationFactories,
+ DataConverter dataConverter,
+ Duration maximumTimerInterval,
+ Logger logger,
+ DurableTaskGrpcWorkerVersioningOptions versioningOptions,
+ boolean useNativeEntityActions) {
this.orchestrationFactories = orchestrationFactories;
this.dataConverter = dataConverter;
this.maximumTimerInterval = maximumTimerInterval;
this.logger = logger;
this.versioningOptions = versioningOptions;
+ this.useNativeEntityActions = useNativeEntityActions;
}
public TaskOrchestratorResult execute(
@@ -63,7 +81,11 @@ public TaskOrchestratorResult execute(
while (context.processNextEvent()) { /* no method body */ }
completed = true;
} catch (OrchestratorBlockedException orchestratorBlockedException) {
- logger.fine("The orchestrator has yielded and will await for new events.");
+ logger.fine(String.format(
+ "%s: Orchestrator yielded. Waiting for events. Outstanding event keys: %s, Pending actions: %d",
+ context.instanceId,
+ context.outstandingEvents.keySet(),
+ context.pendingActions.size()));
} catch (ContinueAsNewInterruption continueAsNewInterruption) {
logger.fine("The orchestrator has continued as new.");
context.complete(null);
@@ -112,6 +134,14 @@ private class ContextImplTask implements TaskOrchestrationContext {
private Object customStatus;
private TraceContext parentTraceContext;
+ // Entity integration state (Phase 4)
+ private String executionId;
+ private boolean isInCriticalSection;
+ private TaskOrchestrationEntityFeature cachedEntityFeature;
+
+ private Set lockedEntityIds;
+ private final Map> pendingLockSets = new HashMap<>();
+
// Stores scheduling metadata (timestamp, name, parentTraceContext) for retroactive client spans
private final HashMap scheduledTaskInfoMap = new HashMap<>();
// Stores timer creation timestamps for timer spans with duration
@@ -132,6 +162,14 @@ public String getName() {
return this.orchestratorName;
}
+ @Override
+ public TaskOrchestrationEntityFeature getEntities() {
+ if (this.cachedEntityFeature == null) {
+ this.cachedEntityFeature = new ContextBackedTaskOrchestrationEntityFeature(this);
+ }
+ return this.cachedEntityFeature;
+ }
+
private void setName(String name) {
// TODO: Throw if name is not null
this.orchestratorName = name;
@@ -381,6 +419,348 @@ public UUID newUUID() {
return UUIDGenerator.generate(version, hashV5, UUID.fromString(dnsNameSpace), name);
}
+ // region Entity integration methods (Phase 4)
+
+ @Override
+ public void signalEntity(EntityInstanceId entityId, String operationName, Object input, SignalEntityOptions options) {
+ Helpers.throwIfOrchestratorComplete(this.isComplete);
+ Helpers.throwIfArgumentNull(entityId, "entityId");
+ Helpers.throwIfArgumentNull(operationName, "operationName");
+
+ int id = this.sequenceNumber++;
+ String requestId = this.newUUID().toString();
+ String serializedInput = this.dataConverter.serialize(input);
+
+ if (TaskOrchestrationExecutor.this.useNativeEntityActions) {
+ // Proto-native SendEntityMessageAction for DTS/standalone sidecar backends
+ EntityOperationSignaledEvent.Builder signalBuilder = EntityOperationSignaledEvent.newBuilder()
+ .setRequestId(requestId)
+ .setOperation(operationName)
+ .setTargetInstanceId(StringValue.of(entityId.toString()));
+ if (serializedInput != null) {
+ signalBuilder.setInput(StringValue.of(serializedInput));
+ }
+ if (options != null && options.getScheduledTime() != null) {
+ signalBuilder.setScheduledTime(
+ DataConverter.getTimestampFromInstant(options.getScheduledTime()));
+ }
+ this.pendingActions.put(id, OrchestratorAction.newBuilder()
+ .setId(id)
+ .setSendEntityMessage(SendEntityMessageAction.newBuilder()
+ .setEntityOperationSignaled(signalBuilder))
+ .build());
+ } else {
+ // Legacy DTFx RequestMessage JSON for Azure Functions extension compatibility.
+ // Uses SendEventAction (external event) instead of SendEntityMessageAction.
+ ObjectNode requestMessage = JSON_MAPPER.createObjectNode();
+ requestMessage.put("op", operationName);
+ requestMessage.put("signal", true);
+ if (serializedInput != null) {
+ requestMessage.put("input", serializedInput);
+ }
+ requestMessage.put("id", requestId);
+ String eventName = "op";
+ if (options != null && options.getScheduledTime() != null) {
+ String scheduledTimeStr = options.getScheduledTime().toString();
+ requestMessage.put("due", scheduledTimeStr);
+ eventName = "op@" + scheduledTimeStr;
+ }
+ this.pendingActions.put(id, OrchestratorAction.newBuilder()
+ .setId(id)
+ .setSendEvent(SendEventAction.newBuilder()
+ .setInstance(OrchestrationInstance.newBuilder()
+ .setInstanceId(entityId.toString()))
+ .setName(eventName)
+ .setData(StringValue.of(requestMessage.toString())))
+ .build());
+ }
+
+ if (!this.isReplaying) {
+ this.logger.fine(() -> String.format(
+ "%s: signaling entity '%s' operation '%s' (#%d)",
+ this.instanceId,
+ entityId,
+ operationName,
+ id));
+ }
+ }
+
+ @Override
+ public Task callEntity(EntityInstanceId entityId, String operationName, Object input, Class returnType) {
+ return this.callEntity(entityId, operationName, input, returnType, null);
+ }
+
+ @Override
+ public Task callEntity(EntityInstanceId entityId, String operationName, Object input, Class returnType, CallEntityOptions options) {
+ Helpers.throwIfOrchestratorComplete(this.isComplete);
+ Helpers.throwIfArgumentNull(entityId, "entityId");
+ Helpers.throwIfArgumentNull(operationName, "operationName");
+ Helpers.throwIfArgumentNull(returnType, "returnType");
+
+ // Validate critical section: calls must target locked entities to prevent deadlocks
+ if (this.isInCriticalSection
+ && !this.lockedEntityIds.contains(entityId.toString())) {
+ throw new IllegalStateException(String.format(
+ "Cannot call entity '%s' from within a critical section because it is not locked. " +
+ "Only locked entities can be called inside a critical section to prevent deadlocks.",
+ entityId));
+ }
+
+ int id = this.sequenceNumber++;
+ String requestId = this.newUUID().toString();
+ String serializedInput = this.dataConverter.serialize(input);
+
+ if (TaskOrchestrationExecutor.this.useNativeEntityActions) {
+ // Proto-native SendEntityMessageAction for DTS/standalone sidecar backends
+ EntityOperationCalledEvent.Builder callBuilder = EntityOperationCalledEvent.newBuilder()
+ .setRequestId(requestId)
+ .setOperation(operationName)
+ .setTargetInstanceId(StringValue.of(entityId.toString()));
+ if (serializedInput != null) {
+ callBuilder.setInput(StringValue.of(serializedInput));
+ }
+ callBuilder.setParentInstanceId(StringValue.of(this.instanceId));
+ if (this.executionId != null) {
+ callBuilder.setParentExecutionId(StringValue.of(this.executionId));
+ }
+ this.pendingActions.put(id, OrchestratorAction.newBuilder()
+ .setId(id)
+ .setSendEntityMessage(SendEntityMessageAction.newBuilder()
+ .setEntityOperationCalled(callBuilder))
+ .build());
+ } else {
+ // Legacy DTFx RequestMessage JSON for Azure Functions extension compatibility.
+ // Uses SendEventAction (external event) instead of SendEntityMessageAction.
+ ObjectNode requestMessage = JSON_MAPPER.createObjectNode();
+ requestMessage.put("op", operationName);
+ requestMessage.put("signal", false);
+ if (serializedInput != null) {
+ requestMessage.put("input", serializedInput);
+ }
+ requestMessage.put("id", requestId);
+ requestMessage.put("parent", this.instanceId);
+ if (this.executionId != null) {
+ requestMessage.put("parentExecution", this.executionId);
+ }
+ this.pendingActions.put(id, OrchestratorAction.newBuilder()
+ .setId(id)
+ .setSendEvent(SendEventAction.newBuilder()
+ .setInstance(OrchestrationInstance.newBuilder()
+ .setInstanceId(entityId.toString()))
+ .setName("op")
+ .setData(StringValue.of(requestMessage.toString())))
+ .build());
+ }
+
+ if (!this.isReplaying) {
+ this.logger.fine(() -> String.format(
+ "%s: calling entity '%s' operation '%s' (#%d) requestId=%s",
+ this.instanceId,
+ entityId,
+ operationName,
+ id,
+ requestId));
+ }
+
+ CompletableTask task = new CompletableTask<>();
+ TaskRecord record = new TaskRecord<>(task, operationName, returnType, entityId);
+ Queue> eventQueue = this.outstandingEvents.computeIfAbsent(requestId, k -> new LinkedList<>());
+ eventQueue.add(record);
+
+ // If a timeout is specified, schedule a durable timer to cancel the call if the entity
+ // doesn't respond in time (same pattern as waitForExternalEvent with timeout).
+ Duration timeout = options != null ? options.getTimeout() : null;
+ if (timeout != null && !Helpers.isInfiniteTimeout(timeout)) {
+ if (timeout.isZero()) {
+ // Immediately cancel
+ eventQueue.removeIf(t -> t.task == task);
+ if (eventQueue.isEmpty()) {
+ this.outstandingEvents.remove(requestId);
+ }
+ String message = String.format(
+ "Timeout of %s expired while calling entity '%s' operation '%s' (requestId=%s).",
+ timeout, entityId, operationName, requestId);
+ task.completeExceptionally(new TaskCanceledException(message, operationName, id));
+ } else {
+ this.createTimer(timeout).future.thenRun(() -> {
+ if (!task.isDone()) {
+ eventQueue.removeIf(t -> t.task == task);
+ if (eventQueue.isEmpty()) {
+ this.outstandingEvents.remove(requestId);
+ }
+ String message = String.format(
+ "Timeout of %s expired while calling entity '%s' operation '%s' (requestId=%s).",
+ timeout, entityId, operationName, requestId);
+ task.completeExceptionally(new TaskCanceledException(message, operationName, id));
+ }
+ });
+ }
+ }
+
+ return task;
+ }
+
+ @Override
+ public Task lockEntities(List entityIds) {
+ Helpers.throwIfOrchestratorComplete(this.isComplete);
+ Helpers.throwIfArgumentNull(entityIds, "entityIds");
+ if (entityIds.isEmpty()) {
+ throw new IllegalArgumentException("entityIds must not be empty");
+ }
+ for (EntityInstanceId eid : entityIds) {
+ if (eid == null) {
+ throw new IllegalArgumentException("entityIds must not contain null elements");
+ }
+ }
+ if (this.isInCriticalSection) {
+ throw new IllegalStateException(
+ "Cannot nest lock calls. The orchestration is already inside a critical section.");
+ }
+
+ // Sort entity IDs deterministically to prevent deadlocks
+ List sortedIds = new ArrayList<>(entityIds);
+ Collections.sort(sortedIds);
+
+ String criticalSectionId = this.newUUID().toString();
+
+ // Build lock set as string list
+ List lockSet = new ArrayList<>(sortedIds.size());
+ for (EntityInstanceId eid : sortedIds) {
+ lockSet.add(eid.toString());
+ }
+
+ // Send a lock request to the FIRST entity in the sorted lock set.
+ // DTFx entity infrastructure handles chaining the lock acquisition
+ // through subsequent entities in the lock set.
+ {
+ int id = this.sequenceNumber++;
+ if (TaskOrchestrationExecutor.this.useNativeEntityActions) {
+ // Proto-native lock request for DTS/standalone sidecar backends
+ this.pendingActions.put(id, OrchestratorAction.newBuilder()
+ .setId(id)
+ .setSendEntityMessage(SendEntityMessageAction.newBuilder()
+ .setEntityLockRequested(EntityLockRequestedEvent.newBuilder()
+ .setCriticalSectionId(criticalSectionId)
+ .addAllLockSet(lockSet)
+ .setPosition(0)
+ .setParentInstanceId(StringValue.of(this.instanceId))))
+ .build());
+ } else {
+ // Legacy DTFx JSON for Azure Functions extension compatibility
+ ObjectNode lockRequestMessage = JSON_MAPPER.createObjectNode();
+ lockRequestMessage.putNull("op");
+ lockRequestMessage.put("id", criticalSectionId);
+ ArrayNode lockSetArray = lockRequestMessage.putArray("lockset");
+ for (EntityInstanceId eid : sortedIds) {
+ ObjectNode entityIdNode = JSON_MAPPER.createObjectNode();
+ entityIdNode.put("name", eid.getName());
+ entityIdNode.put("key", eid.getKey());
+ lockSetArray.add(entityIdNode);
+ }
+ lockRequestMessage.put("pos", 0);
+ lockRequestMessage.put("parent", this.instanceId);
+
+ String targetEntityId = lockSet.get(0);
+ this.pendingActions.put(id, OrchestratorAction.newBuilder()
+ .setId(id)
+ .setSendEvent(SendEventAction.newBuilder()
+ .setInstance(OrchestrationInstance.newBuilder()
+ .setInstanceId(targetEntityId))
+ .setName("op")
+ .setData(StringValue.of(lockRequestMessage.toString())))
+ .build());
+ }
+ }
+
+ // Store the lock set so handleEntityLockGranted can populate lockedEntityIds
+ Set lockSetForStorage = new HashSet<>(lockSet);
+ this.pendingLockSets.put(criticalSectionId, lockSetForStorage);
+
+ if (!this.isReplaying) {
+ this.logger.fine(() -> String.format(
+ "%s: requesting locks on %d entities, criticalSectionId=%s",
+ this.instanceId,
+ sortedIds.size(),
+ criticalSectionId));
+ }
+
+ // Create a waiter keyed by criticalSectionId
+ CompletableTask lockTask = new CompletableTask<>();
+ TaskRecord record = new TaskRecord<>(lockTask, "(lock)", AutoCloseable.class);
+ Queue> eventQueue = this.outstandingEvents.computeIfAbsent(criticalSectionId, k -> new LinkedList<>());
+ eventQueue.add(record);
+
+ // Wrap the result so that when the lock is granted, we return an AutoCloseable
+ // that releases all locks on close(). The boolean guard ensures idempotency
+ // so that double-close (common with try-with-resources) doesn't emit duplicate
+ // unlock actions and corrupt the sequenceNumber for replay.
+ final boolean[] released = { false };
+ return lockTask.thenApply(ignored -> (AutoCloseable) () -> {
+ if (released[0]) {
+ return;
+ }
+ released[0] = true;
+
+ // Release all locks
+ for (EntityInstanceId lockedEntity : sortedIds) {
+ int unlockId = this.sequenceNumber++;
+ if (TaskOrchestrationExecutor.this.useNativeEntityActions) {
+ // Proto-native unlock for DTS/standalone sidecar backends
+ this.pendingActions.put(unlockId, OrchestratorAction.newBuilder()
+ .setId(unlockId)
+ .setSendEntityMessage(SendEntityMessageAction.newBuilder()
+ .setEntityUnlockSent(EntityUnlockSentEvent.newBuilder()
+ .setCriticalSectionId(criticalSectionId)
+ .setParentInstanceId(StringValue.of(this.instanceId))
+ .setTargetInstanceId(StringValue.of(lockedEntity.toString()))))
+ .build());
+ } else {
+ // Legacy DTFx ReleaseMessage JSON for Azure Functions extension compatibility
+ ObjectNode releaseMessage = JSON_MAPPER.createObjectNode();
+ releaseMessage.put("parent", this.instanceId);
+ releaseMessage.put("id", criticalSectionId);
+ this.pendingActions.put(unlockId, OrchestratorAction.newBuilder()
+ .setId(unlockId)
+ .setSendEvent(SendEventAction.newBuilder()
+ .setInstance(OrchestrationInstance.newBuilder()
+ .setInstanceId(lockedEntity.toString()))
+ .setName("release")
+ .setData(StringValue.of(releaseMessage.toString())))
+ .build());
+ }
+ }
+
+ this.isInCriticalSection = false;
+ this.lockedEntityIds = null;
+
+ if (!this.isReplaying) {
+ this.logger.fine(() -> String.format(
+ "%s: released locks for criticalSectionId=%s",
+ this.instanceId,
+ criticalSectionId));
+ }
+ });
+ }
+
+ @Override
+ public boolean isInCriticalSection() {
+ return this.isInCriticalSection;
+ }
+
+ @Override
+ public List getLockedEntities() {
+ if (!this.isInCriticalSection || this.lockedEntityIds == null || this.lockedEntityIds.isEmpty()) {
+ return Collections.emptyList();
+ }
+ List result = new ArrayList<>(this.lockedEntityIds.size());
+ for (String id : this.lockedEntityIds) {
+ result.add(EntityInstanceId.fromString(id));
+ }
+ return Collections.unmodifiableList(result);
+ }
+
+ // endregion
+
@Override
public void sendEvent(String instanceId, String eventName, Object eventData) {
Helpers.throwIfOrchestratorComplete(this.isComplete);
@@ -648,6 +1028,13 @@ private void handleEventRaised(HistoryEvent e) {
Queue> outstandingEventQueue = this.outstandingEvents.get(eventName);
if (outstandingEventQueue == null) {
// No code is waiting for this event. Buffer it in case user-code waits for it later.
+ if (!this.isReplaying) {
+ this.logger.fine(() -> String.format(
+ "%s: Received EventRaised '%s' but no outstanding waiter found. Buffering as unprocessed. Raw input: %s",
+ this.instanceId,
+ eventName,
+ eventRaised.getInput().getValue()));
+ }
this.unprocessedEvents.add(e);
return;
}
@@ -659,16 +1046,299 @@ private void handleEventRaised(HistoryEvent e) {
}
String rawResult = eventRaised.getInput().getValue();
CompletableTask task = matchingTaskRecord.getTask();
+
+ // In the Azure Functions trigger binding code path, entity operation responses arrive as
+ // standard EventRaised events (not EntityOperationCompleted proto events). DTFx wraps entity
+ // responses in a ResponseMessage JSON format: {"result":"","errorMessage":...,"failureDetails":...}
+ // We detect entity call responses by checking if the task record has an associated entityId.
+ if (matchingTaskRecord.getEntityId() != null) {
+ if (!this.isReplaying) {
+ this.logger.fine(() -> String.format(
+ "%s: Routing EventRaised '%s' to entity response handler for entity '%s'. Raw result: %s",
+ this.instanceId,
+ eventName,
+ matchingTaskRecord.getEntityId(),
+ rawResult != null ? rawResult : "(null)"));
+ }
+ this.handleEntityResponseFromEventRaised(matchingTaskRecord, rawResult);
+ } else {
+ try {
+ Object result = this.dataConverter.deserialize(
+ rawResult,
+ matchingTaskRecord.getDataType());
+ task.complete(result);
+ } catch (Exception ex) {
+ task.completeExceptionally(ex);
+ }
+ }
+ }
+
+ /**
+ * Handles an entity operation response that arrived as an EventRaised event (trigger binding path).
+ *
+ * In the trigger binding code path used by Azure Functions, DTFx.Core wraps entity responses
+ * in a ResponseMessage JSON format rather than using proto EntityOperationCompleted events.
+ * This method parses the ResponseMessage wrapper and extracts the actual operation result.
+ *
+ * The DTFx ResponseMessage class (DurableTask.Core.Entities.EventFormat.ResponseMessage) serializes as:
+ *
+ * - {@code "result"} — the serialized operation result (always present, may be null)
+ * - {@code "exceptionType"} — the error message string (misleading name: the C# property is
+ * {@code ErrorMessage} but its {@code [DataMember(Name = "exceptionType")]} annotation overrides
+ * the JSON key). Omitted when null (EmitDefaultValue=false).
+ * - {@code "failureDetails"} — a FailureDetails object with PascalCase fields
+ * ({@code ErrorType}, {@code ErrorMessage}, {@code StackTrace}, etc.).
+ * Omitted when null (EmitDefaultValue=false).
+ *
+ *
+ * @param matchingTaskRecord the task record for the entity call
+ * @param rawResult the raw JSON string from the EventRaised event
+ */
+ @SuppressWarnings("unchecked")
+ private void handleEntityResponseFromEventRaised(TaskRecord matchingTaskRecord, String rawResult) {
+ CompletableTask task = matchingTaskRecord.getTask();
+ try {
+ // Parse the ResponseMessage JSON wrapper from DTFx
+ JsonNode responseNode = JSON_MAPPER.readTree(rawResult);
+
+ if (responseNode == null || !responseNode.isObject() || !responseNode.has("result")) {
+ // Not a recognized ResponseMessage format — fall back to direct deserialization.
+ // This handles the case where the extension may send raw results in the future.
+ Object result = this.dataConverter.deserialize(rawResult, matchingTaskRecord.getDataType());
+ task.complete(result);
+ return;
+ }
+
+ // Check for error in the response.
+ // DTFx ResponseMessage uses "exceptionType" as the JSON key for the ErrorMessage property
+ // (due to [DataMember(Name = "exceptionType")]). These fields are omitted when null.
+ JsonNode exceptionTypeNode = responseNode.get("exceptionType");
+ JsonNode failureDetailsNode = responseNode.get("failureDetails");
+ boolean hasExceptionType = exceptionTypeNode != null && !exceptionTypeNode.isNull();
+ boolean hasFailureDetails = failureDetailsNode != null && !failureDetailsNode.isNull();
+
+ if (hasExceptionType || hasFailureDetails) {
+ // Entity operation failed — extract error info and complete exceptionally.
+ // The "exceptionType" JSON field actually contains the error message (misleading name).
+ String errorMessage = hasExceptionType
+ ? exceptionTypeNode.asText() : "Entity operation failed";
+ String errorType = "unknown";
+
+ if (hasFailureDetails) {
+ // FailureDetails has PascalCase JSON fields: ErrorType, ErrorMessage, StackTrace, etc.
+ JsonNode errorTypeNode = failureDetailsNode.get("ErrorType");
+ if (errorTypeNode != null && !errorTypeNode.isNull()) {
+ errorType = errorTypeNode.asText();
+ }
+ JsonNode detailErrorMsgNode = failureDetailsNode.get("ErrorMessage");
+ if (detailErrorMsgNode != null && !detailErrorMsgNode.isNull()) {
+ errorMessage = detailErrorMsgNode.asText();
+ }
+ }
+
+ if (!this.isReplaying) {
+ final String logErrorType = errorType;
+ final String logErrorMessage = errorMessage;
+ this.logger.warning(() -> String.format(
+ "%s: Entity operation on '%s' failed: [%s] %s",
+ this.instanceId,
+ matchingTaskRecord.getEntityId(),
+ logErrorType,
+ logErrorMessage));
+ }
+
+ FailureDetails details = new FailureDetails(errorType, errorMessage, null, false);
+ task.completeExceptionally(new EntityOperationFailedException(
+ matchingTaskRecord.getEntityId(),
+ matchingTaskRecord.getTaskName(),
+ details));
+ } else {
+ // Success — extract the inner result value
+ JsonNode resultNode = responseNode.get("result");
+ String innerResult = (resultNode == null || resultNode.isNull()) ? null
+ : (resultNode.isTextual() ? resultNode.asText() : resultNode.toString());
+
+ if (!this.isReplaying) {
+ this.logger.fine(() -> String.format(
+ "%s: Entity operation on '%s' completed via EventRaised with result: %s",
+ this.instanceId,
+ matchingTaskRecord.getEntityId(),
+ innerResult != null ? innerResult : "(null)"));
+ }
+
+ Object result = this.dataConverter.deserialize(innerResult, matchingTaskRecord.getDataType());
+ task.complete(result);
+ }
+ } catch (EntityOperationFailedException ex) {
+ // Re-throw entity failures (already handled above via completeExceptionally)
+ task.completeExceptionally(ex);
+ } catch (Exception ex) {
+ task.completeExceptionally(ex);
+ }
+ }
+
+ private void handleEventSent(HistoryEvent e) {
+ // During replay, remove the pending action so we don't re-send already-processed
+ // events. When using the legacy Azure Functions path (useNativeEntityActions=false),
+ // this also applies to entity operations which use SendEventAction.
+ int taskId = e.getEventId();
+ this.pendingActions.remove(taskId);
+ }
+
+ // region Entity event handlers (Phase 4)
+
+ private void handleEntityOperationSignaled(HistoryEvent e) {
+ int taskId = e.getEventId();
+ OrchestratorAction taskAction = this.pendingActions.remove(taskId);
+ if (taskAction == null) {
+ String message = String.format(
+ "Non-deterministic orchestrator detected: a history event for entity signal with sequence ID %d was replayed but the current orchestrator implementation didn't schedule this signal.",
+ taskId);
+ throw new NonDeterministicOrchestratorException(message);
+ }
+ }
+
+ private void handleEntityOperationCalled(HistoryEvent e) {
+ int taskId = e.getEventId();
+ OrchestratorAction taskAction = this.pendingActions.remove(taskId);
+ if (taskAction == null) {
+ String message = String.format(
+ "Non-deterministic orchestrator detected: a history event for entity call with sequence ID %d was replayed but the current orchestrator implementation didn't schedule this call.",
+ taskId);
+ throw new NonDeterministicOrchestratorException(message);
+ }
+ }
+
+ @SuppressWarnings("unchecked")
+ private void handleEntityOperationCompleted(HistoryEvent e) {
+ EntityOperationCompletedEvent completedEvent = e.getEntityOperationCompleted();
+ String requestId = completedEvent.getRequestId();
+
+ Queue> outstandingQueue = this.outstandingEvents.get(requestId);
+ if (outstandingQueue == null) {
+ this.logger.warning("Discarding entity operation completed event with requestId=" + requestId + ": no waiter found. Outstanding event keys: " + this.outstandingEvents.keySet());
+ return;
+ }
+
+ TaskRecord record = outstandingQueue.remove();
+ if (outstandingQueue.isEmpty()) {
+ this.outstandingEvents.remove(requestId);
+ }
+
+ String rawResult = completedEvent.hasOutput() ? completedEvent.getOutput().getValue() : null;
+
+ if (!this.isReplaying) {
+ this.logger.fine(() -> String.format(
+ "%s: Entity operation completed for requestId=%s with output: %s",
+ this.instanceId,
+ requestId,
+ rawResult != null ? rawResult : "(null)"));
+ }
+
+ CompletableTask task = record.getTask();
try {
- Object result = this.dataConverter.deserialize(
- rawResult,
- matchingTaskRecord.getDataType());
+ Object result = this.dataConverter.deserialize(rawResult, record.getDataType());
task.complete(result);
} catch (Exception ex) {
task.completeExceptionally(ex);
}
}
+ private void handleEntityOperationFailed(HistoryEvent e) {
+ EntityOperationFailedEvent failedEvent = e.getEntityOperationFailed();
+ String requestId = failedEvent.getRequestId();
+
+ Queue> outstandingQueue = this.outstandingEvents.get(requestId);
+ if (outstandingQueue == null) {
+ this.logger.warning("Discarding entity operation failed event with requestId=" + requestId + ": no waiter found");
+ return;
+ }
+
+ TaskRecord record = outstandingQueue.remove();
+ if (outstandingQueue.isEmpty()) {
+ this.outstandingEvents.remove(requestId);
+ }
+
+ FailureDetails details = new FailureDetails(failedEvent.getFailureDetails());
+
+ if (!this.isReplaying) {
+ this.logger.info(() -> String.format(
+ "%s: Entity operation failed for requestId=%s: %s",
+ this.instanceId,
+ requestId,
+ details.getErrorMessage()));
+ }
+
+ CompletableTask task = record.getTask();
+ EntityInstanceId failedEntityId = record.getEntityId() != null
+ ? record.getEntityId()
+ : EntityInstanceId.fromString("@unknown@unknown");
+ EntityOperationFailedException exception = new EntityOperationFailedException(
+ failedEntityId,
+ record.getTaskName(),
+ details);
+ task.completeExceptionally(exception);
+ }
+
+ private void handleEntityLockRequested(HistoryEvent e) {
+ int taskId = e.getEventId();
+ OrchestratorAction taskAction = this.pendingActions.remove(taskId);
+ if (taskAction == null) {
+ String message = String.format(
+ "Non-deterministic orchestrator detected: a history event for entity lock request with sequence ID %d was replayed but the current orchestrator implementation didn't issue this lock request.",
+ taskId);
+ throw new NonDeterministicOrchestratorException(message);
+ }
+ }
+
+ @SuppressWarnings("unchecked")
+ private void handleEntityLockGranted(HistoryEvent e) {
+ EntityLockGrantedEvent lockGrantedEvent = e.getEntityLockGranted();
+ String criticalSectionId = lockGrantedEvent.getCriticalSectionId();
+
+ Queue> outstandingQueue = this.outstandingEvents.get(criticalSectionId);
+ if (outstandingQueue == null) {
+ this.logger.warning("Discarding entity lock granted event with criticalSectionId=" + criticalSectionId + ": no waiter found");
+ return;
+ }
+
+ TaskRecord record = outstandingQueue.remove();
+ if (outstandingQueue.isEmpty()) {
+ this.outstandingEvents.remove(criticalSectionId);
+ }
+
+ this.isInCriticalSection = true;
+ this.lockedEntityIds = this.pendingLockSets.remove(criticalSectionId);
+ if (this.lockedEntityIds == null) {
+ throw new NonDeterministicOrchestratorException(
+ "Lock granted for criticalSectionId=" + criticalSectionId
+ + " but no pending lock set was found. This indicates a non-deterministic orchestration.");
+ }
+
+ if (!this.isReplaying) {
+ this.logger.fine(() -> String.format(
+ "%s: Entity lock granted for criticalSectionId=%s",
+ this.instanceId,
+ criticalSectionId));
+ }
+
+ CompletableTask task = record.getTask();
+ task.complete(null); // The actual AutoCloseable is created via thenApply in lockEntities()
+ }
+
+ private void handleEntityUnlockSent(HistoryEvent e) {
+ int taskId = e.getEventId();
+ OrchestratorAction taskAction = this.pendingActions.remove(taskId);
+ if (taskAction == null) {
+ String message = String.format(
+ "Non-deterministic orchestrator detected: a history event for entity unlock with sequence ID %d was replayed but the current orchestrator implementation didn't issue this unlock.",
+ taskId);
+ throw new NonDeterministicOrchestratorException(message);
+ }
+ }
+
+ // endregion
+
private void handleEventWhileSuspended (HistoryEvent historyEvent){
if (historyEvent.getEventTypeCase() != HistoryEvent.EventTypeCase.EXECUTIONSUSPENDED) {
eventsWhileSuspended.offer(historyEvent);
@@ -956,6 +1626,13 @@ private boolean processNextEvent() {
}
private void processEvent(HistoryEvent e) {
+ if (!this.isReplaying) {
+ this.logger.fine(() -> String.format(
+ "%s: Processing new event: %s (eventId=%d)",
+ this.instanceId,
+ e.getEventTypeCase(),
+ e.getEventId()));
+ }
boolean overrideSuspension = e.getEventTypeCase() == HistoryEvent.EventTypeCase.EXECUTIONRESUMED || e.getEventTypeCase() == HistoryEvent.EventTypeCase.EXECUTIONTERMINATED;
if (this.isSuspended && !overrideSuspension) {
this.handleEventWhileSuspended(e);
@@ -974,6 +1651,9 @@ private void processEvent(HistoryEvent e) {
this.setName(name);
String instanceId = startedEvent.getOrchestrationInstance().getInstanceId();
this.setInstanceId(instanceId);
+ if (startedEvent.getOrchestrationInstance().hasExecutionId()) {
+ this.executionId = startedEvent.getOrchestrationInstance().getExecutionId().getValue();
+ }
String input = startedEvent.getInput().getValue();
this.setInput(input);
String version = startedEvent.getVersion().getValue();
@@ -1028,8 +1708,9 @@ private void processEvent(HistoryEvent e) {
case SUBORCHESTRATIONINSTANCEFAILED:
this.handleSubOrchestrationFailed(e);
break;
-// case EVENTSENT:
-// break;
+ case EVENTSENT:
+ this.handleEventSent(e);
+ break;
case EVENTRAISED:
this.handleEventRaised(e);
break;
@@ -1045,6 +1726,28 @@ private void processEvent(HistoryEvent e) {
case EXECUTIONRESUMED:
this.handleExecutionResumed(e);
break;
+ // Entity event cases (Phase 4)
+ case ENTITYOPERATIONSIGNALED:
+ this.handleEntityOperationSignaled(e);
+ break;
+ case ENTITYOPERATIONCALLED:
+ this.handleEntityOperationCalled(e);
+ break;
+ case ENTITYOPERATIONCOMPLETED:
+ this.handleEntityOperationCompleted(e);
+ break;
+ case ENTITYOPERATIONFAILED:
+ this.handleEntityOperationFailed(e);
+ break;
+ case ENTITYLOCKREQUESTED:
+ this.handleEntityLockRequested(e);
+ break;
+ case ENTITYLOCKGRANTED:
+ this.handleEntityLockGranted(e);
+ break;
+ case ENTITYUNLOCKSENT:
+ this.handleEntityUnlockSent(e);
+ break;
default:
throw new IllegalStateException("Don't know how to handle history type " + e.getEventTypeCase());
}
@@ -1055,11 +1758,17 @@ private class TaskRecord {
private final CompletableTask task;
private final String taskName;
private final Class dataType;
+ private final EntityInstanceId entityId;
public TaskRecord(CompletableTask task, String taskName, Class dataType) {
+ this(task, taskName, dataType, null);
+ }
+
+ public TaskRecord(CompletableTask task, String taskName, Class dataType, EntityInstanceId entityId) {
this.task = task;
this.taskName = taskName;
this.dataType = dataType;
+ this.entityId = entityId;
}
public CompletableTask getTask() {
@@ -1073,6 +1782,10 @@ public String getTaskName() {
public Class getDataType() {
return this.dataType;
}
+
+ public EntityInstanceId getEntityId() {
+ return this.entityId;
+ }
}
/**
@@ -1543,6 +2256,10 @@ protected void handleException(Throwable e) {
throw (DataConverter.DataConverterException)e;
}
+ if (e instanceof EntityOperationFailedException) {
+ throw (EntityOperationFailedException)e;
+ }
+
throw new RuntimeException("Unexpected failure in the task execution", e);
}
diff --git a/client/src/main/java/com/microsoft/durabletask/TypedEntityMetadata.java b/client/src/main/java/com/microsoft/durabletask/TypedEntityMetadata.java
new file mode 100644
index 00000000..9fcd8b32
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/TypedEntityMetadata.java
@@ -0,0 +1,74 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import javax.annotation.Nullable;
+
+/**
+ * An extension of {@link EntityMetadata} that provides typed access to the entity's state.
+ *
+ * This mirrors the .NET SDK's {@code EntityMetadata} which inherits from {@code EntityMetadata}
+ * and provides a typed {@code State} property. In Java, the state is eagerly deserialized and accessible
+ * via {@link #getState()}.
+ *
+ * Example:
+ * {@code
+ * TypedEntityMetadata metadata = client.getEntities()
+ * .getEntityMetadata(entityId, Integer.class);
+ * if (metadata != null) {
+ * Integer state = metadata.getState();
+ * System.out.println("Counter value: " + state);
+ * }
+ * }
+ *
+ * @param the type of the entity's state
+ * @see EntityMetadata
+ * @see DurableEntityClient#getEntityMetadata(EntityInstanceId, Class)
+ */
+public final class TypedEntityMetadata extends EntityMetadata {
+
+ private final T state;
+ private final Class stateType;
+
+ /**
+ * Creates a new {@code TypedEntityMetadata} from an existing {@link EntityMetadata} and a state type.
+ *
+ * The state is eagerly deserialized from the metadata's serialized state.
+ *
+ * @param source the source metadata to wrap
+ * @param stateType the class to deserialize the state into
+ */
+ TypedEntityMetadata(EntityMetadata source, Class stateType) {
+ super(
+ source.getInstanceId(),
+ source.getLastModifiedTime(),
+ source.getBacklogQueueSize(),
+ source.getLockedBy(),
+ source.getSerializedState(),
+ source.isIncludesState(),
+ source.getDataConverter());
+ this.stateType = stateType;
+ this.state = source.readStateAs(stateType);
+ }
+
+ /**
+ * Gets the deserialized entity state.
+ *
+ * Returns {@code null} if the entity has no state or if state was not included in the query.
+ *
+ * @return the deserialized state, or {@code null}
+ */
+ @Nullable
+ public T getState() {
+ return this.state;
+ }
+
+ /**
+ * Gets the state type class used for deserialization.
+ *
+ * @return the state type class
+ */
+ public Class getStateType() {
+ return this.stateType;
+ }
+}
diff --git a/client/src/main/java/com/microsoft/durabletask/TypedEntityQueryPageable.java b/client/src/main/java/com/microsoft/durabletask/TypedEntityQueryPageable.java
new file mode 100644
index 00000000..a8a7c1a9
--- /dev/null
+++ b/client/src/main/java/com/microsoft/durabletask/TypedEntityQueryPageable.java
@@ -0,0 +1,74 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+
+/**
+ * An auto-paginating iterable over entity query results with typed state access.
+ *
+ * This class wraps an {@link EntityQueryPageable} and yields {@link TypedEntityMetadata} items
+ * with eagerly deserialized state, mirroring the .NET SDK's {@code AsyncPageable>}
+ * returned by {@code GetAllEntitiesAsync()}.
+ *
+ * Use {@link DurableEntityClient#getAllEntities(EntityQuery, Class)} to obtain an instance.
+ *
+ *
Example:
+ * {@code
+ * EntityQuery query = new EntityQuery().setInstanceIdStartsWith("counter");
+ * for (TypedEntityMetadata entity : client.getEntities().getAllEntities(query, Integer.class)) {
+ * Integer state = entity.getState();
+ * System.out.println("Counter value: " + state);
+ * }
+ * }
+ *
+ * @param the entity state type
+ */
+public final class TypedEntityQueryPageable implements Iterable> {
+ private final EntityQueryPageable inner;
+ private final Class stateType;
+
+ /**
+ * Creates a new {@code TypedEntityQueryPageable}.
+ *
+ * @param inner the underlying pageable that fetches raw entity metadata
+ * @param stateType the class to deserialize each entity's state into
+ */
+ TypedEntityQueryPageable(EntityQueryPageable inner, Class stateType) {
+ this.inner = inner;
+ this.stateType = stateType;
+ }
+
+ /**
+ * Returns an iterator over individual {@link TypedEntityMetadata} items with eagerly
+ * deserialized state, automatically fetching subsequent pages as needed.
+ *
+ * @return an iterator over all matching entities with typed state
+ */
+ @Override
+ public Iterator> iterator() {
+ return new TypedEntityItemIterator(inner.iterator());
+ }
+
+ private class TypedEntityItemIterator implements Iterator> {
+ private final Iterator delegate;
+
+ TypedEntityItemIterator(Iterator delegate) {
+ this.delegate = delegate;
+ }
+
+ @Override
+ public boolean hasNext() {
+ return delegate.hasNext();
+ }
+
+ @Override
+ public TypedEntityMetadata next() {
+ if (!hasNext()) {
+ throw new NoSuchElementException();
+ }
+ return new TypedEntityMetadata<>(delegate.next(), stateType);
+ }
+ }
+}
diff --git a/client/src/test/java/com/microsoft/durabletask/CleanEntityStorageRequestTest.java b/client/src/test/java/com/microsoft/durabletask/CleanEntityStorageRequestTest.java
new file mode 100644
index 00000000..58155968
--- /dev/null
+++ b/client/src/test/java/com/microsoft/durabletask/CleanEntityStorageRequestTest.java
@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Unit tests for {@link CleanEntityStorageRequest}.
+ */
+public class CleanEntityStorageRequestTest {
+
+ @Test
+ void defaults_matchDotNetDefaults() {
+ CleanEntityStorageRequest request = new CleanEntityStorageRequest();
+ assertNull(request.getContinuationToken());
+ assertTrue(request.isRemoveEmptyEntities());
+ assertTrue(request.isReleaseOrphanedLocks());
+ assertFalse(request.isContinueUntilComplete());
+ }
+
+ @Test
+ void setContinuationToken_roundTrip() {
+ CleanEntityStorageRequest request = new CleanEntityStorageRequest()
+ .setContinuationToken("token123");
+ assertEquals("token123", request.getContinuationToken());
+ }
+
+ @Test
+ void setContinuationToken_null_allowed() {
+ CleanEntityStorageRequest request = new CleanEntityStorageRequest()
+ .setContinuationToken("token")
+ .setContinuationToken(null);
+ assertNull(request.getContinuationToken());
+ }
+
+ @Test
+ void setRemoveEmptyEntities_roundTrip() {
+ CleanEntityStorageRequest request = new CleanEntityStorageRequest()
+ .setRemoveEmptyEntities(true);
+ assertTrue(request.isRemoveEmptyEntities());
+ }
+
+ @Test
+ void setReleaseOrphanedLocks_roundTrip() {
+ CleanEntityStorageRequest request = new CleanEntityStorageRequest()
+ .setReleaseOrphanedLocks(true);
+ assertTrue(request.isReleaseOrphanedLocks());
+ }
+
+ @Test
+ void setContinueUntilComplete_roundTrip() {
+ CleanEntityStorageRequest request = new CleanEntityStorageRequest()
+ .setContinueUntilComplete(true);
+ assertTrue(request.isContinueUntilComplete());
+ }
+
+ @Test
+ void fluentChaining_returnsSameInstance() {
+ CleanEntityStorageRequest request = new CleanEntityStorageRequest();
+ assertSame(request, request.setContinuationToken("t"));
+ assertSame(request, request.setRemoveEmptyEntities(true));
+ assertSame(request, request.setReleaseOrphanedLocks(true));
+ assertSame(request, request.setContinueUntilComplete(true));
+ }
+}
diff --git a/client/src/test/java/com/microsoft/durabletask/CleanEntityStorageResultTest.java b/client/src/test/java/com/microsoft/durabletask/CleanEntityStorageResultTest.java
new file mode 100644
index 00000000..90b5ebd2
--- /dev/null
+++ b/client/src/test/java/com/microsoft/durabletask/CleanEntityStorageResultTest.java
@@ -0,0 +1,37 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Unit tests for {@link CleanEntityStorageResult}.
+ */
+public class CleanEntityStorageResultTest {
+
+ @Test
+ void constructor_setsAllFields() {
+ CleanEntityStorageResult result = new CleanEntityStorageResult("nextToken", 5, 3);
+ assertEquals("nextToken", result.getContinuationToken());
+ assertEquals(5, result.getEmptyEntitiesRemoved());
+ assertEquals(3, result.getOrphanedLocksReleased());
+ }
+
+ @Test
+ void constructor_nullContinuationToken_allowed() {
+ CleanEntityStorageResult result = new CleanEntityStorageResult(null, 0, 0);
+ assertNull(result.getContinuationToken());
+ assertEquals(0, result.getEmptyEntitiesRemoved());
+ assertEquals(0, result.getOrphanedLocksReleased());
+ }
+
+ @Test
+ void constructor_zeroCounts() {
+ CleanEntityStorageResult result = new CleanEntityStorageResult("token", 0, 0);
+ assertEquals("token", result.getContinuationToken());
+ assertEquals(0, result.getEmptyEntitiesRemoved());
+ assertEquals(0, result.getOrphanedLocksReleased());
+ }
+}
diff --git a/client/src/test/java/com/microsoft/durabletask/EntityInstanceIdTest.java b/client/src/test/java/com/microsoft/durabletask/EntityInstanceIdTest.java
new file mode 100644
index 00000000..c5083a6e
--- /dev/null
+++ b/client/src/test/java/com/microsoft/durabletask/EntityInstanceIdTest.java
@@ -0,0 +1,215 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Unit tests for {@link EntityInstanceId}.
+ */
+public class EntityInstanceIdTest {
+
+ @Test
+ void constructor_validNameAndKey() {
+ EntityInstanceId id = new EntityInstanceId("Counter", "myCounter");
+ assertEquals("counter", id.getName());
+ assertEquals("myCounter", id.getKey());
+ }
+
+ @Test
+ void constructor_nullName_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> new EntityInstanceId(null, "key"));
+ }
+
+ @Test
+ void constructor_emptyName_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> new EntityInstanceId("", "key"));
+ }
+
+ @Test
+ void constructor_nullKey_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> new EntityInstanceId("name", null));
+ }
+
+ @Test
+ void constructor_emptyKey_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> new EntityInstanceId("name", ""));
+ }
+
+ @Test
+ void toString_format() {
+ EntityInstanceId id = new EntityInstanceId("Counter", "myCounter");
+ assertEquals("@counter@myCounter", id.toString());
+ }
+
+ @Test
+ void fromString_validFormat() {
+ EntityInstanceId id = EntityInstanceId.fromString("@Counter@myCounter");
+ assertEquals("counter", id.getName());
+ assertEquals("myCounter", id.getKey());
+ }
+
+ @Test
+ void fromString_keyContainsAtSymbol() {
+ // The key can contain @ symbols — only the first two @ delimiters matter
+ EntityInstanceId id = EntityInstanceId.fromString("@Counter@key@with@ats");
+ assertEquals("counter", id.getName());
+ assertEquals("key@with@ats", id.getKey());
+ }
+
+ @Test
+ void fromString_null_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> EntityInstanceId.fromString(null));
+ }
+
+ @Test
+ void fromString_empty_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> EntityInstanceId.fromString(""));
+ }
+
+ @Test
+ void fromString_noLeadingAt_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> EntityInstanceId.fromString("Counter@key"));
+ }
+
+ @Test
+ void fromString_onlyOneAt_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> EntityInstanceId.fromString("@Counter"));
+ }
+
+ @Test
+ void roundTrip_toStringAndFromString() {
+ EntityInstanceId original = new EntityInstanceId("BankAccount", "acct-123");
+ EntityInstanceId parsed = EntityInstanceId.fromString(original.toString());
+ assertEquals(original, parsed);
+ }
+
+ @Test
+ void equals_sameValues_areEqual() {
+ EntityInstanceId id1 = new EntityInstanceId("Counter", "c1");
+ EntityInstanceId id2 = new EntityInstanceId("Counter", "c1");
+ assertEquals(id1, id2);
+ assertEquals(id1.hashCode(), id2.hashCode());
+ }
+
+ @Test
+ void equals_differentName_notEqual() {
+ EntityInstanceId id1 = new EntityInstanceId("Counter", "c1");
+ EntityInstanceId id2 = new EntityInstanceId("Timer", "c1");
+ assertNotEquals(id1, id2);
+ }
+
+ @Test
+ void equals_differentKey_notEqual() {
+ EntityInstanceId id1 = new EntityInstanceId("Counter", "c1");
+ EntityInstanceId id2 = new EntityInstanceId("Counter", "c2");
+ assertNotEquals(id1, id2);
+ }
+
+ @Test
+ void equals_null_notEqual() {
+ EntityInstanceId id = new EntityInstanceId("Counter", "c1");
+ assertNotEquals(null, id);
+ }
+
+ @Test
+ void equals_differentType_notEqual() {
+ EntityInstanceId id = new EntityInstanceId("Counter", "c1");
+ assertNotEquals("@counter@c1", id);
+ }
+
+ @Test
+ void constructor_nameIsLowercased() {
+ EntityInstanceId id = new EntityInstanceId("Counter", "c1");
+ assertEquals("counter", id.getName());
+ }
+
+ @Test
+ void equals_differentCaseName_areEqual() {
+ EntityInstanceId id1 = new EntityInstanceId("Counter", "c1");
+ EntityInstanceId id2 = new EntityInstanceId("counter", "c1");
+ assertEquals(id1, id2);
+ assertEquals(id1.hashCode(), id2.hashCode());
+ }
+
+ @Test
+ void equals_mixedCaseName_areEqual() {
+ EntityInstanceId id1 = new EntityInstanceId("COUNTER", "c1");
+ EntityInstanceId id2 = new EntityInstanceId("counter", "c1");
+ assertEquals(id1, id2);
+ }
+
+ @Test
+ void toString_nameIsLowercased() {
+ EntityInstanceId id = new EntityInstanceId("MyEntity", "key1");
+ assertEquals("@myentity@key1", id.toString());
+ }
+
+ @Test
+ void fromString_nameIsLowercased() {
+ EntityInstanceId id = EntityInstanceId.fromString("@MyEntity@key1");
+ assertEquals("myentity", id.getName());
+ }
+
+ @Test
+ void constructor_nameContainsAt_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> new EntityInstanceId("my@entity", "key"));
+ }
+
+ @Test
+ void constructor_nameStartsWithAt_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> new EntityInstanceId("@entity", "key"));
+ }
+
+ @Test
+ void constructor_nameEndsWithAt_throwsException() {
+ assertThrows(IllegalArgumentException.class, () -> new EntityInstanceId("entity@", "key"));
+ }
+
+ @Test
+ void compareTo_ordering() {
+ EntityInstanceId a = new EntityInstanceId("A", "1");
+ EntityInstanceId b = new EntityInstanceId("B", "1");
+ EntityInstanceId a2 = new EntityInstanceId("A", "2");
+
+ // Same values
+ assertEquals(0, a.compareTo(new EntityInstanceId("A", "1")));
+
+ // Same values different case
+ assertEquals(0, a.compareTo(new EntityInstanceId("a", "1")));
+
+ // Sort by name first
+ assertTrue(a.compareTo(b) < 0);
+ assertTrue(b.compareTo(a) > 0);
+
+ // Same name, sort by key
+ assertTrue(a.compareTo(a2) < 0);
+ assertTrue(a2.compareTo(a) > 0);
+ }
+
+ @Test
+ void compareTo_sortsList() {
+ EntityInstanceId c1 = new EntityInstanceId("Counter", "1");
+ EntityInstanceId b2 = new EntityInstanceId("BankAccount", "2");
+ EntityInstanceId c3 = new EntityInstanceId("Counter", "3");
+ EntityInstanceId a1 = new EntityInstanceId("Account", "1");
+
+ List ids = Arrays.asList(c1, b2, c3, a1);
+ Collections.sort(ids);
+
+ assertEquals("account", ids.get(0).getName());
+ assertEquals("bankaccount", ids.get(1).getName());
+ assertEquals("counter", ids.get(2).getName());
+ assertEquals("1", ids.get(2).getKey());
+ assertEquals("counter", ids.get(3).getName());
+ assertEquals("3", ids.get(3).getKey());
+ }
+}
diff --git a/client/src/test/java/com/microsoft/durabletask/EntityIntegrationTests.java b/client/src/test/java/com/microsoft/durabletask/EntityIntegrationTests.java
new file mode 100644
index 00000000..7c3b40de
--- /dev/null
+++ b/client/src/test/java/com/microsoft/durabletask/EntityIntegrationTests.java
@@ -0,0 +1,414 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+
+import java.time.Duration;
+import java.util.Arrays;
+import java.util.UUID;
+import java.util.concurrent.TimeoutException;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Integration tests for durable entity features.
+ *
+ * These tests require a sidecar process running on {@code localhost:4001}.
+ * They exercise the complete entity workflow: client signaling, entity execution,
+ * state persistence, and orchestration-entity interaction.
+ */
+@Tag("integration")
+public class EntityIntegrationTests extends IntegrationTestBase {
+ private static final Duration ENTITY_ORCHESTRATION_TIMEOUT = Duration.ofSeconds(30);
+
+ // region Test entity classes
+
+ /**
+ * A simple counter entity for integration testing.
+ */
+ static class CounterEntity extends AbstractTaskEntity {
+ public void add(int amount) {
+ this.state += amount;
+ }
+
+ public void reset() {
+ this.state = 0;
+ }
+
+ public int get() {
+ return this.state;
+ }
+
+ @Override
+ protected Integer initializeState(TaskEntityOperation operation) {
+ return 0;
+ }
+
+ @Override
+ protected Class getStateType() {
+ return Integer.class;
+ }
+ }
+
+ // endregion
+
+ // region Signal entity + state query tests
+
+ @Test
+ void signalEntityAndGetState() throws TimeoutException, InterruptedException {
+ final String entityName = "Counter";
+ EntityInstanceId entityId = new EntityInstanceId(entityName, "counter-signal-" + UUID.randomUUID());
+
+ this.createWorkerBuilder()
+ .addEntity(entityName, CounterEntity::new)
+ .buildAndStart();
+
+ DurableTaskClient client = this.createClientBuilder().build();
+
+ // Signal the entity to add 10
+ client.getEntities().signalEntity(entityId, "add", 10);
+
+ // Wait for the entity to process the signal
+ Thread.sleep(5000);
+
+ // Query entity state
+ EntityMetadata metadata = client.getEntities().getEntityMetadata(entityId, true);
+ assertNotNull(metadata, "Entity metadata should not be null");
+
+ Integer state = metadata.readStateAs(Integer.class);
+ assertNotNull(state, "Entity state should not be null");
+ assertEquals(10, state, "Entity state should be 10 after adding 10");
+ }
+
+ @Test
+ void signalEntityMultipleSignals() throws TimeoutException, InterruptedException {
+ final String entityName = "Counter";
+ EntityInstanceId entityId = new EntityInstanceId(entityName, "counter-multi-" + UUID.randomUUID());
+
+ this.createWorkerBuilder()
+ .addEntity(entityName, CounterEntity::new)
+ .buildAndStart();
+
+ DurableTaskClient client = this.createClientBuilder().build();
+
+ // Send multiple signals
+ client.getEntities().signalEntity(entityId, "add", 5);
+ client.getEntities().signalEntity(entityId, "add", 3);
+ client.getEntities().signalEntity(entityId, "add", 2);
+
+ // Wait for all signals to be processed
+ Thread.sleep(8000);
+
+ EntityMetadata metadata = client.getEntities().getEntityMetadata(entityId, true);
+ assertNotNull(metadata);
+
+ Integer state = metadata.readStateAs(Integer.class);
+ assertNotNull(state);
+ assertEquals(10, state, "Entity state should be 10 after adding 5+3+2");
+ }
+
+ @Test
+ void signalEntityResetAndGet() throws TimeoutException, InterruptedException {
+ final String entityName = "Counter";
+ EntityInstanceId entityId = new EntityInstanceId(entityName, "counter-reset-" + UUID.randomUUID());
+
+ this.createWorkerBuilder()
+ .addEntity(entityName, CounterEntity::new)
+ .buildAndStart();
+
+ DurableTaskClient client = this.createClientBuilder().build();
+
+ // Add, then reset
+ client.getEntities().signalEntity(entityId, "add", 42);
+ Thread.sleep(3000);
+ client.getEntities().signalEntity(entityId, "reset");
+ Thread.sleep(5000);
+
+ EntityMetadata metadata = client.getEntities().getEntityMetadata(entityId, true);
+ assertNotNull(metadata);
+
+ Integer state = metadata.readStateAs(Integer.class);
+ assertNotNull(state);
+ assertEquals(0, state, "Entity state should be 0 after reset");
+ }
+
+ // endregion
+
+ // region Orchestration ↔ entity tests
+
+ @Test
+ void orchestrationCallsEntity() throws TimeoutException, InterruptedException {
+ final String entityName = "Counter";
+ final String orchestratorName = "CallEntityOrchestration";
+ EntityInstanceId entityId = new EntityInstanceId(entityName, "counter-orch-call-" + UUID.randomUUID());
+
+ this.createWorkerBuilder()
+ .addOrchestrator(orchestratorName, ctx -> {
+ // Signal the entity to set up some state
+ ctx.signalEntity(entityId, "add", 42);
+ // Wait for the signal to be processed
+ ctx.createTimer(Duration.ofSeconds(3)).await();
+ // Then call to get the value
+ int value = ctx.callEntity(entityId, "get", null, int.class).await();
+ ctx.complete(value);
+ })
+ .addEntity(entityName, CounterEntity::new)
+ .buildAndStart();
+
+ DurableTaskClient client = this.createClientBuilder().build();
+
+ String instanceId = client.scheduleNewOrchestrationInstance(orchestratorName);
+ OrchestrationMetadata instance = client.waitForInstanceCompletion(
+ instanceId, ENTITY_ORCHESTRATION_TIMEOUT, true);
+
+ assertNotNull(instance);
+ assertEquals(OrchestrationRuntimeStatus.COMPLETED, instance.getRuntimeStatus());
+ assertEquals(42, instance.readOutputAs(int.class));
+ }
+
+ @Test
+ void orchestrationSignalsEntityFireAndForget() throws TimeoutException, InterruptedException {
+ final String entityName = "Counter";
+ final String orchestratorName = "SignalEntityOrchestration";
+ EntityInstanceId entityId = new EntityInstanceId(entityName, "counter-orch-signal-" + UUID.randomUUID());
+
+ this.createWorkerBuilder()
+ .addOrchestrator(orchestratorName, ctx -> {
+ ctx.signalEntity(entityId, "add", 100);
+ ctx.complete("signaled");
+ })
+ .addEntity(entityName, CounterEntity::new)
+ .buildAndStart();
+
+ DurableTaskClient client = this.createClientBuilder().build();
+
+ String instanceId = client.scheduleNewOrchestrationInstance(orchestratorName);
+ OrchestrationMetadata instance = client.waitForInstanceCompletion(
+ instanceId, ENTITY_ORCHESTRATION_TIMEOUT, true);
+
+ assertNotNull(instance);
+ assertEquals(OrchestrationRuntimeStatus.COMPLETED, instance.getRuntimeStatus());
+ assertEquals("signaled", instance.readOutputAs(String.class));
+
+ // Wait for the signal to be processed
+ Thread.sleep(5000);
+
+ // Verify entity state was updated
+ EntityMetadata metadata = client.getEntities().getEntityMetadata(entityId, true);
+ assertNotNull(metadata);
+ Integer state = metadata.readStateAs(Integer.class);
+ assertNotNull(state);
+ assertEquals(100, state);
+ }
+
+ // endregion
+
+ // region Case-insensitive entity name tests
+
+ @Test
+ void signalEntity_caseInsensitiveName_entityProcessesSignal() throws TimeoutException, InterruptedException {
+ final String entityName = "Counter";
+ // Use mixed case for the entity ID — should still work since names are lowercased
+ EntityInstanceId entityId = new EntityInstanceId("COUNTER", "counter-case-" + UUID.randomUUID());
+
+ this.createWorkerBuilder()
+ .addEntity(entityName, CounterEntity::new)
+ .buildAndStart();
+
+ DurableTaskClient client = this.createClientBuilder().build();
+
+ client.getEntities().signalEntity(entityId, "add", 25);
+ Thread.sleep(5000);
+
+ EntityMetadata metadata = client.getEntities().getEntityMetadata(entityId, true);
+ assertNotNull(metadata, "Entity metadata should not be null");
+
+ Integer state = metadata.readStateAs(Integer.class);
+ assertNotNull(state, "Entity state should not be null");
+ assertEquals(25, state, "Entity state should be 25 after adding 25");
+ }
+
+ // endregion
+
+ // region Lock entities + getLockedEntities tests
+
+ @Test
+ void orchestration_lockAndCallEntity_succeeds() throws TimeoutException, InterruptedException {
+ final String entityName = "Counter";
+ final String orchestratorName = "LockEntityOrchestration";
+ EntityInstanceId entityId = new EntityInstanceId(entityName, "counter-lock-" + UUID.randomUUID());
+
+ this.createWorkerBuilder()
+ .addOrchestrator(orchestratorName, ctx -> {
+ AutoCloseable lock = ctx.lockEntities(Arrays.asList(entityId)).await();
+ // Verify we are in a critical section with locked entities
+ assertTrue(ctx.isInCriticalSection());
+ assertFalse(ctx.getLockedEntities().isEmpty());
+ // Call the locked entity
+ ctx.signalEntity(entityId, "add", 10);
+ try {
+ lock.close();
+ } catch (Exception e) {
+ throw new RuntimeException(e);
+ }
+ ctx.complete("lock-success");
+ })
+ .addEntity(entityName, CounterEntity::new)
+ .buildAndStart();
+
+ DurableTaskClient client = this.createClientBuilder().build();
+
+ String instanceId = client.scheduleNewOrchestrationInstance(orchestratorName);
+ OrchestrationMetadata instance = client.waitForInstanceCompletion(
+ instanceId, ENTITY_ORCHESTRATION_TIMEOUT, true);
+
+ assertNotNull(instance);
+ assertEquals(OrchestrationRuntimeStatus.COMPLETED, instance.getRuntimeStatus());
+ assertEquals("lock-success", instance.readOutputAs(String.class));
+ }
+
+ // endregion
+
+ // region Typed entity proxy integration tests
+
+ /**
+ * Interface for typed proxy interaction with CounterEntity.
+ */
+ public interface ICounter {
+ void add(int amount);
+ void reset();
+ Task get();
+ }
+
+ @Test
+ void typedProxy_signalAndCallEntity() throws TimeoutException, InterruptedException {
+ final String entityName = "Counter";
+ final String orchestratorName = "TypedProxyOrchestration";
+ EntityInstanceId entityId = new EntityInstanceId(entityName, "counter-proxy-" + UUID.randomUUID());
+
+ this.createWorkerBuilder()
+ .addOrchestrator(orchestratorName, ctx -> {
+ // Use the typed entity proxy
+ ICounter counter = ctx.createEntityProxy(entityId, ICounter.class);
+
+ // Void methods → signals
+ counter.add(10);
+ counter.add(20);
+ counter.add(12);
+
+ // Wait for signals to process, then call to get value
+ ctx.createTimer(Duration.ofSeconds(3)).await();
+ int value = counter.get().await();
+ ctx.complete(value);
+ })
+ .addEntity(entityName, CounterEntity::new)
+ .buildAndStart();
+
+ DurableTaskClient client = this.createClientBuilder().build();
+
+ String instanceId = client.scheduleNewOrchestrationInstance(orchestratorName);
+ OrchestrationMetadata instance = client.waitForInstanceCompletion(
+ instanceId, ENTITY_ORCHESTRATION_TIMEOUT, true);
+
+ assertNotNull(instance);
+ assertEquals(OrchestrationRuntimeStatus.COMPLETED, instance.getRuntimeStatus());
+ assertEquals(42, instance.readOutputAs(int.class));
+ }
+
+ @Test
+ void typedProxy_viaEntitiesFeature() throws TimeoutException, InterruptedException {
+ final String entityName = "Counter";
+ final String orchestratorName = "TypedProxyFeatureOrchestration";
+ EntityInstanceId entityId = new EntityInstanceId(entityName, "counter-pf-" + UUID.randomUUID());
+
+ this.createWorkerBuilder()
+ .addOrchestrator(orchestratorName, ctx -> {
+ // Use the entities() feature to create a proxy
+ ICounter counter = ctx.entities().createProxy(entityId, ICounter.class);
+
+ counter.add(100);
+ ctx.createTimer(Duration.ofSeconds(3)).await();
+ int value = counter.get().await();
+ ctx.complete(value);
+ })
+ .addEntity(entityName, CounterEntity::new)
+ .buildAndStart();
+
+ DurableTaskClient client = this.createClientBuilder().build();
+
+ String instanceId = client.scheduleNewOrchestrationInstance(orchestratorName);
+ OrchestrationMetadata instance = client.waitForInstanceCompletion(
+ instanceId, ENTITY_ORCHESTRATION_TIMEOUT, true);
+
+ assertNotNull(instance);
+ assertEquals(OrchestrationRuntimeStatus.COMPLETED, instance.getRuntimeStatus());
+ assertEquals(100, instance.readOutputAs(int.class));
+ }
+
+ // endregion
+
+ // region Re-entrant entity dispatch integration tests
+
+ /**
+ * Entity that uses re-entrant dispatch to compose operations.
+ */
+ static class BonusCounterEntity extends AbstractTaskEntity {
+ public void add(int amount) {
+ this.state += amount;
+ }
+
+ public void addWithBonus(int amount) {
+ dispatch("add", amount); // main add
+ dispatch("add", amount / 10); // 10% bonus
+ }
+
+ public int get() {
+ return this.state;
+ }
+
+ @Override
+ protected Integer initializeState(TaskEntityOperation operation) {
+ return 0;
+ }
+
+ @Override
+ protected Class getStateType() {
+ return Integer.class;
+ }
+ }
+
+ @Test
+ void reentrantDispatch_composesOperations() throws TimeoutException, InterruptedException {
+ final String entityName = "BonusCounter";
+ final String orchestratorName = "ReentrantDispatchOrchestration";
+ EntityInstanceId entityId = new EntityInstanceId(entityName, "bonus-counter-" + UUID.randomUUID());
+
+ this.createWorkerBuilder()
+ .addOrchestrator(orchestratorName, ctx -> {
+ // Signal entity to add with bonus
+ ctx.signalEntity(entityId, "addWithBonus", 100);
+
+ // Wait for signal to process, then get value
+ ctx.createTimer(Duration.ofSeconds(3)).await();
+ int value = ctx.callEntity(entityId, "get", Integer.class).await();
+ ctx.complete(value);
+ })
+ .addEntity(entityName, BonusCounterEntity::new)
+ .buildAndStart();
+
+ DurableTaskClient client = this.createClientBuilder().build();
+
+ String instanceId = client.scheduleNewOrchestrationInstance(orchestratorName);
+ OrchestrationMetadata instance = client.waitForInstanceCompletion(
+ instanceId, ENTITY_ORCHESTRATION_TIMEOUT, true);
+
+ assertNotNull(instance);
+ assertEquals(OrchestrationRuntimeStatus.COMPLETED, instance.getRuntimeStatus());
+ // 100 + 10% bonus = 110
+ assertEquals(110, instance.readOutputAs(int.class));
+ }
+
+ // endregion
+}
diff --git a/client/src/test/java/com/microsoft/durabletask/EntityMetadataTest.java b/client/src/test/java/com/microsoft/durabletask/EntityMetadataTest.java
new file mode 100644
index 00000000..41d5576c
--- /dev/null
+++ b/client/src/test/java/com/microsoft/durabletask/EntityMetadataTest.java
@@ -0,0 +1,96 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Unit tests for {@link EntityMetadata}.
+ */
+public class EntityMetadataTest {
+
+ private static final DataConverter dataConverter = new JacksonDataConverter();
+
+ @Test
+ void getters_returnConstructorValues() {
+ Instant now = Instant.now();
+ EntityMetadata metadata = new EntityMetadata(
+ "@counter@myKey", now, 5, "orch-123", "42", true, dataConverter);
+
+ assertEquals("@counter@myKey", metadata.getInstanceId());
+ assertEquals(now, metadata.getLastModifiedTime());
+ assertEquals(5, metadata.getBacklogQueueSize());
+ assertEquals("orch-123", metadata.getLockedBy());
+ assertEquals("42", metadata.getSerializedState());
+ }
+
+ @Test
+ void getEntityInstanceId_parsesCorrectly() {
+ EntityMetadata metadata = new EntityMetadata(
+ "@counter@myKey", Instant.EPOCH, 0, null, null, false, dataConverter);
+
+ EntityInstanceId entityId = metadata.getEntityInstanceId();
+ assertEquals("counter", entityId.getName());
+ assertEquals("myKey", entityId.getKey());
+ }
+
+ @Test
+ void readStateAs_deserializesIntegerState() {
+ EntityMetadata metadata = new EntityMetadata(
+ "@counter@c1", Instant.EPOCH, 0, null, "42", true, dataConverter);
+
+ Integer state = metadata.readStateAs(Integer.class);
+ assertNotNull(state);
+ assertEquals(42, state);
+ }
+
+ @Test
+ void readStateAs_deserializesStringState() {
+ EntityMetadata metadata = new EntityMetadata(
+ "@myEntity@k1", Instant.EPOCH, 0, null, "\"hello\"", true, dataConverter);
+
+ String state = metadata.readStateAs(String.class);
+ assertEquals("hello", state);
+ }
+
+ @Test
+ void readStateAs_nullState_returnsNull() {
+ EntityMetadata metadata = new EntityMetadata(
+ "@counter@c1", Instant.EPOCH, 0, null, null, false, dataConverter);
+
+ Integer state = metadata.readStateAs(Integer.class);
+ assertNull(state);
+ }
+
+ @Test
+ void lockedBy_nullWhenNotLocked() {
+ EntityMetadata metadata = new EntityMetadata(
+ "@counter@c1", Instant.EPOCH, 0, null, null, false, dataConverter);
+ assertNull(metadata.getLockedBy());
+ }
+
+ @Test
+ void backlogQueueSize_zero() {
+ EntityMetadata metadata = new EntityMetadata(
+ "@counter@c1", Instant.EPOCH, 0, null, null, false, dataConverter);
+ assertEquals(0, metadata.getBacklogQueueSize());
+ }
+
+ @Test
+ void includesState_true_whenStateIncluded() {
+ EntityMetadata metadata = new EntityMetadata(
+ "@counter@c1", Instant.EPOCH, 0, null, "42", true, dataConverter);
+ assertTrue(metadata.isIncludesState());
+ }
+
+ @Test
+ void includesState_false_whenStateNotIncluded() {
+ EntityMetadata metadata = new EntityMetadata(
+ "@counter@c1", Instant.EPOCH, 0, null, null, false, dataConverter);
+ assertFalse(metadata.isIncludesState());
+ }
+}
diff --git a/client/src/test/java/com/microsoft/durabletask/EntityOptionsTest.java b/client/src/test/java/com/microsoft/durabletask/EntityOptionsTest.java
new file mode 100644
index 00000000..9e579718
--- /dev/null
+++ b/client/src/test/java/com/microsoft/durabletask/EntityOptionsTest.java
@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import org.junit.jupiter.api.Test;
+
+import java.time.Duration;
+import java.time.Instant;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Unit tests for {@link SignalEntityOptions} and {@link CallEntityOptions}.
+ */
+public class EntityOptionsTest {
+
+ // region SignalEntityOptions tests
+
+ @Test
+ void signalEntityOptions_default_scheduledTimeIsNull() {
+ SignalEntityOptions options = new SignalEntityOptions();
+ assertNull(options.getScheduledTime());
+ }
+
+ @Test
+ void signalEntityOptions_setScheduledTime_roundTrip() {
+ Instant time = Instant.parse("2025-06-15T10:00:00Z");
+ SignalEntityOptions options = new SignalEntityOptions().setScheduledTime(time);
+ assertEquals(time, options.getScheduledTime());
+ }
+
+ @Test
+ void signalEntityOptions_setScheduledTime_null_resetsToNull() {
+ Instant time = Instant.parse("2025-06-15T10:00:00Z");
+ SignalEntityOptions options = new SignalEntityOptions()
+ .setScheduledTime(time)
+ .setScheduledTime(null);
+ assertNull(options.getScheduledTime());
+ }
+
+ @Test
+ void signalEntityOptions_fluentChaining_returnsSameInstance() {
+ SignalEntityOptions options = new SignalEntityOptions();
+ assertSame(options, options.setScheduledTime(Instant.now()));
+ }
+
+ // endregion
+
+ // region CallEntityOptions tests
+
+ @Test
+ void callEntityOptions_default_timeoutIsNull() {
+ CallEntityOptions options = new CallEntityOptions();
+ assertNull(options.getTimeout());
+ }
+
+ @Test
+ void callEntityOptions_setTimeout_roundTrip() {
+ Duration timeout = Duration.ofSeconds(30);
+ CallEntityOptions options = new CallEntityOptions().setTimeout(timeout);
+ assertEquals(timeout, options.getTimeout());
+ }
+
+ @Test
+ void callEntityOptions_setTimeout_null_resetsToNull() {
+ CallEntityOptions options = new CallEntityOptions()
+ .setTimeout(Duration.ofSeconds(30))
+ .setTimeout(null);
+ assertNull(options.getTimeout());
+ }
+
+ @Test
+ void callEntityOptions_setTimeout_zero_allowed() {
+ CallEntityOptions options = new CallEntityOptions().setTimeout(Duration.ZERO);
+ assertEquals(Duration.ZERO, options.getTimeout());
+ }
+
+ @Test
+ void callEntityOptions_fluentChaining_returnsSameInstance() {
+ CallEntityOptions options = new CallEntityOptions();
+ assertSame(options, options.setTimeout(Duration.ofMinutes(5)));
+ }
+
+ // endregion
+}
diff --git a/client/src/test/java/com/microsoft/durabletask/EntityProxyTest.java b/client/src/test/java/com/microsoft/durabletask/EntityProxyTest.java
new file mode 100644
index 00000000..0bfb2ca8
--- /dev/null
+++ b/client/src/test/java/com/microsoft/durabletask/EntityProxyTest.java
@@ -0,0 +1,475 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.microsoft.durabletask;
+
+import org.junit.jupiter.api.Test;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.*;
+import java.util.concurrent.CompletableFuture;
+import java.util.function.Consumer;
+import java.util.function.Function;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Unit tests for {@link EntityProxy} — typed entity proxy feature.
+ */
+public class EntityProxyTest {
+
+ // region Test interfaces
+
+ /**
+ * Basic counter interface with signal (void) and call (Task) operations.
+ */
+ public interface ICounter {
+ void add(int amount);
+ void reset();
+ Task get();
+ }
+
+ /**
+ * Interface with a parameterized call operation.
+ */
+ public interface IGreeter {
+ Task greet(String name);
+ }
+
+ /**
+ * Interface with only void (signal) methods.
+ */
+ public interface ISignalOnly {
+ void doSomething();
+ void doSomethingWith(String data);
+ }
+
+ /**
+ * Interface with an invalid return type (neither void nor Task).
+ */
+ public interface IInvalidReturn {
+ String badMethod();
+ }
+
+ /**
+ * Interface with too many parameters.
+ */
+ public interface ITooManyParams {
+ void transfer(String from, String to, int amount);
+ }
+
+ /**
+ * Not an interface — used to test validation.
+ */
+ public static class NotAnInterface {
+ }
+
+ // endregion
+
+ // region Simple test Task implementation (package-private constructor accessible from same package)
+
+ /**
+ * Minimal concrete {@link Task} implementation for unit testing.
+ */
+ static class TestTask extends Task {
+ TestTask(V value) {
+ super(CompletableFuture.completedFuture(value));
+ }
+
+ @Override
+ public V await() {
+ try {
+ return this.future.get();
+ } catch (Exception e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ @Override
+ public Task thenApply(Function fn) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public Task thenAccept(Consumer fn) {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+ // endregion
+
+ // region Recording context for verifying proxy behavior
+
+ /**
+ * Minimal {@link TaskOrchestrationContext} that records signal and call invocations.
+ */
+ static class RecordingContext implements TaskOrchestrationContext {
+ final List signals = new ArrayList<>();
+ final List calls = new ArrayList<>();
+
+ // Captured state from the last signalEntity / callEntity call
+ EntityInstanceId lastSignalEntityId;
+ String lastSignalOp;
+ Object lastSignalInput;
+
+ EntityInstanceId lastCallEntityId;
+ String lastCallOp;
+ Object lastCallInput;
+ Class lastCallReturnType;
+
+ @Override
+ public String getName() { return "test"; }
+
+ @Override
+ public V getInput(Class targetType) { return null; }
+
+ @Override
+ public String getInstanceId() { return "test-instance"; }
+
+ @Override
+ public Instant getCurrentInstant() { return Instant.now(); }
+
+ @Override
+ public boolean getIsReplaying() { return false; }
+
+ @Override
+ public String getVersion() { return "1.0"; }
+
+ @Override
+ public Task> allOf(List> tasks) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public Task> anyOf(List> tasks) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public Task callActivity(String name, @Nullable Object input, @Nullable TaskOptions options, Class returnType) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public Task callSubOrchestrator(String name, @Nullable Object input, @Nullable String instanceID, @Nullable TaskOptions options, Class returnType) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public Task createTimer(Duration duration) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public Task waitForExternalEvent(String name, Duration timeout, Class dataType) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public void continueAsNew(Object input, boolean preserveUnprocessedEvents) { }
+
+ @Override
+ public void complete(Object output) { }
+
+ @Override
+ public void signalEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName,
+ @Nullable Object input, @Nullable SignalEntityOptions options) {
+ this.lastSignalEntityId = entityId;
+ this.lastSignalOp = operationName;
+ this.lastSignalInput = input;
+ this.signals.add(operationName);
+ }
+
+ @Override
+ @SuppressWarnings("unchecked")
+ public Task callEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName,
+ @Nullable Object input, @Nonnull Class returnType) {
+ this.lastCallEntityId = entityId;
+ this.lastCallOp = operationName;
+ this.lastCallInput = input;
+ this.lastCallReturnType = returnType;
+ this.calls.add(operationName);
+ // Return a completed task with a default value
+ return new TestTask<>(null);
+ }
+
+ @Override
+ public Task callEntity(@Nonnull EntityInstanceId entityId, @Nonnull String operationName,
+ @Nullable Object input, @Nonnull Class returnType,
+ @Nullable CallEntityOptions options) {
+ return callEntity(entityId, operationName, input, returnType);
+ }
+
+ @Override
+ public Task lockEntities(@Nonnull List entityIds) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public boolean isInCriticalSection() { return false; }
+
+ @Override
+ public List