diff --git a/.github/workflows/java-sdk.yml b/.github/workflows/java-sdk.yml index a8779ee04..5a45ac49b 100644 --- a/.github/workflows/java-sdk.yml +++ b/.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: diff --git a/maven-projects/core/pom.xml b/maven-projects/core/pom.xml new file mode 100644 index 000000000..529ae7569 --- /dev/null +++ b/maven-projects/core/pom.xml @@ -0,0 +1,88 @@ + + + + 4.0.0 + + + org.apache.graphar + graphar-root + ${graphar.version} + ../pom.xml + + + graphar-core + jar + ${graphar.version} + graphar-core + + + 11 + 11 + UTF-8 + + + + + org.apache.graphar + graphar-info + ${graphar.version} + + + junit + junit + 4.13.2 + test + + + + + + + com.diffplug.spotless + spotless-maven-plugin + ${spotless-maven-plugin.version} + + + + 1.7 + + + + + + + org.apache.maven.plugins + maven-javadoc-plugin + + + attach-javadocs + + jar + + + + + + + diff --git a/maven-projects/core/src/main/java/org/apache/graphar/core/ChunkMath.java b/maven-projects/core/src/main/java/org/apache/graphar/core/ChunkMath.java new file mode 100644 index 000000000..0fca2b2c8 --- /dev/null +++ b/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); + } + } +} diff --git a/maven-projects/core/src/main/java/org/apache/graphar/core/ChunkRange.java b/maven-projects/core/src/main/java/org/apache/graphar/core/ChunkRange.java new file mode 100644 index 000000000..982946c0c --- /dev/null +++ b/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 + ")"; + } +} diff --git a/maven-projects/core/src/main/java/org/apache/graphar/core/EdgeRange.java b/maven-projects/core/src/main/java/org/apache/graphar/core/EdgeRange.java new file mode 100644 index 000000000..ab596a989 --- /dev/null +++ b/maven-projects/core/src/main/java/org/apache/graphar/core/EdgeRange.java @@ -0,0 +1,123 @@ +/* + * 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 validated half-open range of edge rows within one GraphAr vertex partition. */ +public final class EdgeRange { + private final long begin; + private final long end; + + private EdgeRange(long begin, long end) { + this.begin = begin; + this.end = end; + } + + /** + * Creates an edge range from the two adjacent values of an ordered offset table. + * + * @param begin the first included edge row + * @param end the first excluded edge row + * @return the validated half-open edge range + */ + public static EdgeRange fromOffsets(long begin, long end) { + if (begin < 0) { + throw new IllegalArgumentException("Edge range begin must be non-negative: " + begin); + } + if (end < begin) { + throw new IllegalArgumentException( + "Offset values must be monotonic: begin=" + begin + ", end=" + end); + } + return new EdgeRange(begin, end); + } + + /** + * Returns the first included edge row. + * + * @return the first included edge row + */ + public long begin() { + return begin; + } + + /** + * Returns the first excluded edge row. + * + * @return the first excluded edge row + */ + public long end() { + return end; + } + + /** + * Returns the number of selected edge rows. + * + * @return the number of selected edge rows + */ + public long length() { + return end - begin; + } + + /** + * Returns whether this range selects no edge rows. + * + * @return whether the range is empty + */ + public boolean isEmpty() { + return begin == end; + } + + /** + * Returns the half-open range of edge chunks intersecting this edge range. + * + * @param edgeChunkSize a positive number of edge rows per chunk + * @return the chunk range intersecting this edge range + */ + public ChunkRange edgeChunks(long edgeChunkSize) { + long first = ChunkMath.chunkIndex(begin, edgeChunkSize); + if (isEmpty()) { + return new ChunkRange(first, first); + } + return new ChunkRange(first, ChunkMath.chunkCount(end, edgeChunkSize)); + } + + @Override + public boolean equals(Object other) { + if (this == other) { + return true; + } + if (!(other instanceof EdgeRange)) { + return false; + } + EdgeRange that = (EdgeRange) other; + return begin == that.begin && end == that.end; + } + + @Override + public int hashCode() { + return Objects.hash(begin, end); + } + + @Override + public String toString() { + return "EdgeRange[" + begin + ", " + end + ")"; + } +} diff --git a/maven-projects/core/src/main/java/org/apache/graphar/core/OffsetChunk.java b/maven-projects/core/src/main/java/org/apache/graphar/core/OffsetChunk.java new file mode 100644 index 000000000..81932444f --- /dev/null +++ b/maven-projects/core/src/main/java/org/apache/graphar/core/OffsetChunk.java @@ -0,0 +1,114 @@ +/* + * 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.Arrays; +import java.util.Objects; + +/** A validated ordered-layout offset chunk with one more value than local vertices. */ +public final class OffsetChunk { + private final long vertexChunkIndex; + private final long[] offsets; + + private OffsetChunk(long vertexChunkIndex, long[] offsets) { + this.vertexChunkIndex = vertexChunkIndex; + this.offsets = offsets; + } + + /** + * Creates an immutable offset chunk read from the offset file of {@code vertexChunkIndex}. + * Values must start at zero and be non-negative and monotonic. + */ + public static OffsetChunk of(long vertexChunkIndex, long[] offsets) { + if (vertexChunkIndex < 0) { + throw new IllegalArgumentException( + "Vertex chunk index must be non-negative: " + vertexChunkIndex); + } + Objects.requireNonNull(offsets, "Offset values cannot be null."); + if (offsets.length < 2) { + throw new IllegalArgumentException("An offset chunk must contain at least two values."); + } + long[] copy = Arrays.copyOf(offsets, offsets.length); + if (copy[0] != 0) { + throw new IllegalArgumentException("The first offset value must be zero: " + copy[0]); + } + long previous = copy[0]; + for (int index = 1; index < copy.length; index++) { + long current = copy[index]; + if (current < previous) { + throw new IllegalArgumentException( + "Offset values must be monotonic at index " + + index + + ": " + + previous + + " > " + + current); + } + previous = current; + } + return new OffsetChunk(vertexChunkIndex, copy); + } + + /** Returns the vertex chunk this offset chunk was read from. */ + public long vertexChunkIndex() { + return vertexChunkIndex; + } + + /** Returns the number of local vertices represented by this chunk. */ + public long vertexCount() { + return offsets.length - 1L; + } + + /** Resolves the half-open edge range for one local vertex position. */ + public EdgeRange rangeFor(long localVertexIndex) { + if (localVertexIndex < 0 || localVertexIndex >= vertexCount()) { + throw new IllegalArgumentException( + "Local vertex index must be in [0, " + + vertexCount() + + "): " + + localVertexIndex); + } + int index = Math.toIntExact(localVertexIndex); + return EdgeRange.fromOffsets(offsets[index], offsets[index + 1]); + } + + /** Fails if the final offset does not equal the corresponding partition edge count. */ + public void validateEdgeCount(long edgeCount) { + if (edgeCount < 0) { + throw new IllegalArgumentException("Edge count must be non-negative: " + edgeCount); + } + long finalOffset = offsets[offsets.length - 1]; + if (finalOffset != edgeCount) { + throw new IllegalArgumentException( + "Final offset must equal edge count: " + finalOffset + " != " + edgeCount); + } + } + + @Override + public String toString() { + return "OffsetChunk{vertexChunk=" + + vertexChunkIndex + + ", vertexCount=" + + vertexCount() + + ", edgeCount=" + + offsets[offsets.length - 1] + + "}"; + } +} diff --git a/maven-projects/core/src/main/java/org/apache/graphar/core/OffsetLocation.java b/maven-projects/core/src/main/java/org/apache/graphar/core/OffsetLocation.java new file mode 100644 index 000000000..ec2a438d1 --- /dev/null +++ b/maven-projects/core/src/main/java/org/apache/graphar/core/OffsetLocation.java @@ -0,0 +1,89 @@ +/* + * 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.net.URI; +import java.util.Objects; + +/** The offset chunk and pair index required to resolve one ordered-layout vertex. */ +public final class OffsetLocation { + private final long vertexId; + private final long vertexChunkIndex; + private final long offsetIndex; + private final URI offsetChunkUri; + + OffsetLocation(long vertexId, long vertexChunkIndex, long offsetIndex, URI offsetChunkUri) { + this.vertexId = vertexId; + this.vertexChunkIndex = vertexChunkIndex; + this.offsetIndex = offsetIndex; + this.offsetChunkUri = + Objects.requireNonNull(offsetChunkUri, "Offset chunk URI cannot be null."); + } + + public long vertexId() { + return vertexId; + } + + public long vertexChunkIndex() { + return vertexChunkIndex; + } + + /** Returns the first of the two adjacent offset values to read. */ + public long offsetIndex() { + return offsetIndex; + } + + public URI offsetChunkUri() { + return offsetChunkUri; + } + + @Override + public boolean equals(Object other) { + if (this == other) { + return true; + } + if (!(other instanceof OffsetLocation)) { + return false; + } + OffsetLocation that = (OffsetLocation) other; + return vertexId == that.vertexId + && vertexChunkIndex == that.vertexChunkIndex + && offsetIndex == that.offsetIndex + && offsetChunkUri.equals(that.offsetChunkUri); + } + + @Override + public int hashCode() { + return Objects.hash(vertexId, vertexChunkIndex, offsetIndex, offsetChunkUri); + } + + @Override + public String toString() { + return "OffsetLocation{vertexId=" + + vertexId + + ", vertexChunk=" + + vertexChunkIndex + + ", offsetIndex=" + + offsetIndex + + ", offsetChunkUri=" + + offsetChunkUri + + "}"; + } +} diff --git a/maven-projects/core/src/main/java/org/apache/graphar/core/OrderedAdjacencyResolver.java b/maven-projects/core/src/main/java/org/apache/graphar/core/OrderedAdjacencyResolver.java new file mode 100644 index 000000000..6de547cca --- /dev/null +++ b/maven-projects/core/src/main/java/org/apache/graphar/core/OrderedAdjacencyResolver.java @@ -0,0 +1,92 @@ +/* + * 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.net.URI; +import java.util.Objects; +import org.apache.graphar.info.EdgeInfo; +import org.apache.graphar.info.type.AdjListType; + +/** Resolves GraphAr ordered adjacency metadata into offset and edge-chunk locations. */ +public final class OrderedAdjacencyResolver { + private final EdgeInfo edgeInfo; + private final AdjListType adjListType; + private final long vertexChunkSize; + + public OrderedAdjacencyResolver(EdgeInfo edgeInfo, AdjListType adjListType) { + this.edgeInfo = Objects.requireNonNull(edgeInfo, "Edge info cannot be null."); + this.adjListType = + Objects.requireNonNull(adjListType, "Adjacency list type cannot be null."); + if (!adjListType.isOrdered()) { + throw new IllegalArgumentException( + "An ordered adjacency resolver requires an ordered layout: " + adjListType); + } + if (!edgeInfo.hasAdjListType(adjListType)) { + throw new IllegalArgumentException( + "Edge info does not declare adjacency layout: " + adjListType); + } + this.vertexChunkSize = + adjListType == AdjListType.ordered_by_source + ? edgeInfo.getSrcChunkSize() + : edgeInfo.getDstChunkSize(); + ChunkMath.validateChunkSize(vertexChunkSize); + ChunkMath.validateChunkSize(edgeInfo.getChunkSize()); + } + + /** Locates the offset pair that the physical reader must fetch for {@code vertexId}. */ + public OffsetLocation locate(long vertexId) { + long vertexChunkIndex = ChunkMath.chunkIndex(vertexId, vertexChunkSize); + long offsetIndex = ChunkMath.offsetInChunk(vertexId, vertexChunkSize); + URI offsetChunkUri = edgeInfo.getOffsetChunkUri(adjListType, vertexChunkIndex); + return new OffsetLocation(vertexId, vertexChunkIndex, offsetIndex, offsetChunkUri); + } + + /** Combines a vertex location and its two ordered-offset values into exact edge chunks. */ + public ResolvedAdjacency resolve(long vertexId, long offsetBegin, long offsetEnd) { + OffsetLocation offsetLocation = locate(vertexId); + EdgeRange edgeRange = EdgeRange.fromOffsets(offsetBegin, offsetEnd); + return resolved(offsetLocation, edgeRange); + } + + /** Resolves a vertex using a complete, validated offset chunk read by a physical backend. */ + public ResolvedAdjacency resolve(long vertexId, OffsetChunk offsetChunk) { + Objects.requireNonNull(offsetChunk, "Offset chunk cannot be null."); + OffsetLocation offsetLocation = locate(vertexId); + if (offsetChunk.vertexChunkIndex() != offsetLocation.vertexChunkIndex()) { + throw new IllegalArgumentException( + "Offset chunk " + + offsetChunk.vertexChunkIndex() + + " does not hold vertex " + + vertexId + + ", which lives in vertex chunk " + + offsetLocation.vertexChunkIndex()); + } + return resolved(offsetLocation, offsetChunk.rangeFor(offsetLocation.offsetIndex())); + } + + private ResolvedAdjacency resolved(OffsetLocation offsetLocation, EdgeRange edgeRange) { + return new ResolvedAdjacency( + edgeInfo, + adjListType, + offsetLocation, + edgeRange, + edgeRange.edgeChunks(edgeInfo.getChunkSize())); + } +} diff --git a/maven-projects/core/src/main/java/org/apache/graphar/core/ResolvedAdjacency.java b/maven-projects/core/src/main/java/org/apache/graphar/core/ResolvedAdjacency.java new file mode 100644 index 000000000..7d729c05e --- /dev/null +++ b/maven-projects/core/src/main/java/org/apache/graphar/core/ResolvedAdjacency.java @@ -0,0 +1,94 @@ +/* + * 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.net.URI; +import java.util.Objects; +import org.apache.graphar.info.EdgeInfo; +import org.apache.graphar.info.type.AdjListType; + +/** The physical GraphAr chunks selected by one ordered-layout vertex's offset range. */ +public final class ResolvedAdjacency { + private final EdgeInfo edgeInfo; + private final AdjListType adjListType; + private final OffsetLocation offsetLocation; + private final EdgeRange edgeRange; + private final ChunkRange edgeChunks; + + ResolvedAdjacency( + EdgeInfo edgeInfo, + AdjListType adjListType, + OffsetLocation offsetLocation, + EdgeRange edgeRange, + ChunkRange edgeChunks) { + this.edgeInfo = Objects.requireNonNull(edgeInfo, "Edge info cannot be null."); + this.adjListType = + Objects.requireNonNull(adjListType, "Adjacency list type cannot be null."); + this.offsetLocation = + Objects.requireNonNull(offsetLocation, "Offset location cannot be null."); + this.edgeRange = Objects.requireNonNull(edgeRange, "Edge range cannot be null."); + this.edgeChunks = Objects.requireNonNull(edgeChunks, "Edge chunk range cannot be null."); + } + + public OffsetLocation offsetLocation() { + return offsetLocation; + } + + public EdgeRange edgeRange() { + return edgeRange; + } + + public ChunkRange edgeChunks() { + return edgeChunks; + } + + public URI edgeCountUri() { + return edgeInfo.getEdgesNumFileUri(adjListType, offsetLocation.vertexChunkIndex()); + } + + /** Returns an adjacency URI only for an edge chunk selected by this result. */ + public URI adjacencyChunkUri(long edgeChunkIndex) { + if (!edgeChunks.contains(edgeChunkIndex)) { + throw new IllegalArgumentException( + "Edge chunk " + + edgeChunkIndex + + " is outside the resolved range [" + + edgeChunks.begin() + + ", " + + edgeChunks.end() + + ")"); + } + return edgeInfo.getAdjacentListChunkUri( + adjListType, offsetLocation.vertexChunkIndex(), edgeChunkIndex); + } + + @Override + public String toString() { + return "ResolvedAdjacency{adjListType=" + + adjListType + + ", offsetLocation=" + + offsetLocation + + ", edgeRange=" + + edgeRange + + ", edgeChunks=" + + edgeChunks + + "}"; + } +} diff --git a/maven-projects/core/src/test/java/org/apache/graphar/core/ChunkRangeTest.java b/maven-projects/core/src/test/java/org/apache/graphar/core/ChunkRangeTest.java new file mode 100644 index 000000000..050c58d02 --- /dev/null +++ b/maven-projects/core/src/test/java/org/apache/graphar/core/ChunkRangeTest.java @@ -0,0 +1,75 @@ +/* + * 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 static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertFalse; +import static org.junit.Assert.assertTrue; + +import org.junit.Test; + +/** Tests GraphAr half-open chunk and edge range arithmetic. */ +public class ChunkRangeTest { + @Test + public void derivesChunkPositionsAndCountsWithoutOverflow() { + assertEquals(2L, ChunkMath.chunkIndex(299L, 100L)); + assertEquals(99L, ChunkMath.offsetInChunk(299L, 100L)); + assertEquals(0L, ChunkMath.chunkCount(0L, 100L)); + assertEquals(3L, ChunkMath.chunkCount(201L, 100L)); + assertEquals(Long.MAX_VALUE, ChunkMath.chunkCount(Long.MAX_VALUE, 1L)); + } + + @Test + public void choosesTheChunkContainingTheLastIncludedEdge() { + EdgeRange range = EdgeRange.fromOffsets(1008L, 1061L); + + ChunkRange chunks = range.edgeChunks(1024L); + + assertEquals(0L, chunks.begin()); + assertEquals(2L, chunks.end()); + assertTrue(chunks.contains(0L)); + assertTrue(chunks.contains(1L)); + assertFalse(chunks.contains(2L)); + } + + @Test + public void keepsEmptyRangesAtTheirBeginChunk() { + ChunkRange chunks = EdgeRange.fromOffsets(2048L, 2048L).edgeChunks(1024L); + + assertEquals(2L, chunks.begin()); + assertEquals(2L, chunks.end()); + assertTrue(chunks.isEmpty()); + } + + @Test(expected = IllegalArgumentException.class) + public void rejectsNegativeElementIdentifiers() { + ChunkMath.chunkIndex(-1L, 1L); + } + + @Test(expected = IllegalArgumentException.class) + public void rejectsNonPositiveChunkSizes() { + EdgeRange.fromOffsets(0L, 1L).edgeChunks(0L); + } + + @Test(expected = IllegalArgumentException.class) + public void rejectsDecreasingOffsetPairs() { + EdgeRange.fromOffsets(2L, 1L); + } +} diff --git a/maven-projects/core/src/test/java/org/apache/graphar/core/OrderedAdjacencyResolverFixtureTest.java b/maven-projects/core/src/test/java/org/apache/graphar/core/OrderedAdjacencyResolverFixtureTest.java new file mode 100644 index 000000000..863a774aa --- /dev/null +++ b/maven-projects/core/src/test/java/org/apache/graphar/core/OrderedAdjacencyResolverFixtureTest.java @@ -0,0 +1,179 @@ +/* + * 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 static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertFalse; +import static org.junit.Assert.assertNotEquals; +import static org.junit.Assert.assertThrows; +import static org.junit.Assert.assertTrue; + +import java.net.URI; +import java.nio.file.Files; +import java.nio.file.Path; +import org.apache.graphar.info.EdgeInfo; +import org.apache.graphar.info.loader.impl.LocalFileSystemStringGraphInfoLoader; +import org.apache.graphar.info.type.AdjListType; +import org.junit.Assume; +import org.junit.Test; + +/** Verifies ordered adjacency resolution against the canonical LDBC GraphAr fixture. */ +public class OrderedAdjacencyResolverFixtureTest { + @Test + public void resolvesLdbcOffsetPairAcrossTwoCanonicalAdjacencyChunks() throws Exception { + Path fixtureRoot = canonicalFixtureRoot(); + Assume.assumeTrue( + "The canonical GraphAr testing fixtures are unavailable." + + " Set GAR_TEST_DATA to the testing directory to run this test.", + fixtureRoot != null); + EdgeInfo edgeInfo = + new LocalFileSystemStringGraphInfoLoader() + .loadEdgeInfo(fixtureRoot.resolve("person_knows_person.edge.yml").toUri()); + OrderedAdjacencyResolver resolver = + new OrderedAdjacencyResolver(edgeInfo, AdjListType.ordered_by_source); + OffsetChunk offsets = OffsetChunk.of(2, offsetsForCanonicalVertex297()); + + assertEquals(100, offsets.vertexCount()); + offsets.validateEdgeCount(1077); + + ResolvedAdjacency resolved = resolver.resolve(297, offsets); + + assertEquals( + new OffsetLocation( + 297, + 2, + 97, + URI.create("edge/person_knows_person/ordered_by_source/offset/chunk2")), + resolved.offsetLocation()); + assertEquals(EdgeRange.fromOffsets(1008, 1061), resolved.edgeRange()); + assertEquals(new ChunkRange(0, 2), resolved.edgeChunks()); + assertEquals( + URI.create("edge/person_knows_person/ordered_by_source/adj_list/part2/chunk0"), + resolved.adjacencyChunkUri(0)); + assertEquals( + URI.create("edge/person_knows_person/ordered_by_source/adj_list/part2/chunk1"), + resolved.adjacencyChunkUri(1)); + assertEquals( + URI.create("edge/person_knows_person/ordered_by_source/edge_count2"), + resolved.edgeCountUri()); + assertFalse(resolved.edgeChunks().isEmpty()); + assertTrue( + Files.isRegularFile( + fixtureRoot.resolve( + "edge/person_knows_person/ordered_by_source/adj_list/part2/chunk0"))); + assertTrue( + Files.isRegularFile( + fixtureRoot.resolve( + "edge/person_knows_person/ordered_by_source/adj_list/part2/chunk1"))); + } + + @Test + public void preservesLongAndHalfOpenBoundaries() { + assertEquals(2, ChunkMath.chunkIndex(299, 100)); + assertEquals(99, ChunkMath.offsetInChunk(299, 100)); + assertEquals(3, ChunkMath.chunkCount(201, 100)); + assertEquals(Long.MAX_VALUE, ChunkMath.chunkCount(Long.MAX_VALUE, 1)); + + EdgeRange range = EdgeRange.fromOffsets(1024, 1025); + assertEquals(1, range.edgeChunks(1024).begin()); + assertEquals(2, range.edgeChunks(1024).end()); + assertFalse(range.edgeChunks(1024).isEmpty()); + assertEquals(1, EdgeRange.fromOffsets(1024, 1024).edgeChunks(1024).begin()); + assertEquals(1, EdgeRange.fromOffsets(1024, 1024).edgeChunks(1024).end()); + + assertThrows(IllegalArgumentException.class, () -> ChunkMath.chunkIndex(-1, 1)); + assertThrows(IllegalArgumentException.class, () -> EdgeRange.fromOffsets(5, 4)); + assertThrows(IllegalArgumentException.class, () -> OffsetChunk.of(0, new long[] {1, 1})); + assertThrows(IllegalArgumentException.class, () -> OffsetChunk.of(0, new long[] {0, 2, 1})); + assertThrows(IllegalArgumentException.class, () -> OffsetChunk.of(-1, new long[] {0, 1})); + } + + @Test + public void rejectsAnOffsetChunkReadFromAnotherVertexChunk() throws Exception { + Path fixtureRoot = canonicalFixtureRoot(); + Assume.assumeTrue( + "The canonical GraphAr testing fixtures are unavailable." + + " Set GAR_TEST_DATA to the testing directory to run this test.", + fixtureRoot != null); + EdgeInfo edgeInfo = + new LocalFileSystemStringGraphInfoLoader() + .loadEdgeInfo(fixtureRoot.resolve("person_knows_person.edge.yml").toUri()); + OrderedAdjacencyResolver resolver = + new OrderedAdjacencyResolver(edgeInfo, AdjListType.ordered_by_source); + OffsetChunk wrongChunk = OffsetChunk.of(1, offsetsForCanonicalVertex297()); + + IllegalArgumentException failure = + assertThrows( + IllegalArgumentException.class, () -> resolver.resolve(297, wrongChunk)); + + assertTrue(failure.getMessage(), failure.getMessage().contains("vertex chunk 2")); + } + + @Test + public void describesRangesAsValues() { + assertEquals(new ChunkRange(0, 2), new ChunkRange(0, 2)); + assertEquals(new ChunkRange(0, 2).hashCode(), new ChunkRange(0, 2).hashCode()); + assertNotEquals(new ChunkRange(0, 2), new ChunkRange(0, 3)); + assertEquals(EdgeRange.fromOffsets(3, 7), EdgeRange.fromOffsets(3, 7)); + assertNotEquals(EdgeRange.fromOffsets(3, 7), EdgeRange.fromOffsets(3, 8)); + assertEquals("ChunkRange[0, 2)", new ChunkRange(0, 2).toString()); + assertEquals("EdgeRange[3, 7)", EdgeRange.fromOffsets(3, 7).toString()); + } + + /** + * Returns the parquet LDBC fixture directory, or {@code null} when the canonical testing data + * is unavailable. Resolution follows the same order as the metadata module tests: the {@code + * GAR_TEST_DATA} environment variable, the {@code gar.test.data} system property, then the + * testing directory of a full checkout. + */ + private static Path canonicalFixtureRoot() { + String configured = System.getenv("GAR_TEST_DATA"); + if (configured == null) { + configured = System.getProperty("gar.test.data"); + } + if (configured != null) { + Path candidate = Path.of(configured, "ldbc_sample", "parquet"); + return isFixtureRoot(candidate) ? candidate : null; + } + for (String relative : new String[] {"../../testing", "../testing", "testing"}) { + Path candidate = Path.of(relative, "ldbc_sample", "parquet"); + if (isFixtureRoot(candidate)) { + return candidate; + } + } + return null; + } + + private static boolean isFixtureRoot(Path candidate) { + return Files.isRegularFile(candidate.resolve("person_knows_person.edge.yml")); + } + + private static long[] offsetsForCanonicalVertex297() { + long[] offsets = new long[101]; + for (int index = 1; index < 97; index++) { + offsets[index] = index * 10L; + } + offsets[97] = 1008; + offsets[98] = 1061; + offsets[99] = 1061; + offsets[100] = 1077; + return offsets; + } +} diff --git a/maven-projects/pom.xml b/maven-projects/pom.xml index 5ea0b89c5..1ccf661bc 100644 --- a/maven-projects/pom.xml +++ b/maven-projects/pom.xml @@ -82,6 +82,7 @@ storage-local io-api storage-s3 + core