OAK-12486: Deprecate Buffer and replace its uses with ByteBuffer

AGENTS.md

@@ -4,7 +4,8 @@
 
 Apache Jackrabbit Oak is a scalable, high-performance hierarchical content repository
 implementing the JCR (Java Content Repository) specification. It is a multi-module Maven
-project with ~47 modules written in Java 11.
+project with ~47 modules written in Java 17 (minimum build/runtime version; `oak-jackrabbit-api`
+still compiles with release 11).
 
 ## General Guidelines
 
@@ -248,7 +249,7 @@ via the Apache RAT plugin. Use this exact header:
 
 ## CI
 
-- **GitHub Actions:** Runs on PRs and pushes to trunk. Builds with Java 11, runs full
+- **GitHub Actions:** Runs on PRs and pushes to trunk. Builds with Java 17, runs full
   test suite with `SEGMENT_TAR` and `DOCUMENT_NS` fixtures.
 - **Jenkins:** Parallel module testing pipeline.
 - **SonarCloud:** Code quality analysis runs after build.

oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/Buffer.java

@@ -41,7 +41,11 @@
  * {@link ByteBuffer}. Since it is not possible to directly convert a {@link
  * Buffer} into a {@link ByteBuffer} and the other way around, {@link Buffer}
  * makes it less likely to develop dangerous code in the future.
+ *
+ * @deprecated For code that can rely on a Java version of at least 9, the
+ * compatibility concern above no longer applies. Use {@link ByteBuffer} directly.
  */
