[Java][native] support InputStream mappings for binary payloads#24295
Draft
wingwogus wants to merge 4 commits into
Draft
[Java][native] support InputStream mappings for binary payloads#24295wingwogus wants to merge 4 commits into
wingwogus wants to merge 4 commits into
Conversation
Java native generation previously kept File-oriented response handling and Jackson request serialization even when file and binary types were explicitly mapped to java.io.InputStream. Mark only resolved native operations, publish mapped request streams directly, and transfer returned response-stream ownership past existing finally cleanup. Constraint: Streaming behavior must be driven by the resolved java.io.InputStream mapping and operation.bodyParam, not isFile/isBinary flags or a new option. Constraint: Existing native File downloads, JSON serialization, gzip wrapping, and finally cleanup must remain intact. Rejected: Infer streaming from isFile/isBinary | would change default File behavior independently of configured mappings. Confidence: high Scope-risk: narrow Directive: Keep response ownership transfer paired with nulling localVarResponseBody before the existing finally block. Tested: JavaClientCodegenTest issue24057 sync/async/control cases plus native empty-response sync/async neighbors. Tested: Generated sync and async native Maven clients packaged with file/binary=InputStream and InputStream=java.io.InputStream mappings. Not-tested: Full repository test suite.
Native raw-stream ownership is valid only when the OpenAPI operation remains classified as binary or file and its resolved Java type is InputStream. Preserve normal Jackson request and response handling for non-binary schemas that users map to InputStream. Constraint: Raw stream paths require both original binary/file metadata and an exact java.io.InputStream resolution Constraint: The existing native template behavior remains unchanged Rejected: Gate only on resolved InputStream type | mapped JSON incorrectly bypasses serialization Confidence: high Scope-risk: narrow Reversibility: clean Directive: Do not remove the binary/file metadata guard without testing mapped JSON request and response schemas Tested: Genuine RED/GREEN regression; 6 focused issue and neighbor tests; fresh sync and async generated clients packaged with Maven Not-tested: Full repository suite and live HTTP integration
Native InputStream responses need an explicit delivery owner because CompletableFuture cancellation does not reliably stop an already-running dependent action. Bridge both async public surfaces, close results that lose delivery races, and propagate cancellation only to the HTTP transport so processing can perform cleanup. Request streams are atomically one-shot for plain and gzip publishers, and gzip cleanup is idempotent after EOF. Constraint: JDK BodyPublishers.ofInputStream may request a fresh stream for repeated subscriptions; the existing API accepts one caller-owned InputStream, not a reopenable supplier. Rejected: Reuse the same request InputStream on retry | a consumed or closed stream can silently publish empty data. Confidence: high Scope-risk: moderate Reversibility: clean Directive: Preserve explicit async delivery bridges; cancelling the processing future can bypass undeliverable-stream cleanup. Tested: Focused JavaClientCodegenTest issue/neighbor scope 9/9; deterministic async ownership and plain/gzip replay runtime harness; gzip exact-close RED/GREEN; generated sync, async, and gzip Maven packages. Not-tested: Full repository test suite; live network redirect/retry behavior.
The cancellation runtime test previously observed cleanup through the inner WithHttpInfo bridge, leaving the convenience future's own lost-delivery branch unexecuted. Encapsulate convenience delivery in its returned future and deterministically invoke that exact path after cancellation with a close-tracking stream. Constraint: The normal cancellation path also cancels WithHttpInfo, so the outer complete(false) race cannot be isolated by transport timing alone. Rejected: Rely on source assertions for the outer branch | they do not execute ownership cleanup. Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep convenience response delivery routed through completeResponse so its undeliverable-stream close remains runtime-testable. Tested: Isolated async ownership runtime test RED on missing delivery method, then GREEN with tests=1 failures=0 errors=0; generated source compiled dynamically at Java 11 release. Not-tested: Full repository test suite; live network transport.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #24057.
Summary
file=InputStreamandbinary=InputStreammappings in the Javanativeclient for binary responses and raw request bodies.InputStreamrequest bodies without Jackson serialization, including the gzip path.Filebehavior and JSON serialization/deserialization unchanged.Implementation notes
The generator derives native-only template flags after type resolution. The stream path is selected only when the original OpenAPI schema is binary/file and the resolved Java type is
java.io.InputStream; mapping an ordinary JSON schema toInputStreamtherefore continues to use Jackson.The native templates transfer response-stream ownership before their cleanup blocks run. Async delivery also propagates cancellation to the transport and closes a stream that loses a delivery race. Request publishers are one-shot and thread-safe, including gzip, so a retry cannot read a consumed stream or double-close the normal source path.
@bbdouglas, this touches the Java 11 native HTTP client templates.
Verification
Filepath and a non-binary JSON mapping remain on their existing branches.checkstyle:checkpassed formodules/openapi-generator.git diff --checkpassed.The full repository test matrix was not run locally; CI is expected to provide the broader generator/sample coverage.
PR checklist
Summary by cubic
Adds support for explicit
file=InputStreamandbinary=InputStreammappings in the Javanativeclient, streaming binary responses and raw request bodies asjava.io.InputStreaminstead of temp files or JSON. Keeps defaultFiledownloads and JSON handling unchanged; fixes #24057.java.io.InputStreamresponses directly when the schema is binary/file and the resolved type isjava.io.InputStream; transfer ownership to the caller and close undeliverable streams on async cancellation.InputStreamrequest bodies directly (plain andgzip) via one‑shot, thread‑safe publishers; skip Jackson serialization.InputStreamkeep normal JSON serialization/deserialization.Written for commit a5b4028. Summary will update on new commits.