Fix #2025

Author: cowtowncoder

src/main/java/com/fasterxml/jackson/databind/jsontype/TypeSerializer.java

@@ -18,7 +18,9 @@
  *<p>
  * NOTE: version 2.9 contains significant attempt at simplifying interface,
  * as well as giving format implementation (via {@link JsonGenerator}) more
- * control over actual serialization details.
+ * control over actual serialization details. Minor changes are required to change
+ * call pattern so that return value of "prefix" write needs to be passed to "suffix"
+ * write.
  */
 public abstract class TypeSerializer
 {
@@ -119,6 +121,12 @@ public WritableTypeId typeId(Object value, Class<?> typeForId,
      * Method called to write initial part of type information for given
      * value, along with possible wrapping to use: details are specified
      * by `typeId` argument.
+     * Note that for structured types (Object, Array), this call will add
+     * necessary start token so it should NOT be explicitly written, unlike
+     * with non-type-id value writes.
+     *<p>
+     * See {@link #writeTypeSuffix(JsonGenerator, WritableTypeId)} for a complete
+     * example of typical usage.
      *
      * @param g Generator to use for outputting type id and possible wrapping
      * @param typeId Details of what type id is to be written, how.
@@ -129,6 +137,25 @@ public abstract WritableTypeId writeTypePrefix(JsonGenerator g,
             WritableTypeId typeId) throws IOException;
 
     /**
+     * Method that should be called after {@link #writeTypePrefix(JsonGenerator, WritableTypeId)}
+     * and matching value write have called, passing {@link WritableTypeId} returned.
+     * Usual idiom is:
+     *<pre>
+     * // Indicator generator that type identifier may be needed; generator may write
+     * // one as suggested, modify information, or take some other action 
+     * // NOTE! For Object/Array types, this will ALSO write start marker!
+     * WritableTypeId typeIdDef = typeSer.writeTypePrefix(gen,
+     *          typeSer.typeId(value, JsonToken.START_OBJECT));
+     *
+     * // serializing actual value for which TypeId may have been written... like
+     * // NOTE: do NOT write START_OBJECT before OR END_OBJECT after:
+     * g.writeStringField("message", "Hello, world!"
+     *
+     * // matching type suffix call to let generator chance to add suffix, if any
+     * // NOTE! For Object/Array types, this will ALSO write end marker!
+     * typeSer.writeTypeSuffix(gen, typeIdDef);
+     *</pre>
+     *
      * @since 2.9
      */
     public abstract WritableTypeId writeTypeSuffix(JsonGenerator g,
@@ -141,110 +168,107 @@ public abstract WritableTypeId writeTypeSuffix(JsonGenerator g,
      */
 
     /**
-     * Method called to write initial part of type information for given
-     * value, when it will be output as scalar JSON value (not as JSON
-     * Object or Array).
-     * This means that the context after call cannot be that of JSON Object;
-     * it may be Array or root context.
-     * 
-     * @param value Value that will be serialized, for which type information is
-     *   to be written
-     * @param g Generator to use for writing type information
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypePrefix(g, typeId(value, JsonToken.VALUE_STRING));}.
+     * See {@link #writeTypePrefix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypePrefix(JsonGenerator, WritableTypeId) instead
      */
     @Deprecated // since 2.9
     public void writeTypePrefixForScalar(Object value, JsonGenerator g) throws IOException {
         writeTypePrefix(g, typeId(value, JsonToken.VALUE_STRING));
     }
 
     /**
-     * Method called to write initial part of type information for given
-     * value, when it will be output as JSON Object value (not as JSON
-     * Array or scalar).
-     * This means that context after call must be JSON Object, meaning that
-     * caller can then proceed to output field entries.
-     * 
-     * @param value Value that will be serialized, for which type information is
-     *   to be written
-     * @param g Generator to use for writing type information
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypePrefix(g, typeId(value, JsonToken.START_OBJECT));}.
+     * See {@link #writeTypePrefix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypePrefix(JsonGenerator, WritableTypeId) instead
      */
     @Deprecated // since 2.9
     public void writeTypePrefixForObject(Object value, JsonGenerator g) throws IOException {
         writeTypePrefix(g, typeId(value, JsonToken.START_OBJECT));
     }
 
     /**
-     * Method called to write initial part of type information for given
-     * value, when it will be output as JSON Array value (not as JSON
-     * Object or scalar).
-     * This means that context after call must be JSON Array, that is, there
-     * must be an open START_ARRAY to write contents in.
-     * 
-     * @param value Value that will be serialized, for which type information is
-     *   to be written
-     * @param g Generator to use for writing type information
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypePrefix(g, typeId(value, JsonToken.START_ARRAY));}.
+     * See {@link #writeTypePrefix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypePrefix(JsonGenerator, WritableTypeId) instead
      */
     @Deprecated // since 2.9
     public void writeTypePrefixForArray(Object value, JsonGenerator g) throws IOException {
         writeTypePrefix(g, typeId(value, JsonToken.START_ARRAY));
     }
 
     /**
-     * Method called after value has been serialized, to close any scopes opened
-     * by earlier matching call to {@link #writeTypePrefixForScalar}.
-     * Actual action to take may depend on various factors, but has to match with
-     * action {@link #writeTypePrefixForScalar} did (close array or object; or do nothing).
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypeSuffix(g, typeId(value, JsonToken.VALUE_STRING));}.
+     * See {@link #writeTypeSuffix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypeSuffix(JsonGenerator, WritableTypeId) instead
      */
     @Deprecated // since 2.9
     public void writeTypeSuffixForScalar(Object value, JsonGenerator g) throws IOException {
         _writeLegacySuffix(g, typeId(value, JsonToken.VALUE_STRING));
     }
 
     /**
-     * Method called after value has been serialized, to close any scopes opened
-     * by earlier matching call to {@link #writeTypePrefixForObject}.
-     * It needs to write closing END_OBJECT marker, and any other decoration
-     * that needs to be matched.
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypeSuffix(g, typeId(value, JsonToken.START_OBJECT));}.
+     * See {@link #writeTypeSuffix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypeSuffix(JsonGenerator, WritableTypeId) instead
      */
     @Deprecated // since 2.9
     public void writeTypeSuffixForObject(Object value, JsonGenerator g) throws IOException {
         _writeLegacySuffix(g, typeId(value, JsonToken.START_OBJECT));
     }
 
     /**
-     * Method called after value has been serialized, to close any scopes opened
-     * by earlier matching call to {@link #writeTypeSuffixForScalar}.
-     * It needs to write closing END_ARRAY marker, and any other decoration
-     * that needs to be matched.
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypeSuffix(g, typeId(value, JsonToken.START_ARRAY));}.
+     * See {@link #writeTypeSuffix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypeSuffix(JsonGenerator, WritableTypeId) instead
      */
     @Deprecated // since 2.9
     public void writeTypeSuffixForArray(Object value, JsonGenerator g) throws IOException {
         _writeLegacySuffix(g, typeId(value, JsonToken.START_ARRAY));
     }
 
     /**
-     * Alternative version of the prefix-for-scalar method, which is given
-     * actual type to use (instead of using exact type of the value); typically
-     * a super type of actual value type
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypePrefix(g, typeId(value, type, JsonToken.VALUE_STRING));}.
+     * See {@link #writeTypePrefix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypePrefix(JsonGenerator, WritableTypeId) instead
      */
     @Deprecated // since 2.9
     public void writeTypePrefixForScalar(Object value, JsonGenerator g, Class<?> type) throws IOException {
         writeTypePrefix(g, typeId(value, type, JsonToken.VALUE_STRING));
     }
 
     /**
-     * Alternative version of the prefix-for-object method, which is given
-     * actual type to use (instead of using exact type of the value); typically
-     * a super type of actual value type
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypePrefix(g, typeId(value, type, JsonToken.START_OBJECT));}.
+     * See {@link #writeTypePrefix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypePrefix(JsonGenerator, WritableTypeId) instead
      */
     @Deprecated // since 2.9
     public void writeTypePrefixForObject(Object value, JsonGenerator g, Class<?> type) throws IOException {
         writeTypePrefix(g, typeId(value, type, JsonToken.START_OBJECT));
     }
 
     /**
-     * Alternative version of the prefix-for-array method, which is given
-     * actual type to use (instead of using exact type of the value); typically
-     * a super type of actual value type
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypePrefix(g, typeId(value, type, JsonToken.START_ARRAY));}.
+     * See {@link #writeTypePrefix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypePrefix(JsonGenerator, WritableTypeId) instead
      */
     @Deprecated // since 2.9
     public void writeTypePrefixForArray(Object value, JsonGenerator g, Class<?> type) throws IOException {
@@ -257,31 +281,61 @@ public void writeTypePrefixForArray(Object value, JsonGenerator g, Class<?> type
     /**********************************************************
      */
 
+    /**
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypePrefix(g, typeId(value, JsonToken.VALUE_STRING, typeId));}.
+     * See {@link #writeTypePrefix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypePrefix(JsonGenerator, WritableTypeId) instead
+     */
     @Deprecated // since 2.9
     public void writeCustomTypePrefixForScalar(Object value, JsonGenerator g, String typeId) throws IOException {
         writeTypePrefix(g, typeId(value, JsonToken.VALUE_STRING, typeId));
     }
 
+    /**
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypePrefix(g, typeId(value, JsonToken.START_OBJECT, typeId));}.
+     * See {@link #writeTypePrefix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypePrefix(JsonGenerator, WritableTypeId) instead
+     */
     @Deprecated // since 2.9
     public void writeCustomTypePrefixForObject(Object value, JsonGenerator g, String typeId) throws IOException {
         writeTypePrefix(g, typeId(value, JsonToken.START_OBJECT, typeId));
     }
 
+    /**
+     * DEPRECATED: now equivalent to:
+     *{@code writeTypePrefix(g, typeId(value, JsonToken.START_ARRAY, typeId));}.
+     * See {@link #writeTypePrefix} for more info.
+     *
+     * @deprecated Since 2.9 use {@link #writeTypePrefix(JsonGenerator, WritableTypeId) instead
+     */
     @Deprecated // since 2.9
     public void writeCustomTypePrefixForArray(Object value, JsonGenerator g, String typeId) throws IOException {
         writeTypePrefix(g, typeId(value, JsonToken.START_ARRAY, typeId));
     }
 
+    /**
+     * @deprecated Since 2.9 use {@link #writeTypeSuffix(JsonGenerator, WritableTypeId) instead
+     */
     @Deprecated // since 2.9
     public void writeCustomTypeSuffixForScalar(Object value, JsonGenerator g, String typeId) throws IOException {
         _writeLegacySuffix(g, typeId(value, JsonToken.VALUE_STRING, typeId));
     }
 
+    /**
+     * @deprecated Since 2.9 use {@link #writeTypeSuffix(JsonGenerator, WritableTypeId) instead
+     */
     @Deprecated // since 2.9
     public void writeCustomTypeSuffixForObject(Object value, JsonGenerator g, String typeId) throws IOException {
         _writeLegacySuffix(g, typeId(value, JsonToken.START_OBJECT, typeId));
     }
 
+    /**
+     * @deprecated Since 2.9 use {@link #writeTypeSuffix(JsonGenerator, WritableTypeId) instead
+     */
     @Deprecated // since 2.9
     public void writeCustomTypeSuffixForArray(Object value, JsonGenerator g, String typeId) throws IOException {
         _writeLegacySuffix(g, typeId(value, JsonToken.START_ARRAY, typeId));