Java SDK: Honor TaskFlow arg bindings sent by the supervisor

[jason810496]

• next: Java SDK: Draw a Java-authored Dag's edges with before and after #73594

Why

The Python @task.stub call site already defines task data flow. Java tasks should consume those bindings directly instead of repeating upstream IDs with @Builder.XCom.

The Java call site is settled by ADR-0001 (merged in #72019); this PR implements its binding half. The wire contract is ADR-0007.

Example

Three authoring syntaxes, exactly the three ADR-0001 specifies. All resolve to the same bindings.

1. Annotation based with positional injection

@Builder.TaskHandler(dag = "etl", task = "score")
public long score(Client client, long rows, double threshold, List<String> regions) { ... }

2. Annotation based with an explicit struct

report(run_label=..., transformed=...) binds with nothing declared — names match ignoring case and underscores:

public static class ReportInput implements TaskInput {
  public String runLabel; // binds run_label through the fold
  public long transformed;
}

@Builder.TaskHandler(dag = "etl", task = "report")
public void report(ReportInput input) { ... }

3. Interface based with an explicit TaskInput

public static class SummarizeInput implements TaskInput {
  // Pinned so the field can be called region. Or drop it: public String regionCode;
  @ArgName("region_code")
  public String region;

  public long transformed;
}

public static class Summarize implements InputTask<SummarizeInput> {
  public void execute(@NotNull Context context, Client client, SummarizeInput input) { ... }
}

Syntax 1 compiles to this — copied out of the example project's generated sources:

public static final class ConsumeDoubleList implements Task {
  @Override
  public void execute(Context context, Client client) throws Exception {
    TaskArgs args = TaskArgs.of(context, client);
    List<Double> values = args.get(0, new TypeRef<List<Double>>() {});
    new XComCastingExample().consumeDoubleList(values);
  }
}

How

• @Builder.TaskHandler(dag, task) names the pair a handler binds to, rather than @Builder.Task(id) inside a @Builder.Dag class. Python declares the task and Java supplies only its body, so the two are different things and should not share a name. @Builder.Dag/@Builder.Task are left for a Dag authored in Java (Java SDK: Declare a Dag's task graph with @Builder.Deps #71189).
• Bundle is created and registered into: register takes the class a handler lives on.
• Data parameters bind by position; injected Client/Context take no position.
• Keyword arguments bind by name through one TaskInput. A task declares flat parameters or one TaskInput, never both.
• Names match ignoring case and underscores — the same fold Go and TS use, so one Python signature binds identically in all three SDKs with nothing declared. @ArgName is for what the fold cannot reach (a Python keyword, an unusable identifier) and is matched literally.
• Declared type arguments survive the decode, so a List<String> parameter or field does not arrive as List<LinkedHashMap>.
• TaskArgs is internal — org.apache.airflow.sdk.internal, not a TaskInput, emitted by the processor only. InputTask<TaskArgs> is a compile error; interface tasks declare a TaskInput.
• Missing reference or boxed values become null; primitive inputs fail with MissingXComException, naming the stub argument.
• @Builder.XCom is removed, keeping the Python call site as the single source of data-flow wiring.

Follow-up

ADR-0001 writes the generic read as Jackson's TypeReference<T>. This PR ships an SDK-owned TypeRef<T> instead, because Jackson is an implementation dependency and exposing it would put Jackson on every consumer's compile classpath. Promoting jackson-core to api and using TypeReference directly is worth doing on its own — it is a deliberate next step, not a limitation this PR works around.

ADR-0001's examples are also over-annotated under the fold: @ArgName("run_label") on a runLabel field is now redundant. Worth a pass over the ADR.

---

Was generative AI tooling used to co-author this PR?

• Yes, with help of Claude Code Opus 5 and Codex (GPT-5) following the guidelines

[FrankYang0529]

Overall LGTM. Thanks for the PR.

[jason810496]

Thanks for the review, I just addressed the comments.

[henry3260]

Thanks, just leave few concerns

[jason810496]

Thanks for the review.

[henry3260]

Thanks for solving my comments :)

[jason810496]

Nice catch, both concerns are valid. TS and Go side did validate your findings.
I addressed them all in the latest commit, thanks.

Additionally, the latest commit filled the gap of mixed language task TaskFlow binding semantic like #73648.

[henry3260]

Thanks for the update!