Merge branch 'master' into timestamp

.github/workflows/codeql-analysis.yml

@@ -37,11 +37,11 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@fdcae64e1484d349b3366718cdfef3d404390e85 # v2.22.1
+        uses: github/codeql-action/init@0116bc2df50751f9724a2e35ef1f24d22f90e4e1 # v2.22.3
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -52,7 +52,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@fdcae64e1484d349b3366718cdfef3d404390e85 # v2.22.1
+        uses: github/codeql-action/autobuild@0116bc2df50751f9724a2e35ef1f24d22f90e4e1 # v2.22.3
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -66,4 +66,4 @@ jobs:
       #   make release
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@fdcae64e1484d349b3366718cdfef3d404390e85 # v2.22.1
+        uses: github/codeql-action/analyze@0116bc2df50751f9724a2e35ef1f24d22f90e4e1 # v2.22.3

.github/workflows/ion-java-performance-regression-detector.yml

@@ -6,7 +6,7 @@ name: Ion Java performance regression detector
 on:
   pull_request:
     paths:
-      - 'src/*'
+      - 'src/**'
 
 permissions:
   contents: read
@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout ion-data-generator
-        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
         with:
           repository: amazon-ion/ion-data-generator
           ref: main
@@ -64,22 +64,25 @@ jobs:
           java-version: 11
 
       - name: Checkout ion-java-benchmark-cli
-        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
         with:
           repository: amazon-ion/ion-java-benchmark-cli
           ref: master
           path: ion-java-benchmark-cli
 
       - name: Checkout ion-java from the previous commit
-        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
         with:
           ref: ${{ github.base_ref }}
+          submodules: recursive
           path: baseline
 
       - name: Checkout ion-java from the new commit.
-        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
         with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
           ref: ${{ github.head_ref }}
+          submodules: recursive
           path: new
 
       - name: Download test Ion Data from artifacts
@@ -92,7 +95,7 @@ jobs:
       - name: Build ion-java from the base commit
         working-directory: baseline
         run: |
-          git submodule init && git submodule update && ./gradlew clean publishToMavenLocal
+          ./gradlew clean publishToMavenLocal
 
       - name: Benchmark ion-java from the base commit
         working-directory: ion-java-benchmark-cli
@@ -104,7 +107,7 @@ jobs:
       - name: Build ion-java from the new commit
         working-directory: new
         run: |
-          git submodule init && git submodule update && ./gradlew clean publishToMavenLocal
+          ./gradlew clean publishToMavenLocal
 
       - name: Benchmark ion-java from the new commit
         working-directory: ion-java-benchmark-cli

.github/workflows/ion-test-driver.yml

@@ -3,7 +3,7 @@ name: ion-test-driver
 on:
   pull_request:
     paths:
-      - 'src/*'
+      - 'src/**'
 
 permissions:
   contents: read
@@ -13,14 +13,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout ion-java
-        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # master
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # master
         with:
           repository: amazon-ion/ion-java
           ref: master
           path: ion-java
 
       - name: Checkout ion-test-driver
-        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # master
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # master
         with:
           repository: amazon-ion/ion-test-driver
           ref: master
@@ -80,7 +80,7 @@ jobs:
     needs: ion-test-driver
     if: ${{ failure() }}
     steps:
-      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # master
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # master
       - name: Open an issue
         uses: JasonEtco/create-an-issue@e27dddc79c92bc6e4562f268fffa5ed752639abd # v2.9.1
         env:

.github/workflows/main.yml

@@ -18,7 +18,7 @@ jobs:
             upload_reports: true
           - java: 17
     steps:
-      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
         with:
           submodules: recursive
       - uses: gradle/wrapper-validation-action@56b90f209b02bf6d1deae490e9ef18b21a389cd4 # v1.1.0
@@ -47,7 +47,7 @@ jobs:
     # https://github.com/amazon-ion/ion-java/blob/master/.github/actions/inspect-version/action.yml
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v3.6.0
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v3.6.0
       - name: Get Project Version
         run: |
           echo "PROJECT_VERSION=v$(<project.version)" >> $GITHUB_ENV

.github/workflows/prepare-release.yml

@@ -44,7 +44,7 @@ jobs:
     outputs:
       should_create_draft: ${{ steps.inspect.outputs.is_valid_to_release }}
     steps:
-      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v3.6.0
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v3.6.0
       - name: Get project version
         run: |
           echo "PROJECT_VERSION=$(<project.version)" >> $GITHUB_ENV
@@ -65,7 +65,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v3.6.0
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v3.6.0
       - name: Create a draft release
         shell: bash
         env:

