Roam API

Roam is the core container for passing data between nodes. Thread-safe, with support for multi-level keys and reference syntax.

Implementation Basis

Language	Underlying Implementation	Thread Safety Mechanism
Java	`ConcurrentHashMap<String, Object>`	CAS + segmented locks
Go	`sync.RWMutex` + `map[string]any`	Read-write lock
Python	`threading.RLock` + `dict`	Reentrant lock

Basic Read/Write

Multi-Level Keys

Keys separated by . automatically build nested data structures:

List Traversal

Numeric segments in multi-level keys can read elements from existing lists/arrays. Note: putDeep with numeric segments creates nested maps (with numeric strings as keys), not lists.

Reference Syntax

The @ prefix indicates indirect value retrieval from Roam. Non-@ prefixed values are returned as-is:

Use Cases for Reference Syntax

In the Server configuration interface, leaf node field values can be set as @key to dynamically retrieve values from Roam instead of hardcoding them.

Meta (Execution Metadata)

Roam holds execution metadata in a separate Meta struct/object (not in the data map).

Contains the following fields: id, scene, nid, ts, trace, debug, process.

Each language provides convenience accessors directly on Roam:

Go Value Fluent API

Value()/ValueDeep() return a RoamValue with chainable typed getters:

roam.Value("score").Int()           // int
roam.Value("score").IntOr(0)        // int, returns default if missing
roam.Value("score").Int64()         // int64
roam.Value("score").Int64Or(0)      // int64, returns default if missing
roam.Value("name").String()         // string
roam.Value("name").StringOr("N/A")  // string, with default
roam.Value("rate").Float64()        // float64
roam.Value("rate").Float64Or(0.0)   // float64, returns default if missing
roam.Value("active").Bool()         // bool
roam.Value("active").BoolOr(false)  // bool, returns default if missing
roam.Value("key").Exists()          // whether the key exists
roam.Value("key").Raw()             // raw any value

// Deep access
roam.ValueDeep("user.profile.level").Int()
roam.ValueDeep("user.profile.level").IntOr(1)

// Bind to pointer
var level int
roam.Value("level").To(&level)

cloneRoam

Shallow-copies the Roam: copies business data and clones Meta with a fresh process buffer. Primarily used for data isolation during parallel handler execution.

Complete Method List

Java (IceRoam)

Method	Description
`put(key, value)`	Write a value. Removes the key when value is null
`get(key)`	Read a value, returns Object
`putValue(key, value)`	Write a value (generic, no cast needed)
`getValue(key)`	Read a value (generic, no cast needed)
`putDeep(multiKey, value)`	Write nested structure using `.`-separated key
`getDeep(multiKey)`	Read nested value using `.`-separated key
`resolve(union)`	Reference syntax: `@` prefix fetches from roam
`getId()`	Get execution ID
`getScene()`	Get scene
`getTs()`	Get timestamp
`cloneRoam()`	Shallow copy Roam (used during parallel execution)

Go (Roam)

Method	Description
`Put(key, value)`	Write a value
`Get(key)`	Read a value, returns any
`PutDeep(multiKey, value)`	Nested write
`GetDeep(multiKey)`	Nested read
`Resolve(union)`	Reference syntax
`Data()`	Return data copy (without metadata)
`String()`	JSON-formatted output
`Value(key)`	Returns RoamValue with chainable typed getters
`ValueDeep(multiKey)`	Deep access, returns RoamValue
`GetMeta()`	Get Meta
`Clone()`	Shallow copy Roam (used during parallel execution)

Python (Roam)

Method	Description
`put(key, value)`	Write a value
`get(key, default=None)`	Read a value
`put_deep(key, value)`	Nested write
`get_deep(key, default=None)`	Nested read
`resolve(union)`	Reference syntax
`contains(key)`	Check if key exists
`remove(key)`	Remove key
`keys()`	All keys
`to_dict()`	Convert to dict
`get_meta()`	Get Meta
`clone()`	Shallow copy Roam (used during parallel execution)