apache / apache/incubator-graphar

[FEATURE][Java] Add dependency-light storage API and local adapter

Open
#953 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
373
Forks
93
Avg merge
7d 21h
Merged PRs (30d)
7

Description

## Describe the enhancement requested

Add a dependency-light pure-Java storage boundary as the verified Phase 2 prerequisite for the Java reader/writer roadmap. The API isolates URI-backed byte access from GraphAr metadata/layout and from physical formats, so a future Parquet backend can consume files without importing Parquet, Hadoop, Arrow, or object-store dependencies into `graphar-info`.

Component(s): Java

## Scope

- `graphar-storage-api`: `Storage`, `InputFile`, `OutputFile`, `SeekableInput`, and `PositionOutput` contracts;
- `graphar-storage-local`: `file:` URI implementation with seek, bounded reads, create-vs-overwrite semantics, and byte positions;
- tests for heap/direct `ByteBuffer`, seek/readFully, overwrite safety, and unsupported URI rejection.

## Non-goals

No GraphAr layout resolution, metadata change, Parquet/ORC decoder, Hadoop/S3 adapter, Arrow public type, predicate/query API, reader, or writer.

## Compatibility and acceptance

The API must remain Java 11-compatible and add no runtime dependency to `graphar-info`. A local adapter must preserve byte content and positions, reject non-file URIs explicitly, and pass repository pre-commit plus the storage reactor's devcontainer `clean verify`.

## Dependencies and evidence

Relates to reader/writer umbrella #947 and architecture umbrella #756. Product-fork evidence is keksmd/incubator-graphar#3: `pre-commit run --files` passed and the declared devcontainer produced storage API/local artifacts with 7/7 JUnit tests.

Contributor guide

Open the contributing guide

Research direction

Start with the graphar-storage-api and graphar-storage-local component scopes, then review the stated Storage, InputFile, OutputFile, SeekableInput, and PositionOutput contracts and their local file: behavior. Run the repository pre-commit checks and the storage reactor devcontainer clean verify; done means Java 11 compatibility, no graphar-info runtime dependency, explicit non-file URI rejection, preserved bytes and positions, and passing JUnit coverage.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.