#77: Add concrete docs on which parts of Projections user-visible API will be moved to a different library and/or package, and which internal Projection-related APIs will be removed altogether

Author: nvamelichev

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,6 +23,9 @@ default E preSave() {
     }
 
     /**
+     * <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>
      */
     default List<Entity<?>> createProjections() {

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/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

@@ -5,7 +5,8 @@
 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

@@ -23,6 +23,8 @@
 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>
  */
 public final class ProjectionMappings {
@@ -151,10 +153,10 @@ public static <P extends Entity<P>> ListViaProjection<P> listViaProjection(@NonN
     }
 
     /**
+     * <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;
@@ -185,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;
@@ -206,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,6 +8,8 @@
 import java.lang.annotation.Target;
 
 /**
+ * <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>
  */
 @Target(ElementType.TYPE)

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

@@ -5,7 +5,8 @@
 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 RoProjectionCache} class 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/RwProjectionCache.java

@@ -14,7 +14,9 @@
 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.
+ * @deprecated Projections will be moved from the core YOJ API in 3.0.0 to an optional module.
+ * The {@code RwProjectionCache} class 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