feat(java): let the storage API reach the local filesystem (#960)

* feat(java): let the storage API reach the local filesystem

The storage API merged in #958 has no implementation, so nothing can
open a GraphAr file yet. This adds the local filesystem adapter that
the same issue asked for, keeping the module free of any GraphAr
layout, format, or query concern: it resolves a URI to a path, opens a
seekable input over it, and writes through a position-reporting output.

Directories are created on demand for an output file, an existing
target is refused unless the caller asked to replace it, and a read
past the end of a file reports the end of the stream rather than a
partial buffer.

Closes the adapter half of #953.

Not-tested: only the file scheme is exercised; other schemes are the
concern of later adapters.

* feat(java): reuse one transfer buffer for direct-buffer writes

Review feedback on #960: a write from a buffer without a backing array
allocated a fresh staging array on every call. The output is single
threaded already, because it tracks its own position, so one instance
buffer can serve every such write. It is allocated on first use, so an
output that only ever sees heap buffers never pays for it.

Adds the missing test for a direct buffer larger than one transfer
chunk, which the previous test did not reach: with the copy loop
reduced to a single pass the new test fails with
"expected:<20000> but was:<8192>".

Author: keksmd

maven-projects/pom.xml

@@ -79,6 +79,7 @@
         <module>spark</module>
         <module>info</module>
         <module>storage-api</module>
+        <module>storage-local</module>
     </modules>
 
     <build>

maven-projects/storage-local/pom.xml

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.apache.graphar</groupId>
+        <artifactId>graphar-root</artifactId>
+        <version>${graphar.version}</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <artifactId>graphar-storage-local</artifactId>
+    <packaging>jar</packaging>
+    <version>${graphar.version}</version>
+
+    <name>graphar-storage-local</name>
+
+    <properties>
+        <maven.compiler.source>11</maven.compiler.source>
+        <maven.compiler.target>11</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.graphar</groupId>
+            <artifactId>graphar-storage-api</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <version>4.13.2</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>com.diffplug.spotless</groupId>
+                <artifactId>spotless-maven-plugin</artifactId>
+                <version>${spotless-maven-plugin.version}</version>
+                <configuration>
+                    <java>
+                        <googleJavaFormat>
+                            <version>1.7</version>
+                            <style>AOSP</style>
+                        </googleJavaFormat>
+                    </java>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

maven-projects/storage-local/src/main/java/org/apache/graphar/storage/local/LocalInputFile.java

@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.graphar.storage.local;
+
+import java.io.IOException;
+import java.net.URI;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import org.apache.graphar.storage.InputFile;
+import org.apache.graphar.storage.SeekableInput;
+
+final class LocalInputFile implements InputFile {
+    private final Path path;
+
+    LocalInputFile(Path path) {
+        this.path = path;
+    }
+
+    @Override
+    public URI uri() {
+        return path.toUri();
+    }
+
+    @Override
+    public long size() throws IOException {
+        return Files.size(path);
+    }
+
+    @Override
+    public SeekableInput open() throws IOException {
+        return new LocalSeekableInput(path);
+    }
+}

maven-projects/storage-local/src/main/java/org/apache/graphar/storage/local/LocalOutputFile.java

@@ -0,0 +1,67 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.graphar.storage.local;
+
+import java.io.IOException;
+import java.net.URI;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardOpenOption;
+import org.apache.graphar.storage.OutputFile;
+import org.apache.graphar.storage.PositionOutput;
+
+final class LocalOutputFile implements OutputFile {
+    private final Path path;
+
+    LocalOutputFile(Path path) {
+        this.path = path;
+    }
+
+    @Override
+    public URI uri() {
+        return path.toUri();
+    }
+
+    @Override
+    public PositionOutput create() throws IOException {
+        createParentDirectories();
+        return new LocalPositionOutput(
+                Files.newOutputStream(
+                        path, StandardOpenOption.CREATE_NEW, StandardOpenOption.WRITE));
+    }
+
+    @Override
+    public PositionOutput createOrOverwrite() throws IOException {
+        createParentDirectories();
+        return new LocalPositionOutput(
+                Files.newOutputStream(
+                        path,
+                        StandardOpenOption.CREATE,
+                        StandardOpenOption.TRUNCATE_EXISTING,
+                        StandardOpenOption.WRITE));
+    }
+
+    private void createParentDirectories() throws IOException {
+        Path parent = path.getParent();
+        if (parent != null) {
+            Files.createDirectories(parent);
+        }
+    }
+}

maven-projects/storage-local/src/main/java/org/apache/graphar/storage/local/LocalPositionOutput.java

@@ -0,0 +1,77 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.graphar.storage.local;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.nio.ByteBuffer;
+import org.apache.graphar.storage.PositionOutput;
+
+final class LocalPositionOutput implements PositionOutput {
+    private static final int BUFFER_SIZE = 8192;
+
+    private final OutputStream output;
+    private long position;
+    private byte[] transfer;
+
+    LocalPositionOutput(OutputStream output) {
+        this.output = output;
+    }
+
+    @Override
+    public long position() {
+        return position;
+    }
+
+    @Override
+    public void write(ByteBuffer source) throws IOException {
+        if (source.hasArray()) {
+            int length = source.remaining();
+            write(source.array(), source.arrayOffset() + source.position(), length);
+            source.position(source.position() + length);
+            return;
+        }
+
+        if (transfer == null) {
+            transfer = new byte[BUFFER_SIZE];
+        }
+        while (source.hasRemaining()) {
+            int length = Math.min(source.remaining(), transfer.length);
+            source.get(transfer, 0, length);
+            write(transfer, 0, length);
+        }
+    }
+
+    @Override
+    public void write(byte[] source, int offset, int length) throws IOException {
+        output.write(source, offset, length);
+        position += length;
+    }
+
+    @Override
+    public void flush() throws IOException {
+        output.flush();
+    }
+
+    @Override
+    public void close() throws IOException {
+        output.close();
+    }
+}

maven-projects/storage-local/src/main/java/org/apache/graphar/storage/local/LocalSeekableInput.java

@@ -0,0 +1,58 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.graphar.storage.local;
+
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.nio.channels.FileChannel;
+import java.nio.file.Path;
+import java.nio.file.StandardOpenOption;
+import org.apache.graphar.storage.SeekableInput;
+
+final class LocalSeekableInput implements SeekableInput {
+    private final FileChannel channel;
+
+    LocalSeekableInput(Path path) throws IOException {
+        this.channel = FileChannel.open(path, StandardOpenOption.READ);
+    }
+
+    @Override
+    public long position() throws IOException {
+        return channel.position();
+    }
+
+    @Override
+    public void seek(long newPosition) throws IOException {
+        if (newPosition < 0) {
+            throw new IllegalArgumentException("Seek position cannot be negative: " + newPosition);
+        }
+        channel.position(newPosition);
+    }
+
+    @Override
+    public int read(ByteBuffer destination) throws IOException {
+        return channel.read(destination);
+    }
+
+    @Override
+    public void close() throws IOException {
+        channel.close();
+    }
+}