jason810496 commented on code in PR #72019: URL: https://github.com/apache/airflow/pull/72019#discussion_r3841837315
########## java-sdk/adr/0001-mixed-lang-dag-interface.md: ########## @@ -0,0 +1,129 @@ +<!-- + 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. + --> + +# ADR-0001: Mixed-Lang Dag — Java Task Interface + +## Status + +Proposed + +## Context + +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`. + +This ADR is scoped to the **Java call-site interface only** — the shape of the argument-binding +spec itself, how it is materialized, and how it travels over the wire is the protocol-level +decision recorded in +[`airflow-core/adr/lang-sdk/0007-taskflow-across-language-boundary.md`](../../airflow-core/adr/lang-sdk/0007-taskflow-across-language-boundary.md). +This ADR only answers: given that spec, what does the Java code a user writes look like? + +## Decision + +We support 4 syntaxes for the TaskFlow binding: + +### 1. Annotation based with positional injection + +```java [email protected](id = "score") +public long score(Client client, long rows, double threshold) { ... } +``` + +### 2. Annotation based with explicit struct + +```java +public static class ReportInput implements TaskInput { + @ArgName("run_label") + public String runLabel; + + public long transformed; +} + [email protected](id = "report") +public void report(ReportInput input) { + log.log(INFO, "Report {0} for transformed value {1}", input.runLabel, input.transformed); + if (!"nightly".equals(input.runLabel)) { + throw new RuntimeException("expected run label 'nightly' but got " + input.runLabel); + } +} +``` + +### 3. Interface based with explicit struct + +```java +public static class SummarizeInput implements TaskInput { + @ArgName("region_code") + public String region; + + public long transformed; + } + + // summarize(region_code=..., transformed=...) is called with keyword + // arguments, which bind to the bundle's fields by name. + public static class Summarize implements InputTask<SummarizeInput> { + public void execute(@NotNull Context context, Client client, SummarizeInput input) { + log.log( + INFO, "Summarize region {0} for transformed value {1}", input.region, input.transformed); + if (!"emea".equals(input.region)) { + throw new RuntimeException("expected region 'emea' but got " + input.region); + } + } + } +``` + +### 4. Interface based with `TaskArgs` getter + +```java +public static class Transform implements InputTask<TaskArgs> { + public void execute(@NotNull Context context, Client client, TaskArgs args) { + var extracted = args.require(0, Long.class); + var threshold = args.get(1, Double.class); // null when it resolves to nothing + log.log(INFO, "Got extracted value from the bound argument: {0}", extracted); + // ... + } +} +``` Review Comment: Remove `TaskArgs`. Support `context.arg_bindings` instead of `TaskArgs` and provide example of pulling XCom via `client` with `arg_bindings`. e.g. ``` arguments = [] for arg in context.arg_bindings: if arg.type == XCom: arguments.append(client.getXCom(arg.taskId)); else: arguments.append(arg.value) ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
