Announcing the New Conductor Java Client v4

By: Miguel Prieto

---

Earlier this year, Python SDK had a major facelift. Now other Conductor SDKs are undergoing significant rehaul, and we are thrilled to announce Java Client v4, featuring significant design enhancements, performance improvements, and optimized dependencies.

In our Java Client v4, we’ve reduced the dependency footprint by improving its design. We’ve added filters, events, and listeners to remove direct dependencies. This design decision was made after careful consideration to make the client easier to use, extend, and maintain.

Read on to learn more!

---

Why are we doing this?

We’ve heard your feedback and are working to improve the developer experience. Orkes and the Conductor OSS community were managing two separate Java client/SDK projects, both of which, like many in our industry, had accumulated some technical debt. We decided it was the right time to address this debt.

Some of the key things we wanted to address immediately were:

1. One Conductor Java client (to rule them all)
   The goal was to consolidate the two existing projects into a unified, more manageable solution, taking the strongest elements from each. This should translate into faster updates, better support, and a more cohesive development experience.

2. Dependency optimization
   As part of code cleanup, we’ve removed several dependencies:

   • Dependencies on backend code—The previous OSS Java client and SDK projects were part of the Conductor OSS repo and depended on conductor-commons. Although this kept the backend/client models in sync, it also meant some backend-related code and dependencies were leaking to the client.
   • Dependencies on deprecated artifacts.
   • Dependencies on stuff you won’t be needing.

   By removing hard-coded dependencies, users and contributors can extend the client without being locked into specific libraries or tools.

3. More modularity
   We’ve restructured the project to increase modularity, making the client more flexible and easier to customize.

   With this modular approach, you can integrate your preferred monitoring, logging, or discovery tools through events, listeners, and filters. This not only simplifies customization but also makes the codebase more maintainable and future-proof, empowering developers to build and scale their own extensions as needed.

4. Code cleanup/refactoring
   With a cleaner codebase, future development should be faster and less error-prone, making it easier for community contributions as well.

5. Better examples
   We've introduced a module within the project specifically for examples. While it's still a work in progress, this module will serve as a central resource for practical, real-world examples whether you're getting started or looking for advanced use cases.

Home, sweet home

Official Conductor Client and SDKs are currently housed in https://github.com/conductor-sdk, with the exception of the OSS Java Client/SDK, which is part of the Conductor OSS repo https://github.com/orkes-io/orkes-conductor-client/tree/main.

Going forward, all Conductor Clients and SDKs will eventually be housed in the same conductor-clients directory in the conductor-oss/conductor repo. Head there to find the source code for the Java Client/SDK v4.

What’s new in Java Client v4?

1. Optimized dependencies

Java Client v4 introduces a more streamlined and efficient dependency set compared to the two projects it replaces.

We’ve removed all unused, deprecated, and unnecessary dependencies, significantly reducing classpath pollution. This optimization not only minimizes the risk of conflicts between libraries but should also improve overall performance and maintainability. By simplifying the dependency tree, v4 provides a cleaner and more lightweight client that is easier to work with and integrates more smoothly into your projects.

2. New TaskRunner

TaskRunner has been refactored. It replaces TaskPollExecutor, since both share the same core responsibility: managing the thread pool that workers use for polling, executing, and updating tasks.

With that, we've removed direct dependencies on Netflix Eureka and Spectator, introduced event-driven mechanisms, and added a PollFilter—a callback that determines whether polling should occur. Additionally, error handling and concurrency management have been improved.

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 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": "[e-mail]",
  "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("[e-mail]")
        .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.