#77: Mark projections as deprecated for removal in YOJ 3.0.0

Author: nvamelichev

repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/table/YdbTable.java

@@ -558,9 +558,16 @@ public void delete(Entity.Id<T> id) {
      * If the entity has projections, its {@link Entity#createProjections() createProjections()}
      * method <strong>MUST NOT</strong> fail when called on a raw, non-{@link Entity#postLoad() post-loaded} entity.
      *
+     * @deprecated This method will be removed in YOJ 3.0.0, along with projection-related logic; because without projection magic&trade;,
+     * it will works the same as {@code Table.find()} + {@code Table.save()} (which will apply the {@code Entity.postLoad()} and
+     * {@code Entity.preSave()} and save the entity only if it has been changed by these calls).
+     *
+     * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
+     *
      * @param id   entity ID
      * @param <ID> entity ID type
      */
+    @Deprecated(forRemoval = true)
     public <ID extends Id<T>> void migrate(ID id) {
         var statement = new FindYqlStatement<>(tableDescriptor, schema, schema);
         List<T> foundRaw = executor.execute(statement, id);

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

@@ -22,6 +22,11 @@ default E preSave() {
         return (E) this;
     }
 
+    /**
+     * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
+     * @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/cache/TransactionLocal.java

@@ -46,10 +46,12 @@ 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.
-     * <p>Also, projection support <em>might</em> be dropped or seriously reworked in YOJ 3.x, so please
-     * do not rely on this implementation detail.
+     *
+     * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
+     * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
      */
     @InternalApi
+    @Deprecated(forRemoval = true)
     public ProjectionCache projectionCache() {
         return instance(projectionCacheSupplier);
     }

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

@@ -5,7 +5,12 @@
 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.
+ * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
+ */
 @InternalApi
+@Deprecated(forRemoval = true)
 public interface ProjectionCache {
     void load(Entity<?> entity);
 

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

@@ -5,6 +5,7 @@
 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;
@@ -22,6 +23,11 @@
 import static java.util.stream.Collectors.toList;
 import static lombok.AccessLevel.PRIVATE;
 
+/**
+ * @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() {
     }
@@ -90,6 +96,9 @@ 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();
@@ -144,9 +153,15 @@ 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);
     }
 
+    /**
+     * @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.
+     */
     @RequiredArgsConstructor(access = PRIVATE)
     public static final class ListViaProjection<P extends Entity<P>> {
         private final Class<P> projectionType;
@@ -176,6 +191,10 @@ public <T extends Entity<T>> Listing<T, P> entities(@NonNull ListRequest<T> requ
             return new Listing<>(request, request.forEntity(projectionType, fieldMapping));
         }
 
+        /**
+         * @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.
+         */
         @RequiredArgsConstructor(access = PRIVATE)
         public static final class Listing<T extends Entity<T>, P extends Entity<P>> {
             private final ListRequest<T> request;
@@ -192,6 +211,10 @@ public ListResult<P> run(@NonNull Function<ListRequest<P>, ListResult<P>> listFu
             }
         }
 
+        /**
+         * @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.
+         */
         @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

@@ -7,6 +7,11 @@
 import java.lang.annotation.RetentionPolicy;
 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.
+ * @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 {

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

@@ -4,7 +4,12 @@
 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.
+ * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
+ */
 @InternalApi
+@Deprecated(forRemoval = true)
 public class RoProjectionCache implements ProjectionCache {
     @Override
     public void load(Entity<?> entity) {

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

@@ -1,18 +1,26 @@
 package tech.ydb.yoj.repository.db.projection;
 
+import lombok.NonNull;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import tech.ydb.yoj.DeprecationWarnings;
 import tech.ydb.yoj.InternalApi;
 import tech.ydb.yoj.repository.db.Entity;
 import tech.ydb.yoj.repository.db.RepositoryTransaction;
 
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.stream.Stream;
 
 import static java.util.stream.Collectors.toMap;
 
+/**
+ * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
+ * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
+ */
 @InternalApi
+@Deprecated(forRemoval = true)
 public class RwProjectionCache implements ProjectionCache {
     private static final Logger log = LoggerFactory.getLogger(RwProjectionCache.class);
 
@@ -104,11 +112,27 @@ void delete() {
         }
 
         Stream<Entity<?>> projectionsBefore() {
-            return writable && loaded != null ? loaded.createProjections().stream() : Stream.empty();
+            return projectionStream(loaded);
         }
 
         Stream<Entity<?>> projectionsAfter() {
-            return writable && saved != null ? saved.createProjections().stream() : Stream.empty();
+            return projectionStream(saved);
+        }
+
+        @NonNull
+        private Stream<Entity<?>> projectionStream(Entity<?> entity) {
+            if (writable && entity != null) {
+                List<Entity<?>> projectionList = entity.createProjections();
+                if (!projectionList.isEmpty()) {
+                    String entityClassName = entity.getClass().getName();
+                    DeprecationWarnings.warnOnce("RwProjectionCache/" + entityClassName, "You are using projections for " + entityClassName + ". "
+                            + "Projections will be removed from YOJ core in YOJ 3.0.0. See https://github.com/ydb-platform/yoj-project/issues/77");
+                }
+
+                return projectionList.stream();
+            } else {
+                return Stream.empty();
+            }
         }
 
         void flush() {

repository/src/main/java/tech/ydb/yoj/repository/db/projection/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * @deprecated Projections will be removed from the core YOJ API in 3.0.0 and possibly reintroduced as an optional module.
+ * @see <a href="https://github.com/ydb-platform/yoj-project/issues/77">#77</a>
+ */
+@Deprecated(forRemoval = true)
+package tech.ydb.yoj.repository.db.projection;