align entity API defaults with .NET SDK and add TypedEntityMetadata<T>

Author: bachuv

client/src/main/java/com/microsoft/durabletask/DurableEntityClient.java

@@ -80,14 +80,16 @@ public abstract void signalEntity(
             @Nullable SignalEntityOptions options);
 
     /**
-     * Fetches the metadata for a durable entity instance, excluding its state.
+     * Fetches the metadata for a durable entity instance, including its state by default.
+     * <p>
+     * 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, false);
+        return this.getEntityMetadata(entityId, true);
     }
 
     /**
@@ -100,6 +102,36 @@ public EntityMetadata getEntityMetadata(EntityInstanceId entityId) {
     @Nullable
     public abstract EntityMetadata getEntityMetadata(EntityInstanceId entityId, boolean includeState);
 
+    /**
+     * Fetches the metadata for a durable entity instance with typed state access.
+     * <p>
+     * This always includes state in the result, matching the .NET SDK's
+     * {@code GetEntityAsync<T>()} pattern. The returned {@link TypedEntityMetadata} provides
+     * a {@link TypedEntityMetadata#getState()} method for direct typed state access.
+     *
+     * <pre>{@code
+     * TypedEntityMetadata<Integer> metadata = client.getEntities()
+     *     .getEntityMetadata(entityId, Integer.class);
+     * if (metadata != null) {
+     *     Integer state = metadata.getState();
+     *     System.out.println("Counter value: " + state);
+     * }
+     * }</pre>
+     *
+     * @param entityId  the entity instance ID to query
+     * @param stateType the class to deserialize the entity's state into
+     * @param <T>       the entity state type
+     * @return the typed entity metadata with state, or {@code null} if the entity does not exist
+     */
+    @Nullable
+    public <T> TypedEntityMetadata<T> getEntityMetadata(EntityInstanceId entityId, Class<T> 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.
      *
@@ -149,6 +181,44 @@ public EntityQueryPageable getAllEntities() {
         return getAllEntities(new EntityQuery());
     }
 
+    /**
+     * Returns an auto-paginating iterable over entity instances matching the specified filter criteria,
+     * with state included for typed access.
+     * <p>
+     * This convenience overload ensures that entity state is fetched, matching the .NET SDK's
+     * {@code GetAllEntitiesAsync<T>()} pattern. Use {@link EntityMetadata#readStateAs(Class)} on
+     * each result to access the typed state.
+     * <p>
+     * Note: The provided query's {@code includeState} setting is preserved. A copy of the query
+     * is made with {@code includeState} set to {@code true} so the original query is not modified.
+     *
+     * <pre>{@code
+     * EntityQuery query = new EntityQuery().setInstanceIdStartsWith("counter");
+     * for (EntityMetadata entity : client.getEntities().getAllEntities(query, Integer.class)) {
+     *     Integer state = entity.readStateAs(Integer.class);
+     *     System.out.println("Counter value: " + state);
+     * }
+     * }</pre>
+     *
+     * @param query     the query filter criteria
+     * @param stateType the expected type of the entity's state, used with
+     *                  {@link EntityMetadata#readStateAs(Class)} for deserialization
+     * @param <T>       the entity state type
+     * @return a pageable iterable over all matching entities with state included
+     */
+    public <T> EntityQueryPageable getAllEntities(EntityQuery query, Class<T> stateType) {
+        // Create a copy with includeState=true so we don't mutate the caller's query
+        EntityQuery typedQuery = new EntityQuery()
+                .setInstanceIdStartsWith(query.getInstanceIdStartsWith())
+                .setLastModifiedFrom(query.getLastModifiedFrom())
+                .setLastModifiedTo(query.getLastModifiedTo())
+                .setIncludeState(true)
+                .setIncludeTransient(query.isIncludeTransient())
+                .setPageSize(query.getPageSize())
+                .setContinuationToken(query.getContinuationToken());
+        return new EntityQueryPageable(typedQuery, this::queryEntities);
+    }
+
     /**
      * Cleans up entity storage by removing empty entities and/or releasing orphaned locks.
      * <p>

client/src/main/java/com/microsoft/durabletask/EntityMetadata.java

@@ -7,8 +7,13 @@
 
 /**
  * Represents metadata about a durable entity instance, including its identity, state, and lock status.
+ * <p>
+ * 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 final class EntityMetadata {
+public class EntityMetadata {
     private final String instanceId;
     private final Instant lastModifiedTime;
     private final int backlogQueueSize;
@@ -115,6 +120,17 @@ public boolean isIncludesState() {
         return this.includesState;
     }
 
+    /**
+     * Gets the data converter used for state deserialization.
+     * <p>
+     * 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.
      *

client/src/main/java/com/microsoft/durabletask/EntityQuery.java

@@ -13,10 +13,17 @@
  * {@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;
+    private boolean includeState = true;
     private boolean includeTransient;
     private Integer pageSize;
     private String continuationToken;

client/src/main/java/com/microsoft/durabletask/TaskEntity.java

@@ -65,11 +65,13 @@ public abstract class TaskEntity<TState> implements ITaskEntity {
 
     /**
      * Controls whether operations can be dispatched to methods on the state object.
-     * When {@code true} (the default), if no matching method is found on the entity class itself,
+     * 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}, only methods on the entity class are considered.
+     * When {@code false} (the default), only methods on the entity class are considered.
+     * <p>
+     * This matches the .NET SDK default where {@code AllowStateDispatch} is {@code false}.
      */
-    private boolean allowStateDispatch = true;
+    private boolean allowStateDispatch = false;
 
     // Cache for resolved methods, keyed by (class, operationName).
     // Uses Optional<Method> so that "not found" results are also cached.
@@ -93,9 +95,9 @@ protected boolean getAllowStateDispatch() {
     /**
      * Sets whether operations can be dispatched to methods on the state object.
      * <p>
-     * When {@code true} (the default), if no matching method is found on the entity class itself,
+     * 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}, only methods on the entity class are considered.
+     * 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
      */

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.
+ * <p>
+ * This mirrors the .NET SDK's {@code EntityMetadata<TState>} which inherits from {@code EntityMetadata}
+ * and provides a typed {@code State} property. In Java, the state is eagerly deserialized and accessible
+ * via {@link #getState()}.
+ *
+ * <h3>Example:</h3>
+ * <pre>{@code
+ * TypedEntityMetadata<Integer> metadata = client.getEntities()
+ *     .getEntityMetadata(entityId, Integer.class);
+ * if (metadata != null) {
+ *     Integer state = metadata.getState();
+ *     System.out.println("Counter value: " + state);
+ * }
+ * }</pre>
+ *
+ * @param <T> the type of the entity's state
+ * @see EntityMetadata
+ * @see DurableEntityClient#getEntityMetadata(EntityInstanceId, Class)
+ */
+public final class TypedEntityMetadata<T> extends EntityMetadata {
+
+    private final T state;
+    private final Class<T> stateType;
+
+    /**
+     * Creates a new {@code TypedEntityMetadata} from an existing {@link EntityMetadata} and a state type.
+     * <p>
+     * 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<T> 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.
+     * <p>
+     * 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<T> getStateType() {
+        return this.stateType;
+    }
+}

client/src/test/java/com/microsoft/durabletask/EntityQueryTest.java

@@ -56,19 +56,28 @@ void setInstanceIdStartsWith_mixedCase_lowercased() {
     // region defaults
 
     @Test
-    void defaults_allNullOrFalse() {
+    void defaults_includeStateTrue_othersNullOrFalse() {
         EntityQuery query = new EntityQuery();
         assertNull(query.getInstanceIdStartsWith());
         assertNull(query.getLastModifiedFrom());
         assertNull(query.getLastModifiedTo());
-        assertFalse(query.isIncludeState());
+        assertTrue(query.isIncludeState());
         assertFalse(query.isIncludeTransient());
         assertNull(query.getPageSize());
         assertNull(query.getContinuationToken());
     }
 
     // endregion
 
+    // region DefaultPageSize constant
+
+    @Test
+    void defaultPageSize_is100() {
+        assertEquals(100, EntityQuery.DEFAULT_PAGE_SIZE);
+    }
+
+    // endregion
+
     // region setter/getter round-trip tests
 
     @Test

client/src/test/java/com/microsoft/durabletask/TaskEntityTest.java

@@ -105,10 +105,15 @@ public void setValue(int value) {
 
     /**
      * Entity that has no matching method but whose state type has the method (state dispatch).
+     * Explicitly enables state dispatch since the default is now {@code false}.
      */
     static class StateDispatchEntity extends TaskEntity<MyState> {
         // No "increment" method on the entity itself — should dispatch to MyState.increment()
 
+        public StateDispatchEntity() {
+            setAllowStateDispatch(true);
+        }
+
         @Override
         protected Class<MyState> getStateType() {
             return MyState.class;
@@ -336,10 +341,10 @@ void stateDispatch_disabledWithAllowStateDispatchFalse() {
     }
 
     @Test
-    void stateDispatch_enabledByDefault() throws Exception {
-        // StateDispatchEntity has allowStateDispatch=true (default)
-        StateDispatchEntity entity = new StateDispatchEntity();
-        assertTrue(entity.getAllowStateDispatch());
+    void stateDispatch_disabledByDefault() throws Exception {
+        // Default is now false, matching the .NET SDK
+        CounterEntity entity = new CounterEntity();
+        assertFalse(entity.getAllowStateDispatch());
     }
 
     // endregion