This is an automated email from the ASF dual-hosted git repository.
SYaoJun pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-graphar.git
The following commit(s) were added to refs/heads/main by this push:
new c51b0284 feat(java): add dependency-light storage API (#958)
c51b0284 is described below
commit c51b02849c2f0b04e147d6974aa8b641cba72488
Author: alex <[email protected]>
AuthorDate: Wed Aug 19 02:34:58 2026 +0300
feat(java): add dependency-light storage API (#958)
---
maven-projects/pom.xml | 1 +
maven-projects/storage-api/pom.xml | 85 ++++++++++++++++++++
.../java/org/apache/graphar/storage/InputFile.java | 35 ++++++++
.../org/apache/graphar/storage/OutputFile.java | 35 ++++++++
.../org/apache/graphar/storage/PositionOutput.java | 42 ++++++++++
.../org/apache/graphar/storage/SeekableInput.java | 56 +++++++++++++
.../java/org/apache/graphar/storage/Storage.java | 35 ++++++++
.../apache/graphar/storage/SeekableInputTest.java | 93 ++++++++++++++++++++++
8 files changed, 382 insertions(+)
diff --git a/maven-projects/pom.xml b/maven-projects/pom.xml
index 5d46381f..205ea123 100644
--- a/maven-projects/pom.xml
+++ b/maven-projects/pom.xml
@@ -78,6 +78,7 @@
<module>java</module>
<module>spark</module>
<module>info</module>
+ <module>storage-api</module>
</modules>
<build>
diff --git a/maven-projects/storage-api/pom.xml
b/maven-projects/storage-api/pom.xml
new file mode 100644
index 00000000..68489bf4
--- /dev/null
+++ b/maven-projects/storage-api/pom.xml
@@ -0,0 +1,85 @@
+<?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-api</artifactId>
+ <packaging>jar</packaging>
+ <version>${graphar.version}</version>
+
+ <name>graphar-storage-api</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>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>
diff --git
a/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/InputFile.java
b/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/InputFile.java
new file mode 100644
index 00000000..61cb7aaa
--- /dev/null
+++
b/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/InputFile.java
@@ -0,0 +1,35 @@
+/*
+ * 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;
+
+import java.io.IOException;
+import java.net.URI;
+
+/** A readable object in GraphAr storage. */
+public interface InputFile {
+ /** Returns the stable storage location for this file. */
+ URI uri();
+
+ /** Returns the file size in bytes. */
+ long size() throws IOException;
+
+ /** Opens an independent seekable stream. */
+ SeekableInput open() throws IOException;
+}
diff --git
a/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/OutputFile.java
b/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/OutputFile.java
new file mode 100644
index 00000000..e73a23e2
--- /dev/null
+++
b/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/OutputFile.java
@@ -0,0 +1,35 @@
+/*
+ * 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;
+
+import java.io.IOException;
+import java.net.URI;
+
+/** A writable object in GraphAr storage. */
+public interface OutputFile {
+ /** Returns the stable storage location for this file. */
+ URI uri();
+
+ /** Creates a new file and fails if a file already exists at this
location. */
+ PositionOutput create() throws IOException;
+
+ /** Creates a file, replacing any existing file at this location. */
+ PositionOutput createOrOverwrite() throws IOException;
+}
diff --git
a/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/PositionOutput.java
b/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/PositionOutput.java
new file mode 100644
index 00000000..cd4e80c5
--- /dev/null
+++
b/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/PositionOutput.java
@@ -0,0 +1,42 @@
+/*
+ * 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;
+
+import java.io.Closeable;
+import java.io.Flushable;
+import java.io.IOException;
+import java.nio.ByteBuffer;
+
+/** A sequential output with a byte position suitable for file-format writers.
*/
+public interface PositionOutput extends Closeable, Flushable {
+ /** Returns the number of bytes written to this output. */
+ long position() throws IOException;
+
+ /** Writes bytes from {@code source}, advancing its position by the bytes
written. */
+ void write(ByteBuffer source) throws IOException;
+
+ /** Writes bytes from {@code source}. */
+ void write(byte[] source, int offset, int length) throws IOException;
+
+ /** Writes all bytes from {@code source}. */
+ default void write(byte[] source) throws IOException {
+ write(source, 0, source.length);
+ }
+}
diff --git
a/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/SeekableInput.java
b/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/SeekableInput.java
new file mode 100644
index 00000000..73ac298b
--- /dev/null
+++
b/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/SeekableInput.java
@@ -0,0 +1,56 @@
+/*
+ * 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;
+
+import java.io.Closeable;
+import java.io.EOFException;
+import java.io.IOException;
+import java.nio.ByteBuffer;
+
+/** A readable stream whose position can be changed without reopening the
file. */
+public interface SeekableInput extends Closeable {
+ /** Returns the current byte offset. */
+ long position() throws IOException;
+
+ /** Moves this stream to {@code newPosition}. */
+ void seek(long newPosition) throws IOException;
+
+ /**
+ * Reads bytes into {@code destination}.
+ *
+ * <p>Implementations must return a positive byte count while {@code
destination} has remaining
+ * capacity, or {@code -1} at end of input. Implementations that wrap a
non-blocking source must
+ * wait or retry internally rather than return zero.
+ */
+ int read(ByteBuffer destination) throws IOException;
+
+ /** Reads until {@code destination} is full or throws on end of input. */
+ default void readFully(ByteBuffer destination) throws IOException {
+ while (destination.hasRemaining()) {
+ int bytesRead = read(destination);
+ if (bytesRead < 0) {
+ throw new EOFException("Reached end of input before filling
destination.");
+ }
+ if (bytesRead == 0) {
+ throw new IOException("Seekable input made no progress while
reading.");
+ }
+ }
+ }
+}
diff --git
a/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/Storage.java
b/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/Storage.java
new file mode 100644
index 00000000..7d85924b
--- /dev/null
+++
b/maven-projects/storage-api/src/main/java/org/apache/graphar/storage/Storage.java
@@ -0,0 +1,35 @@
+/*
+ * 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;
+
+import java.io.IOException;
+import java.net.URI;
+
+/** Resolves GraphAr URIs to storage-specific readable and writable objects. */
+public interface Storage {
+ /** Resolves a readable file without opening it. */
+ InputFile inputFile(URI uri);
+
+ /** Resolves a writable file without opening it. */
+ OutputFile outputFile(URI uri);
+
+ /** Returns whether a file exists at {@code uri}. */
+ boolean exists(URI uri) throws IOException;
+}
diff --git
a/maven-projects/storage-api/src/test/java/org/apache/graphar/storage/SeekableInputTest.java
b/maven-projects/storage-api/src/test/java/org/apache/graphar/storage/SeekableInputTest.java
new file mode 100644
index 00000000..1924a2b2
--- /dev/null
+++
b/maven-projects/storage-api/src/test/java/org/apache/graphar/storage/SeekableInputTest.java
@@ -0,0 +1,93 @@
+/*
+ * 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;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThrows;
+
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import org.junit.Test;
+
+public class SeekableInputTest {
+ @Test
+ public void readFullyCombinesPartialReads() throws IOException {
+ ByteBuffer destination = ByteBuffer.allocate(3);
+ try (SeekableInput input = new StubSeekableInput(bytes("a"),
bytes("bc"))) {
+ input.readFully(destination);
+ assertEquals(3, input.position());
+ }
+ assertArrayEquals(bytes("abc"), destination.array());
+ }
+
+ @Test
+ public void readFullyFailsAtEndOfInput() throws IOException {
+ try (SeekableInput input = new StubSeekableInput(bytes("a"), null)) {
+ assertThrows(IOException.class, () ->
input.readFully(ByteBuffer.allocate(2)));
+ }
+ }
+
+ @Test
+ public void readFullyFailsOnZeroProgress() throws IOException {
+ try (SeekableInput input = new StubSeekableInput(new byte[0])) {
+ assertThrows(IOException.class, () ->
input.readFully(ByteBuffer.allocate(1)));
+ }
+ }
+
+ private static byte[] bytes(String value) {
+ return value.getBytes(UTF_8);
+ }
+
+ private static final class StubSeekableInput implements SeekableInput {
+ private final byte[][] reads;
+ private int readIndex;
+ private long position;
+
+ StubSeekableInput(byte[]... reads) {
+ this.reads = reads;
+ }
+
+ @Override
+ public long position() {
+ return position;
+ }
+
+ @Override
+ public void seek(long newPosition) {
+ position = newPosition;
+ }
+
+ @Override
+ public int read(ByteBuffer destination) {
+ byte[] bytes = reads[readIndex++];
+ if (bytes == null) {
+ return -1;
+ }
+ destination.put(bytes);
+ position += bytes.length;
+ return bytes.length;
+ }
+
+ @Override
+ public void close() {}
+ }
+}
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
