DEV Community: devteam@scivicslab.com

quarkus-chat-ui (2): The Actor Design Behind LLM-to-LLM Conversation

devteam@scivicslab.com — Sun, 05 Apr 2026 09:58:50 +0000

Originally published on ScivicsLab Blog

In a previous post I introduced POJO-actor — a lightweight actor-model library for Java that needs no framework, no annotation processor, and no external runtime. Just plain Java 21.

This post is about how I actually use it in quarkus-chat-ui, a Quarkus-based LLM chat UI that connects to Claude Code CLI, vLLM, and other backends. The application manages stateful LLM sessions, streams responses via SSE, handles concurrent MCP requests, and supports a /btw command for side questions — all without a single synchronized block.

The three actors that make this work are ChatActor, BtwActor, and QueueActor. This post focuses on the first two and the design principle behind them.

Quick POJO-actor recap

A POJO-actor actor wraps any plain Java object. Messages are lambdas dispatched through a LinkedBlockingQueue. The actor runs its message loop on a single virtual thread, processing one message at a time.

ActorSystem system = new ActorSystem("chat-ui");
ActorRef<Counter> counter = system.actorOf("counter", new Counter());

// tell() — enqueue, return immediately
counter.tell(c -> c.increment());

// ask() — enqueue, return CompletableFuture with result
int value = counter.ask(c -> c.getValue()).join(); // = 1

// tellNow() — bypass queue, execute on a NEW virtual thread immediately
counter.tellNow(c -> c.emergencyStop());

The key properties:

tell() and ask(): FIFO, safe by default — only one message runs at a time on the actor's virtual thread.
tellNow() and askNow(): bypass the queue, run concurrently on a fresh virtual thread. The caller takes responsibility for thread safety.

This is the whole API. The class itself is a plain Java object — no annotations, no base class to extend, no interface to implement. Any POJO becomes an actor simply by passing it to ActorSystem.actorOf(). The object does not know it is running inside an actor.

The problem: blocking I/O kills the message loop

An LLM API call can take 30–60 seconds. If ChatActor calls the LLM directly inside a message handler, the actor's message loop is blocked for the entire duration:

tell(startPrompt) → message.run() → provider.sendPrompt() ← blocks for 30s
                                                               |
tell(cancel)  ← enqueued, but not processed until sendPrompt() returns

The cancel button press arrives as a tell(cancel), but the actor won't see it until the blocking call returns. That's useless.

The fix: delegate the blocking I/O to a separate virtual thread and return immediately.

ChatActor: the state guardian

ChatActor holds all session state — API key, model, history, busy flag. It protects that state by being the single thread that reads and writes it.

public class ChatActor {

    private final LlmProvider provider;
    private volatile Thread activeThread;  // written by actor thread, read by cancel()

    private boolean busy;
    private String apiKey;
    private String sessionId;
    // ... other session state

    public void startPrompt(String text, String model, Consumer<ChatEvent> emitter,
                            ActorRef<ChatActor> self, Runnable done) {
        busy = true;
        emitter.accept(ChatEvent.status(sessionId, true));

        // Delegate the blocking I/O to a virtual thread and return immediately.
        // The actor's message loop is now free to process the next message.
        activeThread = Thread.startVirtualThread(() -> {
            try {
                ProviderContext ctx = new ProviderContext(apiKey, history, false, () -> {});
                provider.sendPrompt(text, model, emitter, ctx);
            } catch (Exception e) {
                emitter.accept(ChatEvent.error(e.getMessage()));
            } finally {
                // Report completion back through the actor's queue (thread-safe)
                self.tell(a -> a.onPromptComplete(emitter));
            }
        });
        // ← returns here immediately. The actor is ready for the next message.
    }

    public void cancel() {
        provider.cancel();
        Thread t = activeThread;       // read volatile field
        if (t != null) t.interrupt(); // interrupt the I/O virtual thread
    }

    private void onPromptComplete(Consumer<ChatEvent> emitter) {
        busy = false;
        activeThread = null;
        emitter.accept(ChatEvent.status(sessionId, false));
    }
}

The message flow after startPrompt() is called:

tell(startPrompt) → starts I/O thread → returns immediately
                    actor loop is now idle, waiting for next message

tell(cancel)      → no queue wait → cancel() runs → I/O thread interrupted
                    I/O thread catches exception → finally → self.tell(onPromptComplete)

This is the core pattern. The actor is the state guardian; the virtual thread is the I/O worker. The actor never blocks. Every cancel, every MCP request, every queue tick finds the actor ready to respond.

Why `volatile Thread activeThread`?

activeThread is written by the actor's virtual thread (in startPrompt) and read by cancel(). Normally both are on the same actor thread, so volatile is redundant — but cancel() is also called via tellNow(), which runs on a different virtual thread. volatile ensures the write to activeThread is visible across that thread boundary. It's a defensive declaration that costs nothing and prevents a subtle bug.

Why `tellNow()` for cancel?

The REST endpoint that handles the cancel button:

@POST
@Path("/cancel")
public ChatEvent cancel() {
    actorSystem.getChatActor().tellNow(ChatActor::cancel);
    return ChatEvent.info("Cancelled");
}

Why tellNow() and not tell()?

With tell(), cancel() would be enqueued behind whatever is currently in the queue. But startPrompt() delegates its I/O immediately and returns — so in practice, the actor's queue is already empty and tell(cancel) would be processed right away. The behavior is correct either way.

The reason to use tellNow() is semantic clarity: "cancel NOW" — not "cancel when it's your turn". It also makes the intent obvious to readers of the code. cancel() touches only volatile activeThread and provider.cancel(), both of which are designed for concurrent access, so bypassing the queue is safe here.

BtwActor: a second independent actor

Claude Code CLI has a /btw command: while the LLM is processing a long task, you can type /btw what does this mean? and get an immediate answer from a parallel LLM call, without interrupting the main task.

quarkus-chat-ui implements the same UX. The Web UI detects the /btw prefix and sends the question to POST /api/btw. The response appears in a floating overlay in the bottom-right corner; the main chat continues uninterrupted.

The key insight: this is just a second independent actor that follows the same pattern as ChatActor.

public class BtwActor {

    private final LlmProvider provider;
    private volatile Thread activeThread;

    public void startBtw(String question, String model, String apiKey,
                         Consumer<ChatEvent> emitter, ActorRef<BtwActor> self) {
        activeThread = Thread.startVirtualThread(() -> {
            try {
                ProviderContext ctx = new ProviderContext(apiKey, List.of(), false, () -> {});
                provider.sendPrompt(question, model, event -> {
                    // Map provider events to btw-specific SSE event types
                    if ("delta".equals(event.type()))  emitter.accept(ChatEvent.btwDelta(event.content()));
                    if ("result".equals(event.type())) emitter.accept(ChatEvent.btwResult());
                }, ctx);
            } catch (Exception e) {
                emitter.accept(ChatEvent.error("BTW error: " + e.getMessage()));
            } finally {
                self.tell(a -> a.activeThread = null);
            }
        });
    }

    public void cancel() {
        Thread t = activeThread;
        if (t != null) { provider.cancel(); t.interrupt(); }
    }

    public boolean isBusy() { return activeThread != null; }
}

BtwActor is registered alongside ChatActor in LlmConsoleActorSystem:

chatActorRef = actorSystem.actorOf("chat", new ChatActor(provider, configApiKey));
btwActorRef  = actorSystem.actorOf("btw",  new BtwActor(provider));

The REST endpoint is three lines:

@POST
@Path("/btw")
public ChatEvent btw(BtwRequest request) {
    String apiKey = actorSystem.getChatActor().ask(ChatActor::getApiKey).join();
    String model  = request.model != null ? request.model : provider.getCurrentModel();
    var btwRef    = actorSystem.getBtwActor();
    btwRef.tell(a -> a.startBtw(request.question, model, apiKey, this::emitSse, btwRef));
    return ChatEvent.info("BTW processing");
}

