sk.robotics.rlcs.agentspace
Class Space

java.lang.Object
  extended by sk.robotics.rlcs.agentspace.Space

public class Space
extends java.lang.Object

The space. Stores just references to objects, so it is a very good idea to try to store only immutable objects in the space. If mutable objects are stored, great care must be taken to avoid surprises. Space has its own thread, which manages block expiration, and takes care of expiration triggers.


Nested Class Summary
static class Space.Block
          A block in space.
 
Method Summary
 void attachTrigger(java.lang.String blockName, Agent agent, int triggerId)
          Add an agent trigger to a block.
 java.lang.Object delete(java.lang.String blockName)
           
 java.lang.Object delete(java.lang.String blockName, long validFor, float priority)
          Delete a block from the space.
 void detachTriggers(Agent agent)
          Detach an agent trigger from all blocks.
 Space.Block getBlock(java.lang.String blockName)
          Get a Block object (not only the stored value) from the space.
static Space getInstance()
          Access to the space.
 java.lang.Object read(java.lang.String blockName)
          Read an object from the space.
 java.lang.Object read(java.lang.String blockName, java.lang.Object def)
           
 void trigger(java.lang.String blockName)
          Simulate a block change, firing associated triggers.
 java.lang.Object write(java.lang.String blockName, java.lang.Object value)
           
 java.lang.Object write(java.lang.String blockName, java.lang.Object value, long validFor)
           
 java.lang.Object write(java.lang.String blockName, java.lang.Object value, long validFor, float priority)
           
 java.lang.Object write(java.lang.String blockName, java.lang.Object value, long validFrom, long validTo, float priority)
          Write an object into the space.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInstance

public static Space getInstance()
Access to the space.

Returns:
The singleton space object.

read

public java.lang.Object read(java.lang.String blockName)
Read an object from the space.

Parameters:
blockName - The block to read from space.
def - Object to return, when there is no such block in space.

read

public java.lang.Object read(java.lang.String blockName,
                             java.lang.Object def)

getBlock

public Space.Block getBlock(java.lang.String blockName)
Get a Block object (not only the stored value) from the space. Useful to query block's meta data (validity, priority).

Parameters:
blockName - The block to get.
Returns:
A copy (except value, which is referenced) of the actual Block object. For expired blocks, null is returned.

write

public java.lang.Object write(java.lang.String blockName,
                              java.lang.Object value,
                              long validFrom,
                              long validTo,
                              float priority)
Write an object into the space.

Parameters:
blockName - The block in space to write to.
value - The value to write to the block.
validFor - Time period for which the data is valid (from now). Zero or less means infinite validity.
priority - The write priority - existing values with greater priority won't get overwritten.
Returns:
Object previously stored in given block.

write

public java.lang.Object write(java.lang.String blockName,
                              java.lang.Object value,
                              long validFor,
                              float priority)

write

public java.lang.Object write(java.lang.String blockName,
                              java.lang.Object value,
                              long validFor)

write

public java.lang.Object write(java.lang.String blockName,
                              java.lang.Object value)

delete

public java.lang.Object delete(java.lang.String blockName,
                               long validFor,
                               float priority)
Delete a block from the space. This in fact just calls write() to store null in the block, instead of completely removing the block, to allow rejecting future lower-priority writes.

A special case is delete() call with validFor set to zero. In this case, the zero does not mean infinite validity, but instead just deleting the block, and expring, so that any subsequent attempt to write into that block will succeed.

Parameters:
blockName - The block to delete.
validFor - How long lower-priority writes will be ignored.
priority - The write priority.
Returns:
Object previously stored in given block.

delete

public java.lang.Object delete(java.lang.String blockName)

attachTrigger

public void attachTrigger(java.lang.String blockName,
                          Agent agent,
                          int triggerId)
Add an agent trigger to a block. When the block changes (on write(), delete(), or expiration), the agent gets trigerred.

Parameters:
blockName - The block to attach the trigger to.
agent - The agent to trigger, when the block changes.

detachTriggers

public void detachTriggers(Agent agent)
Detach an agent trigger from all blocks. Useful to release agent references on agent exit.


trigger

public void trigger(java.lang.String blockName)
Simulate a block change, firing associated triggers. Useful if application changes a mutable object in space.

Parameters:
blockName - The block whose change to simulate.