Merge branch '3.x' of github.com:FasterXML/jackson-core into 3.x

Author: cowtowncoder

release-notes/CREDITS

@@ -14,6 +14,11 @@ Sven Döring (@sdoeringNew)
  * Contributed #680: Allow use of `java.nio.file.Path` as parser source, generator target
   (3.0.0)
 
+@sri-adarsh-kumar
+ * Contributed #1288: Add new method like `JsonParser.readText(Writer)` (and
+   implementation) for truly non-buffering reads
+  (3.1.0)
+
 Nicholas Rayburn (@nrayburn-tech)
  * Contributed #1514: Additional configuration to closer match Jackson 2 behavior
   (3.1.0)

release-notes/VERSION

@@ -17,6 +17,9 @@ JSON library.
 
 3.1.0 (not yet released)
 
+#1288: Add new method like `JsonParser.readText(Writer)` (and
+  implementation) for truly non-buffering reads
+ (contributed by @sri-adarsh-kumar)
 #1548: `StreamReadConstraints.maxDocumentLength` not checked when
   creating parser with fixed buffer
 #1553: Max Depth validation not working for `DataInput`-backed `JsonParser`s

src/main/java/tools/jackson/core/JsonParser.java

@@ -884,8 +884,9 @@ public Boolean nextBooleanValue() throws JacksonException {
      * other {@code getString()} calls (that is, it will not be consumed).
      * So this accessor only avoids construction of {@link java.lang.String}
      * compared to plain {@link #getString()} method.
+     * Note there is method {@link #readString(Writer)} that may avoid buffering.
      *<p>
-     * NOTE: In Jackson 2.x this method was called {@code getString(Writer)}.
+     * NOTE: In Jackson 2.x this method was called {@code getText(Writer)}.
      *
      * @param writer Writer to write String value to
      *
@@ -896,6 +897,58 @@ public Boolean nextBooleanValue() throws JacksonException {
      */
     public abstract int getString(Writer writer) throws JacksonException;
 
+    /**
+     * Method to read the textual representation of the current {@link JsonToken#VALUE_STRING}
+     * token in chunks and stream it directly to the given Writer, without buffering the entire
+     * String value in memory. Functionally same as calling:
+     *<pre>
+     *  writer.write(parser.getString());
+     *</pre>
+     * but tries to stream the decoded content directly without storing it in {@link TextBuffer},
+     * making it suitable for arbitrarily large strings without memory constraints.
+     *<p>
+     * NOTE: whether streaming happens depends on format-specific implementation of
+     * this method -- the default implementation delegates to
+     * {@link #getString(Writer)} which does not stream content.
+     *<p>
+     * NOTE: This method <b>consumes</b> the contents of the {@link JsonToken#VALUE_STRING}
+     * token, advancing the parser state so that the underlying String value is <b>no longer
+     * available</b> via {@link #getString()} or other {@code getString*} accessors after
+     * this method completes. This differs from {@link #getString(Writer)} which preserves
+     * the buffered string for subsequent access.
+     *<p>
+     * NOTE: This method is primarily intended for very large JSON string values (megabytes
+     * or larger) where full buffering would be prohibitive. For typical string sizes, prefer
+     * {@link #getString()} or {@link #getString(Writer)} which provide more convenient access.
+     * The implementation uses an intermediate buffer for efficient bulk writes
+     * to the Writer.
+     *<p>
+     * NOTE: This method <b>does</b> enforce
+     * {@link tools.jackson.core.StreamReadConstraints#getMaxStringLength()} validation during
+     * streaming, checking the string length at buffer boundaries and at completion. Strings
+     * exceeding the configured limit will result in a {@link tools.jackson.core.exc.StreamConstraintsException}.
+     *<p>
+     * NOTE: This method is <b>NOT supported</b> by non-blocking (async) parsers and will
+     * throw {@link UnsupportedOperationException} if called on such parsers, since content
+     * availability is unpredictable in asynchronous parsing mode.
+     *
+     * @param writer Writer to stream the String value to
+     *
+     * @return The number of characters written to the Writer (as {@code long} to support
+     *         strings exceeding {@code Integer.MAX_VALUE})
+     *
+     * @throws JacksonIOException for low-level read issues, or failed write using {@link Writer}
+     * @throws tools.jackson.core.exc.StreamReadException for decoding problems
+     * @throws tools.jackson.core.exc.StreamConstraintsException if string length exceeds
+     *         {@link tools.jackson.core.StreamReadConstraints#getMaxStringLength()}
+     *
+     * @since 3.1
+     */
+    public long readString(Writer writer) throws JacksonException {
+        // Default implementation simply buffers it all
+        return getString(writer);
+    }
+
     /**
      * Method similar to {@link #getString()}, but that will return
      * underlying (unmodifiable) character array that contains

src/main/java/tools/jackson/core/StreamReadConstraints.java

@@ -226,6 +226,9 @@ public Builder maxNumberLength(final int maxNumLen) {
          *<p>
          * NOTE: Jackson 2.15.0 initially used a lower setting ({@code 5,000,000}); and versions
          * up to 3.0 {@code 20,000,000}.
+         * Jackson 3.1 further raised this to {@code 100,000,000}.
+         *<p>
+         * NOTE: Setting this to {@link Integer#MAX_VALUE} effectively <b>DISABLES</b> limit.
          *
          * @param maxStringLen the maximum string length (in chars or bytes, depending on input context)
          *
@@ -575,6 +578,27 @@ public void validateStringLength(int length) throws StreamConstraintsException
         }
     }
 
+    /**
+     * Variant of {@link #validateStringLength} but takes {@code long} instead
+     * {@code int}.
+     *<p>
+     * NOTE: value of {@link Integer#MAX_VALUE} is considered special value
+     * meaning "no limit".
+     *
+     * @param length Length to validate against limit
+     *
+     * @throws StreamConstraintsException
+     */
+    public void validateStringLengthLong(long length) throws StreamConstraintsException
+    {
+        if (length > _maxStringLen && _maxStringLen != Integer.MAX_VALUE) {
+            throw _constructException(
+                    "String value length (%d) exceeds the maximum allowed (%d, from %s)",
+                    length, _maxStringLen,
+                    _constrainRef("getMaxStringLength"));
+        }
+    }
+
     /**
      * Convenience method that can be used to verify that a name
      * of specified length does not exceed maximum specific by this

src/main/java/tools/jackson/core/json/JsonParserBase.java

@@ -69,14 +69,26 @@ public abstract class JsonParserBase
      */
     protected boolean _nameCopied;
 
+    /**
+     * Lazily-allocated intermediate buffer used by {@code _streamString()}
+     * implementations to batch writes to the target {@link java.io.Writer}.
+     * Allocated on first call and reused on subsequent calls to avoid
+     * repeated allocation for parsers that call {@code readString(Writer)}
+     * multiple times.
+     *
+     * @since 3.1
+     */
+    private char[] _streamStringBuffer;
+
     /*
     /**********************************************************************
     /* Life-cycle
     /**********************************************************************
      */
 
     protected JsonParserBase(ObjectReadContext readCtxt,
-            IOContext ctxt, int streamReadFeatures, int formatReadFeatures) {
+            IOContext ctxt, int streamReadFeatures, int formatReadFeatures)
+    {
         super(readCtxt, ctxt, streamReadFeatures);
         _formatReadFeatures = formatReadFeatures;
         DupDetector dups = StreamReadFeature.STRICT_DUPLICATE_DETECTION.enabledIn(streamReadFeatures)
@@ -339,6 +351,21 @@ protected char[] currentNameInBuffer() {
         return _nameCopyBuffer;
     }
 
+    /**
+     * Returns the lazily-allocated intermediate buffer used by
+     * {@code _streamString()} to batch-write decoded characters to a
+     * {@link java.io.Writer}. The same buffer is reused across calls.
+     *
+     * @since 3.1
+     */
+    protected char[] _bufferForStringStreaming() {
+        char[] buf = _streamStringBuffer;
+        if (buf == null) {
+            _streamStringBuffer = buf = new char[1024];
+        }
+        return buf;
+    }
+    
     /*
     /**********************************************************************
     /* Internal/package methods: Error reporting

src/main/java/tools/jackson/core/json/ReaderBasedJsonParser.java

@@ -47,7 +47,7 @@ public class ReaderBasedJsonParser
     protected char[] _inputBuffer;
 
     /**
-     * Flag that indicates whether the input buffer is recycable (and
+     * Flag that indicates whether the input buffer is recyclable (and
      * needs to be returned to recycler once we are done) or not.
      *<p>
      * If it is not, it also means that parser CANNOT modify underlying
@@ -338,6 +338,24 @@ public int getString(Writer writer) throws JacksonException
         return 0;
     }
 
+    @Override
+    public long readString(Writer writer) throws JacksonException
+    {
+        if (_currToken == JsonToken.VALUE_STRING) {
+            try {
+                if (_tokenIncomplete) {
+                    return _streamString(writer);
+                }
+                long len = _textBuffer.contentsToWriter(writer);
+                _textBuffer.resetWithEmpty();
+                return len;
+            } catch (IOException e) {
+                throw _wrapIOFailure(e);
+            }
+        }
+        return getString(writer);
+    }
+
     // // // Let's override default impls for improved performance
 
     @Override
@@ -2268,6 +2286,89 @@ protected final void _skipString() throws JacksonException
         }
     }
 
+    // @since 3.1
+    private long _streamString(Writer writer)
+        throws IOException, JacksonException
+    {
+        _tokenIncomplete = false;
+
+        long totalLen = 0;
+        int inPtr = _inputPtr;
+        int inLen = _inputEnd;
+        char[] inBuf = _inputBuffer;
+        final long maxStringLen = _streamReadConstraints.getMaxStringLength();
+
+        // Intermediate buffer for bulk writes to improve performance (reused across calls)
+        char[] outBuf = _bufferForStringStreaming();
+        int outPtr = 0;
+
+        while (true) {
+            // Flush intermediate buffer when full
+            if (outPtr >= outBuf.length) {
+                writer.write(outBuf, 0, outPtr);
+                totalLen += outPtr;
+                outPtr = 0;
+                // Check constraints only at flush boundaries
+                if (totalLen > maxStringLen) {
+                    _streamReadConstraints.validateStringLengthLong(totalLen);
+                }
+            }
+
+            if (inPtr >= inLen) {
+                // Flush intermediate buffer before loading more
+                if (outPtr > 0) {
+                    writer.write(outBuf, 0, outPtr);
+                    totalLen += outPtr;
+                    outPtr = 0;
+                    // Check constraints at input buffer boundary
+                    if (totalLen > maxStringLen) {
+                        _streamReadConstraints.validateStringLengthLong(totalLen);
+                    }
+                }
+                _inputPtr = inPtr;
+                if (!_loadMore()) {
+                    _reportInvalidEOF(": was expecting closing quote for a string value",
+                            JsonToken.VALUE_STRING);
+                }
+                inPtr = _inputPtr;
+                inLen = _inputEnd;
+            }
+            char c = inBuf[inPtr++];
+            int i = c;
+            if (i <= INT_BACKSLASH) {
+                if (i == INT_BACKSLASH) {
+                    _inputPtr = inPtr;
+                    c = _decodeEscaped();
+                    inPtr = _inputPtr;
+                    inLen = _inputEnd;
+                } else if (i <= INT_QUOTE) {
+                    if (i == INT_QUOTE) {
+                        _inputPtr = inPtr;
+                        break;
+                    }
+                    if (i < INT_SPACE) {
+                        _inputPtr = inPtr;
+                        _throwUnquotedSpace(i, "string value");
+                    }
+                }
+            }
+            // Accumulate character in intermediate buffer
+            outBuf[outPtr++] = c;
+        }
+
+        // Final flush of remaining characters
+        if (outPtr > 0) {
+            writer.write(outBuf, 0, outPtr);
+            totalLen += outPtr;
+            // Validate final string length
+            if (totalLen > maxStringLen) {
+                _streamReadConstraints.validateStringLengthLong(totalLen);
+            }
+        }
+        _textBuffer.resetWithEmpty();
+        return totalLen;
+    }
+
     /*
     /**********************************************************************
     /* Internal methods, other parsing