Coder Legion - Recent posts tagged actor-model

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

Wed, 28 Jan 2026 06:47:58 +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
Tutorial Part 2-3 (blog): Improving the Workflow API — Introducing the @Action Annotation

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

Wed, 28 Jan 2026 06:29:19 +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

Wed, 31 Dec 2025 10:51:18 +0000

Recap of the First Half

In the first half, we introduced the basic concepts of the workflow engine (actor-WF) added in POJO-actor v2.x. actor-WF is described using a simple model of "send this message to this actor," where all steps can be expressed uniformly with just three elements: actor, method, and arguments. Workflow behavior, conditional branching, and loops are expressed as state transitions, essentially having the same expressive power as a Turing machine.

In the first half, we examined YAML workflow descriptions and state transition-based conditional branching using turing83 (a Turing machine that outputs the binary representation of 1/3) and turing87 (a Turing machine that outputs an irrational number) as examples. In this second half, we introduce how to implement IIActorRef, which is necessary for creating your own workflows.

Overview

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 WorkStealingPool, 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

Wed, 31 Dec 2025 10:48:21 +0000

Recap of Part 1

In Part 1, we introduced the basic features of POJO-actor ver 1.x: POJO-actor is a library that allows you to convert ordinary POJOs into actors simply by wrapping them with ActorRef<T>, without modifying existing code. With Virtual Threads available since JDK 21, even commodity hardware can run tens of thousands of actors.

Since most of this is implemented using standard JDK 21+ features, POJO-actor ver 1.x is realized in under 1000 lines of code. POJO-actor ver 1.x was designed to explain the core implementation by implementing only the fundamental concepts.

Version 2.x adds features for practical use.

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