Announcing the New Conductor Java Client v4

作者：米格尔·普列托

---

今年早些时候，Python SDK 进行了重大改版。现在，其他 Conductor SDK 正在进行重大改造，我们很高兴地宣布 Java Client v4，具有显着的设计增强、性能改进和优化的依赖项。

在我们的 Java 客户端 v4 中，我们通过改进其设计减少了依赖足迹。我们添加了过滤器、事件和侦听器来消除直接依赖关系。这个设计决策是经过深思熟虑后做出的，旨在让客户端更易于使用、扩展和维护。

继续阅读以了解更多信息！

---

我们为什么要这样做？

我们已听取您的反馈，并正在努力改善开发者体验。 Orkes 和 Conductor OSS 社区正在管理两个独立的 Java 客户端/SDK 项目，这两个项目与我们行业中的许多项目一样，都积累了一些技术债务。我们认为现在是解决这笔债务的最佳时机。

我们想要立即解决的一些关键问题是：

1. 一个 Conductor Java 客户端（统治它们）
   目标是将两个现有项目整合为一个统一的、更易于管理的解决方案，汲取每个项目中最强大的元素。这应该转化为更快的更新、更好的支持和更具凝聚力的开发体验。

2. 依赖优化
   作为代码清理的一部分，我们删除了几个依赖项：

   • 对后端代码的依赖 - 之前的 OSS Java 客户端和 SDK 项目是 Conductor OSS 存储库的一部分，并且依赖于conductor-commons。虽然这使后端/客户端模型保持同步，但这也意味着一些与后端相关的代码和依赖项会泄漏给客户端。
   • 对已弃用工件的依赖。
   • 对你不需要的东西的依赖。

   通过删除硬编码的依赖项，用户和贡献者可以扩展客户端，而无需锁定到特定的库或工具。

3. 更多模块化
   我们重组了项目以提高模块化程度，使客户端更加灵活且更易于定制。

   通过这种模块化方法，您可以通过事件、侦听器和过滤器集成您喜欢的监控、日志记录或发现工具。这不仅简化了定制，还使代码库更具可维护性和面向未来的能力，使开发人员能够根据需要构建和扩展自己的扩展。

4. 代码清理/重构
   有了更干净的代码库，未来的开发应该更快、更不容易出错，也让社区贡献变得更容易。

5. 更好的例子
   我们在项目中引入了一个专门用于示例的模块。虽然它仍在进行中，但无论您是入门还是寻找高级用例，该模块都将作为实际示例的中心资源。

家，甜蜜的家

官方 Conductor 客户端和 SDK 目前位于 https://github.com/conductor-sdk，但 OSS Java 客户端/SDK 除外，它是 Conductor OSS 存储库的一部分 https://github.com /orkes-io/orkes-conductor-client/tree/main.

展望未来，所有 Conductor 客户端和 SDK 最终都将存放在conductor-oss/conductor 存储库中的同一个conductor-clients 目录中。前往那里查找 Java 客户端/SDK v4 的源代码。

Java 客户端 v4 有哪些新增功能？

1.优化依赖

与它所取代的两个项目相比，Java Client v4 引入了更精简、更高效的依赖项集。

我们删除了所有未使用的、已弃用的和不必要的依赖项，显着减少了类路径污染。 这种优化不仅可以最大限度地降低库之间发生冲突的风险，而且还可以提高整体性能和可维护性。通过简化依赖关系树，v4 提供了一个更干净、更轻量的客户端，更易于使用并更顺利地集成到您的项目中。

2.新的TaskRunner

TaskRunner 已被重构。它取代了 TaskPollExecutor，因为两者共享相同的核心职责：管理工作人员用于轮询、执行和更新任务的线程池。

这样，我们就删除了对 Netflix Eureka 和 Spectator 的直接依赖，引入了事件驱动机制，并添加了 PollFilter——一个确定是否应该进行轮询的回调​​。此外，错误处理和并发管理也得到了改进。

If you’re using Eureka and Spectator, no need to worry—events and filters are provided for seamless integration with these great tools and libraries.

3. Extensibility using events, listeners, and filters

Java Client v4 introduces enhanced extensibility through events, listeners, and filters. These can be used for various purposes, including metrics tracking, logging, auditing, and triggering custom actions based on specific conditions.

For example, you can use a Lambda Function as a PollFilter to check the instance status as reported by Eureka. If the instance is marked as UP—meaning Eureka considers it healthy and available—the worker will proceed to poll for tasks.

