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:

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.

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)
`putMulti(multiKey, value)`	Write nested structure using `.`-separated key
`getMulti(multiKey)`	Read nested value using `.`-separated key
`getUnion(union)`	Reference syntax: `@` prefix fetches from roam

Go (Roam)

Method	Description
`Put(key, value)`	Write a value
`Get(key)`	Read a value, returns any
`GetInt(key, default)`	Read int
`GetFloat64(key, default)`	Read float64
`GetString(key)`	Read string
`PutMulti(multiKey, value)`	Nested write
`GetMulti(multiKey)`	Nested read
`GetUnion(union)`	Reference syntax
`Data()`	Return underlying map (read-only)
`String()`	JSON-formatted output

Python (Roam)

Method	Description
`put(key, value)`	Write a value
`get(key, default=None)`	Read a value
`get_int(key, default=0)`	Read int
`get_float(key, default=0.0)`	Read float
`get_str(key, default="")`	Read str
`get_bool(key, default=False)`	Read bool
`get_list(key, default=None)`	Read list
`get_dict(key, default=None)`	Read dict
`put_multi(key, value)`	Nested write
`get_multi(key)`	Nested read
`get_union(union)`	Reference syntax
`contains(key)`	Check if key exists
`remove(key)`	Remove key
`keys()`	All keys
`to_dict()`	Convert to dict
`shallow_copy()`	Shallow copy (used during parallel execution)