apache / apache/incubator-graphar
[FEATURE][Java] Add dependency-light storage API and local adapter
- 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
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