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.

Entity: holds values and links EntityValue: produces data PassiveEntityValue: holds data ActiveEntityValue: creates data Simpleton: manipulates entities Pool: holds entities Constraint: specifies sets of entities 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.

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 Constraints, a simple query language; a constraint specifies a subset of entities.

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. 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, DataManagerException.

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.

Entity API

• [package: org.datamanager.kernel]
  public abstract class Entity
  implements EventGenerator
• public static Entity create(String)
throws DataManagerException
  Create an entity with the given name

 

• public String getName()
throws DataManagerException
  Report the entity's name

 

• public Entity[] getAttributes(Constraint)
throws DataManagerException
  Report a constrained set of all entities linked to the bound entity

 

• public Entity[] getBases(Constraint)
throws DataManagerException
  Report a constrained set of all entities that the bound entity is linked to

 

• public void attach(Entity)
throws DataManagerException
  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)
throws DataManagerException
  Detach an entity that's presently an attribute of this entity. Do nothing if it's not attached.

 

• public EntityValue getValue()
throws DataManagerException
  Report the entity's value

 

• public void setValue(EntityValue)
throws DataManagerException
  Alter the entity's value

 

• public String toString()
  Report a String representation of the entity

 

• for subscribe() and unsubscribe() see EventGenerator

EntityValue API

• [package: org.datamanager.kernel]
  public interface EntityValue
  extends Serializable

PassiveEntityValue API

• [package: org.datamanager.passiveentityvalue]
  public interface PassiveEntityValue
  extends EntityValue
  • 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

Expanded PassiveEntityValue API.

ActiveEntityValue API

• [package: org.datamanager.activeentityvalue]
  public interface ActiveEntityValue
  extends EntityValue
  • public abstract EntityValue getEntityValue();
throws DataManagerException
    Return a dynamically computed entity value

Simpleton API

• [package: org.datamanager.kernel]
  public abstract class Simpleton
• protected abstract void process();
  Start simpleton execution

Pool API

• [package: org.datamanager.kernel]
  public class Pool
  implements EventGenerator
• public static Pool getDefaultPool()
throws DataManagerException
  Report the default pool

 

• public Entity[] search(Constraint)
throws DataManagerException
  Search for all entities in the pool that satisfy the constraint

 

• public void add(Entity)
throws DataManagerException
  Link an entity to the pool.
  Note: If you create() an entity it will not be found in a search() on a pool until you either add() it to the pool or attach() it to an entity already in the pool. You need not add() an entity to a pool if you attach() it to an entity already in the pool. In such a case, executing an add() has no effect.

 

• public void remove(Entity)
throws DataManagerException
  Remove all the entity's entity links as well as its link to the pool.

 

• for subscribe() and unsubscribe() see EventGenerator

Constraint APIs

• [package: org.datamanager.constraint]
  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

Expanded Constraint API.

EventHandler API

• [package: org.datamanager.kernel]
  public interface EventHandler
  • public abstract void handle(DataManagerEvent);
    Handle subscribed events

EventGenerator API

• [package: org.datamanager.kernel]
  public interface EventGenerator
  • public abstract void subscribe(EventHandler, Constraint)
throws DataManagerException
    Ask the event generator to pass all of its DataManagerEvents satisfying the given constraint to the given event handler
  
   
  
  • public abstract void unsubscribe(EventHandler)
throws DataManagerException
    Ask the event generator to stop passing any DataManagerEvents to the given event handler

DataManagerEvent API

• [package: org.datamanager.event]
  public interface DataManagerEvent
  extends EntityValue
  • 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()
    Report a String representation of the event

Expanded DataManagerEvent API.

DataManagerException API

• [package: org.datamanager.exception]
  public class DataManagerException
  extends java.lang.Exception