Additionally, a listener can be registered to handle PollCompleted events. In this scenario, the listener logs event details and uses Prometheus to track the duration of the polling process, attaching the task type as a label for detailed metrics tracking. This approach not only adds flexibility but also improves observability and control over the client's behavior.

var runnerConfigurer = new TaskRunnerConfigurer
        .Builder(taskClient, List.of(new HelloWorldWorker()))
        .withThreadCount(10)
        .withPollFilter((String taskType, String domain) -> {
            return eurekaClient.getInstanceRemoteStatus().equals(InstanceStatus.UP);
        })
        .withListener(PollCompleted.class, (e) -> {
            log.info("Poll Completed {}", e);
            var timer = prometheusRegistry.timer("poll_completed", "type", e.getTaskType());
            timer.record(e.getDuration());
        })
        .build();

runnerConfigurer.init();

The client also has some specialized interfaces like MetricsCollector, which is built on top of these events and listeners. We’ll be providing concrete implementations of Metrics Collectors soon.

4. OkHttp3 v4 — the right amount of features OOTB

OkHttp3 v4 is one of the most popular and well-regarded HTTP clients for Java. By upgrading to it, our Java Client/SDK v4 now supports HTTP2 and Gzip out-of-the-box, allowing you to make swifter HTTP requests or data transfers. While there are other excellent options, OkHTTP was chosen for its simplicity, performance, and reliability.

With the OkHttp upgrade, we also decided to remove one abstraction layer, Jersey. Jersey is more feature-rich but also more heavyweight compared to a simple HTTP client like OkHttp. Some of these features (such as dependency injection, filters, and exception mappers) can be overkill if you just want to make basic HTTP requests.

5. Ease of migration from OSS to Orkes

The client promotes seamless integration between OSS Conductor and Orkes Conductor, empowering users with the flexibility to switch as their needs evolve, while maintaining support for the open-source community first.

The Orkes Client module simply extends the Conductor Client by adding authentication through a HeaderSupplier.

For OSS users who have created workers with Client v4 but want to give Orkes Conductor a shot, they just need to add the orkes-conductor-client dependency to their project and instantiate the client with OrkesAuthentication as a Header Supplier. Switching back to OSS is as simple as removing that Header Supplier.

var client = ConductorClient.builder()
                .basePath(BASE_PATH)
                .addHeaderSupplier(new OrkesAuthentication(KEY, SECRET))
                .build();
return new TaskClient(client); // Use this TaskClient with TaskRunner to initialize workers

Find out the 6 differences between Conductor OSS and Orkes Conductor.

6. Improved examples and documentation

We’ve started consolidating examples into a dedicated module, with improvements that cover key areas like authorization, managing workflow and task definitions, scheduling workflows, and more. While this module is still a work in progress, we’ll continuously add and refine examples to provide better guidance and cover real-world use cases.

Our goal is to enable developers to use our Client/SDK effectively and explore best practices as the module evolves.

Getting started with Java Client v4

Here’s how you can get started using Java Client v4:

Step 1: Spin up Conductor

Use Conductor OSS or Orkes Conductor:

• Conductor OSS—Run it from source or use Docker.
• Orkes Conductor—Try out Orkes Playground or sign up for a free trial.

Step 2: Add conductor-client dependency to your project

For Gradle-based projects:

implementation 'org.conductoross:conductor-client:4.0.0'
implementation 'io.orkes:orkes-conductor-client:4.0.0' // required if using Orkes Conductor

For Maven-based projects:

<dependency>
    <groupId>org.conductoross</groupId>
    <artifactId>conductor-client</artifactId>
    <version>4.0.0</version>
</dependency>
<dependency>
    <groupId>io.orkes</groupId>
    <artifactId>orkes-conductor-client</artifactId>
    <version>4.0.0</version>
</dependency> <!-- Required if using Orkes Conductor –->

Step 3: Create a ConductorClient instance

import com.netflix.conductor.client.http.ConductorClient;

// … boilerplate or other code omitted
var client = new ConductorClient("http://localhost:8080/api");

If you are using Orkes Conductor, you will need to create an application and grab your credentials. With your key id and secret, create a ConductorClient instance:

import com.netflix.conductor.client.http.ConductorClient;
import io.orkes.conductor.client.http.OrkesAuthentication;

var client = ConductorClient.builder()
           .basePath("https://play.orkes.io/api")
           .addHeaderSupplier(new OrkesAuthentication(KEY, SECRET))
           .build();

or

import io.orkes.conductor.client.ApiClient;

var client = ApiClient.builder() // ApiClient extends ConductorClient
                 .basePath("https://play.orkes.io/api")
                .credentials(KEY, SECRET)
                .build();

Step 4: Create a workflow