.github/workflows/publish-release-artifacts.yml

@@ -29,7 +29,7 @@ jobs:
     # First, a sanity check to ensure that the library version matches the release version
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v3.6.0
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v3.6.0
       - name: Validate project version matches tag
         shell: bash
         run: |
@@ -48,7 +48,7 @@ jobs:
     steps:
         # TODO: replace with artifact upload/download -- make sure there's no race condition with other builds also
         # uploading an artifact.
-      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v3.6.0
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v3.6.0
         with:
           submodules: recursive
       - uses: gradle/gradle-build-action@842c587ad8aa4c68eeba24c396e15af4c2e9f30a # v2.9.0

.github/workflows/scorecard.yml

@@ -32,7 +32,7 @@ jobs:
 
     steps:
       - name: "Checkout code"
-        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v3.1.0
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v3.1.0
         with:
           persist-credentials: false
 
@@ -67,6 +67,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@fdcae64e1484d349b3366718cdfef3d404390e85 # v2.22.1
+        uses: github/codeql-action/upload-sarif@0116bc2df50751f9724a2e35ef1f24d22f90e4e1 # v2.22.3
         with:
           sarif_file: results.sarif

.github/workflows/test-inspect-version-action.yml

@@ -53,7 +53,7 @@ jobs:
             expected: action_failure
 
     steps:
-      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v3.6.0
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v3.6.0
       - name: Invoke Action
         id: inspect
         continue-on-error: ${{ matrix.expected == 'action_failure' }}

src/com/amazon/ion/BufferConfiguration.java

