docs(examples): standardize annotated file workers

Author: v1r3n

README.md

@@ -259,7 +259,7 @@ public class Workers {
 }
 ```
 
-**Start workers** with `TaskRunnerConfigurer` or `WorkflowExecutor`:
+**Start workers** with `TaskRunnerConfigurer` or `AnnotatedWorkerExecutor`:
 
 ```java
 // Option 1: Using TaskRunnerConfigurer
@@ -272,9 +272,9 @@ TaskRunnerConfigurer configurer = new TaskRunnerConfigurer.Builder(
 .build();
 configurer.init();
 
-// Option 2: Using WorkflowExecutor (auto-discovers @WorkerTask annotations)
-WorkflowExecutor executor = new WorkflowExecutor(client, 10);
-executor.initWorkers("com.mycompany.workers");  // Package to scan for @WorkerTask
+// Option 2: Register dependency-injected @WorkerTask instances
+AnnotatedWorkerExecutor executor = new AnnotatedWorkerExecutor(taskClient);
+executor.initWorkersFromInstances(List.of(new Workers()));
 ```
 
 **Worker Design Principles:**

docs/file-client.md

@@ -122,84 +122,54 @@ files.download(workflowId, modelHandle, existing);
 
 The download first goes to a unique sibling `.part` file. Only a complete transfer atomically replaces `current-model.bin`. Failure removes the partial file and preserves the existing destination. A filesystem that cannot perform atomic replacement is rejected explicitly.
 
-## Raw worker example
+## Recommended annotated worker pattern
 
 ```java
-public final class ConvertWorker implements Worker {
+public final class ConvertWorker {
     private final FileClient files;
 
     public ConvertWorker(FileClient files) {
         this.files = files;
     }
 
-    @Override
-    public String getTaskDefName() {
-        return "convert_document";
+    public static class ConvertInput {
+        public String document;
     }
 
-    @Override
-    public TaskResult execute(Task task) {
-        TaskResult result = new TaskResult(task);
-        Path input = null;
-        Path output = null;
+    @WorkerTask("convert_document")
+    public @OutputParam("document") String convert(
+            ConvertInput input,
+            @WorkflowInstanceIdInputParam String workflowId) throws IOException {
+        Path source = Files.createTempFile("document-", ".bin");
+        Path output = Files.createTempFile("converted-", ".pdf");
         try {
-            String workflowId = task.getWorkflowInstanceId();
-            String inputHandle = (String) task.getInputData().get("document");
-            input = Files.createTempFile("document-", ".bin");
-            output = Files.createTempFile("converted-", ".pdf");
-
-            files.download(workflowId, inputHandle, input);
-            convertToPdf(input, output);
-
-            String outputHandle = files.upload(
+            files.download(workflowId, input.document, source);
+            convertToPdf(source, output);
+            return files.upload(
                     workflowId,
                     output,
                     new FileUploadOptions()
                             .setFileName("converted.pdf")
-                            .setContentType("application/pdf")
-                            .setTaskId(task.getTaskId()));
-
-            result.setStatus(TaskResult.Status.COMPLETED);
-            result.addOutputData("document", outputHandle);
-        } catch (Exception e) {
-            result.setStatus(TaskResult.Status.FAILED);
-            result.setReasonForIncompletion(e.getMessage());
+                            .setContentType("application/pdf"));
         } finally {
-            deleteQuietly(input);
-            deleteQuietly(output);
+            Files.deleteIfExists(source);
+            Files.deleteIfExists(output);
         }
-        return result;
     }
 }
 ```
 
-The task input and output are strings. No task-runner file integration is required.
+`@WorkerTask` names the `SIMPLE` task, the unannotated POJO receives the full resolved input map, `@WorkflowInstanceIdInputParam` supplies the workflow context required by `FileClient`, and `@OutputParam` maps the returned handle to `output.document`. Thrown exceptions become failed task results.
 
-## Annotated worker example
+Register already-constructed worker instances so normal constructor injection continues to work:
 
 ```java
-public record ConvertInput(String document) {}
-
-@WorkerTask("convert_document")
-public @OutputParam("document") String convert(
-        ConvertInput input,
-        @WorkflowInstanceIdInputParam String workflowId) throws IOException {
-    Path source = Files.createTempFile("document-", ".bin");
-    Path output = Files.createTempFile("converted-", ".pdf");
-    try {
-        files.download(workflowId, input.document(), source);
-        convertToPdf(source, output);
-        return files.upload(
-                workflowId,
-                output,
-                new FileUploadOptions().setContentType("application/pdf"));
-    } finally {
-        Files.deleteIfExists(source);
-        Files.deleteIfExists(output);
-    }
-}
+AnnotatedWorkerExecutor workers = new AnnotatedWorkerExecutor(taskClient);
+workers.initWorkersFromInstances(List.of(new ConvertWorker(files)));
 ```
 
+The annotation value must exactly match both the workflow task's `name` and a registered task definition. The task input and output remain plain strings; no task-runner file integration is required. Implement the lower-level `Worker` interface only when the method-binding model is insufficient and direct access to the full `Task` or `TaskResult` is necessary.
+
 ## Retry and security behavior
 
 - A new signed URL is requested before every retry.

examples/README.md

@@ -30,7 +30,7 @@ See [`manifest.json`](manifest.json) for per-example metadata: category, workflo
 
 | Example | Description |
 |---|---|
-| [media-transcoder](file-storage/media-transcoder/) | Complete `FileClient` workflow covering path and stream uploads, metadata, downloads, raw and annotated workers, handle passing, and automatic multipart selection. |
+| [media-transcoder](file-storage/media-transcoder/) | Complete `FileClient` workflow covering path and stream uploads, metadata, downloads, a consistent `@WorkerTask` pattern, handle passing, and automatic multipart selection. |
 
 ---
 

examples/file-storage/media-transcoder/README.md

@@ -6,15 +6,71 @@ This example passes videos, thumbnails, and a JSON manifest through a workflow a
 
 | Case | Source |
 |---|---|
-| Upload a caller-owned `InputStream` with required filename and content type | [`UploadPrimaryVideoWorker.java`](src/main/java/io/conductor/example/mediatranscoder/workers/UploadPrimaryVideoWorker.java) |
-| Download a handle, process the file, and upload a `Path` from an annotated worker | [`TranscodeWorker.java`](src/main/java/io/conductor/example/mediatranscoder/workers/TranscodeWorker.java) |
-| Download and upload from a raw `Worker`, including task ID metadata | [`ThumbnailWorker.java`](src/main/java/io/conductor/example/mediatranscoder/workers/ThumbnailWorker.java) |
-| Read metadata and download before producing another handle | [`ManifestWorker.java`](src/main/java/io/conductor/example/mediatranscoder/workers/ManifestWorker.java) |
+| Upload a caller-owned `InputStream` with required filename and content type | Annotated [`UploadPrimaryVideoWorker.java`](src/main/java/io/conductor/example/mediatranscoder/workers/UploadPrimaryVideoWorker.java) |
+| Download a handle, process the file, and upload a `Path` | Annotated [`TranscodeWorker.java`](src/main/java/io/conductor/example/mediatranscoder/workers/TranscodeWorker.java) |
+| Download and upload a second derived file in a parallel workflow branch | Annotated [`ThumbnailWorker.java`](src/main/java/io/conductor/example/mediatranscoder/workers/ThumbnailWorker.java) |
+| Read metadata and download before producing another handle | Annotated [`ManifestWorker.java`](src/main/java/io/conductor/example/mediatranscoder/workers/ManifestWorker.java) |
 | Every public `FileClient` overload in small copyable methods | [`FileClientUsage.java`](src/main/java/io/conductor/example/mediatranscoder/FileClientUsage.java) |
 | Pass only handle strings between sequential and parallel tasks | [`media_transcode.json`](src/main/resources/workflow/media_transcode.json) |
 
 Large `Path` uploads use the same call shown in the workers. `FileClient` automatically selects multipart for S3 and Azure when the configured threshold is exceeded; GCS and local storage use one request.
 
+## Annotated worker pattern
+
+Every worker follows the same four-part pattern from [`WorkerTask.java`](../../../conductor-client/src/main/java/com/netflix/conductor/sdk/workflow/task/WorkerTask.java):
+
+1. Inject `FileClient` into a plain Java object.
+2. Put the workflow task name on a method with `@WorkerTask`.
+3. Receive the resolved task input as a typed object and workflow context with `@WorkflowInstanceIdInputParam`.
+4. Return the handle string and use `@OutputParam` to name the task output.
+
+```java
+public final class TranscodeWorker {
+    private final FileClient files;
+
+    public TranscodeWorker(FileClient files) {
+        this.files = files;
+    }
+
+    public static class TranscodeInput {
+        public String primary_video;
+        public String resolution;
+    }
+
+    @WorkerTask("transcode_video")
+    public @OutputParam("output_file") String transcode(
+            TranscodeInput input,
+            @WorkflowInstanceIdInputParam String workflowId) throws IOException {
+        Path source = Files.createTempFile("source-", ".mov");
+        Path output = Files.createTempFile("transcoded-", ".mp4");
+        try {
+            files.download(workflowId, input.primary_video, source);
+            transcode(source, output, input.resolution);
+            return files.upload(
+                    workflowId,
+                    output,
+                    new FileUploadOptions().setContentType("video/mp4"));
+        } finally {
+            Files.deleteIfExists(source);
+            Files.deleteIfExists(output);
+        }
+    }
+}
+```
+
+Register dependency-injected instances directly. `AnnotatedWorkerExecutor` discovers the annotated methods, binds task inputs, maps return values to task outputs, and converts thrown exceptions into failed task results:
+
+```java
+AnnotatedWorkerExecutor workers = new AnnotatedWorkerExecutor(taskClient);
+workers.initWorkersFromInstances(List.of(
+        new UploadPrimaryVideoWorker(fileClient),
+        new TranscodeWorker(fileClient),
+        new ThumbnailWorker(fileClient),
+        new ManifestWorker(fileClient)));
+```
+
+The annotation value must exactly match the `name` of the corresponding `SIMPLE` task and its registered task definition. This application checks all four task definitions before starting the workflow, so a missing worker definition cannot silently leave the workflow queued.
+
 ## Prerequisites
 
 - Java 21 and Maven 3.8+

examples/file-storage/media-transcoder/src/main/java/io/conductor/example/mediatranscoder/MediaTranscoderApp.java

@@ -20,18 +20,16 @@
 import java.util.Set;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
-import com.netflix.conductor.client.automator.TaskRunnerConfigurer;
 import com.netflix.conductor.client.http.ConductorClient;
 import com.netflix.conductor.client.http.MetadataClient;
 import com.netflix.conductor.client.http.TaskClient;
 import com.netflix.conductor.client.http.WorkflowClient;
-import com.netflix.conductor.client.worker.Worker;
 import com.netflix.conductor.common.metadata.tasks.TaskDef;
 import com.netflix.conductor.common.metadata.tasks.TaskDef.RetryLogic;
 import com.netflix.conductor.common.metadata.workflow.StartWorkflowRequest;
 import com.netflix.conductor.common.metadata.workflow.WorkflowDef;
 import com.netflix.conductor.common.run.Workflow;
-import com.netflix.conductor.sdk.workflow.executor.task.AnnotatedWorker;
+import com.netflix.conductor.sdk.workflow.executor.task.AnnotatedWorkerExecutor;
 import io.conductor.example.mediatranscoder.workers.ManifestWorker;
 import io.conductor.example.mediatranscoder.workers.ThumbnailWorker;
 import io.conductor.example.mediatranscoder.workers.TranscodeWorker;
@@ -69,25 +67,14 @@ public static void main(String[] args) throws Exception {
         // 2. Start workers. upload_primary_video runs first inside the workflow and publishes
         // the primary video handle; downstream tasks consume it via
         // ${upload_primary_video_ref.output.primary_video}.
-        // TranscodeWorker is an @WorkerTask-annotated bean. Both raw and annotated workers inject
-        // FileClient explicitly and exchange only opaque handle strings.
-        TranscodeWorker transcodeBean = new TranscodeWorker(fileClient);
-        AnnotatedWorker transcodeWorker = new AnnotatedWorker(
-                "transcode_video",
-                TranscodeWorker.class.getMethod(
-                        "transcode", TranscodeWorker.TranscodeInput.class, String.class),
-                transcodeBean);
-
-        List<Worker> workers = List.of(
+        // Every worker is an ordinary dependency-injected object whose work method is annotated
+        // with @WorkerTask. The executor discovers those methods and handles input/output binding.
+        AnnotatedWorkerExecutor workerExecutor = new AnnotatedWorkerExecutor(taskClient);
+        workerExecutor.initWorkersFromInstances(List.of(
                 new UploadPrimaryVideoWorker(fileClient),
-                transcodeWorker,
+                new TranscodeWorker(fileClient),
                 new ThumbnailWorker(fileClient),
-                new ManifestWorker(fileClient));
-
-        TaskRunnerConfigurer configurer = new TaskRunnerConfigurer.Builder(taskClient, workers)
-                .withThreadCount(4)
-                .build();
-        configurer.init();
+                new ManifestWorker(fileClient)));
         System.out.println("Workers started: upload_primary_video, transcode_video, extract_thumbnail, create_manifest");
 
         // 3. Start workflow — no inputs; upload_primary_video publishes primaryVideo.
@@ -99,7 +86,7 @@ public static void main(String[] args) throws Exception {
         String workflowId = workflowClient.startWorkflow(request);
         System.out.println("Workflow started: " + workflowId);
 
-        // 5. Poll for completion
+        // 4. Poll for completion.
         System.out.println("Waiting for workflow to complete...");
         for (int i = 0; i < 30; i++) {
             Thread.sleep(2000);
@@ -108,13 +95,13 @@ public static void main(String[] args) throws Exception {
             if (workflow.getStatus().isTerminal()) {
                 System.out.println("Workflow " + workflow.getStatus() + "!");
                 System.out.println("Output: " + workflow.getOutput());
-                configurer.shutdown();
+                workerExecutor.shutdown();
                 System.exit(workflow.getStatus().isSuccessful() ? 0 : 1);
             }
         }
 
         System.err.println("Workflow did not complete in 60s");
-        configurer.shutdown();
+        workerExecutor.shutdown();
         System.exit(1);
     }
 

examples/file-storage/media-transcoder/src/main/java/io/conductor/example/mediatranscoder/workers/ManifestWorker.java

@@ -17,14 +17,14 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 
-import com.netflix.conductor.client.worker.Worker;
-import com.netflix.conductor.common.metadata.tasks.Task;
-import com.netflix.conductor.common.metadata.tasks.TaskResult;
+import com.netflix.conductor.sdk.workflow.task.OutputParam;
+import com.netflix.conductor.sdk.workflow.task.WorkerTask;
+import com.netflix.conductor.sdk.workflow.task.WorkflowInstanceIdInputParam;
 import org.conductoross.conductor.client.FileClient;
 import org.conductoross.conductor.client.model.file.FileMetadata;
 import org.conductoross.conductor.sdk.file.FileUploadOptions;
 
-public class ManifestWorker implements Worker {
+public class ManifestWorker {
 
     private static final String MANIFEST = "{\"video\":\"%s\",\"videoName\":\"%s\",\"videoSize\":%d,\"thumbnail\":\"%s\",\"thumbName\":\"%s\",\"thumbSize\":%d}";
     private final FileClient fileClient;
@@ -33,20 +33,20 @@ public ManifestWorker(FileClient fileClient) {
         this.fileClient = fileClient;
     }
 
-    @Override
-    public String getTaskDefName() {
-        return "create_manifest";
+    public static class ManifestInput {
+        public String transcoded_video;
+        public String thumbnail;
     }
 
-    @Override
-    public TaskResult execute(Task task) {
-        TaskResult result = new TaskResult(task);
-        String video = (String) task.getInputData().get("transcoded_video");
-        String thumb = (String) task.getInputData().get("thumbnail");
+    @WorkerTask("create_manifest")
+    public @OutputParam("output_file") String create(
+            ManifestInput input,
+            @WorkflowInstanceIdInputParam String workflowId) throws IOException {
+        String video = input.transcoded_video;
+        String thumb = input.thumbnail;
         Path manifestFile = null;
 
         try {
-            String workflowId = task.getWorkflowInstanceId();
             System.out.println("[create_manifest] Inputs:");
             FileMetadata videoMetadata = describe(workflowId, video);
             FileMetadata thumbMetadata = describe(workflowId, thumb);
@@ -59,17 +59,12 @@ public TaskResult execute(Task task) {
             manifestFile = Files.createTempFile("manifest-", ".json");
             Files.writeString(manifestFile, manifest);
 
-            FileUploadOptions options = new FileUploadOptions().setContentType("application/json").setTaskId(task.getTaskId());
+            FileUploadOptions options = new FileUploadOptions().setContentType("application/json");
             String uploaded = fileClient.upload(workflowId, manifestFile, options);
-            result.getOutputData().put("output_file", uploaded);
-            result.setStatus(TaskResult.Status.COMPLETED);
 
             System.out.println("[create_manifest] Uploaded: " + uploaded);
             System.out.println("[create_manifest] Content: " + manifest);
-        } catch (Exception e) {
-            result.setStatus(TaskResult.Status.FAILED);
-            result.setReasonForIncompletion(e.getMessage());
-            e.printStackTrace();
+            return uploaded;
         } finally {
             if (manifestFile != null) {
                 try {
@@ -78,7 +73,6 @@ public TaskResult execute(Task task) {
                 }
             }
         }
-        return result;
     }
 
     private FileMetadata describe(String workflowId, String fileHandleId) throws IOException {