More detailed deprecation ERRORs and WARNs in log for `@Deprecated(fo…

…rRemoval)` method calls - We now include stack traces! - We use WARNs for trivial but high-volume violations (`Entity.Id.resolve()`, `new Range<>()`)
ydb-platform · Apr 11, 2024 · 7b00447 · 7b00447
1 parent a7123cf
commit 7b00447
Show file tree

Hide file tree

Showing 17 changed files with 207 additions and 126 deletions.
diff --git a/databind/src/main/java/tech/ydb/yoj/databind/FieldValueType.java b/databind/src/main/java/tech/ydb/yoj/databind/FieldValueType.java
@@ -134,12 +134,10 @@ public enum FieldValueType {
     @Deprecated(forRemoval = true)
     @ExperimentalApi(issue = "https://github.com/ydb-platform/yoj-project/issues/24")
     public static void registerStringValueType(@NonNull Class<?> clazz) {
-        log.error(
-                """
-                You are using FieldValueType.registerStringValueType({}.class) which is deprecated for removal in YOJ 3.0.0.
-                Please use @StringColumn annotation on the Entity field or a @StringValueType annotation on the string-valued type
-                """,
-                clazz.getCanonicalName()
+        log.error("You are using FieldValueType.registerStringValueType({}.class) which is deprecated for removal in YOJ 3.0.0. "
+                        + "Please use @StringColumn annotation on the Entity field or a @StringValueType annotation on the string-valued type",
+                clazz.getCanonicalName(),
+                new Throwable("FieldValueType.registerStringValueType(Class) call stack trace")
         );
 
         boolean isFinal = isFinal(clazz.getModifiers());
@@ -157,10 +155,8 @@ public static void registerStringValueType(@NonNull Class<?> clazz) {
      * Detects the data binding type appropriate for the specified Schema field.
      *
      * @param schemaField schema field
-     *
      * @return database value type
      * @throws IllegalArgumentException if object of this type cannot be mapped to a database value
-     *
      * @see JavaField#getType()
      * @see #forJavaType(Type, ReflectField)
      */
@@ -257,7 +253,7 @@ public static FieldValueType forJavaType(@NonNull Type type, @Nullable Column co
      * @return {@code true} if this class is a custom string value type registered by {@link #registerStringValueType(Class)};
      * {@code false} otherwise
      */
-    @Deprecated
+    @Deprecated(forRemoval = true)
     @ExperimentalApi(issue = "https://github.com/ydb-platform/yoj-project/issues/24")
     public static boolean isCustomStringValueType(Class<?> clazz) {
         return CUSTOM_STRING_VALUE_TYPES.contains(clazz);
@@ -282,7 +278,8 @@ public static boolean isCustomStringValueType(Class<?> clazz) {
      */
     @Deprecated(forRemoval = true)
     public static boolean isComposite(@NonNull Type type) {
-        log.error("You are using FieldValueType.isComposite(Type) which is deprecated for removal in YOJ 3.0.0. Please update your code accordingly");
+        log.error("You are using FieldValueType.isComposite(Type) which is deprecated for removal in YOJ 3.0.0. Please update your code accordingly",
+                new Throwable("FieldValueType.isComposite(Type) call stack trace"));
         return forJavaType(type).isComposite();
     }
 
@@ -300,7 +297,8 @@ public boolean isComposite() {
      */
     @Deprecated(forRemoval = true)
     public boolean isUnknown() {
-        log.error("You are using FieldValueType.isUnknown() which is deprecated for removal in YOJ 3.0.0. Please update your code accordingly");
+        log.error("You are using FieldValueType.isUnknown() which is deprecated for removal in YOJ 3.0.0. Please update your code accordingly",
+                new Throwable("FieldValueType.isUnknown() call stack trace"));
         return this == UNKNOWN;
     }
 
@@ -318,7 +316,8 @@ public boolean isUnknown() {
      */
     @Deprecated(forRemoval = true)
     public boolean isSortable() {
-        log.error("You are using FieldValueType.isSortable() which is deprecated for removal in YOJ 3.0.0. Please update your code accordingly");
+        log.error("You are using FieldValueType.isSortable() which is deprecated for removal in YOJ 3.0.0. Please update your code accordingly",
+                new Throwable("FieldValueType.isSortable() call stack trace"));
         return SORTABLE_VALUE_TYPES.contains(this);
     }
 }
diff --git a/repository-test/src/main/java/tech/ydb/yoj/repository/test/RepositoryTest.java b/repository-test/src/main/java/tech/ydb/yoj/repository/test/RepositoryTest.java
diff --git a/repository-test/src/main/java/tech/ydb/yoj/repository/test/entity/TestEntities.java b/repository-test/src/main/java/tech/ydb/yoj/repository/test/entity/TestEntities.java
@@ -55,7 +55,7 @@ private TestEntities() {
 
     @SuppressWarnings("unchecked")
     public static Repository init(@NonNull Repository repository) {
-        // Legacy registration. Used in e.g. UniqueEntity
+        // Intentional Legacy registration. Used in e.g. UniqueEntity
         FieldValueType.registerStringValueType(UUID.class);
 
         repository.createTablespace();

diff --git a/repository-ydb-v1/src/main/java/tech/ydb/yoj/repository/ydb/YdbLegacySpliterator.java b/repository-ydb-v1/src/main/java/tech/ydb/yoj/repository/ydb/YdbLegacySpliterator.java
@@ -1,21 +1,28 @@
 package tech.ydb.yoj.repository.ydb;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import java.util.Spliterator;
 import java.util.function.Consumer;
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 
 /**
- * @deprecated Legacy implementation of {@code Spliterator} for {@code ReadTable}.
- * <p>Please use the new {@code Spliterator} contract-conformant implementation by explicitly setting
- * {@code ReadTableParams.builder().<...>.useNewSpliterator(true)}.
+ * @deprecated Legacy implementation of {@code Spliterator} for {@code ReadTable}. Will be removed in YOJ 3.0.0.
+ * <p>To opt into using of this legacy implementation, explicitly set {@code ReadTableParams.<ID>builder().<...>.useNewSpliterator(false)}.
  */
-@Deprecated
+@Deprecated(forRemoval = true)
 class YdbLegacySpliterator<V> implements Spliterator<V> {
+    private static final Logger log = LoggerFactory.getLogger(YdbLegacySpliterator.class);
+
     private final int flags;
     private final Consumer<Consumer<? super V>> action;
 
     public YdbLegacySpliterator(boolean isOrdered, Consumer<Consumer<? super V>> action) {
+        log.error("You are using YdbLegacySpliterator which is deprecated for removal in YOJ 3.0.0. "
+                + "Please use readTable(ReadTableParams.builder().<...>.useNewSpliterator(true).build())",
+                new Throwable("YdbLegacySpliterator construction stack trace"));
         this.action = action;
         flags = (isOrdered ? ORDERED : 0) | NONNULL;
     }

diff --git a/repository-ydb-v1/src/main/java/tech/ydb/yoj/repository/ydb/table/BatchFindSpliterator.java b/repository-ydb-v1/src/main/java/tech/ydb/yoj/repository/ydb/table/BatchFindSpliterator.java
@@ -46,7 +46,7 @@ abstract class BatchFindSpliterator<R, T extends Entity<T>, ID extends Entity.Id
         );
         this.top = YqlLimit.top(batchSize);
         if (partial != null) {
-            Range<ID> range = new Range<>(partial);
+            Range<ID> range = Range.create(partial);
             Map<String, Object> eqMap = range.getEqMap();
             this.initialPartialPredicates = this.idSchema
                     .flattenFields().stream()

diff --git a/repository-ydb-v1/src/main/java/tech/ydb/yoj/repository/ydb/yql/YqlPredicate.java b/repository-ydb-v1/src/main/java/tech/ydb/yoj/repository/ydb/yql/YqlPredicate.java
@@ -5,6 +5,8 @@
 import lombok.AllArgsConstructor;
 import lombok.NonNull;
 import lombok.RequiredArgsConstructor;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import tech.ydb.yoj.repository.db.Entity;
 import tech.ydb.yoj.repository.db.EntitySchema;
 import tech.ydb.yoj.repository.ydb.statement.PredicateStatement;
@@ -54,13 +56,26 @@ public abstract class YqlPredicate implements YqlStatementPart<YqlPredicate> {
     public static final String TYPE = "Predicate";
     private static final AtomicBoolean useLegacyIn = new AtomicBoolean(false);
     private static final AtomicBoolean useLegacyRel = new AtomicBoolean(false);
+    private static final Logger log = LoggerFactory.getLogger(YqlPredicate.class);
 
-    public static void setUseLegacyIn(boolean useLegacyIn) {
-        YqlPredicate.useLegacyIn.set(useLegacyIn);
+    /**
+     * @deprecated This method will be removed in YOJ 3.0.0. There is no alternative, just stop calling it.
+     */
+    @Deprecated(forRemoval = true)
+    public static void setUseLegacyIn(boolean value) {
+        log.error("You are using YqlPredicate.setUseLegacyIn(boolean) which is deprecated for removal in YOJ 3.0.0. Please stop calling this method",
+                new Throwable("YqlPredicate.setUseLegacyIn(boolean) call stack trace"));
+        YqlPredicate.useLegacyIn.set(value);
     }
 
-    public static void setUseLegacyRel(boolean useLegacyRel) {
-        YqlPredicate.useLegacyRel.set(useLegacyRel);
+    /**
+     * @deprecated This method will be removed in YOJ 3.0.0. There is no alternative, just stop calling it.
+     */
+    @Deprecated(forRemoval = true)
+    public static void setUseLegacyRel(boolean value) {
+        log.error("You are using YqlPredicate.setUseLegacyRel(boolean) which is deprecated for removal in YOJ 3.0.0. Please stop calling this method",
+                new Throwable("YqlPredicate.setUseLegacyRel(boolean) call stack trace"));
+        YqlPredicate.useLegacyRel.set(value);
     }
 
     public static FieldPredicateBuilder where(@NonNull String fieldPath) {
@@ -362,7 +377,6 @@ public String toString() {
         }
     }
 
-    @Deprecated(forRemoval = true)
     /*package*/ static final class RelPredicate<V> extends YqlPredicate {
         private final Rel rel;
         private final String fieldPath;
@@ -450,7 +464,10 @@ public final Rel negate() {
             return Rel.valueOf(negation);
         }
 
-        @Deprecated
+        /**
+         * @deprecated Will be removed in YOJ 3.0.0 because combining relational predicates is no longer needed.
+         */
+        @Deprecated(forRemoval = true)
         public final String combine(String result, String element) {
             return result == null ? element : exprCombiner.apply(result, element);
         }
@@ -556,7 +573,7 @@ public Type negate() {
     }
 
     @AllArgsConstructor(access = PRIVATE)
-    @Deprecated
+    @Deprecated(forRemoval = true)
     /*package*/ static final class InLegacyPredicate<V> extends YqlPredicate {
         private final YqlPredicateParam<Collection<V>> param;
         private final String fieldPath;

diff --git a/repository-ydb-v1/src/main/java/tech/ydb/yoj/repository/ydb/yql/YqlPrimitiveType.java b/repository-ydb-v1/src/main/java/tech/ydb/yoj/repository/ydb/yql/YqlPrimitiveType.java
@@ -12,6 +12,8 @@
 import lombok.NonNull;
 import lombok.Value;
 import lombok.With;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import tech.ydb.yoj.databind.ByteArray;
 import tech.ydb.yoj.databind.CustomValueType;
 import tech.ydb.yoj.databind.CustomValueTypes;
@@ -48,6 +50,8 @@
 @Value
 @AllArgsConstructor(access = PRIVATE)
 public class YqlPrimitiveType implements YqlType {
+    private static final Logger log = LoggerFactory.getLogger(YqlPrimitiveType.class);
+
     // Only table column data types. See https://ydb.tech/en/docs/yql/reference/types/
     private static final Map<PrimitiveTypeId, String> YQL_TYPE_NAMES = Map.ofEntries(
             Map.entry(PrimitiveTypeId.BOOL, "Bool"),
@@ -333,14 +337,16 @@ public static void resetStringDefaultTypeToDefaults() {
     }
 
     /**
-     * @deprecated Nothing in YOJ calls {@code YqlPrimitiveType.of(Type)} any more.
+     * @deprecated This method will be removed in YOJ 3.0.0. Nothing in YOJ calls {@code YqlPrimitiveType.of(Type)} any more.
      * <p>Please use {@link #of(JavaField) YqlPrimitiveType.of(JavaField)} because it correcly
      * respects the customizations specified in the {@link Column &#64;Column} and
      * {@link CustomValueType &#64;CustomValueType} annotations.
      */
     @NonNull
     @Deprecated(forRemoval = true)
     public static YqlPrimitiveType of(Type javaType) {
+        log.error("You are using YqlPrimitiveType.of(Type) which will be removed in YOJ 3.0.0. Please use YqlPrimitiveType.of(JavaField)",
+                new Throwable("YqlPrimitiveType.of(Type) call stack trace"));
         var valueType = FieldValueType.forJavaType(javaType, null, null);
         return resolveYqlType(javaType, valueType, null, null);
     }

diff --git a/repository-ydb-v1/src/main/java/tech/ydb/yoj/repository/ydb/yql/YqlType.java b/repository-ydb-v1/src/main/java/tech/ydb/yoj/repository/ydb/yql/YqlType.java
@@ -11,7 +11,7 @@ public interface YqlType {
     ValueProtos.Type.Builder getYqlTypeBuilder();
 
     /**
-     * @deprecated Nothing in YOJ calls {@code YqlType.of(Type)} any more.
+     * @deprecated This method will be removed in YOJ 3.0.0. Nothing in YOJ calls {@code YqlType.of(Type)} any more.
      * <p>Please use {@link #of(JavaField) YqlType.of(JavaField)} because it correcly
      * respects the customizations specified in the {@link Column &#64;Column} annotation.
      */

diff --git a/repository-ydb-v1/src/test/java/tech/ydb/yoj/repository/ydb/YdbRepositoryCacheTest.java b/repository-ydb-v1/src/test/java/tech/ydb/yoj/repository/ydb/YdbRepositoryCacheTest.java
@@ -91,7 +91,7 @@ public void findRangeAndPutInCache() {
 
         when(session.executeDataQuery(any(), any(), any(), any())).thenReturn(convertEntity(results));
 
-        ops.complexes().find(new Range<>(new Complex.Id(1, null, null, null)));
+        ops.complexes().find(Range.create(new Complex.Id(1, null, null, null)));
         for (Complex c : results) {
             ops.complexes().find(c.getId());
         }

diff --git a/repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/YdbLegacySpliterator.java b/repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/YdbLegacySpliterator.java
@@ -1,21 +1,29 @@
 package tech.ydb.yoj.repository.ydb;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import java.util.Spliterator;
 import java.util.function.Consumer;
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 
 /**
- * @deprecated Legacy implementation of {@code Spliterator} for {@code ReadTable}.
+ * @deprecated Legacy implementation of {@code Spliterator} for {@code ReadTable}. Will be removed in YOJ 3.0.0.
  * <p>Please use the new {@code Spliterator} contract-conformant implementation by explicitly setting
  * {@code ReadTableParams.builder().<...>.useNewSpliterator(true)}.
  */
-@Deprecated
+@Deprecated(forRemoval = true)
 public class YdbLegacySpliterator<V> implements Spliterator<V> {
+    private static final Logger log = LoggerFactory.getLogger(YdbLegacySpliterator.class);
+
     private final int flags;
     private final Consumer<Consumer<? super V>> action;
 
     public YdbLegacySpliterator(boolean isOrdered, Consumer<Consumer<? super V>> action) {
+        log.error("You are using YdbLegacySpliterator which is deprecated for removal in YOJ 3.0.0. "
+                + "Please use readTable(ReadTableParams.builder().<...>.useNewSpliterator(true).build())",
+                new Throwable("YdbLegacySpliterator construction stack trace"));
         this.action = action;
         flags = (isOrdered ? ORDERED : 0) | NONNULL;
     }

diff --git a/repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/table/BatchFindSpliterator.java b/repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/table/BatchFindSpliterator.java
@@ -46,7 +46,7 @@ abstract class BatchFindSpliterator<R, T extends Entity<T>, ID extends Entity.Id
         );
         this.top = YqlLimit.top(batchSize);
         if (partial != null) {
-            Range<ID> range = new Range<>(partial);
+            Range<ID> range = Range.create(partial);
             Map<String, Object> eqMap = range.getEqMap();
             this.initialPartialPredicates = this.idSchema
                     .flattenFields().stream()

diff --git a/repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/yql/YqlPredicate.java b/repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/yql/YqlPredicate.java
@@ -5,6 +5,8 @@
 import lombok.AllArgsConstructor;
 import lombok.NonNull;
 import lombok.RequiredArgsConstructor;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import tech.ydb.yoj.repository.db.Entity;
 import tech.ydb.yoj.repository.db.EntitySchema;
 import tech.ydb.yoj.repository.ydb.statement.PredicateStatement;
@@ -52,15 +54,28 @@
  */
 public abstract class YqlPredicate implements YqlStatementPart<YqlPredicate> {
     public static final String TYPE = "Predicate";
+    private static final Logger log = LoggerFactory.getLogger(YqlPredicate.class);
     private static final AtomicBoolean useLegacyIn = new AtomicBoolean(false);
     private static final AtomicBoolean useLegacyRel = new AtomicBoolean(false);
 
-    public static void setUseLegacyIn(boolean useLegacyIn) {
-        YqlPredicate.useLegacyIn.set(useLegacyIn);
+    /**
+     * @deprecated This method will be removed in YOJ 3.0.0. There is no alternative, just stop calling it.
+     */
+    @Deprecated(forRemoval = true)
+    public static void setUseLegacyIn(boolean value) {
+        log.error("You are using YqlPredicate.setUseLegacyIn(boolean) which is deprecated for removal in YOJ 3.0.0. Please stop calling this method",
+                new Throwable("YqlPredicate.setUseLegacyIn(boolean) call stack trace"));
+        YqlPredicate.useLegacyIn.set(value);
     }
 
-    public static void setUseLegacyRel(boolean useLegacyRel) {
-        YqlPredicate.useLegacyRel.set(useLegacyRel);
+    /**
+     * @deprecated This method will be removed in YOJ 3.0.0. There is no alternative, just stop calling it.
+     */
+    @Deprecated(forRemoval = true)
+    public static void setUseLegacyRel(boolean value) {
+        log.error("You are using YqlPredicate.setUseLegacyRel(boolean) which is deprecated for removal in YOJ 3.0.0. Please stop calling this method",
+                new Throwable("YqlPredicate.setUseLegacyRel(boolean) call stack trace"));
+        YqlPredicate.useLegacyRel.set(value);
     }
 
     public static FieldPredicateBuilder where(@NonNull String fieldPath) {
@@ -362,7 +377,6 @@ public String toString() {
         }
     }
 
-    @Deprecated(forRemoval = true)
     /*package*/ static final class RelPredicate<V> extends YqlPredicate {
         private final Rel rel;
         private final String fieldPath;
@@ -450,7 +464,10 @@ public final Rel negate() {
             return Rel.valueOf(negation);
         }
 
-        @Deprecated
+        /**
+         * @deprecated Will be removed in YOJ 3.0.0 because combining relational predicates is no longer needed.
+         */
+        @Deprecated(forRemoval = true)
         public final String combine(String result, String element) {
             return result == null ? element : exprCombiner.apply(result, element);
         }
@@ -556,7 +573,7 @@ public Type negate() {
     }
 
     @AllArgsConstructor(access = PRIVATE)
-    @Deprecated
+    @Deprecated(forRemoval = true)
     /*package*/ static final class InLegacyPredicate<V> extends YqlPredicate {
         private final YqlPredicateParam<Collection<V>> param;
         private final String fieldPath;

diff --git a/repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/yql/YqlPrimitiveType.java b/repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/yql/YqlPrimitiveType.java
@@ -339,18 +339,26 @@ private static void registerYqlType(
     }
 
     /**
-     * @deprecated Call {@link #useRecommendedMappingFor(FieldValueType[]) useNewMappingFor(STRING, ENUM)} instead.
+     * @deprecated This method will be removed in YOJ 3.0.0.
+     * Call {@link #useRecommendedMappingFor(FieldValueType[]) useNewMappingFor(STRING, ENUM)} instead.
      */
     @Deprecated(forRemoval = true)
     public static void changeStringDefaultTypeToUtf8() {
+        log.error("You are using YqlPrimitiveType.changeStringDefaultTypeToUtf8() which will be removed in YOJ 3.0.0. "
+                        + "Please use YqlPrimitiveType.useNewMappingFor(STRING, ENUM)",
+                new Throwable("YqlPrimitiveType.changeStringDefaultTypeToUtf8() call stack trace"));
         useRecommendedMappingFor(FieldValueType.STRING, FieldValueType.ENUM);
     }
 
     /**
-     * @deprecated This method has a misleading name. Call {@link #useLegacyMappingFor(FieldValueType[]) useLegacyMappingFor(STRING, ENUM)} instead.
+     * @deprecated This method has a misleading name and will be removed in YOJ 3.0.0.
+     * Call {@link #useLegacyMappingFor(FieldValueType[]) useLegacyMappingFor(STRING, ENUM)} instead.
      */
     @Deprecated(forRemoval = true)
     public static void resetStringDefaultTypeToDefaults() {
+        log.error("You are using YqlPrimitiveType.resetStringDefaultTypeToDefaults() which will be removed in YOJ 3.0.0. "
+                + "Please use YqlPrimitiveType.useLegacyMappingFor(STRING, ENUM)",
+                new Throwable("YqlPrimitiveType.resetStringDefaultTypeToDefaults() call stack trace"));
         useLegacyMappingFor(FieldValueType.STRING, FieldValueType.ENUM);
     }
 
@@ -406,14 +414,16 @@ public static void useRecommendedMappingFor(FieldValueType... fieldValueTypes) {
     }
 
     /**
-     * @deprecated Nothing in YOJ calls {@code YqlPrimitiveType.of(Type)} any more.
+     * @deprecated This method will be removed in YOJ 3.0.0. Nothing in YOJ calls {@code YqlPrimitiveType.of(Type)} any more.
      * <p>Please use {@link #of(JavaField) YqlPrimitiveType.of(JavaField)} because it correcly
      * respects the customizations specified in the {@link Column &#64;Column} and
      * {@link CustomValueType &#64;CustomValueType} annotations.
      */
     @NonNull
     @Deprecated(forRemoval = true)
     public static YqlPrimitiveType of(Type javaType) {
+        log.error("You are using YqlPrimitiveType.of(Type) which will be removed in YOJ 3.0.0. Please use YqlPrimitiveType.of(JavaField) instead",
+                new Throwable("YqlPrimitiveType.of(Type) call stack trace"));
         var valueType = FieldValueType.forJavaType(javaType, null, null);
         return resolveYqlType(javaType, valueType, null, null);
     }