@@ -1,42 +1,39 @@
-package com.amazon.ion;
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
-import com.amazon.ion.impl.ReaderLookaheadBuffer;
+package com.amazon.ion;
 
 /**
  * Provides logic common to all BufferConfiguration implementations.
- * @param <Configuration> the type of the concrete subclass of this BufferConfiguration that is applicable to the
- *                        ReaderLookaheadBufferBase subclass.
+ * @param <Configuration> the type of the concrete subclass of this BufferConfiguration.
  */
 public abstract class BufferConfiguration<Configuration extends BufferConfiguration<Configuration>> {
 
     /**
      * Functional interface for handling oversized values.
      */
+    @FunctionalInterface
     public interface OversizedValueHandler {
         /**
-         * Invoked each time a value (and any symbol tables that immediately precede it) exceed the buffer size limit
-         * specified by the LookaheadReaderWrapper instance, but the symbol tables by themselves do not exceed the
-         * limit. This is recoverable. If the implementation wishes to recover, it should simply return normally from
-         * this method. The oversized value will be flushed from the input pipe; normal processing will resume with the
-         * next value. If the implementation wishes to abort processing immediately, it may throw an exception from this
-         * method. Such an exception will propagate upward and will be thrown from
-         * {@link ReaderLookaheadBuffer#fillInput()}.
-         * @throws Exception if handler logic fails.
+         * Invoked each time a user value exceeds the buffer size limit specified. This is recoverable. If the
+         * implementation wishes to recover, it should simply return normally from this method. The oversized value will
+         * be flushed from the buffer; normal processing will resume with the next value. If the implementation wishes
+         * to abort processing immediately, it may throw an exception from this method.
          */
-        void onOversizedValue() throws Exception;
+        void onOversizedValue();
     }
 
     /**
      * Functional interface for reporting processed data.
      */
+    @FunctionalInterface
     public interface DataHandler {
         /**
          * Invoked whenever the bytes from a value are processed, regardless of whether the bytes are buffered or
          * skipped due to the value being oversized.
          * @param numberOfBytes the number of bytes processed.
-         * @throws Exception if handler logic fails.
          */
-        void onData(int numberOfBytes) throws Exception;
+        void onData(int numberOfBytes);
     }
 
     /**
@@ -88,7 +85,7 @@ public final BuilderType withInitialBufferSize(final int initialBufferSizeInByte
         }
 
         /**
-         * @return the initial size of the lookahead buffer, in bytes.
+         * @return the initial size of the buffer, in bytes.
          */
         public final int getInitialBufferSize() {
             return initialBufferSize;
@@ -133,10 +130,10 @@ public final DataHandler getDataHandler() {
         }
 
         /**
-         * Set the maximum number of bytes between top-level values. This can be used to limit growth of the internal
-         * buffer. For binary Ion, the minimum value is 5 because all valid binary Ion data begins with a 4-byte Ion
-         * version marker and the smallest value is 1 byte. For delimited text Ion, the minimum value is 2 because the
-         * smallest text Ion value is 1 byte and the smallest delimiter is 1 byte. Default: Integer.MAX_VALUE.
+         * Set the maximum size of the buffer. For binary Ion, the minimum value is 5 because all valid binary Ion data
+         * begins with a 4-byte Ion version marker and the smallest value is 1 byte. For text Ion, the minimum value is
+         * 2 because the smallest text Ion value is 1 byte and the smallest delimiter is 1 byte.
+         * Default: Integer.MAX_VALUE.
          *
          * @param maximumBufferSizeInBytes the value.
          * @return this builder.
@@ -177,12 +174,12 @@ public int getMaximumBufferSize() {
     }
 
     /**
-     * The initial size of the lookahead buffer, in bytes.
+     * The initial size of the buffer, in bytes.
      */
     private final int initialBufferSize;
 
     /**
-     * The maximum number of bytes that will be buffered.
+     * The maximum number of bytes that may be buffered.
      */
     private final int maximumBufferSize;
 
@@ -236,7 +233,7 @@ protected void requireUnlimitedBufferSize() {
     }
 
     /**
-     * @return the initial size of the lookahead buffer, in bytes.
+     * @return the initial size of the buffer, in bytes.
      */
     public final int getInitialBufferSize() {
         return initialBufferSize;

src/com/amazon/ion/IonBufferConfiguration.java

@@ -1,24 +1,24 @@
-package com.amazon.ion;
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
-import com.amazon.ion.impl.IonReaderLookaheadBuffer;
+package com.amazon.ion;
 
 /**
- * Configures Ion lookahead buffers.
+ * Configures buffers that hold Ion data.
  */
 public final class IonBufferConfiguration extends BufferConfiguration<IonBufferConfiguration> {
 
     /**
      * Functional interface for handling oversized symbol tables.
      */
+    @FunctionalInterface
     public interface OversizedSymbolTableHandler {
         /**
          * Invoked when the user specifies a finite maximum buffer size and that size is exceeded by symbol table(s)
          * alone. Because symbol tables cannot be truncated without corrupting values that follow in the stream,
-         * this condition is not recoverable. After this method is called,
-         * {@link IonReaderLookaheadBuffer#fillInput()} has no effect.
-         * @throws Exception if handler logic fails.
+         * this condition is not recoverable.
          */
-        void onOversizedSymbolTable() throws Exception;
+        void onOversizedSymbolTable();
     }
 
     /**
@@ -34,41 +34,28 @@ public static final class Builder extends BufferConfiguration.Builder<IonBufferC
         /**
          * An OversizedValueHandler that does nothing.
          */
-        private static final OversizedValueHandler NO_OP_OVERSIZED_VALUE_HANDLER = new OversizedValueHandler() {
-
-            @Override
-            public void onOversizedValue() {
-                // If no maximum buffer size is configured, values cannot be considered oversized and this
-                // implementation will never be called.
-                // If a maximum buffer size is configured, a handler must also be configured. In that case,
-                // this implementation will only be called if the user provides it to the builder manually.
-            }
+        private static final OversizedValueHandler NO_OP_OVERSIZED_VALUE_HANDLER = () -> {
+            // If no maximum buffer size is configured, values cannot be considered oversized and this
+            // implementation will never be called.
+            // If a maximum buffer size is configured, a handler must also be configured. In that case,
+            // this implementation will only be called if the user provides it to the builder manually.
         };
 
         /**
          * A DataHandler that does nothing.
          */
-        private static final DataHandler NO_OP_DATA_HANDLER = new DataHandler() {
-
-            @Override
-            public void onData(int bytes) {
-                // Do nothing.
-            }
+        private static final DataHandler NO_OP_DATA_HANDLER = bytes -> {
+            // Do nothing.
         };
 
         /**
          * An OversizedSymbolTableHandler that does nothing.
          */
-        private static final OversizedSymbolTableHandler NO_OP_OVERSIZED_SYMBOL_TABLE_HANDLER
-            = new OversizedSymbolTableHandler() {
-
-            @Override
-            public void onOversizedSymbolTable() {
-                // If no maximum buffer size is configured, symbol tables cannot be considered oversized and this
-                // implementation will never be called.
-                // If a maximum buffer size is configured, a handler must also be configured. In that case,
-                // this implementation will only be called if the user provides it to the builder manually.
-            }
+        private static final OversizedSymbolTableHandler NO_OP_OVERSIZED_SYMBOL_TABLE_HANDLER = () -> {
+            // If no maximum buffer size is configured, symbol tables cannot be considered oversized and this
+            // implementation will never be called.
+            // If a maximum buffer size is configured, a handler must also be configured. In that case,
+            // this implementation will only be called if the user provides it to the builder manually.
         };
 
         /**