The frontend receives btw_delta and btw_result SSE events (distinct from the main chat's delta/result), streams the response into the overlay, and closes it on ESC or the × button.

Thread safety with a shared provider

ChatActor and BtwActor share the same LlmProvider instance. For HTTP-based providers (Anthropic API, vLLM), each sendPrompt() call is an independent HTTP request — parallel calls are safe by construction.

BtwActor intentionally does not call provider.setModel() before sendPrompt(). Calling setModel() would mutate shared provider state, potentially corrupting ChatActor's current model mid-stream. Instead, the model is passed directly as a parameter to sendPrompt(). The actors are isolated at the state level even though they share the provider.

The actor system structure

ActorSystem "chat-ui"
  ├── ChatActor    — session state, model selection, history
  ├── BtwActor     — /btw side questions (independent)
  ├── QueueActor   — message queuing for MCP/concurrent requests
  └── WatchdogActor — stall detection (CLI providers only)

All four follow the same pattern: the actor is the state guardian, virtual threads handle I/O. tell() for normal messages, tellNow() for urgent bypasses that are provably safe.

What I like about this approach

No framework tax. Each actor is a POJO. The actor model adds one concept (tell vs tellNow) on top of plain Java. Reading ChatActor requires no knowledge of Akka, Quarkus, or any actor framework — just Java.

The virtual thread + actor split is explicit. The code visually shows the boundary: Thread.startVirtualThread(...) inside startPrompt() is the handoff from "actor's domain" to "I/O worker's domain". When something goes wrong, it's immediately clear which side owns the problem.

Adding actors is cheap. BtwActor is 30 lines. Adding /btw cancel in the future is one tellNow() call. The pattern scales to new actors (WatchdogActor, QueueActor) without changing the existing ones.

State bugs are localized. ChatActor is the only place that can modify session state. If the session ID is wrong, the bug is in ChatActor. There is no "it could be any thread" scenario.

quarkus-chat-ui: A Web Front-End for LLMs, and a Real-World Case for POJO-actor

devteam@scivicslab.com — Sun, 05 Apr 2026 07:46:44 +0000

Note: This article was originally published on
SciVicsLab.

quarkus-chat-ui: A Web Front-End for LLMs, and a Real-World Case for POJO-actor

quarkus-chat-ui is a web UI for LLMs where multiple instances can talk to each other — built as a real-world use case for POJO-actor.

Each quarkus-chat-ui instance exposes an HTTP MCP server at /mcp, so Instance A can call tools on Instance B, and Instance B can reply by calling tools back on A. The LLM backend — Claude Code CLI, Codex, or a local model via claw-code-local — acts as an MCP client that can reach these endpoints. The question was how to wire that up over HTTP, and how to handle the fact that LLM responses take tens of seconds and arrive as a stream.

quarkus-chat-ui is the bridge that makes this work. Each instance wraps one LLM backend and exposes it as an HTTP MCP server at /mcp. For multi-agent communication, use a backend with MCP client capability: Claude Code CLI, Codex, or claw-code-local (which brings MCP support to Ollama, vLLM, and other local models). The openai-compat provider works for single-agent use but cannot call other MCP servers. Agents call each other by name. Humans can watch both sides of the conversation in their browsers.

Once the async communication layer was in place, a capable web UI and a prompt queue came along naturally. The browser gives you a stable place to type — your input won't vanish when the AI responds, and paste and multi-line just work. If you need an LLM front-end and happen to be a Java developer, those turn out to be useful in their own right.

This post is about quarkus-chat-ui as a tool you can use. Companion posts cover:

The internal design — how POJO-actor keeps the concurrency clean → quarkus-chat-ui (2): The Actor Design Behind LLM-to-LLM Communication
Scaling beyond two agents — why quarkus-mcp-gateway becomes necessary → quarkus-chat-ui (3): Scaling Multi-Agent Communication with MCP Gateway

What it does

1. LLM instances talking to each other via MCP

Each quarkus-chat-ui instance exposes an HTTP MCP server at /mcp. The tools are submitPrompt, getPromptStatus, getPromptResult, cancelRequest, and a few others.

submitPrompt accepts a _caller parameter. When Instance B receives a prompt with _caller pointing back to A, it enriches the prompt with position awareness and reply instructions before forwarding it to its LLM:

[Context]
You are running on: http://localhost:28020
Received via MCP from: localhost:28010

[Message]
What should we work on today?

[How to Reply]
Use callMcpServer tool:
- serverUrl: http://localhost:28010
- toolName: submitPrompt
- arguments: {"prompt": "your reply", "_caller": "http://localhost:28020"}

The LLM reads this, formulates a reply, and calls submitPrompt on Instance A. The conversation continues autonomously.

Browser A (port 28010)             Browser B (port 28020)
──────────────────────             ──────────────────────
[MCP from localhost:28020]         [MCP from localhost:28010]
What should we work on today? ←→   Let's start with the API layer.
                                   [MCP from localhost:28010]
[MCP from localhost:28020]         ...
Good idea. Let's define...

You can also put a quarkus-mcp-gateway in front of many instances, routing by name instead of port. Service discovery scans a port range and registers all running agents automatically.

2. Written in Quarkus — streaming made simple

LLM tooling tends to be Python. If you want to customise how prompts are enriched, add a new backend, or change the queue policy, quarkus-chat-ui is a straightforward Quarkus Maven project.

Adding a new LLM backend means implementing one interface:

public interface LlmProvider {
    String id();
    void sendPrompt(String prompt, String model,
                    Consumer<ChatEvent> emitter, ProviderContext ctx);
    void cancel();
    // ...
}

SSE streaming, queue management, MCP server, and conversation history are already there.

Quarkus made the streaming part almost trivial. Exposing an SSE endpoint is a matter of returning Multi<T> from a JAX-RS method:

@GET @Path("/events/{sessionId}")
@Produces(MediaType.SERVER_SENT_EVENTS)
@RestStreamElementType(MediaType.APPLICATION_JSON)
public Multi<ChatEvent> events(@PathParam("sessionId") String sessionId) {
    return chatService.getEventStream(sessionId);
}

That is all. The framework handles chunked encoding, keep-alive, and client reconnection. Backpressure flows naturally through Mutiny's reactive streams. There is no manual buffer management, no explicit flush calls, no thread-pool tuning. You return a Multi, Quarkus streams it.

3. A prompt queue that does the obvious thing

When the LLM is busy and you want to queue your next question, you can. When the current response finishes, the queued prompt runs automatically.

[LLM is processing "Explain this code"]

You type: "Now write the tests"    →  added to queue
You type: "And the documentation"  →  added to queue

[Response arrives]
→ "Now write the tests" runs automatically
[Response arrives]
→ "And the documentation" runs automatically

The queue is visible in the UI, persistent across page reloads, and editable — reorder or delete items before they run.

Cancel works correctly in the multi-agent case too. Pressing Cancel stops the current generation and removes MCP-sourced messages from the backend queue. Messages you typed yourself stay in the queue and run after the cancel.

Why the concurrency is manageable

Multi-agent HTTP conversation sounds like a concurrency nightmare: SSE streams arriving from multiple agents, a queue draining as responses land, cancel signals that need to reach the right places. In practice it is not, because the design is explicit about who owns what state.

Each concern — chat session, side questions, queue management, stall detection — runs in its own actor backed by POJO-actor. Blocking I/O runs on virtual threads that report back to the actor when done. The actors communicate through tell() and ask() calls. There are no synchronized blocks in the application code.

The companion post goes into detail: quarkus-chat-ui (2): The Actor Design Behind LLM-to-LLM Communication.

Quick start

Three providers are supported:

`chat-ui.provider`	What it wraps	Requires
`claude`	Claude Code CLI	`ANTHROPIC_API_KEY`
`codex`	OpenAI Codex CLI	`OPENAI_API_KEY`
`openai-compat`	Any OpenAI-compatible HTTP server (vLLM, Ollama, …)	running local server

Preparing a local LLM (openai-compat)

If you want to run a local model instead of a cloud API, Ollama is the easiest way to get started:

# Install Ollama, then pull a model
ollama pull qwen2.5-coder:7b

# Ollama listens on http://localhost:11434 by default
# Use -Dchat-ui.servers=http://localhost:11434/v1 when starting quarkus-chat-ui

For GPU-accelerated inference, vLLM serves any HuggingFace-compatible model on the same OpenAI-compatible API:

vllm serve Qwen/Qwen2.5-Coder-7B-Instruct --port 8000
# Use -Dchat-ui.servers=http://localhost:8000

Option 1: Native executable (no JDK required)

Java traditionally requires a JVM to run. You install a JDK, compile your code to bytecode, and the JVM interprets or JIT-compiles it at runtime. This is why "installing Java" has always been a prerequisite for running Java applications.

GraalVM native image changes this. It compiles Java bytecode ahead-of-time into a native executable for your OS and CPU architecture. The result is a standalone binary — just like a C or Go program. No JVM, no JDK, no JAVA_HOME. Download, run, done.

This is where Quarkus shines again. Traditional Java frameworks rely heavily on runtime reflection, making native image compilation painful — you end up maintaining long lists of reflection configuration by hand. Quarkus was designed from the start with native compilation in mind. It moves reflection and configuration processing to build time, and its extensions generate the necessary GraalVM hints automatically. You just run mvn package -Dnative and it works.

Pre-built native executables are available on the Releases page.

Platform	Binary
Linux x86_64	`quarkus-chat-ui-linux-amd64`
Linux ARM64	`quarkus-chat-ui-linux-arm64`
macOS Intel	`quarkus-chat-ui-macos-amd64`
macOS Apple Silicon (M1/M2/M3)	`quarkus-chat-ui-macos-arm64`
Windows x64	`quarkus-chat-ui-windows-amd64.exe`

# Linux x86_64
./quarkus-chat-ui-linux-amd64 -Dchat-ui.provider=claude -Dquarkus.http.port=28010

# Linux ARM64
./quarkus-chat-ui-linux-arm64 -Dchat-ui.provider=claude -Dquarkus.http.port=28010

# macOS Intel
./quarkus-chat-ui-macos-amd64 -Dchat-ui.provider=claude -Dquarkus.http.port=28010

# macOS Apple Silicon (M1/M2/M3)
./quarkus-chat-ui-macos-arm64 -Dchat-ui.provider=claude -Dquarkus.http.port=28010

# Windows PowerShell
.\quarkus-chat-ui-windows-amd64.exe -Dchat-ui.provider=claude -Dquarkus.http.port=28010

Option 2: Build from source

Prerequisites: JDK 21+ and Maven 3.x

git clone https://github.com/scivicslab/quarkus-chat-ui
cd quarkus-chat-ui
mvn install -DskipTests

Run with Claude Code CLI:

java -Dchat-ui.provider=claude \
     -Dquarkus.http.port=28010 \
     -jar app/target/quarkus-app/quarkus-run.jar

Run with vLLM or Ollama (OpenAI-compatible API):

java -Dchat-ui.provider=openai-compat \
     -Dchat-ui.openai-compat.base-url=http://localhost:11434/v1 \
     -Dquarkus.http.port=28010 \
     -jar app/target/quarkus-app/quarkus-run.jar

Open http://localhost:28010 in a browser.

For all providers (claude, codex, openai-compat) and configuration options, see the README.

Setting up two agents to talk (Claude Code CLI)

Two quarkus-chat-ui instances talking to each other via MCP.

Overview:

You will set up two instances (Alice and Bob) that can send messages to each other via MCP:

Alice runs on port 28010
Bob runs on port 28020
Each instance has its own browser window
Claude Code CLI acts as the MCP client for both instances

Prerequisites:

quarkus-chat-ui repository cloned and built (see "Option 2: Build from source" above)
Working directory: quarkus-chat-ui/ (repository root)
3 terminal windows (or tabs)
2 browser windows (or tabs)

1. Install Claude Code CLI

Where: Any directory

npm install -g @anthropic-ai/claude-code

Verify:

claude --version

2. Set API Key

Where: Any terminal (environment variable applies to all subsequent commands in that terminal)

export ANTHROPIC_API_KEY=sk-ant-api03-...

3. Start Alice (port 28010)

Terminal 1, working directory: quarkus-chat-ui/ (repository root)

java -Dchat-ui.provider=claude \
     -Dquarkus.http.port=28010 \
     -jar app/target/quarkus-app/quarkus-run.jar

Open http://localhost:28010 in your browser

4. Start Bob (port 28020)

Terminal 2, working directory: quarkus-chat-ui/ (repository root)

First, set the API key in this terminal too:

export ANTHROPIC_API_KEY=sk-ant-api03-...

Then start Bob:

java -Dchat-ui.provider=claude \
     -Dquarkus.http.port=28020 \
     -jar app/target/quarkus-app/quarkus-run.jar

Open http://localhost:28020 in another browser tab

5. Register MCP Endpoints

Terminal 3, working directory: Any directory (MCP registrations are stored in ~/.claude/)

# So Alice can call Bob
claude mcp add bob --transport http http://localhost:28020/mcp

# So Bob can call Alice
claude mcp add alice --transport http http://localhost:28010/mcp

Verify the registrations:

claude mcp list

Expected output:

alice: http (http://localhost:28010/mcp)
bob: http (http://localhost:28020/mcp)

6. Restart Both Instances

Claude Code CLI reads MCP registrations at startup. Stop and restart both.

Terminal 1 (Ctrl+C to stop, then restart Alice):

java -Dchat-ui.provider=claude \
     -Dquarkus.http.port=28010 \
     -jar app/target/quarkus-app/quarkus-run.jar

Terminal 2 (Ctrl+C to stop, then restart Bob):

java -Dchat-ui.provider=claude \
     -Dquarkus.http.port=28020 \
     -jar app/target/quarkus-app/quarkus-run.jar

7. Test: Alice Sends to Bob

Where: Alice's browser (http://localhost:28010)

In the prompt input field, type:

Use mcp__bob__submitPrompt to send "Hello Bob!" to Bob.
Set _caller to http://localhost:28010

Then click Send. Claude will use the MCP tool to send the message to Bob.

8. Verify: Bob Receives

Where: Bob's browser (http://localhost:28020)

You should see the message appear in Bob's chat area:

[MCP from localhost:28010] Hello Bob!

Testing the reply: In Bob's browser, type:

Use mcp__alice__submitPrompt to reply "Hi Alice!" to Alice.
Set _caller to http://localhost:28020

Then check Alice's browser — the reply should appear there.

Cleanup

Where: Any terminal

When you're done testing, remove the MCP registrations:

claude mcp remove alice
claude mcp remove bob

Verify they're removed:

claude mcp list

Troubleshooting

Problem	Solution
`mcp__bob__submitPrompt` not found	Run `claude mcp add bob --transport http http://localhost:28020/mcp` and restart Alice (Terminal 1)
Connection refused	Check that the target instance is running on the expected port (use `lsof -i :28010` or `lsof -i :28020`)
Bob can't reply to Alice	Run `claude mcp add alice --transport http http://localhost:28010/mcp` and restart Bob (Terminal 2)
`ANTHROPIC_API_KEY` not found	Set the environment variable in each terminal: `export ANTHROPIC_API_KEY=sk-ant-api03-...`
`app/target/quarkus-app/quarkus-run.jar` not found	Run `mvn install -DskipTests` from the `quarkus-chat-ui/` repository root

Beyond two agents

For three or more agents, use quarkus-mcp-gateway. See quarkus-chat-ui (3): Scaling Multi-Agent Communication with MCP Gateway.

actor-IaC: POJO-actor Workflow Based Infrastructure as Code for Cluster Management (Part 1)

devteam@scivicslab.com — Wed, 28 Jan 2026 05:57:39 +0000

actor-IaC is an Infrastructure as Code (IaC) tool built on top of the POJO-actor workflow engine.
It uses actor-based workflows written in Java and YAML to manage and operate compute clusters in a scalable and traceable way.

In this article (Part 1), we introduce actor-IaC through a practical example: collecting system information from multiple compute nodes in parallel.
This tutorial demonstrates how POJO-actor workflows can be applied to real-world cluster management tasks.

Why Use POJO-actor Workflow for IaC?

In previous posts, we explained the design of a framework that easily enables asynchronous parallel processing by turning any POJO into an actor, and introduced the Turing Machine-based workflow engine built on top of it.

In this post, we demonstrate that this workflow mechanism is effective even for practical, real-world applications. As a concrete example, we built a full-featured Infrastructure as Code tool called "actor-IaC" using the POJO-actor workflow engine.

Consistent Notation

In POJO-actor Workflow, all operations are written in a consistent format: "call a method on a POJO."

actions:
  - actor: this
    method: executeCommand
    arguments: ["hostname -f"]

The granularity of operations depends on your POJO design. You can freely define methods ranging from executing a single shell command to complex deployment procedures. You're not constrained by DSL limitations.

Natural Conditional Branching

POJO-actor Workflow is based on state machines (Turing machines). Each step is defined as a pair of "current state" and "next state", and conditional branching is expressed as steps with multiple possible transitions.

steps:
  - states: ["check", "success"]
    when: "result.exitCode == 0"
    actions: [...]
  - states: ["check", "failure"]
    when: "result.exitCode != 0"
    actions: [...]

No special control syntax is needed. Branching can be described naturally as state transitions.

The Actor Tree: A Mental Model for Cluster Management

In actor-IaC, actors corresponding to each node defined in the inventory file are automatically generated.

IIActorSystem
├── nodeGroup                # Group actor that manages all nodes
│   ├── node-node13          #   Corresponds to each node in inventory
│   ├── node-node14          #   (Number of nodes depends on inventory.ini)
│   └── ...
├── outputMultiplexer        # Aggregates output from all nodes
├── loader                   # Dynamic plugin loading
└── logStore                 # Log DB writing (when --log-db specified)

The advantage of this structure is that when writing workflows, you only need to think about sequential processing on a single machine.

Sub-workflows describe only "what to do on this one node." Parallelization is handled by nodeGroup.apply(). You don't need to worry about synchronization or mutual exclusion across multiple nodes.

Because the mental model is simple, workflow design, debugging, and maintenance all become easier.

Complete Traceability of Execution Logs (Cluster Operations)

When the mental model is simple, checking logs also becomes easier.

actor-IaC automatically saves execution logs from all nodes to an H2 database. Even logs from parallel execution can be filtered later to extract specific nodes.

# Show logs for node13 only
./actor_iac.java log-search --db ./actor-iac-logs --node node-node13

Even in situations like "1 out of 6 nodes failed. What happened?", you can immediately check the logs for that specific node.

Hands-on: Collecting Cluster Information

Enough theory—let's actually use actor-IaC.

When managing a cluster, you need to understand the configuration of each node:

CPU: How many cores? What model?
Memory: How many GB?
Disk: Capacity and usage?
GPU: NVIDIA? AMD?
Network: IP addresses?

Manually checking this for 6 nodes is tedious. With actor-IaC, you can collect information from all nodes in parallel with a single command.

1. Inventory File

Define the target nodes. It uses the same INI format as Ansible.

[compute]
node13 actoriac_host=192.168.5.13
node14 actoriac_host=192.168.5.14
node15 actoriac_host=192.168.5.15
node21 actoriac_host=192.168.5.21
node22 actoriac_host=192.168.5.22
node23 actoriac_host=192.168.5.23

[compute:vars]
actoriac_user=youruser

2. Sub-workflow (Processing Executed on Each Node)

Create collect-sysinfo.yaml. This is the workflow executed on each node.

name: collect-sysinfo

steps:
  - states: ["0", "1"]
    note: Get hostname and OS info
    actions:
      - actor: this
        method: executeCommand
        arguments:
          - |
            echo "===== HOSTNAME ====="
            hostname -f
            echo "===== OS INFO ====="
            cat /etc/os-release | grep -E "^(NAME|VERSION)="

  - states: ["1", "2"]
    note: Get CPU info
    actions:
      - actor: this
        method: executeCommand
        arguments:
          - |
            echo "===== CPU INFO ====="
            lscpu | grep -E "^(Architecture|CPU\(s\)|Model name)"

  - states: ["2", "3"]
    note: Get memory info
    actions:
      - actor: this
        method: executeCommand
        arguments:
          - |
            echo "===== MEMORY INFO ====="
            free -h

  - states: ["3", "4"]
    note: Get disk info
    actions:
      - actor: this
        method: executeCommand
        arguments:
          - |
            echo "===== DISK INFO ====="
            df -h | grep -E "^(/dev|Filesystem)"

  - states: ["4", "5"]
    note: Get GPU info
    actions:
      - actor: this
        method: executeCommand
        arguments:
          - |
            echo "===== GPU INFO ====="
            if command -v nvidia-smi &> /dev/null; then
                nvidia-smi --query-gpu=name,memory.total,driver_version --format=csv,noheader
            else
                lspci | grep -i -E "(vga|3d)" || echo "No GPU detected"
            fi

  - states: ["5", "end"]
    note: Get network info
    actions:
      - actor: this
        method: executeCommand
        arguments:
          - |
            echo "===== NETWORK INFO ====="
            ip -4 addr show | grep -E "(^[0-9]+:|inet )" | head -20

Note that this workflow is written as sequential processing for a single node. There's no consideration for parallel execution.

3. Main Workflow (Applying to All Nodes)

Create main-collect-sysinfo.yaml.

name: main-collect-sysinfo

steps:
  - states: ["0", "end"]
    note: Execute sub-workflow in parallel on all nodes
    actions:
      - actor: nodeGroup
        method: apply
        arguments:
          actor: "node-*"
          method: runWorkflow
          arguments: ["collect-sysinfo.yaml"]

Just one step. nodeGroup.apply() executes the sub-workflow in parallel on all nodes matching the pattern node-*.

Execution

./actor_iac.java run -w sysinfo/main-collect-sysinfo.yaml -i inventory.ini -g compute

When executed, it simultaneously connects via SSH to all 6 nodes and collects system information.

[node-node13] ===== HOSTNAME =====
[node-node13] node13.local
[node-node14] ===== HOSTNAME =====
[node-node14] node14.local
[node-node13] ===== CPU INFO =====
[node-node13] Architecture:          x86_64
[node-node13] CPU(s):                32
[node-node13] Model name:            AMD Ryzen 9 5950X
...

The prefix like [node-node13] at the beginning of each line indicates which node the output came from. Since execution is parallel, outputs arrive in mixed order, but you can distinguish them by the prefix.

Checking Results

All logs are automatically saved to an H2 database (actor-iac-logs.mv.db).

# Show session list
./actor_iac.java log-search --db ./actor-iac-logs --list

# Show logs for a specific node
./actor_iac.java log-search --db ./actor-iac-logs --node node-node13

actor-IaC Features

actor-IaC is not an experimental tool—it already has production-ready features.

Command	Description
`run`	Execute a workflow
`list`	List available workflows
`describe`	Show workflow details
`log-search`	Search and display execution logs
`log-merge`	Merge distributed log DBs
`db-clear`	Delete log DB

The overlay feature allows you to use the same workflow across development, staging, and production environments.

Plugin-based extensions are planned for the future.

Summary

actor-IaC is the answer to "Can POJO-actor Workflow express complex workflows?"

Consistent notation: A unified format of POJO method calls
Natural conditional branching: State machine-based, no special syntax needed
Simple mental model: Just think about sequential processing on a single node
Complete traceability: All logs saved to DB, searchable anytime

In Part 2, we'll introduce how to format and analyze the collected information.

Try It Yourself

You don't need a cluster to try actor-IaC. The actor-IaC-examples repository includes examples that run on localhost:

# Install dependencies
git clone https://github.com/scivicslab/POJO-actor && cd POJO-actor && mvn install && cd ..
git clone https://github.com/scivicslab/actor-IaC && cd actor-IaC && mvn install && cd ..

# Clone examples and run
git clone https://github.com/scivicslab/actor-IaC-examples
cd actor-IaC-examples

# Hello World example
./actor_iac.java run -d ./hello -w main-hello -i localhost.ini -g all

# Collect system info from localhost
./actor_iac.java run -d ./sysinfo -w main-collect-sysinfo -i localhost.ini -g all

See the repository's README for more examples and detailed instructions.

References

This article is part of the official actor-IaC documentation and tutorial series.

Official Website: https://scivicslab.com
Original Article: https://scivicslab.com/blog/2026-01-28-actor-iac-cluster-inventory
Documentation: https://scivicslab.com/docs/actor-iac/introduction
GitHub Repository: https://github.com/scivicslab/actor-iac
API Reference (Javadoc): https://scivicslab.github.io/actor-IaC/
POJO-actor v1.0 Introduction (blog): A Lightweight Actor Model Library for Java
Tutorial Part 2-1 (blog): Workflow Language Basics
Tutorial Part 2-2 (blog): Creating Workflows

POJO-actor Tutorial Part 2-3: Improving the Workflow API — Introducing the @Action Annotation

devteam@scivicslab.com — Wed, 28 Jan 2026 05:37:53 +0000

This article is a hands-on tutorial for the POJO-actor workflow API, focusing on the @Action annotation introduced in POJO-actor v2.14.
We explain how to define workflow-callable actions in Java actors without overriding callByActionName(), using a practical example with conditional branching.

In Part 2-2, we implemented workflow actions by overriding callByActionName() and dispatching actions with a switch-case statement.
While this approach works, the method grows quickly as the number of actions increases and becomes difficult to maintain.

To solve this problem, POJO-actor v2.14 introduces the @Action annotation.
With this annotation, workflow actions can be defined declaratively on actor methods, eliminating the need for explicit dispatch logic.

In this tutorial, we reimplement the Turing machine example (turing87), which outputs an irrational binary sequence (0.001011011101111...), using the @Action-based workflow API.
This example includes conditional branching and represents a more practical workflow scenario.

Introduction

In Part 2-2, we explained how to extend IIActorRef and override the callByActionName() method.

@Override
public ActionResult callByActionName(String actionName, String args) {
    switch (actionName) {
        case "initMachine": ...
        case "put": ...
        case "move": ...
        default: return new ActionResult(false, "Unknown action: " + actionName);
    }
}

This works, but the callByActionName() method grows larger as you add more workflow-callable actions.

To solve this problem, POJO-actor v2.14 introduces the @Action annotation. You no longer need to explicitly write callByActionName() — just annotate your methods.

In this tutorial, we implement turing87 (a Turing machine that outputs the irrational number 0.001011011101111...) introduced in Part 2-1 using the @Action annotation. This is a more practical example that includes conditional branching.

Step 1: Create the POJO (Same as Part 2-2)

The POJO requires no changes. It's a plain Java class that knows nothing about the workflow.

Turing.java

public class Turing {
    int currentPos = 0;
    Tape tape = new Tape();

    /** Initialize the machine */
    public void initMachine() {
        this.currentPos = 0;
        this.tape = new Tape();
    }

    /** Write a value to the tape */
    public void put(String value) {
        this.tape.setWithResizing(this.currentPos, value);
    }

    /** Move the head ("L"=left, "R"=right) */
    public void move(String direction) {
        if (direction.equalsIgnoreCase("L")) {
            this.currentPos--;
        } else if (direction.equalsIgnoreCase("R")) {
            this.currentPos++;
        }
    }

    /** Print the tape contents */
    public void printTape() {
        System.out.println("TAPE\t" + this.tape.toString());
    }

    // Methods for conditional branching (used in turing87)

    /** Check if current position value matches expected */
    public boolean matchCurrentValue(String expected) {
        String current = this.tape.get(this.currentPos);
        return expected.equals(current);
    }

    /** Check if current position has any value */
    public boolean isAny() {
        String current = this.tape.get(this.currentPos);
        return current != null && !current.isEmpty();
    }

    /** Check if current position is empty */
    public boolean isNone() {
        String current = this.tape.get(this.currentPos);
        return current == null || current.isEmpty();
    }
}

Step 2: Create the IIActorRef — @Action Annotation Version

This is the main topic. Let's first review the code from Part 2-2.

Part 2-2 Code (switch statement version)

public class TuringIIAR extends IIActorRef<Turing> {

    public TuringIIAR(String actorName, Turing turing, IIActorSystem system) {
        super(actorName, turing, system);
    }

    private String parseFirstArg(String args) {
        if (args == null || args.isEmpty() || args.equals("[]")) {
            return "";
        }
        JSONArray array = new JSONArray(args);
        return array.length() > 0 ? array.getString(0) : "";
    }

    @Override
    public ActionResult callByActionName(String actionName, String args) {
        try {
            switch (actionName) {
                case "initMachine":
                    this.tell(t -> t.initMachine()).get();
                    return new ActionResult(true, "initialized");

                case "put":
                    String putValue = parseFirstArg(args);
                    this.tell(t -> t.put(putValue)).get();
                    return new ActionResult(true, "put " + putValue);

                case "move":
                    String direction = parseFirstArg(args);
                    this.tell(t -> t.move(direction)).get();
                    return new ActionResult(true, "moved " + direction);

                case "printTape":
                    this.tell(t -> t.printTape()).get();
                    return new ActionResult(true, "printed");

                case "matchCurrentValue":
                    String expected = parseFirstArg(args);
                    boolean match = this.ask(t -> t.matchCurrentValue(expected)).get();
                    return new ActionResult(match, "match=" + match);

                case "isAny":
                    boolean any = this.ask(t -> t.isAny()).get();
                    return new ActionResult(any, "isAny=" + any);

                case "isNone":
                    boolean none = this.ask(t -> t.isNone()).get();
                    return new ActionResult(none, "isNone=" + none);

                default:
                    return new ActionResult(false, "Unknown action: " + actionName);
            }
        } catch (Exception e) {
            return new ActionResult(false, "Error: " + e.getMessage());
        }
    }
}

To connect action names written in YAML workflow files to the Java program, we override callByActionName() and dispatch actions using a switch statement.
In turing87, we also need conditional branching actions (matchCurrentValue, isAny, isNone), making the switch statement quite long.

Part 2-3 Code (@Action version)

Rewriting the same functionality with the @Action annotation looks like this:

import static com.scivicslab.pojoactor.core.ActionArgs.*;
import com.scivicslab.pojoactor.core.Action;
import com.scivicslab.pojoactor.core.ActionResult;
import com.scivicslab.pojoactor.workflow.IIActorRef;
import com.scivicslab.pojoactor.workflow.IIActorSystem;

public class TuringIIAR extends IIActorRef<Turing> {

    public TuringIIAR(String actorName, Turing turing, IIActorSystem system) {
        super(actorName, turing, system);
    }

    @Action("initMachine")
    public ActionResult initMachine(String args) {
        this.object.initMachine();
        return new ActionResult(true, "Machine initialized");
    }

    @Action("put")
    public ActionResult put(String args) {
        String value = getFirst(args);
        this.object.put(value);
        return new ActionResult(true, "Put " + value);
    }

    @Action("move")
    public ActionResult move(String args) {
        String direction = getFirst(args);
        this.object.move(direction);
        return new ActionResult(true, "Moved " + direction);
    }

    @Action("printTape")
    public ActionResult printTape(String args) {
        this.object.printTape();
        return new ActionResult(true, "Tape printed");
    }

    // Conditional branching actions (used in turing87)

    @Action("matchCurrentValue")
    public ActionResult matchCurrentValue(String args) {
        String expected = getFirst(args);
        boolean match = this.object.matchCurrentValue(expected);
        return new ActionResult(match, "match=" + match);
    }

    @Action("isAny")
    public ActionResult isAny(String args) {
        boolean any = this.object.isAny();
        return new ActionResult(any, "isAny=" + any);
    }

    @Action("isNone")
    public ActionResult isNone(String args) {
        boolean none = this.object.isNone();
        return new ActionResult(none, "isNone=" + none);
    }

    // No need to override callByActionName()!
}

You no longer need to write the callByActionName() method. Each action becomes an independent method, linked to the YAML via @Action("actionName"). The base class uses reflection to discover @Action-annotated methods and dispatches automatically.

@Action Method Requirements

Methods annotated with @Action must follow this format:

@Action("actionName")
public ActionResult methodName(String args) {
    // processing
    return new ActionResult(success/failure, message);
}

Return type: ActionResult
Parameter: Single String (YAML arguments passed as JSON string)
Visibility: public

Argument Formats

YAML arguments can be written in three formats:

YAML notation	Value passed to `args`	Parse example
`arguments: "value"`	`["value"]`	`new JSONArray(args).getString(0)`
`arguments: ["a", "b"]`	`["a", "b"]`	`new JSONArray(args)`
`arguments: {key: "value"}`	`{"key": "value"}`	`new JSONObject(args)`

The args parameter receives a JSON string. Use ActionArgs.parse() for unified access.

import com.scivicslab.pojoactor.core.ActionArgs;

@Action("example")
public ActionResult example(String args) {
    var p = ActionArgs.parse(args);  // Parse in one line

    // For array format (arguments: "value" or arguments: ["a", "b"])
    String first = p.get(0);
    String second = p.get(1);

    // For object format (arguments: {host: "server", port: 8080})
    String host = p.get("host");
    int port = p.getInt("port", 80);  // With default value
}

Step 3: Create the YAML Workflow

Define the workflow in YAML. POJO-actor v2.14 allows you to write actions concisely using array format.

Array Format vs Object Format

Traditional object format:

- actor: turing
  method: put
  arguments: "e"

Array format (introduced in v2.14):

- [turing, put, "e"]

Array elements are in order: [actorName, methodName, arguments]. If there are no arguments, just [actorName, methodName] is fine.

turing87.yaml

turing87 uses conditional branching to output the irrational number 0.001011011101111... Here is the state transition diagram:

Using array format makes it very concise:

name: turing87
steps:
- states: ["0", "100"]
  actions:
  - [turing, initMachine]
- states: ["100", "1"]
  actions:
  - [turing, printTape]
- states: ["1", "2"]
  actions:
  - [turing, put, "e"]
  - [turing, move, "R"]
  - [turing, put, "e"]
  - [turing, move, "R"]
  - [turing, put, "0"]
  - [turing, move, "R"]
  - [turing, move, "R"]
  - [turing, put, "0"]
  - [turing, move, "L"]
  - [turing, move, "L"]
- states: ["101", "2"]
  actions:
  - [turing, printTape]
- states: ["2", "2"]
  actions:
  - [turing, matchCurrentValue, "1"]
  - [turing, move, "R"]
  - [turing, put, "x"]
  - [turing, move, "L"]
  - [turing, move, "L"]
  - [turing, move, "L"]
- states: ["2", "3"]
  actions:
  - [turing, matchCurrentValue, "0"]
- states: ["3", "3"]
  actions:
  - [turing, isAny]
  - [turing, move, "R"]
  - [turing, move, "R"]
- states: ["3", "4"]
  actions:
  - [turing, isNone]
  - [turing, put, "1"]
  - [turing, move, "L"]
- states: ["4", "3"]
  actions:
  - [turing, matchCurrentValue, "x"]
  - [turing, put, " "]
  - [turing, move, "R"]
- states: ["4", "5"]
  actions:
  - [turing, matchCurrentValue, "e"]
  - [turing, move, "R"]
- states: ["4", "4"]
  actions:
  - [turing, isNone]
  - [turing, move, "L"]
  - [turing, move, "L"]
- states: ["5", "5"]
  actions:
  - [turing, isAny]
  - [turing, move, "R"]
  - [turing, move, "R"]
- states: ["5", "101"]
  actions:
  - [turing, isNone]
  - [turing, put, "0"]
  - [turing, move, "L"]
  - [turing, move, "L"]

Approximately 170 lines reduced to about 70 lines. Array format greatly improves workflow readability.

Step 4: Create the Application (Same as Part 2-2)

The application code is exactly the same. Just change the YAML filename.

TuringWorkflowApp.java

import com.scivicslab.pojoactor.core.ActionResult;
import com.scivicslab.pojoactor.workflow.IIActorSystem;
import com.scivicslab.pojoactor.workflow.Interpreter;
import java.io.InputStream;

public class TuringWorkflowApp {

    public static void main(String[] args) {
        String yamlPath = "/code/turing87.yaml";
        new TuringWorkflowApp().runWorkflow(yamlPath);
    }

    public void runWorkflow(String yamlPath) {
        // 1. Create IIActorSystem
        IIActorSystem system = new IIActorSystem("turing-system");

        try {
            // 2. Create POJO
            Turing turing = new Turing();

            // 3. Wrap with IIActorRef and register with system
            TuringIIAR turingActor = new TuringIIAR("turing", turing, system);
            system.addIIActor(turingActor);

            // 4. Create Interpreter
            Interpreter interpreter = new Interpreter.Builder()
                    .loggerName("TuringWorkflow")
                    .team(system)
                    .build();

            // 5. Load YAML
            InputStream yamlStream = getClass().getResourceAsStream(yamlPath);
            interpreter.readYaml(yamlStream);

            // 6. Execute workflow (max 100 iterations)
            ActionResult result = interpreter.runUntilEnd(100);

            // 7. Display result
            System.out.println("Result: " + result.getResult());

        } finally {
            // 8. Cleanup
            system.terminateIIActors();
            system.terminate();
        }
    }
}

Execution Result (Same as Part 2-2)

Loading workflow from: /code/turing87.yaml
Workflow loaded successfully
Executing workflow...

TAPE    C 0 1
TAPE    C C 0 1 1
TAPE    C C C 0 1 1 1
TAPE    C C C C 0 1 1 1 1
...

Workflow finished: Maximum iterations (100) exceeded

The output pattern shows "0 followed by an increasing number of 1s" (C is a counter). The output is exactly the same as Part 2-2. The only difference is the implementation method of the IIActorRef.

Internal Mechanism: How @Action Works

When callByActionName is called, the IIActorRef base class processes in this order:

Search for @Action methods — Scans the wrapped object's (this.object) class for methods annotated with @Action
If found, invoke it — Calls the method via reflection and returns the result
If not found, fallback — Tries subclass switch statements or built-in actions (like putJson)

This allows switch-based code and @Action-based code to coexist. Gradual migration is possible.

Summary

The difference between Part 2-2 and Part 2-3 is only Step 2 (IIActorRef creation):

Step	Content	Part 2-2	Part 2-3
1	Create POJO	Same	Same
2	Create IIActorRef	Override `callByActionName()`	Just add `@Action`
3	Create YAML	Same	Same
4	Create Application	Same	Same

With the @Action annotation:

No need to override callByActionName() — Boilerplate disappears
Manage by method — Easy to add/remove actions
Coexists with existing code — Gradual migration possible

Less boilerplate means cleaner, more readable code.

Try It Yourself

All examples in this tutorial are available in the actor-WF-examples repository. To run the @Action annotation version:

git clone https://github.com/scivicslab/POJO-actor
cd POJO-actor
mvn install

cd ..
git clone https://github.com/scivicslab/actor-WF-examples
cd actor-WF-examples
mvn compile
mvn exec:java -Dexec.mainClass="com.scivicslab.turing.TuringWorkflowApp" -Dexec.args="turing87-array --action"

See the repository's README for detailed setup instructions and project structure.

References

Official Manual: https://scivicslab.com/docs/pojo-actor/introduction
GitHub (POJO-actor): https://github.com/scivicslab/POJO-actor
GitHub (Workflow examples): https://github.com/scivicslab/actor-WF-examples
Maven Repository: https://mvnrepository.com/search?q=com.scivicslab
POJO-actor v1.0 Introduction (blog): A Lightweight Actor Model Library for Java
Tutorial Part 2-1 (blog): Workflow Language Basics
Tutorial Part 2-2 (blog): Creating Workflows

POJO-actor Tutorial Part 2 (Second Half): Creating Workflows

devteam@scivicslab.com — Sun, 25 Jan 2026 19:18:47 +0000

Original: scivicslab.com
Documentation: POJO-actor Docs
GitHub: scivicslab/POJO-actor
Javadoc: API Reference

This tutorial explains the complete process of making ordinary Java classes (POJOs) callable from workflows.

Using turing83 (a Turing machine that outputs the binary representation of 1/3) as an example, we proceed through the following four steps:

Create POJO: An ordinary Java class with business logic
Create IIActorRef: An adapter to call the POJO from workflows
Create YAML: The workflow definition
Execute: Run the workflow with IIActorSystem

[YAML] → [Interpreter] → [IIActorRef] → [POJO]

Step 1: Creating the POJO

First, create an ordinary Java class containing the business logic you want to manipulate in the workflow. This class knows nothing about workflows. It's just a plain POJO.

Turing.java (excerpt)

public class Turing {
    int currentPos = 0;
    Tape tape = new Tape();

    /** Initialize the machine */
    public void initMachine() {
        this.currentPos = 0;
        this.tape = new Tape();
    }

    /** Write a value to the tape */
    public void put(String value) {
        this.tape.setWithResizing(this.currentPos, value);
    }

    /** Move the head ("L"=left, "R"=right) */
    public void move(String direction) {
        if (direction.equalsIgnoreCase("L")) {
            this.currentPos--;
        } else if (direction.equalsIgnoreCase("R")) {
            this.currentPos++;
        }
    }

    /** Print the tape contents */
    public void printTape() {
        System.out.println("TAPE\t" + this.tape.toString());
    }
}

Key points:

No knowledge of workflows or actors required
Testable as an ordinary Java class
Methods have simple inputs and outputs

Step 2: Creating the IIActorRef

Next, create an adapter (IIActorRef) to call the POJO from workflows. This class receives method names and arguments specified in YAML and invokes the actual POJO methods.

TuringIIAR.java

import com.scivicslab.pojoactor.core.ActionResult;
import com.scivicslab.pojoactor.workflow.IIActorRef;
import com.scivicslab.pojoactor.workflow.IIActorSystem;
import org.json.JSONArray;

public class TuringIIAR extends IIActorRef<Turing> {

    public TuringIIAR(String actorName, Turing turing, IIActorSystem system) {
        super(actorName, turing, system);
    }

    // Parse arguments from JSON array: ["0"] → "0"
    private String parseFirstArg(String args) {
        if (args == null || args.isEmpty() || args.equals("[]")) {
            return "";
        }
        JSONArray array = new JSONArray(args);
        return array.length() > 0 ? array.getString(0) : "";
    }

    @Override
    public ActionResult callByActionName(String actionName, String args) {
        try {
            switch (actionName) {
                case "initMachine":
                    this.tell(t -> t.initMachine()).get();
                    return new ActionResult(true, "Machine initialized");

                case "put":
                    String putValue = parseFirstArg(args);
                    this.tell(t -> t.put(putValue)).get();
                    return new ActionResult(true, "Put " + putValue);

                case "move":
                    String direction = parseFirstArg(args);
                    this.tell(t -> t.move(direction)).get();
                    return new ActionResult(true, "Moved " + direction);

                case "printTape":
                    this.tell(t -> t.printTape()).get();
                    return new ActionResult(true, "Tape printed");

                default:
                    return new ActionResult(false, "Unknown action: " + actionName);
            }
        } catch (Exception e) {
            return new ActionResult(false, "Error: " + e.getMessage());
        }
    }
}

Key Concepts

The callByActionName Method

The core part to implement when extending IIActorRef is the callByActionName method. The first argument actionName receives the name specified in YAML's method: (e.g., "put", "move"), and the second argument args receives the YAML's arguments: converted to a JSON array string (e.g., ["0"], ["R"]). Within this method, you call the appropriate POJO method based on actionName and return the result as an ActionResult.

The Role of ActionResult

The return value ActionResult controls workflow branching. Returning ActionResult(true, message) is considered success, and the next action is executed, or if all actions succeed, transition to the to-state occurs. On the other hand, returning ActionResult(false, message) is considered failure, and this Row is immediately aborted, and the next Row with the same from-state is tried. This mechanism enables conditional branching by listing multiple Rows with the same from-state.

tell() and ask()

tell() is used for method calls that don't use the return value, and ask() is used for method calls that use the return value (such as condition checking).

// tell: wait for result but don't use the value
this.tell(t -> t.put("0")).get();

// ask: use the result value
boolean result = this.ask(t -> t.matchCurrentValue("1")).get();
return new ActionResult(result, "match=" + result);

Within IIActorRef, simply write tell(action).get() or ask(action).get(). You don't need to worry about which thread pool executes the action on the IIActorRef side. The Interpreter examines the Action class's execution field (ExecutionMode) and selects the appropriate pool. ExecutionMode has two types: POOL (execute on ManagedThreadPool, default) and DIRECT (direct call). Unless explicitly specified in YAML, POOL is used, so CPU-intensive processing is executed safely.

Step 3: Creating the YAML Workflow

Once the POJO and IIActorRef are ready, describe the workflow in YAML.

turing83.yaml

name: turing83
steps:
- states: ["0", "1"]
  actions:
  - actor: turing
    method: initMachine
- states: ["1", "2"]
  actions:
  - actor: turing
    method: printTape
- states: ["2", "3"]
  actions:
  - actor: turing
    method: put
    arguments: "0"
  - actor: turing
    method: move
    arguments: "R"
- states: ["3", "4"]
  actions:
  - actor: turing
    method: move
    arguments: "R"
- states: ["4", "5"]
  actions:
  - actor: turing
    method: put
    arguments: "1"
  - actor: turing
    method: move
    arguments: "R"
- states: ["5", "1"]
  actions:
  - actor: turing
    method: move
    arguments: "R"

YAML Structure

Element	Description
`name`	Workflow name
`steps`	List of Rows
`states`	`[from-state, to-state]`
`actions`	List of actions to execute
`actor`	IIActorRef name (the name registered in Step 4)
`method`	Action name passed to callByActionName
`arguments`	Arguments passed to callByActionName (converted to JSON array)

Step 4: Creating the Execution Application

Finally, create an application that combines everything and executes it.

TuringWorkflowApp.java

import com.scivicslab.pojoactor.core.ActionResult;
import com.scivicslab.pojoactor.workflow.IIActorSystem;
import com.scivicslab.pojoactor.workflow.Interpreter;
import java.io.InputStream;

public class TuringWorkflowApp {

    public static void main(String[] args) {
        String yamlPath = "/code/turing83.yaml";
        new TuringWorkflowApp().runWorkflow(yamlPath);
    }

    public void runWorkflow(String yamlPath) {
        // 1. Create IIActorSystem
        IIActorSystem system = new IIActorSystem("turing-system");

        try {
            // 2. Create POJO
            Turing turing = new Turing();

            // 3. Wrap with IIActorRef and register with system
            TuringIIAR turingActor = new TuringIIAR("turing", turing, system);
            system.addIIActor(turingActor);

            // 4. Create Interpreter
            Interpreter interpreter = new Interpreter.Builder()
                    .loggerName("TuringWorkflow")
                    .team(system)
                    .build();

            // 5. Load YAML
            InputStream yamlStream = getClass().getResourceAsStream(yamlPath);
            interpreter.readYaml(yamlStream);

            // 6. Execute workflow (max 50 iterations)
            ActionResult result = interpreter.runUntilEnd(50);

            // 7. Display result
            System.out.println("Result: " + result.getResult());

        } finally {
            // 8. Cleanup
            system.terminateIIActors();
            system.terminate();
        }
    }
}

Execution Flow

1. Create IIActorSystem
       ↓
2. Create POJO (Turing)
       ↓
3. Wrap with IIActorRef (TuringIIAR)
   └─ Register with name "turing"
       ↓
4. Create Interpreter
   └─ Reference IIActorSystem
       ↓
5. Load YAML
   └─ actor: "turing" → Reference registered TuringIIAR
       ↓
6. Execute with runUntilEnd()
   └─ Repeat state transitions
       ↓
7. Finish

How to Run

# Build POJO-actor
git clone https://github.com/scivicslab/POJO-actor
cd POJO-actor
mvn clean install

# Build and run actor-WF-examples
git clone https://github.com/scivicslab/actor-WF-examples
cd actor-WF-examples
mvn compile
mvn exec:java -Dexec.mainClass="com.scivicslab.turing.TuringWorkflowApp" -Dexec.args="turing83"

Output:

Loading workflow from: /code/turing83.yaml
Workflow loaded successfully
Executing workflow...

TAPE    0    value
TAPE    0    value    0 1
TAPE    0    value    0 1 0 1
TAPE    0    value    0 1 0 1 0 1
...

Workflow finished: Maximum iterations (50) exceeded

Summary

Steps to create a workflow:

Step	What to Create	Role
1	POJO	Business logic (workflow-independent)
2	IIActorRef	Bridge between YAML and POJO
3	YAML	Workflow definition
4	App	Assemble and execute everything

This structure separates business logic (POJO) from workflow control (YAML), allowing each to be tested and modified independently.

Last updated: 2025-12-31
Related documents:

POJO-actor Tutorial Part 2 (First Half): Workflow Language Basics

devteam@scivicslab.com — Sun, 25 Jan 2026 19:16:35 +0000

Original: scivicslab.com
Documentation: POJO-actor Docs
GitHub: scivicslab/POJO-actor
Javadoc: API Reference

POJO-actor v1.x delivers a complete actor model foundation—ActorSystem, ActorRef with tell()/ask() messaging, virtual thread-based concurrency, and work-stealing pools—all in under 800 lines of code. Virtual threads enable even an ordinary laptop to handle tens of thousands of actors effortlessly. With no reflection and full GraalVM Native Image support, it turns any POJO into an actor without modification.

Version 2.x introduces a workflow engine that enables actors to become autonomous agents --- entities that observe their environment and act according to their state.

From Actor to Agent: Introducing the Workflow Engine

In the actor model, each actor has a mailbox (message queue). Each actor retrieves messages from its queue one at a time and processes them sequentially. Meanwhile, multiple actors can operate independently and concurrently. This "sequential internally, parallel externally" structure allows programmers to achieve concurrent processing without worrying about locks.

The actor model is intuitive for humans, so it inherently has various applications. However, traditionally, implementations where one actor occupies one OS thread were common. This constrained the number of actors to the number of CPU cores, making large-scale applications difficult. With Virtual Threads since JDK 21, this constraint is being lifted. Being able to handle tens of thousands of actors opens up applications such as Agent-Based Simulations with many agents, or infrastructure-as-code platforms that monitor and autonomously repair computing resources.

As a foundation for enabling actors to behave autonomously—that is, to act as Agents that observe their environment and act according to their state—a workflow engine has been added in POJO-actor v2.x.

An agent is anything that can be viewed as perceiving its environment through sensors and acting upon that environment through actuators.
— Russell & Norvig, "Artificial Intelligence: A Modern Approach"

actor-WF: Simplifying Workflows

POJO-actor's workflow (actor-WF) is described using a simple model of "send this message to this actor":

  - states: ["start", "processed"]
    actions:
      - actor: dataProcessor    # actor name
        method: process          # method name
        arguments: ["data.csv"]  # arguments

With just three elements—actor, method, and arguments—all steps can be expressed uniformly. This follows the same mental model as tell()/ask() in Java code, and since actors operate independently, parallel execution can be described naturally.

Workflow behavior, conditional branching, and loops are expressed as state transitions. actor-WF is essentially a Turing machine, and complex conditional branching that traditional YAML/JSON-based workflow languages struggle with can be expressed without introducing custom syntax.

How actor-WF Works

actor-WF is essentially a Turing machine. Here we reproduce examples from Turing's original paper using actor-WF.

The following workflow is a Turing machine that computes the binary representation of the rational number 1/3. It writes symbols "0 1 0 1 0 1..." alternately on the tape while cycling through states 1→2→3→4→5→1.

— Charles Petzold, "The Annotated Turing", Wiley Publishing, Inc. (2008)

name: turing83
steps:
- states: ["0", "1"]
  actions:
  - actor: turing
    method: initMachine
- states: ["1", "2"]
  actions:
  - actor: turing
    method: printTape
- states: ["2", "3"]
  actions:
  - actor: turing
    method: put
    arguments: "0"
  - actor: turing
    method: move
    arguments: "R"
- states: ["3", "4"]
  actions:
  - actor: turing
    method: move
    arguments: "R"
- states: ["4", "5"]
  actions:
  - actor: turing
    method: put
    arguments: "1"
  - actor: turing
    method: move
    arguments: "R"
- states: ["5", "1"]
  actions:
  - actor: turing
    method: move
    arguments: "R"

Workflow Behavior

A workflow has multiple Rows (combinations of states and actions) under steps. The Interpreter maintains a current state (initially "0") and operates as follows.

State Matching and Transitions

Each Row's states is in the format [from-state, to-state]. The Interpreter searches from top to bottom for a Row with a from-state matching the current state.

Let's look at the turing83 example:

Initial state: current state = "0"
First Row states: ["0", "1"] matches
Execute actions (initMachine)
On success, update current state to "1"
Search for next matching Row → states: ["1", "2"]
Continue cycling: "1"→"2"→"3"→"4"→"5"→"1"→...

Action Execution and Conditional Branching

Each Row's actions are executed from top to bottom. Actions return either success (true) or failure (false).

All succeed: Transition to to-state
Failure midway: Abort this Row and try the next Row with the same from-state

This mechanism allows conditional branching by listing multiple Rows with the same from-state.

Termination Conditions

The workflow terminates under any of the following:

Current state becomes "end" (success)
No matching Row is found (failure)
Maximum iteration count is reached (failure)

Since turing83 has no "end" state and is an infinite loop, it terminates when the maximum iteration count is reached.

Running the Example

Clone https://github.com/scivicslab/actor-WF-examples, then build and run in the actor-WF-examples directory (requires JDK 21 or later):

git clone https://github.com/scivicslab/POJO-actor
cd POJO-actor
mvn clean install

git clone https://github.com/scivicslab/actor-WF-examples
cd actor-WF-examples
mvn compile
mvn exec:java -Dexec.mainClass="com.scivicslab.turing.TuringWorkflowApp" -Dexec.args="turing83"

Output:

Loading workflow from: /code/turing83.yaml
Workflow loaded successfully
Executing workflow...

TAPE    0    value
TAPE    0    value    0 1
TAPE    0    value    0 1 0 1
TAPE    0    value    0 1 0 1 0 1
TAPE    0    value    0 1 0 1 0 1 0 1
...

Workflow finished: Maximum iterations (50) exceeded

The pattern "0 1 0 1..." is generated on the tape. Since it's an infinite loop, it terminates when maxIterations (50) is reached.

A More Complex Example

The following is a Turing machine that outputs an irrational number. It outputs 001011011101111011111...

— Charles Petzold, "The Annotated Turing", Wiley Publishing, Inc. (2008)

Written in actor-WF:

name: turing87
steps:
- states: ["0", "100"]
  actions:
  - actor: turing
    method: initMachine
- states: ["100", "1"]
  actions:
  - actor: turing
    method: printTape
- states: ["1", "2"]
  actions:
  - actor: turing
    method: put
    arguments: "e"
  - actor: turing
    method: move
    arguments: "R"
  - actor: turing
    method: put
    arguments: "e"
  - actor: turing
    method: move
    arguments: "R"
  - actor: turing
    method: put
    arguments: "0"
  - actor: turing
    method: move
    arguments: "R"
  - actor: turing
    method: move
    arguments: "R"
  - actor: turing
    method: put
    arguments: "0"
  - actor: turing
    method: move
    arguments: "L"
  - actor: turing
    method: move
    arguments: "L"
- states: ["101", "2"]
  actions:
  - actor: turing
    method: printTape
- states: ["2", "2"]
  actions:
  - actor: turing
    method: matchCurrentValue
    arguments: "1"
  - actor: turing
    method: move
    arguments: "R"
  - actor: turing
    method: put
    arguments: "x"
  - actor: turing
    method: move
    arguments: "L"
  - actor: turing
    method: move
    arguments: "L"
  - actor: turing
    method: move
    arguments: "L"
- states: ["2", "3"]
  actions:
  - actor: turing
    method: matchCurrentValue
    arguments: "0"
- states: ["3", "3"]
  actions:
  - actor: turing
    method: isAny
  - actor: turing
    method: move
    arguments: "R"
  - actor: turing
    method: move
    arguments: "R"
- states: ["3", "4"]
  actions:
  - actor: turing
    method: isNone
  - actor: turing
    method: put
    arguments: "1"
  - actor: turing
    method: move
    arguments: "L"
- states: ["4", "3"]
  actions:
  - actor: turing
    method: matchCurrentValue
    arguments: "x"
  - actor: turing
    method: put
    arguments: " "
  - actor: turing
    method: move
    arguments: "R"
- states: ["4", "5"]
  actions:
  - actor: turing
    method: matchCurrentValue
    arguments: "e"
  - actor: turing
    method: move
    arguments: "R"
- states: ["4", "4"]
  actions:
  - actor: turing
    method: isNone
  - actor: turing
    method: move
    arguments: "L"
  - actor: turing
    method: move
    arguments: "L"
- states: ["5", "5"]
  actions:
  - actor: turing
    method: isAny
  - actor: turing
    method: move
    arguments: "R"
  - actor: turing
    method: move
    arguments: "R"
- states: ["5", "101"]
  actions:
  - actor: turing
    method: isNone
  - actor: turing
    method: put
    arguments: "0"
  - actor: turing
    method: move
    arguments: "L"
  - actor: turing
    method: move
    arguments: "L"

This example includes conditional branching using multiple Rows with the same from-state.

# From state 2: if current value is "1", stay in state 2
- states: ["2", "2"]
  actions:
    - actor: turing
      method: matchCurrentValue
      arguments: "1"
    # ... subsequent actions

# From state 2: if current value is "0", go to state 3
- states: ["2", "3"]
  actions:
    - actor: turing
      method: matchCurrentValue
      arguments: "0"

If matchCurrentValue("1") returns true → Execute first Row, remain in state 2
If matchCurrentValue("1") returns false → Abort this Row, try next Row
If matchCurrentValue("0") returns true → Transition to state 3

Running the Example

git clone https://github.com/scivicslab/POJO-actor
cd POJO-actor
mvn clean install

git clone https://github.com/scivicslab/actor-WF-examples
cd actor-WF-examples
mvn compile
mvn exec:java -Dexec.mainClass="com.scivicslab.turing.TuringWorkflowApp" -Dexec.args="turing87"

Output:

Loading workflow from: /code/turing87.yaml
Workflow loaded successfully
Executing workflow...

TAPE    0    value
TAPE    0    value    ee0 0 1 0
TAPE    0    value    ee0 0 1 0 1 1 0
TAPE    0    value    ee0 0 1 0 1 1 0 1 1 1 0
TAPE    0    value    ee0 0 1 0 1 1 0 1 1 1 0 1 1 1 1 0

Workflow finished: Maximum iterations (200) exceeded

Summary

What we covered in this tutorial:

Basic workflow structure: Combinations of states and actions
State transitions: Control flow through transitions from from-state to to-state
Conditional branching: Achieved by listing multiple Rows with the same from-state
Loops: Achieved through state cycles (e.g., 1→2→3→4→5→1)

actor-WF is based on the same design philosophy as Turing machines. Any complexity of processing can be expressed through combinations of state transitions and actions.

Next Steps

To create your own workflows, you need to implement an adapter (IIActorRef) to call POJOs from workflows. See the following for details:

References

POJO-actor: https://github.com/scivicslab/POJO-actor
actor-WF-examples: https://github.com/scivicslab/actor-WF-examples

POJO-actor v1.0: A Lightweight Actor Model Library for Java

devteam@scivicslab.com — Mon, 22 Dec 2025 19:51:55 +0000

📚 Official Documentation: scivicslab.com/docs/pojo-actor

🔗 GitHub: github.com/scivicslab/POJO-actor

The actor model is a programming paradigm where independent entities (actors) communicate through message passing, eliminating the need for locks and avoiding the complexities of shared-state concurrency. Traditionally, using the actor model required specialized frameworks, and because these frameworks relied on real operating system threads, you could only create as many actors as you had CPU cores — typically just a handful. However, recent advancements in the JDK, particularly the introduction of virtual threads in Java 21, have changed everything: now even an ordinary laptop can handle tens of thousands of actors simultaneously.

https://github.com/scivicslab/POJO-actor

Architecture

POJO-actor implements a simplified actor model built on modern Java features. Built with just ~800 lines of code, POJO-actor delivers a practical actor model implementation without sacrificing functionality or performance.

ActorSystem: Manages actor lifecycle and configurable work-stealing thread pools
ActorRef: Reference to an actor that provides tell() and ask() messaging interface
Virtual Threads: Each actor runs on its own virtual thread for lightweight message handling
Work-Stealing Pools: Heavy computations are delegated to configurable thread pools
Zero Reflection: Built entirely with standard JDK APIs, making it GraalVM Native Image ready

Quick Start

Maven Dependency

<dependency>
    <groupId>com.scivicslab</groupId>
    <artifactId>POJO-actor</artifactId>
    <version>1.0.0</version>
</dependency>

Note: This library will be published to Maven Central soon. For now, please install it to your local repository first:

git clone https://github.com/scivicslab/POJO-actor
cd POJO-actor
./mvnw install

Basic Usage

import com.scivicslab.pojoactor.ActorSystem;
import com.scivicslab.pojoactor.ActorRef;

// Define your POJO
class Counter {
    private int count = 0;

    public void increment() {
        count++;
    }

    public int getValue() {
        return count;
    }
}

// Create actor system and actors
ActorSystem system = new ActorSystem("mySystem", 4); // 4 threads for CPU-intensive tasks
ActorRef<Counter> counter = system.actorOf("counter", new Counter());

// Send messages to actors
counter.tell(c -> c.increment());  // Fire-and-forget
CompletableFuture<Integer> result = counter.ask(c -> c.getValue());  // Request-response

// Get the result
int value = result.get(); // Returns 1

// Cleanup
system.terminate();

Any POJO Can Become an Actor

One of POJO-actor’s biggest advantages is that you don’t need to design your code specifically for the actor model from the beginning. Any existing Java object can instantly become an actor, including standard library classes:

import java.util.ArrayList;
import java.util.concurrent.CompletableFuture;

// Turn a standard ArrayList into an actor - no modifications needed!
ActorSystem system = new ActorSystem("listSystem");
ActorRef<ArrayList<String>> listActor = system.actorOf("myList", new ArrayList<String>());

// Send messages to the ArrayList actor
listActor.tell(list -> list.add("Hello"));
listActor.tell(list -> list.add("World"));
listActor.tell(list -> list.add("from"));
listActor.tell(list -> list.add("POJO-actor"));

// Query the list size
CompletableFuture<Integer> sizeResult = listActor.ask(list -> list.size());
System.out.println("List size: " + sizeResult.get()); // Prints: List size: 4

// Get specific elements
CompletableFuture<String> firstElement = listActor.ask(list -> list.get(0));
System.out.println("First element: " + firstElement.get()); // Prints: First element: Hello

// Even complex operations work
CompletableFuture<String> joinedResult = listActor.ask(list ->
    String.join(" ", list));
System.out.println(joinedResult.get()); // Prints: Hello World from POJO-actor

system.terminate();

This means you can:

Retrofit existing codebases without architectural changes
Protect any object with actor-based thread safety
Scale incrementally by converting objects to actors as needed
Reuse existing POJOs without any modifications

Massive Actor Scalability

Thanks to virtual threads, POJO-actor can handle thousands of actors efficiently. Here’s an example creating 10,000 counter actors:

ActorSystem system = new ActorSystem("massiveSystem", 4); // Only 4 CPU threads for computation
List<ActorRef<Counter>> actors = new ArrayList<>();

// Create 10,000 actors - no problem with virtual threads!
for (int i = 0; i < 10000; i++) {
    ActorRef<Counter> actor = system.actorOf("counter" + i, new Counter());
    actors.add(actor);
}

// Send messages to all actors concurrently
List<CompletableFuture<Void>> futures = new ArrayList<>();
for (ActorRef<Counter> actor : actors) {
    futures.add(actor.tell(c -> c.increment()));
}

// Wait for all messages to be processed
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).get();

// Verify results from all 10,000 actors
for (ActorRef<Counter> actor : actors) {
    int value = actor.ask(c -> c.getValue()).get();
    assert value == 1; // Each counter was incremented once
}

System.out.println("Successfully processed messages for 10,000 actors!");
system.terminate();

This demonstrates POJO-actor’s ability to:

Create thousands of actors without thread exhaustion
Control CPU usage (only 4 threads for heavy computation)
Scale beyond traditional thread-per-actor limitations

Advanced Usage

Parallel Matrix Multiplication

POJO-actor excels at parallel computation tasks. Here’s an example of distributed matrix multiplication that demonstrates the proper use of work-stealing pools for heavy computations:

// Create large matrices for multiplication
final int matrixSize = 400;
final int blockSize = 100;
double[][] matrixA = new double[matrixSize][matrixSize];
double[][] matrixB = new double[matrixSize][matrixSize];

// Create ActorSystem with 4 CPU threads for heavy computation
ActorSystem system = new ActorSystem("matrixSystem", 4);
List<CompletableFuture<Double>> futures = new ArrayList<>();

// Divide matrix into blocks and assign to different actors
for (int blockRow = 0; blockRow < 4; blockRow++) {
    for (int blockCol = 0; blockCol < 4; blockCol++) {
        MatrixCalculator calculator = new MatrixCalculator();
        ActorRef<MatrixCalculator> actor = system.actorOf(
            String.format("block_%d_%d", blockRow, blockCol), calculator);

        // Light operation: Initialize actor with block coordinates (uses virtual thread)
        actor.tell(calc -> calc.initBlock(matrixA, matrixB, blockRow, blockCol)).get();

        // Heavy computation: Matrix multiplication (uses work-stealing pool)
        CompletableFuture<Double> blockSum = actor.ask(
            calc -> calc.calculateBlock(), // CPU-intensive matrix multiplication
            system.getWorkStealingPool()   // Delegate to work-stealing pool
        );

        futures.add(blockSum);
    }
}

// Wait for all parallel calculations to complete
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).get();

Key Performance Points:

Light operations: initBlock() just sets references, so virtual threads are perfect
Heavy computation: calculateBlock() does actual matrix multiplication, so work-stealing pool is essential
Virtual threads: Handle only setter/getter level operations, almost no computation
CPU control: Only 4 CPU threads handle all heavy computation, regardless of actor count
Responsiveness: Actors remain responsive to light messages during heavy computation
Scalability: Can create thousands of actors without exhausting system resources

Custom Thread Pools

ActorSystem system = new ActorSystem("system");

// Add additional work-stealing pools
system.addWorkStealingPool(8);  // CPU-intensive tasks
system.addWorkStealingPool(2);  // I/O-bound tasks

// Use specific thread pools
counter.tell(c -> c.increment(), system.getWorkStealingPool(1));

Actor Hierarchies

ActorRef<ParentActor> parent = system.actorOf("parent", new ParentActor());
ActorRef<ChildActor> child = parent.createChild("child", new ChildActor());

GraalVM Native Image Support

Traditional actor model frameworks rely heavily on reflection for message routing, serialization, and dynamic proxy generation, making them incompatible with GraalVM Native Image compilation. These frameworks require extensive configuration files and reflection hints to work with native compilation, if at all.

POJO-actor is built using only modern JDK features, making the library itself very simple and easy to understand. It uses no reflection whatsoever. As a result, code written with POJO-actor compiles seamlessly to GraalVM Native Images without any obstacles:

# Compile to native image
native-image -jar target/POJO-actor-1.0.0-fat.jar -o pojo-actor-native

# Run native executable
./pojo-actor-native# Run native executable
./pojo-actor-native

No additional configuration files or reflection hints are required.

Performance

Startup Time: Near-instant with native compilation
Memory Usage: Minimal heap allocation due to POJO-based design
Throughput: High message processing rates with virtual threads
Scalability: Efficient work-stealing thread pools for parallel tasks

Performance Best Practices

For optimal performance, it’s crucial to understand when to use virtual threads vs. work-stealing pools:

Light Operations — Use Default Virtual Threads

// Fast operations that don't block or consume much CPU
counter.tell(c -> c.increment());
counter.tell(c -> c.setName("newName"));
listActor.tell(list -> list.add("item"));

CompletableFuture<Integer> size = listActor.ask(list -> list.size());

Heavy Computations — Delegate to Work-Stealing Pools

ActorSystem system = new ActorSystem("system", 4); // 4 CPU threads for heavy work

// CPU-intensive calculations should use work-stealing pool
CompletableFuture<Double> result = calculator.ask(c -> c.performMatrixMultiplication(),
                                                 system.getWorkStealingPool());

// I/O operations or blocking calls should also use work-stealing pool
CompletableFuture<String> data = dataProcessor.ask(p -> p.readLargeFile(),
                                                   system.getWorkStealingPool());

Why This Matters

Virtual threads are perfect for lightweight message passing and state changes
Work-stealing pools handle CPU-intensive tasks without blocking virtual threads
This separation prevents heavy computations from affecting the actor system’s responsiveness
You can control CPU core usage by configuring the work-stealing pool size

// Example: Mixed workload with proper thread pool usage
ActorSystem system = new ActorSystem("mixedSystem", 4);
ActorRef<DataProcessor> processor = system.actorOf("processor", new DataProcessor());

// Light operation - uses virtual thread
processor.tell(p -> p.updateCounter());

// Heavy operation - uses work-stealing pool
CompletableFuture<ProcessResult> heavyResult = processor.ask(
    p -> p.performComplexAnalysis(largeDataset),
    system.getWorkStealingPool()
);

// The actor remains responsive to light messages while heavy computation runs in background
processor.tell(p -> p.logStatus()); // This won't be blocked by heavy computation

Requirements

Java 21 or higher
Maven 3.6+

Dependencies

Runtime: JDK standard library only
Testing: JUnit 5, Apache Commons Math (test scope only)

Building

# Compile and test
mvn clean test

# Build JAR
mvn clean package

# Generate Javadoc
mvn javadoc:javadoc# Build JAR
mvn clean package

Acknowledgments

POJO-actor was inspired by Alexander Zakusylo’s actr library, which pioneered the POJO-based actor model approach in Java. While actr introduced many excellent concepts, POJO-actor extends and improves upon them with:

Message ordering guarantee: Unlike actr, POJO-actor ensures that messages sent to an actor are processed in the order they were sent
Modern Java features: Built with Java 21+ virtual threads and modern concurrency patterns
Enhanced thread pool management: actr used real threads for actors, limiting scalability to CPU core count and causing performance issues with heavy computations. POJO-actor uses virtual threads for actors and delegates heavy computations to configurable work-stealing pools, allowing thousands of actors while controlling CPU core usage

We acknowledge the foundational work done by the actr library team in making actor model programming more accessible to Java developers.

We also acknowledge Comedy.js, a Node.js actor framework, which inspired POJO-actor's basic architecture design, particularly the ActorSystem and ActorRef concepts. While Comedy.js uses one process or one real thread per actor, POJO-actor leverages Java's virtual threads to enable thousands of lightweight actors.

DEV Community: devteam@scivicslab.com

quarkus-chat-ui (2): The Actor Design Behind LLM-to-LLM Conversation

Quick POJO-actor recap

The problem: blocking I/O kills the message loop

ChatActor: the state guardian

Why volatile Thread activeThread?

Why tellNow() for cancel?

BtwActor: a second independent actor

Thread safety with a shared provider

The actor system structure

What I like about this approach

Links

quarkus-chat-ui: A Web Front-End for LLMs, and a Real-World Case for POJO-actor

quarkus-chat-ui: A Web Front-End for LLMs, and a Real-World Case for POJO-actor

What it does

1. LLM instances talking to each other via MCP

2. Written in Quarkus — streaming made simple

3. A prompt queue that does the obvious thing

Why the concurrency is manageable

Quick start

Preparing a local LLM (openai-compat)

Option 1: Native executable (no JDK required)

Option 2: Build from source

Setting up two agents to talk (Claude Code CLI)

1. Install Claude Code CLI

2. Set API Key

3. Start Alice (port 28010)

4. Start Bob (port 28020)

5. Register MCP Endpoints

6. Restart Both Instances

7. Test: Alice Sends to Bob

8. Verify: Bob Receives

Cleanup

Troubleshooting

Beyond two agents

Links

actor-IaC: POJO-actor Workflow Based Infrastructure as Code for Cluster Management (Part 1)

Why Use POJO-actor Workflow for IaC?

Consistent Notation

Natural Conditional Branching

The Actor Tree: A Mental Model for Cluster Management

Complete Traceability of Execution Logs (Cluster Operations)

Hands-on: Collecting Cluster Information

1. Inventory File

2. Sub-workflow (Processing Executed on Each Node)

3. Main Workflow (Applying to All Nodes)

Execution

Checking Results

actor-IaC Features

Summary

Try It Yourself

References

POJO-actor Tutorial Part 2-3: Improving the Workflow API — Introducing the @Action Annotation

Introduction

Step 1: Create the POJO (Same as Part 2-2)

Turing.java

Step 2: Create the IIActorRef — @Action Annotation Version

Part 2-2 Code (switch statement version)

Part 2-3 Code (@Action version)

@Action Method Requirements

Argument Formats

Step 3: Create the YAML Workflow

Array Format vs Object Format

turing87.yaml

Step 4: Create the Application (Same as Part 2-2)

TuringWorkflowApp.java

Execution Result (Same as Part 2-2)

Internal Mechanism: How @Action Works

Summary

Try It Yourself

References

POJO-actor Tutorial Part 2 (Second Half): Creating Workflows

Step 1: Creating the POJO

Turing.java (excerpt)

Step 2: Creating the IIActorRef

TuringIIAR.java

Key Concepts

The callByActionName Method

The Role of ActionResult

tell() and ask()

Why `volatile Thread activeThread`?

Why `tellNow()` for cancel?