Merge branch '2.12'

Author: cowtowncoder

release-notes/VERSION-2.x

@@ -21,6 +21,8 @@ JSON library.
 #619: Add `StreamReadCapability` for further format-based/format-agnostic
   handling improvements
 #627: Add `JsonParser.isExpectedNumberIntToken()` convenience method
+#630: Add `StreamWriteCapability` for further format-based/format-agnostic
+  handling improvements
 - Deprecate `JsonParser.getCurrentTokenId()` (use `#currentTokenId()` instead)
 
 2.11.1 (25-Jun-2020)

src/main/java/com/fasterxml/jackson/core/JsonGenerator.java

@@ -13,6 +13,7 @@
 import com.fasterxml.jackson.core.io.CharacterEscapes;
 import com.fasterxml.jackson.core.type.WritableTypeId;
 import com.fasterxml.jackson.core.type.WritableTypeId.Inclusion;
+import com.fasterxml.jackson.core.util.JacksonFeatureSet;
 import com.fasterxml.jackson.core.util.VersionUtil;
 
 import static com.fasterxml.jackson.core.JsonTokenId.*;
@@ -285,6 +286,16 @@ protected JsonGenerator() { }
      */
     public boolean canWriteFormattedNumbers() { return false; }
 
+    /**
+     * Accessor for getting metadata on capabilities of this parser, based on
+     * underlying data format being read (directly or indirectly).
+     *
+     * @return Set of read capabilities for content to read via this parser
+     *
+     * @since 2.12
+     */
+    public abstract JacksonFeatureSet<StreamWriteCapability> getWriteCapabilities();
+
     /*
     /**********************************************************************
     /* Public API, write methods, structural

src/main/java/com/fasterxml/jackson/core/StreamWriteCapability.java

@@ -0,0 +1,55 @@
+package com.fasterxml.jackson.core;
+
+import com.fasterxml.jackson.core.util.JacksonFeature;
+
+/**
+ * Set of on/off capabilities that a {@link JsonGenerator} for given format
+ * (or in case of buffering, original format) has.
+ * Used in some cases to adjust aspects of things like content conversions and
+ * coercions by format-agnostic functionality.
+ * Specific or expected usage documented by individual capability entry Javadocs.
+ *
+ * @since 2.12
+ */
+public enum StreamWriteCapability
+    implements JacksonFeature
+{
+    /**
+     * Capability that indicates that the data format is able to express binary
+     * data natively, without using textual encoding like Base64.
+     *<p>
+     * Capability is currently enabled for all binary formats and none of textual
+     * formats.
+     */
+    CAN_WRITE_BINARY_NATIVELY(false),
+
+    /**
+     * Capability that indicates that the data format is able to write
+     * "formatted numbers": that is, output of numbers is done as Strings
+     * and caller is allowed to pass in logical number values as Strings.
+     *<p>
+     * Capability is currently enabled for most textual formats and none of binary
+     * formats.
+     */
+    CAN_WRITE_FORMATTED_NUMBERS(false)
+    ;
+
+    /**
+     * Whether feature is enabled or disabled by default.
+     */
+    private final boolean _defaultState;
+
+    private final int _mask;
+
+    private StreamWriteCapability(boolean defaultState) {
+        _defaultState = defaultState;
+        _mask = (1 << ordinal());
+    }
+
+    @Override
+    public boolean enabledByDefault() { return _defaultState; }
+    @Override
+    public boolean enabledIn(int flags) { return (flags & _mask) != 0; }
+    @Override
+    public int getMask() { return _mask; }
+}

src/main/java/com/fasterxml/jackson/core/base/GeneratorBase.java

@@ -2,6 +2,7 @@
 
 import com.fasterxml.jackson.core.*;
 import com.fasterxml.jackson.core.util.DefaultPrettyPrinter;
+import com.fasterxml.jackson.core.util.JacksonFeatureSet;
 
 import java.io.IOException;
 import java.io.InputStream;
@@ -35,7 +36,35 @@ public abstract class GeneratorBase extends JsonGenerator
      * huge "plain" serialization. See [core#315] for details.
      */
     protected final static int MAX_BIG_DECIMAL_SCALE = 9999;
-    
+
+    /*
+    /**********************************************************************
+    /* Default capabilities
+    /**********************************************************************
+     */
+
+    /**
+     * Default set of {@link StreamReadCapability}ies that may be used as
+     * basis for format-specific readers (or as bogus instance if non-null
+     * set needs to be passed).
+     */
+    protected final static JacksonFeatureSet<StreamWriteCapability> DEFAULT_WRITE_CAPABILITIES
+        = JacksonFeatureSet.fromDefaults(StreamWriteCapability.values());
+
+    /**
+     * Default set of {@link StreamReadCapability}ies for typical textual formats,
+     * to use either as-is, or as a base with possible differences.
+     */
+    protected final static JacksonFeatureSet<StreamWriteCapability> DEFAULT_TEXTUAL_WRITE_CAPABILITIES
+        = DEFAULT_WRITE_CAPABILITIES.with(StreamWriteCapability.CAN_WRITE_FORMATTED_NUMBERS);
+
+    /**
+     * Default set of {@link StreamReadCapability}ies for typical binary formats,
+     * to use either as-is, or as a base with possible differences.
+     */
+    protected final static JacksonFeatureSet<StreamWriteCapability> DEFAULT_BINARY_WRITE_CAPABILITIES
+        = DEFAULT_WRITE_CAPABILITIES.with(StreamWriteCapability.CAN_WRITE_BINARY_NATIVELY);
+
     /*
     /**********************************************************************
     /* Configuration

src/main/java/com/fasterxml/jackson/core/json/JsonGeneratorBase.java

@@ -7,6 +7,7 @@
 import com.fasterxml.jackson.core.io.CharTypes;
 import com.fasterxml.jackson.core.io.CharacterEscapes;
 import com.fasterxml.jackson.core.io.IOContext;
+import com.fasterxml.jackson.core.util.JacksonFeatureSet;
 
 /**
  * Intermediate base class shared by JSON-backed generators
@@ -156,14 +157,19 @@ public JsonGeneratorBase(ObjectWriteContext writeCtxt, IOContext ctxt,
 
     /*
     /**********************************************************************
-    /* Versioned, accessors
+    /* Versioned, accessors, capabilities
     /**********************************************************************
      */
 
     @Override public Version version() { return PackageVersion.VERSION; }
 
     public boolean isEnabled(JsonWriteFeature f) { return f.enabledIn(_formatWriteFeatures); }
-    
+
+    @Override
+    public JacksonFeatureSet<StreamWriteCapability> getWriteCapabilities() {
+        return DEFAULT_WRITE_CAPABILITIES;
+    }
+
     /*
     /**********************************************************************
     /* Overridden configuration methods

src/main/java/com/fasterxml/jackson/core/util/JsonGeneratorDelegate.java

@@ -85,6 +85,11 @@ public void setCurrentValue(Object v) {
     @Override
     public boolean canWriteFormattedNumbers() { return delegate.canWriteFormattedNumbers(); }
 
+    @Override
+    public JacksonFeatureSet<StreamWriteCapability> getWriteCapabilities() {
+        return delegate.getWriteCapabilities();
+    }
+
     /*
     /**********************************************************************
     /* Public API, configuration