+@Deprecated
 final public class Buffer {
 
     private final ByteBuffer buffer;

oak-segment-aws/src/main/java/org/apache/jackrabbit/oak/segment/aws/AwsSegmentArchiveReader.java

@@ -20,10 +20,10 @@
 
 import java.io.File;
 import java.io.IOException;
+import java.nio.ByteBuffer;
 import java.util.Iterator;
 import java.util.NoSuchElementException;
 
-import org.apache.jackrabbit.oak.commons.Buffer;
 import org.apache.jackrabbit.oak.segment.remote.AbstractRemoteSegmentArchiveReader;
 import org.apache.jackrabbit.oak.segment.remote.RemoteSegmentArchiveEntry;
 import org.apache.jackrabbit.oak.segment.spi.monitor.IOMonitor;
@@ -38,7 +38,7 @@ public class AwsSegmentArchiveReader extends AbstractRemoteSegmentArchiveReader
     }
 
     private static Iterable<ArchiveEntry> createEntryIterable(S3Directory directory, String archiveName) throws IOException{
-        Buffer buffer = directory.readObjectToBuffer(archiveName + ".idx", OFF_HEAP);
+        ByteBuffer buffer = directory.readObjectToBuffer(archiveName + ".idx", OFF_HEAP);
         return () -> new Iterator<>() {
             @Override
             public boolean hasNext() {
@@ -64,12 +64,12 @@ public ArchiveEntry next() {
     }
 
     @Override
-    protected void doReadSegmentToBuffer(String segmentFileName, Buffer buffer) throws IOException {
+    protected void doReadSegmentToBuffer(String segmentFileName, ByteBuffer buffer) throws IOException {
         directory.readObjectToBuffer(segmentFileName, buffer);
     }
 
     @Override
-    protected Buffer doReadDataFile(String extension) throws IOException {
+    protected ByteBuffer doReadDataFile(String extension) throws IOException {
         return readObjectToBuffer(getName() + extension);
     }
 
@@ -78,7 +78,7 @@ protected File archivePathAsFile() {
         return new File(directory.getPath());
     }
 
-    private Buffer readObjectToBuffer(String name) throws IOException {
+    private ByteBuffer readObjectToBuffer(String name) throws IOException {
         if (directory.doesObjectExist(name)) {
             return directory.readObjectToBuffer(name, false);
         }

oak-segment-aws/src/main/java/org/apache/jackrabbit/oak/segment/aws/AwsSegmentArchiveWriter.java

@@ -21,9 +21,9 @@
 
 import java.io.File;
 import java.io.IOException;
+import java.nio.ByteBuffer;
 import java.util.concurrent.TimeUnit;
 
-import org.apache.jackrabbit.oak.commons.Buffer;
 import org.apache.jackrabbit.oak.commons.time.Stopwatch;
 import org.apache.jackrabbit.oak.segment.remote.AbstractRemoteSegmentArchiveWriter;
 import org.apache.jackrabbit.oak.segment.remote.RemoteSegmentArchiveEntry;
@@ -61,7 +61,7 @@ protected void doWriteArchiveEntry(RemoteSegmentArchiveEntry indexEntry, byte[]
     }
 
     @Override
-    protected Buffer doReadArchiveEntry(RemoteSegmentArchiveEntry indexEntry) throws IOException {
+    protected ByteBuffer doReadArchiveEntry(RemoteSegmentArchiveEntry indexEntry) throws IOException {
         return directory.readObjectToBuffer(getSegmentFileName(indexEntry), OFF_HEAP);
     }
 
@@ -79,15 +79,15 @@ protected void afterQueueClosed() throws IOException {
 
     private void writeIndex() throws IOException {
         // 33 bytes = 2 x 8 bytes (long) +  4 x 4 bytes (int) + 1 x 1 byte (boolean)
-        Buffer buffer = Buffer.allocate(index.size() * 33);
+        ByteBuffer buffer = ByteBuffer.allocate(index.size() * 33);
         for (RemoteSegmentArchiveEntry entry : index.values()) {
-            buffer.putLong(entry.getMsb());
-            buffer.putLong(entry.getLsb());
-            buffer.putInt(entry.getPosition());
-            buffer.putInt(entry.getLength());
-            buffer.putInt(entry.getGeneration());
-            buffer.putInt(entry.getFullGeneration());
-            buffer.put(entry.isCompacted() ? (byte) 1 : 0);
+            buffer.putLong(entry.getMsb())
+                    .putLong(entry.getLsb())
+                    .putInt(entry.getPosition())
+                    .putInt(entry.getLength())
+                    .putInt(entry.getGeneration())
+                    .putInt(entry.getFullGeneration())
+                    .put(entry.isCompacted() ? (byte) 1 : 0);
         }
         directory.writeObject(archiveName + ".idx", buffer.array());
     }

oak-segment-aws/src/main/java/org/apache/jackrabbit/oak/segment/aws/S3Directory.java

@@ -30,12 +30,12 @@
 import com.amazonaws.services.s3.model.S3ObjectSummary;
 import com.amazonaws.util.IOUtils;
 
-import org.apache.jackrabbit.oak.commons.Buffer;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
+import java.nio.ByteBuffer;
 import java.io.InputStream;
 import java.util.ArrayList;
 import java.util.List;
@@ -101,18 +101,13 @@ public ObjectMetadata getObjectMetadata(String key) {
         return s3.getObjectMetadata(bucketName, key);
     }
 
-    public Buffer readObjectToBuffer(String name, boolean offHeap) throws IOException {
+    public ByteBuffer readObjectToBuffer(String name, boolean offHeap) throws IOException {
         byte[] data = readObject(rootDirectory + name);
-        Buffer buffer = offHeap ? Buffer.allocateDirect(data.length) : Buffer.allocate(data.length);
-        buffer.put(data);
-        buffer.flip();
-        return buffer;
+        return offHeap ? ByteBuffer.allocateDirect(data.length).put(data).flip() : ByteBuffer.wrap(data);
     }
 
-    public void readObjectToBuffer(String name, Buffer buffer) throws IOException {
-        byte[] data = readObject(rootDirectory + name);
-        buffer.put(data);
-        buffer.flip();
+    public void readObjectToBuffer(String name, ByteBuffer buffer) throws IOException {
+        buffer.put(readObject(rootDirectory + name)).flip();
     }
 
     public byte[] readObject(String key) throws IOException {

oak-segment-aws/src/main/java/org/apache/jackrabbit/oak/segment/aws/tool/AwsSegmentStoreMigrator.java

@@ -19,6 +19,7 @@
 import static org.apache.jackrabbit.oak.segment.aws.tool.AwsToolUtils.fetchByteArray;
 import static org.apache.jackrabbit.oak.segment.aws.tool.AwsToolUtils.storeDescription;
 
+import java.nio.ByteBuffer;
 import java.io.Closeable;
 import java.io.File;
 import java.io.IOException;
@@ -34,7 +35,6 @@
 import java.util.concurrent.TimeUnit;
 import java.util.stream.Collectors;
 
-import org.apache.jackrabbit.oak.commons.Buffer;
 import org.apache.jackrabbit.oak.segment.aws.AwsContext;
 import org.apache.jackrabbit.oak.segment.aws.AwsPersistence;
 import org.apache.jackrabbit.oak.segment.aws.tool.AwsToolUtils.SegmentStoreType;
@@ -205,7 +205,7 @@ private void migrateSegments(SegmentArchiveReader reader, SegmentArchiveWriter w
     }
 
     private void migrateBinaryRef(SegmentArchiveReader reader, SegmentArchiveWriter writer) throws IOException {
-        Buffer binaryReferences = reader.getBinaryReferences();
+        ByteBuffer binaryReferences = reader.getBinaryReferences();
         if (binaryReferences != null) {
             byte[] array = fetchByteArray(binaryReferences);
             writer.writeBinaryReferences(array);
@@ -264,7 +264,7 @@ private static class Segment {
 
         private final SegmentArchiveEntry entry;
 
-        private volatile Buffer data;
+        private volatile ByteBuffer data;
 
         private Segment(SegmentArchiveEntry entry) {
             this.entry = entry;

oak-segment-aws/src/main/java/org/apache/jackrabbit/oak/segment/aws/tool/AwsToolUtils.java

@@ -22,12 +22,12 @@
 
 import java.io.File;
 import java.io.IOException;
+import java.nio.ByteBuffer;
 import java.io.PrintWriter;
 import java.lang.annotation.Annotation;
 import java.text.MessageFormat;
 import java.util.concurrent.TimeUnit;
 
-import org.apache.jackrabbit.oak.commons.Buffer;
 import org.apache.jackrabbit.oak.commons.time.Stopwatch;
 import org.apache.jackrabbit.oak.segment.aws.AwsContext;
 import org.apache.jackrabbit.oak.segment.aws.AwsPersistence;
@@ -175,7 +175,7 @@ public static void printMessage(PrintWriter pw, String format, Object... arg) {
         pw.println(MessageFormat.format(format, arg));
     }
 
-    public static byte[] fetchByteArray(Buffer buffer) throws IOException {
+    public static byte[] fetchByteArray(ByteBuffer buffer) throws IOException {
         byte[] data = new byte[buffer.remaining()];
         buffer.get(data);
         return data;

oak-segment-aws/src/test/java/org/apache/jackrabbit/oak/segment/aws/AwsReadSegmentTest.java

@@ -19,14 +19,14 @@
 package org.apache.jackrabbit.oak.segment.aws;
 
 import java.io.File;
+import java.nio.ByteBuffer;
 import java.io.IOException;
 import java.util.Date;
 
 import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
 import com.amazonaws.services.dynamodbv2.local.embedded.DynamoDBEmbedded;
 import com.amazonaws.services.s3.AmazonS3;
 
-import org.apache.jackrabbit.oak.commons.Buffer;
 import org.apache.jackrabbit.oak.segment.SegmentId;
 import org.apache.jackrabbit.oak.segment.SegmentNotFoundException;
 import org.apache.jackrabbit.oak.segment.file.FileStore;
@@ -101,7 +101,7 @@ public SegmentArchiveReader open(String archiveName) throws IOException {
                     S3Directory archiveDirectory = awsContext.directory.withDirectory(archiveName);
                     return new AwsSegmentArchiveReader(archiveDirectory, archiveName, ioMonitor) {
                         @Override
-                        public Buffer readSegment(long msb, long lsb) throws IOException {
+                        public ByteBuffer readSegment(long msb, long lsb) throws IOException {
                             throw new RepositoryNotReachableException(new RuntimeException("Cannot access AWS S3"));
                         }
                     };
@@ -112,7 +112,7 @@ public SegmentArchiveWriter create(String archiveName) throws IOException {
                     S3Directory archiveDirectory = awsContext.directory.withDirectory(archiveName);
                     return new AwsSegmentArchiveWriter(archiveDirectory, archiveName, ioMonitor, fileStoreMonitor) {
                         @Override
-                        public Buffer readSegment(long msb, long lsb) throws IOException {
+                        public ByteBuffer readSegment(long msb, long lsb) throws IOException {
                             throw new RepositoryNotReachableException(new RuntimeException("Cannot access AWS S3"));
                         }
                     };

oak-segment-aws/src/test/java/org/apache/jackrabbit/oak/segment/aws/tool/SegmentCopyTestBase.java

@@ -24,12 +24,12 @@
 import static org.junit.Assert.assertTrue;
 
 import java.io.File;
+import java.nio.ByteBuffer;
 import java.io.IOException;
 import java.io.PrintWriter;
 import java.util.Collections;
 import java.util.List;
 
-import org.apache.jackrabbit.oak.commons.Buffer;
 import org.apache.jackrabbit.oak.segment.SegmentCache;
 import org.apache.jackrabbit.oak.segment.SegmentNodeStore;
 import org.apache.jackrabbit.oak.segment.SegmentNodeStoreBuilders;
@@ -167,14 +167,14 @@ private void checkArchives(SegmentArchiveManager srcArchiveManager, SegmentArchi
                 assertEquals(srcSegment.getFullGeneration(), destSegment.getFullGeneration());
                 assertEquals(srcSegment.getGeneration(), destSegment.getFullGeneration());
 
-                Buffer srcDataBuffer = srcArchiveReader.readSegment(srcSegment.getMsb(), srcSegment.getLsb());
-                Buffer destDataBuffer = destArchiveReader.readSegment(destSegment.getMsb(), destSegment.getLsb());
+                ByteBuffer srcDataBuffer = srcArchiveReader.readSegment(srcSegment.getMsb(), srcSegment.getLsb());
+                ByteBuffer destDataBuffer = destArchiveReader.readSegment(destSegment.getMsb(), destSegment.getLsb());
 
                 assertEquals(srcDataBuffer, destDataBuffer);
             }
 
-            Buffer srcBinRefBuffer = srcArchiveReader.getBinaryReferences();
-            Buffer destBinRefBuffer = destArchiveReader.getBinaryReferences();
+            ByteBuffer srcBinRefBuffer = srcArchiveReader.getBinaryReferences();
+            ByteBuffer destBinRefBuffer = destArchiveReader.getBinaryReferences();
             assertEquals(srcBinRefBuffer, destBinRefBuffer);
 
             SegmentGraph srcGraph = srcArchiveReader.getGraph();

oak-segment-azure/src/main/java/org/apache/jackrabbit/oak/segment/azure/AzureSegmentArchiveReader.java

@@ -20,11 +20,11 @@
 import com.azure.storage.blob.models.BlobStorageException;
 import com.azure.storage.blob.models.ListBlobsOptions;
 import com.azure.storage.blob.specialized.BlockBlobClient;
-import org.apache.jackrabbit.oak.commons.Buffer;
 import org.apache.jackrabbit.oak.segment.remote.AbstractRemoteSegmentArchiveReader;
 import org.apache.jackrabbit.oak.segment.spi.monitor.IOMonitor;
 import org.jetbrains.annotations.NotNull;
 
+import java.nio.ByteBuffer;
 import java.io.File;
 import java.io.IOException;
 import java.util.Map;
@@ -61,12 +61,12 @@ private static Iterable<ArchiveEntry> createEntryIterable(BlobContainerClient bl
     }
 
     @Override
-    protected void doReadSegmentToBuffer(String segmentFileName, Buffer buffer) throws IOException {
+    protected void doReadSegmentToBuffer(String segmentFileName, ByteBuffer buffer) throws IOException {
         readBufferFully(getBlobClient(segmentFileName), buffer);
     }
 
     @Override
-    protected Buffer doReadDataFile(String extension) throws IOException {
+    protected ByteBuffer doReadDataFile(String extension) throws IOException {
         return readBlob(getName() + extension);
     }
 
@@ -84,14 +84,14 @@ private BlockBlobClient getBlobClient(String name) throws IOException {
         }
     }
 
-    private Buffer readBlob(String name) throws IOException {
+    private ByteBuffer readBlob(String name) throws IOException {
         try {
             BlockBlobClient blob = getBlobClient(name);
             if (!blob.exists()) {
                 return null;
             }
             long length = blob.getProperties().getBlobSize();
-            Buffer buffer = Buffer.allocate((int) length);
+            ByteBuffer buffer = ByteBuffer.allocate((int) length);
             AzureUtilities.readBufferFully(blob, buffer);
             return buffer;
         } catch (BlobStorageException e) {

oak-segment-azure/src/main/java/org/apache/jackrabbit/oak/segment/azure/AzureSegmentArchiveWriter.java

@@ -22,7 +22,6 @@
 import com.azure.storage.blob.models.BlobStorageException;
 import com.azure.storage.blob.options.BlockBlobSimpleUploadOptions;
 import com.azure.storage.blob.specialized.BlockBlobClient;
-import org.apache.jackrabbit.oak.commons.Buffer;
 import org.apache.jackrabbit.oak.commons.time.Stopwatch;
 import org.apache.jackrabbit.oak.segment.azure.util.Retrier;
 import org.apache.jackrabbit.oak.segment.remote.AbstractRemoteSegmentArchiveWriter;
@@ -31,6 +30,7 @@
 import org.apache.jackrabbit.oak.segment.spi.monitor.FileStoreMonitor;
 import org.apache.jackrabbit.oak.segment.spi.monitor.IOMonitor;
 
+import java.nio.ByteBuffer;
 import java.io.ByteArrayInputStream;
 import java.io.File;
 import java.io.IOException;
@@ -95,13 +95,9 @@ protected void doWriteArchiveEntry(RemoteSegmentArchiveEntry indexEntry, byte[]
     }
 
     @Override
-    protected Buffer doReadArchiveEntry(RemoteSegmentArchiveEntry indexEntry)  throws IOException {
-        Buffer buffer;
-        if (OFF_HEAP) {
-            buffer = Buffer.allocateDirect(indexEntry.getLength());
-        } else {
-            buffer = Buffer.allocate(indexEntry.getLength());
-        }
+    protected ByteBuffer doReadArchiveEntry(RemoteSegmentArchiveEntry indexEntry)  throws IOException {
+        int length = indexEntry.getLength();
+        ByteBuffer buffer = OFF_HEAP ? ByteBuffer.allocateDirect(length) : ByteBuffer.allocate(length);
         readBufferFully(getBlockBlobClient(getSegmentFileName(indexEntry)), buffer);
         return buffer;
     }

oak-segment-azure/src/main/java/org/apache/jackrabbit/oak/segment/azure/AzureUtilities.java

@@ -23,13 +23,13 @@
 import com.azure.storage.blob.models.ListBlobsOptions;
 import com.azure.storage.blob.specialized.AppendBlobClient;
 import com.azure.storage.blob.specialized.BlockBlobClient;
-import org.apache.jackrabbit.oak.commons.Buffer;
 import org.apache.jackrabbit.oak.commons.PathUtils;
 import org.apache.jackrabbit.oak.segment.spi.RepositoryNotReachableException;
 import org.jetbrains.annotations.NotNull;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import java.nio.ByteBuffer;
 import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.OutputStream;
@@ -77,7 +77,7 @@ public static boolean archiveExists(BlobContainerClient blobContainerClient, Str
     }
 
 
-    public static void readBufferFully(BlockBlobClient blob, Buffer buffer) throws IOException {
+    public static void readBufferFully(BlockBlobClient blob, ByteBuffer buffer) throws IOException {
         try {
             blob.downloadStream(new ByteBufferOutputStream(buffer));
             buffer.flip();
@@ -124,9 +124,9 @@ public static void deleteAllEntries(BlobContainerClient blobContainerClient, Lis
     private static class ByteBufferOutputStream extends OutputStream {
 
         @NotNull
-        private final Buffer buffer;
+        private final ByteBuffer buffer;
 
-        public ByteBufferOutputStream(@NotNull Buffer buffer) {
+        public ByteBufferOutputStream(@NotNull ByteBuffer buffer) {
             this.buffer = buffer;
         }