You can create a workflow in Conductor using this JSON:

{
  "name": "hello_workflow",
  "description": "Hello Workflow!",
  "version": 1,
  "tasks": [
    {
      "name": "hello_task",
      "taskReferenceName": "hello_task_ref",
      "type": "SIMPLE",
      "inputParameters": {}
    }
  ],
  "inputParameters": [],
  "outputParameters": {

  },
  "schemaVersion": 2,
  "restartable": true,
  "workflowStatusListenerEnabled": false,
  "ownerEmail": "example@orkes.io",
  "timeoutPolicy": "ALERT_ONLY",
  "timeoutSeconds": 0
}

Or use our SDK module to create workflows as code. For that, you need to add the following dependency to your project:

For Gradle-based projects:

implementation 'org.conductoross:java-sdk::4.0.0'

For Maven-based projects:

<dependency>
    <groupId>org.conductoross</groupId>
    <artifactId>java-sdk</artifactId>
    <version>4.0.0</version>
</dependency>

With the dependency added, you can execute the following code to register the workflow:

import com.netflix.conductor.sdk.workflow.def.WorkflowBuilder;
import com.netflix.conductor.sdk.workflow.def.tasks.SimpleTask;
import com.netflix.conductor.sdk.workflow.executor.WorkflowExecutor;

// … boilerplate or other code omitted
var executor = new WorkflowExecutor("http://localhost:8080/api");
var workflow = new WorkflowBuilder<Void>(executor)
        .name("hello_workflow")
        .version(1)
        .description("Hello Workflow!")
        .ownerEmail("examples@orkes.io")
        .add(new SimpleTask("hello_task", "hello_task_ref"))
        .build();
workflow.registerWorkflow(true, true);
executor.shutdown();

Step 5: Start a workflow

Now that you have registered a workflow, you can start it with code:

import com.netflix.conductor.client.http.ConductorClient;
import com.netflix.conductor.client.http.WorkflowClient;
import com.netflix.conductor.common.metadata.workflow.StartWorkflowRequest;

var client = new ConductorClient("http://localhost:8080/api");
var workflowClient = new WorkflowClient(client);
var workflowId = workflowClient.startWorkflow(new StartWorkflowRequest()
        .withName("hello_workflow")
        .withVersion(1));

System.out.println("Started workflow " + workflowId);

Step 6: Run a worker

You need a worker polling for “hello_workflow” tasks and executing them to complete the workflow you started in Step 5.

For that, you can run this example:

import com.netflix.conductor.client.automator.TaskRunnerConfigurer;
import com.netflix.conductor.client.http.ConductorClient;
import com.netflix.conductor.client.http.TaskClient;
import com.netflix.conductor.client.worker.Worker;
import com.netflix.conductor.common.metadata.tasks.Task;
import com.netflix.conductor.common.metadata.tasks.TaskResult;

import java.util.List;

public class HelloWorker implements Worker {

    @Override
    public TaskResult execute(Task task) {
        var taskResult = new TaskResult(task);
        taskResult.setStatus(TaskResult.Status.COMPLETED);
        taskResult.getOutputData().put("message", "Hello World!");
        return taskResult;
    }

    @Override
    public String getTaskDefName() {
        return "hello_task";
    }

    public static void main(String[] args) {
        var client = new ConductorClient("http://localhost:8080/api");
        var taskClient = new TaskClient(client);
        var runnerConfigurer = new TaskRunnerConfigurer
                .Builder(taskClient, List.of(new HelloWorker()))
                .withThreadCount(10)
                .build();
        runnerConfigurer.init();
    }
}

These complete examples can be found here.

Note: If you want to run these code snippets in Orkes Conductor, remember to authenticate.

What’s next?: Roadmap

We aim for full parity between OSS server models and SDKs, so stay tuned for more changes to Conductor’s Java SDK and improved documentation. To stay up-to-date with our progress, check out the Conductor OSS Project Board. To request features or report bugs, create a ticket in our GitHub repository or contact us on Slack.

We’ll also soon tackle other supported languages: JavaScript, C#, Go, and Clojure. In the meantime, happy coding! Don’t forget to follow the Conductor OSS project and support us by giving a ⭐.

Orkes Cloud is a fully managed and hosted Conductor service that can scale seamlessly to meet your needs. When you use Conductor via Orkes Cloud, your engineers don’t need to worry about setting up, tuning, patching, and managing high-performance Conductor clusters. Try it out with our 14-day free trial for Orkes Cloud.

The above is the detailed content of Announcing the New Conductor Java Client v4. For more information, please follow other related articles on the PHP Chinese website!