#77: Remove deprecation from user-visible parts of the Projections API (for now) + Improve messages for dry-run mode transactions

We remove `@Deprecated` annotation and deprecation warning logs from user-visible parts
of the Projections API: `t.y.y.r.d.{Entity.createProjections, EntityList}`, `t.y.y.r.d.projection.*` 
(except for `@InternalApi`s). 

We add concrete docs on which parts of the APIs will be moved to a different library and/or
package, and which internal Projection-related APIs will be removed entirely (or at least *may* be.)

Drive-by change: Improve transaction log message and ordinary log message when we roll back
a dry-run transaction. It's not caused by any "inconsistency", and is in fact entirely normal and indended.

Co-authored-by: Alexander Lavrukov <[email protected]>
Co-authored-by: Nikolai Amelichev <[email protected]>

Author: 3 people

databind/src/main/java/tech/ydb/yoj/databind/schema/Schema.java

@@ -577,7 +577,8 @@ public void setName(String newName) {
         }
 
         /**
-         * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
+         * @deprecated Projections will be moved from the core YOJ API in 3.0.0 to an optional module.
+         * The {@code getRawPath()} method is only used by projection logic, and will most likely be removed.
          * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
          */
         @Deprecated(forRemoval = true)
@@ -586,7 +587,8 @@ public String getRawPath() {
         }
 
         /**
-         * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
+         * @deprecated Projections will be moved from the core YOJ API in 3.0.0 to an optional module.
+         * The {@code getRawSubPath(int)} method is only used by projection logic, and will most likely be removed.
          * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
          */
         @Deprecated(forRemoval = true)

repository/src/main/java/tech/ydb/yoj/repository/db/Entity.java

@@ -23,10 +23,11 @@ default E preSave() {
     }
 
     /**
-     * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
+     * <strong>Warning!</strong> Projections will be moved to a separate YOJ module in YOJ 3.0.0.
+     * The {@code Entity.createProjections()} method will be moved to a subinterface of {@code Entity}
+     * in a separate library.
      * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
      */
-    @Deprecated(forRemoval = true)
     default List<Entity<?>> createProjections() {
         return List.of();
     }

repository/src/main/java/tech/ydb/yoj/repository/db/EntityList.java

@@ -6,10 +6,11 @@
 import java.util.stream.Stream;
 
 /**
+ * <strong>Warning!</strong> Projections will be moved to a separate YOJ library in YOJ 3.0.0.
+ * The {@code EntityList} class will be moved to {@code tech.ydb.yoj.repository.db.projection} package in
+ * a separate library.
  * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
- * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
  */
