The KnownSpace Hydrogen API
This API lists four classes and seven interfaces, divided into seven main 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, pools store entities, and constraints describe entities.
holds values and links
EntityValue: produces data
Pool: holds entities
Constraint: specifies sets of entities
Event: holds state change
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
Stored entity values should implement the
An entity can also have an
a computation that generates new values dynamically.
An active value may execute any computation whatsoever,
just as a
can, except that it has no thread of its own.
It will execute only when some simpleton requests its entity's value.
Simpletons and active entity values are together called 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 pool.
An actor can search a pool for entities using
a simple query language;
a constraint specifies a subset of entities.
An actor can delegate an
to listen for changes in any
by subscribing to a constraint-delimited set of
generated by the event generator as it changes state.
Events can be stored as entity values inside entities,
which can be tossed into the pool and then listened for by any event handler.
Currently, only pools and entities are event generators,
but since generators and handlers are defined by interfaces,
any class may also be a generator or handler
(although generators currently require special kernel support,
that is likely to change soon).
Finally, methods currently report errors through one catchall exception class,
This API applies to all application code written for KnownSpace Hydrogen.
It will be stable, or at least, backwardly compatible,
from January 1, 2000 to December 31, 2000.
public abstract class Entity
public static Entity create(String)
Create an entity with the given name
public String getName()
Report the entity's name
public Entity getAttributes(Constraint)
Report a constrained set of all entities linked to the bound entity
public Entity getBases(Constraint)
Report a constrained set of all entities that the bound entity is linked to
public void attach(Entity)
Attach an entity as an attribute of this entity. Do nothing if it's already attached as an attribute and throw an exception if it's attached as a base.
public void detach(Entity)
Detach an entity that's presently an attribute of this entity. Do nothing if it's not attached.
public EntityValue getValue()
Report the entity's value
public void setValue(EntityValue)
Alter the entity's value
public String toString()
String representation of the entity
public interface EntityValue
public interface PassiveEntityValue
public abstract boolean equals(Object);
Report whether the entity value has the same value as the given Object
public abstract int hashCode();
Report the entity value's hash code
public interface ActiveEntityValue
public abstract EntityValue getEntityValue();
Return a dynamically computed entity value
public abstract class Simpleton
protected abstract void process();
Start simpleton execution
public class Pool
public static Pool getDefaultPool()
Report the default pool
public Entity search(Constraint)
Search for all entities in the pool that satisfy the constraint
public void add(Entity)
Link an entity to the pool.
Note: If you
create() an entity it will not be found
search() on a pool
until you either
add() it to the pool
attach() it to an entity already in the pool.
You need not
add() an entity to a pool
attach() it to an entity already
in the pool.
In such a case, executing an
add() has no effect.
public void remove(Entity)
Remove all the entity's entity links as well as its link to the pool.
public interface Constraint
public abstract boolean accepts(Entity);
Report whether the given entity is in the set described by the constraint
public final static Constraint NONE
A constraint constant that places no constraints on entities
public interface EventHandler
public abstract void handle(DataManagerEvent);
Handle subscribed events
public interface EventGenerator
public abstract void subscribe(EventHandler, Constraint)
Ask the event generator to pass all of its
satisfying the given constraint
to the given event handler
public abstract void unsubscribe(EventHandler)
Ask the event generator to stop passing any
to the given event handler
public interface DataManagerEvent
public abstract EventGenerator getSource()
Report the object generating the event
public abstract long getTime()
Report the time the event occurred (in milliseconds)
public abstract String toString()
String representation of the event
public class DataManagerException