#21: EXPERIMENTAL: Allow Entity IDs to be String-valued types

...represented as string values in YDB and marshaled using `valueOf()`/`fromString()`
and `toString()`` methods.

To enable this experimental feature, annotate your ID type with `@StringValueType(entityId=true)`.

Author: nvamelichev

Diff for: databind/src/main/java/tech/ydb/yoj/ExperimentalApi.java

@@ -0,0 +1,23 @@
+package tech.ydb.yoj;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.SOURCE;
+
+/**
+ * Annotates experimental features.
+ */
+@Target({TYPE, FIELD, METHOD, PARAMETER, ANNOTATION_TYPE})
+@Retention(SOURCE)
+public @interface ExperimentalApi {
+    /**
+     * @return URL of the GitHub issue tracking the experimental API
+     */
+    String issue();
+}

Diff for: databind/src/main/java/tech/ydb/yoj/databind/FieldValueType.java

@@ -2,7 +2,10 @@
 
 import com.google.common.base.Preconditions;
 import lombok.NonNull;
+import org.jetbrains.annotations.NotNull;
+import tech.ydb.yoj.ExperimentalApi;
 import tech.ydb.yoj.databind.schema.Column;
+import tech.ydb.yoj.databind.schema.StringValueType;
 
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
@@ -100,15 +103,33 @@ public enum FieldValueType {
             String.class
     ));
 
+    /**
+     * @deprecated It is recommended to use the new {@link StringValueType} annotation instead of calling this method.
+     * <p>
+     * To register a class <em>not in your code</em> (e.g., {@code UUID} from the JDK) as a string-value type, continue using this
+     * method. A later version of YOJ will provide an alternative way of doing so, probably by calling some method on {@code SchemaRegistry}.
+     *
+     * @param clazz class to register as string-value. Must either be final or sealed with permissible final-only implementations.
+     *              All permissible implementations of a sealed class will be registered automatically.
+     */
+    @Deprecated
+    @ExperimentalApi(issue = "https://github.com/ydb-platform/yoj-project/issues/21")
     public static void registerStringValueType(@NonNull Class<?> clazz) {
+        ensureValidStringValueType(clazz);
+        STRING_VALUE_TYPES.add(clazz);
+        if (clazz.isSealed()) {
+            STRING_VALUE_TYPES.addAll(Arrays.asList(clazz.getPermittedSubclasses()));
+        }
+    }
+
+    private static void ensureValidStringValueType(@NotNull Class<?> clazz) {
         boolean isFinal = isFinal(clazz.getModifiers());
         boolean isSealed = clazz.isSealed();
         Preconditions.checkArgument(isFinal || isSealed,
                 "String-value type must either be final or sealed, but got: %s", clazz);
 
-        STRING_VALUE_TYPES.add(clazz);
         if (isSealed) {
-            Arrays.stream(clazz.getPermittedSubclasses()).forEach(FieldValueType::registerStringValueType);
+            Arrays.stream(clazz.getPermittedSubclasses()).forEach(FieldValueType::ensureValidStringValueType);
         }
     }
 
@@ -140,8 +161,7 @@ public static FieldValueType forJavaType(@NonNull Type type) {
         if (type instanceof ParameterizedType || type instanceof TypeVariable) {
             return OBJECT;
         } else if (type instanceof Class<?> clazz) {
-            // FIXME: remove static configuration here, more it to e.g. a class annotation (or SchemaRegistry)
-            if (STRING_VALUE_TYPES.contains(clazz)) {
+            if (isStringValueType(clazz)) {
                 return STRING;
             } else if (INTEGER_NUMERIC_TYPES.contains(clazz)) {
                 return INTEGER;
@@ -176,6 +196,18 @@ public static FieldValueType forJavaType(@NonNull Type type) {
         }
     }
 
+    private static boolean isStringValueType(Class<?> clazz) {
+        if (STRING_VALUE_TYPES.contains(clazz)) {
+            return true;
+        }
+        if (clazz.getAnnotation(StringValueType.class) != null) {
+            // FIXME: Move the Set of string-value types to SchemaRegistry
+            registerStringValueType(clazz);
+            return true;
+        }
+        return false;
+    }
+
     /**
      * Checks whether Java object of type {@code type} is mapped to a composite database value
      * (i.e. > 1 database field)

Diff for: databind/src/main/java/tech/ydb/yoj/databind/schema/Schema.java

@@ -44,6 +44,7 @@
 import static java.util.stream.Collectors.toList;
 import static java.util.stream.Collectors.toMap;
 import static lombok.AccessLevel.PROTECTED;
+import static tech.ydb.yoj.databind.FieldValueType.STRING;
 
 public abstract class Schema<T> {
     public static final String PATH_DELIMITER = ".";
@@ -194,9 +195,20 @@ protected Schema(Schema<?> schema, String subSchemaFieldPath) {
 
         staticName = schema.staticName;
         globalIndexes = schema.globalIndexes;
-        fields = (subSchemaField.fields == null)
-                ? List.of()
-                : subSchemaField.fields.stream().map(this::newRootJavaField).toList();
+
+        if (subSchemaField.fields != null) {
+            fields = subSchemaField.fields.stream().map(this::newRootJavaField).toList();
+        } else {
+            var subSchemaFieldType = subSchemaField.getRawType();
+            if (subSchemaFieldType.getAnnotation(StringValueType.class) != null
+                    && subSchemaFieldType.getAnnotation(StringValueType.class).entityId()) {
+                var dummyField = new JavaField(new DummyStringValueField(subSchemaField), subSchemaField, __ -> true);
+                dummyField.setName(subSchemaField.getName());
+                fields = List.of(dummyField);
+            } else {
+                fields = List.of();
+            }
+        }
         ttlModifier = schema.ttlModifier;
         changefeeds = schema.changefeeds;
     }
@@ -379,6 +391,65 @@ public final String toString() {
                 + " [type=" + getType().getName() + "]";
     }
 
+    private static final class DummyStringValueField implements ReflectField {
+        private final JavaField donor;
+
+        private DummyStringValueField(JavaField donor) {
+            this.donor = donor;
+        }
+
+        @Override
+        public String getName() {
+            return donor.getName();
+        }
+
+        @Override
+        public Column getColumn() {
+            return donor.getField().getColumn();
+        }
+
+        @Override
+        public Type getGenericType() {
+            return String.class;
+        }
+
+        @Override
+        public Class<?> getType() {
+            return String.class;
+        }
+
+        @Override
+        public ReflectType<?> getReflectType() {
+            return donor.getField().getReflectType();
+        }
+
+        @Override
+        public Object getValue(Object containingObject) {
+            Preconditions.checkArgument(donor.getRawType().isInstance(containingObject),
+                    "Tried to get value of a string-value field '%s' on an invalid type: expected %s, got %s",
+                    donor.getPath(),
+                    donor.getRawType(),
+                    containingObject == null ? "<null value>" : containingObject.getClass()
+            );
+            return containingObject.toString();
+        }
+
+        @Override
+        public Collection<ReflectField> getChildren() {
+            return Set.of();
+        }
+
+        @Override
+        public FieldValueType getValueType() {
+            return STRING;
+        }
+
+        @Override
+        public String toString() {
+            return "DummyStringValueField[donor=" + donor + "]";
+        }
+    }
+
     public static final class JavaField {
         @Getter
         private final ReflectField field;
@@ -462,6 +533,10 @@ public Type getType() {
             return field.getGenericType();
         }
 
+        public Class<?> getRawType() {
+            return field.getType();
+        }
+
         // FIXME: make this method non-public
         @Deprecated
         public void setName(String newName) {

Diff for: databind/src/main/java/tech/ydb/yoj/databind/schema/StringValueType.java

@@ -0,0 +1,25 @@
+package tech.ydb.yoj.databind.schema;
+
+import tech.ydb.yoj.ExperimentalApi;
+
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Marks the type as a <em>String-value type</em>, serialized to the database as text by calling {@code toString()} and
+ * deserialized back using {@code static [TYPE] fromString(String)} or {@code static [TYPE] valueOf(String)} method.
+ */
+@Target(TYPE)
+@Retention(RUNTIME)
+@Inherited
+public @interface StringValueType {
+    /**
+     * Experimental feature: Represent the whole Entity ID as a String.
+     */
+    @ExperimentalApi(issue = "https://github.com/ydb-platform/yoj-project/issues/21")
+    boolean entityId();
+}

Diff for: repository-inmemory/src/test/java/tech/ydb/yoj/repository/test/inmemory/TestInMemoryRepository.java

@@ -23,6 +23,7 @@
 import tech.ydb.yoj.repository.test.sample.model.Supabubble2;
 import tech.ydb.yoj.repository.test.sample.model.Team;
 import tech.ydb.yoj.repository.test.sample.model.TypeFreak;
+import tech.ydb.yoj.repository.test.sample.model.UpdateFeedEntry;
 
 import java.util.Set;
 
@@ -100,6 +101,11 @@ public SupabubbleTable supabubbles() {
         public Supabubble2Table supabubbles2() {
             return new Supabubble2InMemoryTable(getMemory(Supabubble2.class));
         }
+
+        @Override
+        public Table<UpdateFeedEntry> updateFeedEntries() {
+            return table(UpdateFeedEntry.class);
+        }
     }
 
     private static class Supabubble2InMemoryTable extends InMemoryTable<Supabubble2> implements TestEntityOperations.Supabubble2Table {

Diff for: repository-test/src/main/java/tech/ydb/yoj/repository/test/RepositoryTest.java

@@ -51,6 +51,7 @@
 import tech.ydb.yoj.repository.test.sample.model.TypeFreak.A;
 import tech.ydb.yoj.repository.test.sample.model.TypeFreak.B;
 import tech.ydb.yoj.repository.test.sample.model.TypeFreak.Embedded;
+import tech.ydb.yoj.repository.test.sample.model.UpdateFeedEntry;
 import tech.ydb.yoj.repository.test.sample.model.WithUnflattenableField;
 
 import java.time.Instant;
@@ -60,6 +61,7 @@
 import java.util.HashSet;
 import java.util.Iterator;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
 import java.util.concurrent.atomic.AtomicBoolean;
@@ -2095,7 +2097,7 @@ public void rangeLock() {
 
         parallelTx(true, true, t -> t.find(new Range<>(new Complex.Id(1, 2L, null, null)))); //lock on range
         parallelTx(false, false, t -> t.find(new Range<>(new Complex.Id(1, 2L, null, null)))); //lock on range
-        
+
         parallelTx(false, true, t -> t.find(new Range<>(new Complex.Id(2, 2L, null, null)))); //not lock on another range
         parallelTx(false, false, t -> t.find(new Range<>(new Complex.Id(2, 2L, null, null)))); //not lock on another range
     }
@@ -2606,6 +2608,30 @@ public void readAndFailOnInconsistentDataSucceedOnRetry() {
         assertThat(twoElements).hasSize(2);
     }
 
+    @Test
+    public void stringValuedIdInsert() {
+        Map<UpdateFeedEntry.Id, UpdateFeedEntry> inserted = new HashMap<>();
+        for (int i = 0; i < 100; i++) {
+            var snap = new UpdateFeedEntry(UpdateFeedEntry.Id.generate("insert"), Instant.now(), "payload-" + i);
+            db.tx(() -> db.updateFeedEntries().insert(snap));
+            inserted.put(snap.getId(), snap);
+        }
+
+        assertThat(db.tx(() -> db.updateFeedEntries().find(inserted.keySet())))
+                .containsExactlyInAnyOrderElementsOf(inserted.values());
+
+        assertThat(db.tx(() -> db.updateFeedEntries().list(ListRequest.builder(UpdateFeedEntry.class)
+                .filter(fb -> fb.where("id").in(inserted.keySet()))
+                .build())))
+                .containsExactlyInAnyOrderElementsOf(inserted.values());
+
+        for (var e : inserted.entrySet()) {
+            assertThat(db.tx(() -> db.updateFeedEntries().query()
+                    .filter(fb -> fb.where("id").eq(e.getKey()))
+                    .findOne())).isEqualTo(e.getValue());
+        }
+    }
+
     protected void runInTx(Consumer<RepositoryTransaction> action) {
         // We do not retry transactions, because we do not expect conflicts in our test scenarios.
         RepositoryTransaction transaction = startTransaction();

Diff for: repository-test/src/main/java/tech/ydb/yoj/repository/test/entity/TestEntities.java

@@ -19,6 +19,7 @@
 import tech.ydb.yoj.repository.test.sample.model.Supabubble2;
 import tech.ydb.yoj.repository.test.sample.model.Team;
 import tech.ydb.yoj.repository.test.sample.model.TypeFreak;
+import tech.ydb.yoj.repository.test.sample.model.UpdateFeedEntry;
 import tech.ydb.yoj.repository.test.sample.model.WithUnflattenableField;
 
 import java.util.List;
@@ -39,7 +40,8 @@ private TestEntities() {
             Supabubble.class,
             Supabubble2.class,
             NonDeserializableEntity.class,
-            WithUnflattenableField.class
+            WithUnflattenableField.class,
+            UpdateFeedEntry.class
     );
 
     @SuppressWarnings("unchecked")

Diff for: repository-test/src/main/java/tech/ydb/yoj/repository/test/sample/TestEntityOperations.java

@@ -19,6 +19,7 @@
 import tech.ydb.yoj.repository.test.sample.model.Supabubble2;
 import tech.ydb.yoj.repository.test.sample.model.Team;
 import tech.ydb.yoj.repository.test.sample.model.TypeFreak;
+import tech.ydb.yoj.repository.test.sample.model.UpdateFeedEntry;
 
 import java.util.ArrayList;
 import java.util.Collection;
@@ -57,6 +58,8 @@ default Table<BytePkEntity> bytePkEntities() {
 
     Supabubble2Table supabubbles2();
 
+    Table<UpdateFeedEntry> updateFeedEntries();
+
     class ProjectTable extends AbstractDelegatingTable<Project> {
         public ProjectTable(Table<Project> target) {
             super(target);

Diff for: repository-test/src/main/java/tech/ydb/yoj/repository/test/sample/model/ChangefeedEntity.java

@@ -15,7 +15,7 @@
         format = JSON,
         virtualTimestamps = true,
         retentionPeriod = "PT1H",
-        initialScan = true
+        initialScan = false
 )
 @Changefeed(name = "test-changefeed2")
 public class ChangefeedEntity implements Entity<ChangefeedEntity> {

Diff for: repository-test/src/main/java/tech/ydb/yoj/repository/test/sample/model/TypeFreak.java

@@ -138,7 +138,7 @@ public String toString() {
     }
 
     /**
-     * String-valued type with canonical static factory ({@link #valueOf(String)}) and a matching {@link #toString()}
+     * String-value type with canonical static factory ({@link #valueOf(String)}) and a matching {@link #toString()}
      * instance method.
      * <p><em>E.g.,</em> {@code "XYZ-100500" <=> new Ticket(queue="XYZ", num=100500)}
      */