Helium Developer Documentation

The KnownSpace API

This API lists fifteen types (four classes, two inner classes, and nine interfaces), divided into seven groups: entities, entity values, simpletons, pools, constraints, events, and exceptions. Entities store data and data relationships, entity values store or generate data, simpletons manipulate entities and events, pools store entities and events, constraints describe entities or events, events describe state change, and exceptions describe execution errors.
Entity: holds values and links

EntityValue: produces data
PassiveEntityValue: holds data

ActiveEntityValue: creates data
Simpleton: a generic process
Priority: its priority

Information: its description
Pool: holds entities

Constraint: specifies sets ...
EntityConstraint: ...of entities

EventConstraint: ...of events
Event: holds state change
EventGenerator: creates events

EventHandler: listens for events
Exception: holds execution failure

An Entity has three parts: a name, a value, and a set of links to other entities. Its name is a shorthand way to refer to it in constraints, events, and exceptions. Its value is what it stores. Its links specify what entities it has as attributes and what entities it is an attribute of.

Each link relates two entities, a base entity and an attribute entity. Any entity may be an attribute of any other entity. Which entity is the base and which is the attribute depends solely on the direction of the link (bases point to attributes). There is no other difference between a base entity and an attribute entity.

What entities an entity may or may not be linked to has no bearing on the value that entity stores. Any entity may be the value of any entity, but that won't establish a link between one entity and another.

Entities can have arbitrary persistent objects as values, but those objects' classes must implement the EntityValue interface. Stored entity values should implement the PassiveEntityValue interface. An entity can also have an ActiveEntityValue, a computation that generates new values dynamically. An active value may execute any computation whatsoever, just as a Simpleton can, except that it has no thread of its own. It will execute only when some simpleton requests its entity's value.

Both simpletons and active entity values are actors. An actor can create entities, install and remove entity links, read and write entity values, and read and (on entity creation only) write an entity's name. Further, it can add entities to a Pool, remove them, and search a pool for entities. Currently, however, there is only one (default) pool. An actor can search a pool for entities using Constraints, a simple query language; a constraint specifies either a subset of entities or a subset of events.

An actor can delegate an EventHandler to listen for changes in any EventGenerator's state, by subscribing to a constraint-delimited set of DataManagerEvents generated by the event generator as it changes state. More generally, any class can toss events into a pool, and any event handler can listen for those events. Unlike entities, however, events are transient in the pool---they are not stored, so they can't be searched for. Currently, only pools and entities are event generators.

Finally, methods currently report errors through one catchall exception class, DataManagerException.

API links