From df541d3c74133496454dd9bfccc404b54a0faea6 Mon Sep 17 00:00:00 2001 From: "Kim, Joo Hyuk" Date: Sat, 6 May 2023 12:32:13 +0900 Subject: [PATCH] Improve and fix JavaDocs for Jackson 2.15 (#3917) --- .../databind/AnnotationIntrospector.java | 4 ++-- .../jackson/databind/MapperFeature.java | 7 ++++++- .../jackson/databind/ObjectMapper.java | 2 +- .../jackson/databind/SerializerProvider.java | 18 +++++++----------- .../deser/std/CollectionDeserializer.java | 4 ++-- .../databind/introspect/AnnotatedClass.java | 3 +-- .../util/internal/PrivateMaxEntriesMap.java | 4 ++-- .../dos/StreamReadStringConstraintsTest.java | 2 +- .../TestPolymorphicDeserialization676.java | 2 +- 9 files changed, 23 insertions(+), 23 deletions(-) diff --git a/src/main/java/com/fasterxml/jackson/databind/AnnotationIntrospector.java b/src/main/java/com/fasterxml/jackson/databind/AnnotationIntrospector.java index 2905a9beac..53d5bc9838 100644 --- a/src/main/java/com/fasterxml/jackson/databind/AnnotationIntrospector.java +++ b/src/main/java/com/fasterxml/jackson/databind/AnnotationIntrospector.java @@ -59,7 +59,7 @@ public enum Type { * Usually this can be defined by using * {@link com.fasterxml.jackson.annotation.JsonManagedReference} */ - MANAGED_REFERENCE + MANAGED_REFERENCE, /** * Reference property that Jackson manages by suppressing it during serialization, @@ -67,7 +67,7 @@ public enum Type { * Usually this can be defined by using * {@link com.fasterxml.jackson.annotation.JsonBackReference} */ - ,BACK_REFERENCE + BACK_REFERENCE ; } diff --git a/src/main/java/com/fasterxml/jackson/databind/MapperFeature.java b/src/main/java/com/fasterxml/jackson/databind/MapperFeature.java index 2ecf7ee450..2d73fc3fb9 100644 --- a/src/main/java/com/fasterxml/jackson/databind/MapperFeature.java +++ b/src/main/java/com/fasterxml/jackson/databind/MapperFeature.java @@ -322,7 +322,7 @@ public enum MapperFeature implements ConfigFeature * Feature is enabled by default which means that deserialization does * support deserializing types via builders with type parameters (generic types). *

- * See: https://github.com/FasterXML/jackson-databind/issues/921 + * See: databind#921 * * @since 2.12 */ @@ -401,6 +401,11 @@ public enum MapperFeature implements ConfigFeature *

* Note: does not apply to {@link java.util.Map} serialization (since * entries are not considered Bean/POJO properties. + *

+ * WARNING: Disabling it may have a negative impact on deserialization performance. + * When disabled, all properties before the last creator property in the input need to be buffered, + * since all creator properties are required to create the instance. + * Enabling this feature ensures that there is as little buffering as possible. *

* Feature is enabled by default. * diff --git a/src/main/java/com/fasterxml/jackson/databind/ObjectMapper.java b/src/main/java/com/fasterxml/jackson/databind/ObjectMapper.java index 7c92f52dab..0ce19c8689 100644 --- a/src/main/java/com/fasterxml/jackson/databind/ObjectMapper.java +++ b/src/main/java/com/fasterxml/jackson/databind/ObjectMapper.java @@ -4623,7 +4623,7 @@ public T updateValue(T valueToUpdate, Object overrides) * @param t The class to generate schema for * @return Constructed JSON schema. * - * @deprecated Since 2.6 use external JSON Schema generator (https://github.com/FasterXML/jackson-module-jsonSchema) + * @deprecated Since 2.6 use external JSON Schema generator (jackson-module-jsonSchema) * (which under the hood calls {@link #acceptJsonFormatVisitor(JavaType, JsonFormatVisitorWrapper)}) */ @Deprecated diff --git a/src/main/java/com/fasterxml/jackson/databind/SerializerProvider.java b/src/main/java/com/fasterxml/jackson/databind/SerializerProvider.java index c48639927f..7ad51f1b8c 100644 --- a/src/main/java/com/fasterxml/jackson/databind/SerializerProvider.java +++ b/src/main/java/com/fasterxml/jackson/databind/SerializerProvider.java @@ -947,19 +947,15 @@ public JsonSerializer getDefaultNullValueSerializer() { } /** - * Method called to get the serializer to use for serializing - * Map keys that are nulls: this is needed since JSON does not allow - * any non-String value as key, including null. - *

- * Typically, returned serializer - * will either throw an exception, or use an empty String; but - * other behaviors are possible. - */ - /** - * Method called to find a serializer to use for null values for given - * declared type. Note that type is completely based on declared type, + * Method called to find a serializer to serializes Map keys that are nulls, + * as JSON does not allow any non-String value as a key, including null. + * Note that type is completely based on declared type, * since nulls in Java have no type and thus runtime type cannot be * determined. + * + * @return JsonSerializer that handles the serialization of null keys, + * usually by throwing an exception or using an empty String, + * but other behaviors are also possible. * * @since 2.0 */ diff --git a/src/main/java/com/fasterxml/jackson/databind/deser/std/CollectionDeserializer.java b/src/main/java/com/fasterxml/jackson/databind/deser/std/CollectionDeserializer.java index 15175767d4..76c07a661f 100644 --- a/src/main/java/com/fasterxml/jackson/databind/deser/std/CollectionDeserializer.java +++ b/src/main/java/com/fasterxml/jackson/databind/deser/std/CollectionDeserializer.java @@ -529,8 +529,8 @@ public void resolveForwardReference(Object id, Object value) throws IOException /** * Helper class to maintain processing order of value. The resolved - * object associated with {@link #_id} comes before the values in - * {@link #next}. + * object associated with {@code #id} parameter from {@link #handleResolvedForwardReference(Object, Object)} + * comes before the values in {@link #next}. */ private final static class CollectionReferring extends Referring { private final CollectionReferringAccumulator _parent; diff --git a/src/main/java/com/fasterxml/jackson/databind/introspect/AnnotatedClass.java b/src/main/java/com/fasterxml/jackson/databind/introspect/AnnotatedClass.java index 24e850315b..c184c80701 100644 --- a/src/main/java/com/fasterxml/jackson/databind/introspect/AnnotatedClass.java +++ b/src/main/java/com/fasterxml/jackson/databind/introspect/AnnotatedClass.java @@ -202,8 +202,7 @@ public static AnnotatedClass construct(JavaType type, MapperConfig config, * Method similar to {@link #construct}, but that will NOT include * information from supertypes; only class itself and any direct * mix-ins it may have. - */ - /** + * * @deprecated Since 2.9, use methods in {@link AnnotatedClassResolver} instead. */ @Deprecated diff --git a/src/main/java/com/fasterxml/jackson/databind/util/internal/PrivateMaxEntriesMap.java b/src/main/java/com/fasterxml/jackson/databind/util/internal/PrivateMaxEntriesMap.java index 4cd867afdd..d74b89aa0b 100644 --- a/src/main/java/com/fasterxml/jackson/databind/util/internal/PrivateMaxEntriesMap.java +++ b/src/main/java/com/fasterxml/jackson/databind/util/internal/PrivateMaxEntriesMap.java @@ -136,7 +136,7 @@ public final class PrivateMaxEntriesMap extends AbstractMap /** * The number of read buffers to use. - * The max of 4 was introduced due to https://github.com/FasterXML/jackson-databind/issues/3665. + * The max of 4 was introduced due to databind#3665. */ static final int NUMBER_OF_READ_BUFFERS = Math.min(4, ceilingNextPowerOfTwo(NCPU)); @@ -145,7 +145,7 @@ public final class PrivateMaxEntriesMap extends AbstractMap /** * The number of pending read operations before attempting to drain. - * The threshold of 4 was introduced due to https://github.com/FasterXML/jackson-databind/issues/3665. + * The threshold of 4 was introduced due to databind#3665. */ static final int READ_BUFFER_THRESHOLD = 4; diff --git a/src/test/java/com/fasterxml/jackson/databind/deser/dos/StreamReadStringConstraintsTest.java b/src/test/java/com/fasterxml/jackson/databind/deser/dos/StreamReadStringConstraintsTest.java index eea77178f3..2e607e1b4f 100644 --- a/src/test/java/com/fasterxml/jackson/databind/deser/dos/StreamReadStringConstraintsTest.java +++ b/src/test/java/com/fasterxml/jackson/databind/deser/dos/StreamReadStringConstraintsTest.java @@ -9,7 +9,7 @@ import com.fasterxml.jackson.databind.json.JsonMapper; /** - * Tests for {@a href="https://github.com/FasterXML/jackson-core/issues/863"}. + * Tests for databind#863" */ public class StreamReadStringConstraintsTest extends BaseMapTest { diff --git a/src/test/java/com/fasterxml/jackson/databind/jsontype/TestPolymorphicDeserialization676.java b/src/test/java/com/fasterxml/jackson/databind/jsontype/TestPolymorphicDeserialization676.java index d6b1bcc557..063e4bf594 100644 --- a/src/test/java/com/fasterxml/jackson/databind/jsontype/TestPolymorphicDeserialization676.java +++ b/src/test/java/com/fasterxml/jackson/databind/jsontype/TestPolymorphicDeserialization676.java @@ -8,7 +8,7 @@ import java.util.*; /** - * Reproduction of [https://github.com/FasterXML/jackson-databind/issues/676] + * Reproduction of databind#676 *

* Deserialization of class with generic collection inside * depends on how is was deserialized first time.