-@Deprecated(forRemoval = true)
 public class EntityList extends LinkedList<Entity<?>> {
     public static EntityList create() {
         return new EntityList();

repository/src/main/java/tech/ydb/yoj/repository/db/StdTxManager.java

@@ -337,6 +337,11 @@ public boolean isFirstLevelCache() {
         return options.isFirstLevelCache();
     }
 
+    @Override
+    public boolean isDryRun() {
+        return options.isDryRun();
+    }
+
     @Nullable
     @Override
     public IsolationLevel getIsolationLevel() {

repository/src/main/java/tech/ydb/yoj/repository/db/TxImpl.java

@@ -86,9 +86,8 @@ private <R> R runImpl(Supplier<R> supplier) {
         }
 
         if (dryRun) {
-            doRollback(true,
-                    String.format("[%s] runInTx(): Rollback because dry-run transaction read inconsistent data", sw));
-            log.debug("[{}] runInTx(): Rollback due to dry-run mode {}", sw, formatExecutionLogMultiline("# "));
+            doRollback(true, String.format("[%s] runInTx(): Rollback due to DRY-RUN mode", sw));
+            log.debug("[{}] runInTx(): Rollback due to DRY-RUN mode {}", sw, formatExecutionLogMultiline("# "));
             return res;
         }
 

repository/src/main/java/tech/ydb/yoj/repository/db/TxManagerState.java

@@ -19,4 +19,6 @@ public interface TxManagerState {
     boolean isScan();
 
     boolean isFirstLevelCache();
+
+    boolean isDryRun();
 }

repository/src/main/java/tech/ydb/yoj/repository/db/cache/TransactionLocal.java

@@ -47,7 +47,8 @@ public <X> X instance(@NonNull Supplier<X> supplier) {
      * <strong>Warning:</strong> Unlike {@link #log()}, this method is not intended to be used by end-users,
      * only by the YOJ implementation itself.
      *
-     * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
+     * @deprecated Projections will be moved from the core YOJ API in 3.0.0 to an optional module.
+     * The {@code projectionCache()} method is an implementation detail, and will be removed.
      * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
      */
     @InternalApi

repository/src/main/java/tech/ydb/yoj/repository/db/projection/ProjectionCache.java

@@ -1,12 +1,12 @@
 package tech.ydb.yoj.repository.db.projection;
 
-
 import tech.ydb.yoj.InternalApi;
 import tech.ydb.yoj.repository.db.Entity;
 import tech.ydb.yoj.repository.db.RepositoryTransaction;
 
 /**
- * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
+ * @deprecated Projections will be moved from the core YOJ API in 3.0.0 to an optional module.
+ * The {@code ProjectionCache} interface is an implementation detail, and will be removed or moved to an internal package.
  * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
  */
 @InternalApi

repository/src/main/java/tech/ydb/yoj/repository/db/projection/ProjectionMappings.java

@@ -5,7 +5,6 @@
 import com.google.common.collect.HashBiMap;
 import lombok.NonNull;
 import lombok.RequiredArgsConstructor;
-import tech.ydb.yoj.DeprecationWarnings;
 import tech.ydb.yoj.databind.schema.Schema;
 import tech.ydb.yoj.repository.db.Entity;
 import tech.ydb.yoj.repository.db.EntityIdSchema;
@@ -24,10 +23,10 @@
 import static lombok.AccessLevel.PRIVATE;
 
 /**
+ * <strong>Warning!</strong> Projections will be moved to a separate YOJ module in YOJ 3.0.0.
+ * The {@code ProjectionMappings} class will be moved to a separate library.
  * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
- * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
  */
-@Deprecated(forRemoval = true)
 public final class ProjectionMappings {
     private ProjectionMappings() {
     }
@@ -96,9 +95,6 @@ public static <P extends Entity<P>, T extends Entity<T>> Map<String, String> len
     @NonNull
     public static <P extends Entity<P>, T extends Entity<T>> Map<String, String> strictFieldMapping(
             @NonNull Class<P> projectionType, @NonNull Class<T> entityType) {
-        DeprecationWarnings.warnOnce("ProjectionMappings.*fieldMapping", "You are using ProjectionMappings.{lenient,strict}FieldMapping(). "
-                + "Projections will be removed from YOJ core in YOJ 3.0.0. See https://github.com/ydb-platform/yoj-project/issues/77");
-
         EntitySchema<T> entitySchema = EntitySchema.of(entityType);
         Class<?> entityIdType = entitySchema.getIdSchema().getType();
         List<Schema.JavaField> projectionIdFields = EntityIdSchema.ofEntity(projectionType).getFields();
@@ -153,16 +149,14 @@ private static Schema.JavaField getMatchingIdField(@NonNull Schema.JavaField pro
 
     @NonNull
     public static <P extends Entity<P>> ListViaProjection<P> listViaProjection(@NonNull Class<P> projectionType) {
-        DeprecationWarnings.warnOnce("ProjectionMappings.listViaProjection", "You are using ProjectionMappings.listViaProjection(). "
-                + "Projections will be removed from YOJ core in YOJ 3.0.0. See https://github.com/ydb-platform/yoj-project/issues/77");
         return new ListViaProjection<>(projectionType);
     }
 
     /**
+     * <strong>Warning!</strong> Projections will be moved to a separate YOJ module in YOJ 3.0.0.
+     * The {@code ProjectionMappings.ListViaProjection} class will be moved to a separate library.
      * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
-     * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
      */
-    @Deprecated(forRemoval = true)
     @RequiredArgsConstructor(access = PRIVATE)
     public static final class ListViaProjection<P extends Entity<P>> {
         private final Class<P> projectionType;
@@ -193,10 +187,10 @@ public <T extends Entity<T>> Listing<T, P> entities(@NonNull ListRequest<T> requ
         }
 
         /**
+         * <strong>Warning!</strong> Projections will be moved to a separate YOJ module in YOJ 3.0.0.
+         * The {@code ProjectionMappings.Listing} class will be moved to a separate library.
          * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
-         * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
          */
-        @Deprecated(forRemoval = true)
         @RequiredArgsConstructor(access = PRIVATE)
         public static final class Listing<T extends Entity<T>, P extends Entity<P>> {
             private final ListRequest<T> request;
@@ -214,10 +208,10 @@ public ListResult<P> run(@NonNull Function<ListRequest<P>, ListResult<P>> listFu
         }
 
         /**
+         * <strong>Warning!</strong> Projections will be moved to a separate YOJ module in YOJ 3.0.0.
+         * The {@code ProjectionMappings.TransformedListing} class will be moved to a separate library.
          * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
-         * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
          */
-        @Deprecated(forRemoval = true)
         @RequiredArgsConstructor(access = PRIVATE)
         public static final class TransformedListing<T extends Entity<T>, P extends Entity<P>> {
             private final Listing<T, P> listing;

repository/src/main/java/tech/ydb/yoj/repository/db/projection/Projections.java

@@ -8,10 +8,10 @@
 import java.lang.annotation.Target;
 
 /**
- * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
+ * <strong>Warning!</strong> Projections will be moved to a separate YOJ module in YOJ 3.0.0.
+ * The {@code Projections} annotation interface will be moved to a separate library.
  * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
  */
-@Deprecated(forRemoval = true)
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Projections {