feat(java): add chunk and edge-range primitives

.github/workflows/java-sdk.yml

@@ -55,7 +55,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     env:
-      SDK_MODULES: storage-api,storage-local,io-api,storage-s3
+      SDK_MODULES: storage-api,storage-local,io-api,storage-s3,core
     steps:
       - uses: actions/checkout@v7
         with:

maven-projects/core/pom.xml

@@ -0,0 +1,88 @@
+<?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-core</artifactId>
+    <packaging>jar</packaging>
+    <version>${graphar.version}</version>
+    <name>graphar-core</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-info</artifactId>
+            <version>${graphar.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/core/src/main/java/org/apache/graphar/core/ChunkMath.java

@@ -0,0 +1,79 @@
+/*
+ * 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.core;
+
+/** Long-safe operations on GraphAr vertex and edge chunks. */
+public final class ChunkMath {
+    private ChunkMath() {}
+
+    /**
+     * Returns the chunk containing a non-negative element identifier.
+     *
+     * @param elementId an element identifier
+     * @param chunkSize a positive chunk size
+     * @return the zero-based chunk index
+     */
+    public static long chunkIndex(long elementId, long chunkSize) {
+        validateElementId(elementId);
+        validateChunkSize(chunkSize);
+        return elementId / chunkSize;
+    }
+
+    /**
+     * Returns an element's zero-based position inside its chunk.
+     *
+     * @param elementId an element identifier
+     * @param chunkSize a positive chunk size
+     * @return the zero-based offset within the chunk
+     */
+    public static long offsetInChunk(long elementId, long chunkSize) {
+        validateElementId(elementId);
+        validateChunkSize(chunkSize);
+        return elementId % chunkSize;
+    }
+
+    /**
+     * Returns the number of chunks required for a non-negative number of elements.
+     *
+     * @param elementCount a number of elements
+     * @param chunkSize a positive chunk size
+     * @return the number of chunks needed to contain the elements
+     */
+    public static long chunkCount(long elementCount, long chunkSize) {
+        if (elementCount < 0) {
+            throw new IllegalArgumentException(
+                    "Element count must be non-negative: " + elementCount);
+        }
+        validateChunkSize(chunkSize);
+        return elementCount == 0 ? 0 : 1 + (elementCount - 1) / chunkSize;
+    }
+
+    static void validateElementId(long elementId) {
+        if (elementId < 0) {
+            throw new IllegalArgumentException("Element ID must be non-negative: " + elementId);
+        }
+    }
+
+    static void validateChunkSize(long chunkSize) {
+        if (chunkSize <= 0) {
+            throw new IllegalArgumentException("Chunk size must be positive: " + chunkSize);
+        }
+    }
+}

maven-projects/core/src/main/java/org/apache/graphar/core/ChunkRange.java

@@ -0,0 +1,105 @@
+/*
+ * 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.core;
+
+import java.util.Objects;
+
+/** A half-open range of non-negative chunk indexes. */
+public final class ChunkRange {
+    private final long begin;
+    private final long end;
+
+    /**
+     * Creates a chunk range.
+     *
+     * @param begin the first included non-negative chunk index
+     * @param end the first excluded chunk index
+     */
+    public ChunkRange(long begin, long end) {
+        if (begin < 0) {
+            throw new IllegalArgumentException("Chunk range begin must be non-negative: " + begin);
+        }
+        if (end < begin) {
+            throw new IllegalArgumentException(
+                    "Chunk range end must not precede begin: [" + begin + ", " + end + ")");
+        }
+        this.begin = begin;
+        this.end = end;
+    }
+
+    /**
+     * Returns the first included chunk index.
+     *
+     * @return the first included chunk index
+     */
+    public long begin() {
+        return begin;
+    }
+
+    /**
+     * Returns the first excluded chunk index.
+     *
+     * @return the first excluded chunk index
+     */
+    public long end() {
+        return end;
+    }
+
+    /**
+     * Returns whether this range selects no chunks.
+     *
+     * @return whether the range is empty
+     */
+    public boolean isEmpty() {
+        return begin == end;
+    }
+
+    /**
+     * Returns whether {@code chunkIndex} belongs to this range.
+     *
+     * @param chunkIndex a chunk index
+     * @return whether the chunk index belongs to this range
+     */
+    public boolean contains(long chunkIndex) {
+        return chunkIndex >= begin && chunkIndex < end;
+    }
+
+    @Override
+    public boolean equals(Object other) {
+        if (this == other) {
+            return true;
+        }
+        if (!(other instanceof ChunkRange)) {
+            return false;
+        }
+        ChunkRange that = (ChunkRange) other;
+        return begin == that.begin && end == that.end;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(begin, end);
+    }
+
+    @Override
+    public String toString() {
+        return "ChunkRange[" + begin + ", " + end + ")";
+    }
+}