gov.nasa.arc.brahms.vm.api.components
Interface IWorldState


public interface IWorldState

Each Brahms virtual machine has one world state component. The world state component in the virtual machine is responsible for maintaining the fact set. All agents and objects share the same fact set. The fact set defines the state of the world by means of object attribute values and object relations. The facts in the world are the states in the world that can be detected by agents and objects (active instances). The objects also use the facts in the world to reason with. The preconditions defined for the work of an object are evaluated based on facts instead of beliefs as with agents. The world state is responsible for distributing the fact to all the agents and objects in the virtual machine. In a simulation environment the world state posts the fact on the agents or objects event queues. The assertion of the fact in the world state and the distribution of this fact to all agents and objects must happen synchronously. In simulation mode agents or objects are not allowed to process their event queues until they received the new fact. In an intelligent agent environment the new fact immediately triggers the reasoning process for an object if the fact is relevant for the work of the object. The fact set as defined in the world state is also used to initialize agents and objects that are dynamically loaded during a simulation or intelligent agent session.


Method Summary
 void assertFact(IFact fact, IContext ctx)
          Schedules the assertion of the specified fact into the world state including the distribution of the fact to all agents and objects.
 IFact getFact(IConcept lhsConcept, IAttribute lhsAttribute, int relop, boolean value)
          Find the fact using the specified parameters and return the fact if found, null if the fact was not found.
 IFact getFact(IConcept lhsConcept, IAttribute lhsAttribute, int relop, double value)
          Find the fact using the specified parameters and return the fact if found, null if the fact was not found.
 IFact getFact(IConcept lhsConcept, IAttribute lhsAttribute, int relop, IConcept value)
          Find the fact using the specified parameters and return the fact if found, null if the fact was not found.
 IFact getFact(IConcept lhsConcept, IAttribute lhsAttribute, int relop, int value)
          Find the fact using the specified parameters and return the fact if found, null if the fact was not found.
 IFact getFact(IConcept lhsConcept, IAttribute lhsAttribute, int relop, IUnknown value)
          Find the fact using the specified parameters and return the fact if found, null if the fact was not found.
 IFact getFact(IConcept lhsConcept, IAttribute lhsAttribute, int relop, java.lang.String value)
          Find the fact using the specified parameters and return the fact if found, null if the fact was not found.
 IFact getFact(IConcept lhsConcept, IRelation relation, IConcept rhsConcept, int truthValue)
          Find the fact using the specified parameters and return the fact if found, null if the fact was not found.
 IFact getFact(IConcept lhsConcept, IRelation relation, IUnknown rhsConcept, int truthValue)
          Find the fact using the specified parameters and return the fact if found, null if the fact was not found.
 java.util.Enumeration getFacts()
          Returns a list of all the facts in the world state's fact set.
 java.util.Enumeration getFacts(IAttribute attribute)
          Returns a list of all the facts that have the specified attribute regardless of the lhs concept, relational operator and right hand side value.
 java.util.Enumeration getFacts(IConcept lhsConcept, IAttribute lhsAttribute)
          Returns a list of all the facts that have the specified concept and attribute on their left hand side regardless of their relational operator or value.
 java.util.Enumeration getFacts(IConcept lhsConcept, IAttribute lhsAttribute, int relop)
          Returns a list of all the facts that have the specified concept and attribute on their left hand side and that use the specified relational operator.
 java.util.Enumeration getFacts(IConcept lhsConcept, IRelation relation)
          Returns a list of all the facts that have the specified left hand side concept and relation regardless of their right hand side concept.
 java.util.Enumeration getFacts(IConcept lhsConcept, IRelation relation, int truthValue)
          Returns a list of all the facts that have the specified left hand side concept, relation and truth value regardless of their right hand side concept.
 java.util.Enumeration getFacts(IRelation relation)
          Returns a list of all the facts that have the specified relation regardless of their left and right hand side concept.
 java.util.Enumeration getFacts(IRelation relation, IConcept rhsConcept, int truthValue)
          Returns a list of all the facts that have the specified relation and right hand side concept, and truth value regardless of their left hand side concept.
 java.util.Enumeration getFacts(IRelation relation, IUnknown rhsConcept, int truthValue)
          Returns a list of all the facts that have the specified relation, as right hand side 'unknown', and the specified truth value regardless of their left hand side concept.
 void retractFact(IFact fact, IContext ctx)
          Schedules the retraction of the specified fact from the world state including the notification of the retraction to all agents and objects.
 

Method Detail

assertFact

void assertFact(IFact fact,
                IContext ctx)
                throws ExternalException
Schedules the assertion of the specified fact into the world state including the distribution of the fact to all agents and objects. The fact is not guaranteed to immediately be asserted in the world state.

Parameters:
fact - the IFact to be asserted
ctx - the IContext for the action
Throws:
ExternalException - if an internal error occurs

retractFact

void retractFact(IFact fact,
                 IContext ctx)
                 throws ExternalException
Schedules the retraction of the specified fact from the world state including the notification of the retraction to all agents and objects. The fact is not guaranteed to immediately be retracted from the world state.

Parameters:
fact - the IFact to be retracted
ctx - the IContext for the action
Throws:
ExternalException - if an internal error occurs

getFacts

java.util.Enumeration getFacts()
                               throws ExternalException
Returns a list of all the facts in the world state's fact set.

Returns:
Enumeration a list of IFact
Throws:
ExternalException - if an internal error occurs

getFacts

java.util.Enumeration getFacts(IAttribute attribute)
                               throws ExternalException
Returns a list of all the facts that have the specified attribute regardless of the lhs concept, relational operator and right hand side value.

Parameters:
attribute - the IAttribute in the requested fact(s)
Returns:
Enumeration a list of IFact's
Throws:
ExternalException - if an internal error occurs

getFact

IFact getFact(IConcept lhsConcept,
              IAttribute lhsAttribute,
              int relop,
              int value)
              throws ExternalException
Find the fact using the specified parameters and return the fact if found, null if the fact was not found.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact
lhsAttribute - the left hand side IAttribute in the requested fact
relop - the relational operator in the requested fact
value - the right hand side integer value in the requested fact
Returns:
IFact if the matching fact is found, null otherwise
Throws:
ExternalException - if an internal error occurs
See Also:
IRelationalOperator.EQUALS, IRelationalOperator.NOT_EQUALS

getFact

IFact getFact(IConcept lhsConcept,
              IAttribute lhsAttribute,
              int relop,
              double value)
              throws ExternalException
Find the fact using the specified parameters and return the fact if found, null if the fact was not found.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact
lhsAttribute - the left hand side IAttribute in the requested fact
relop - the relational operator in the requested fact
value - the right hand side double value in the requested fact
Returns:
IFact if the matching fact is found, null otherwise
Throws:
ExternalException - if an internal error occurs
See Also:
IRelationalOperator.EQUALS, IRelationalOperator.NOT_EQUALS

getFact

IFact getFact(IConcept lhsConcept,
              IAttribute lhsAttribute,
              int relop,
              boolean value)
              throws ExternalException
Find the fact using the specified parameters and return the fact if found, null if the fact was not found.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact
lhsAttribute - the left hand side IAttribute in the requested fact
relop - the relational operator in the requested fact
value - the right hand side boolean value in the requested fact
Returns:
IFact if the matching fact is found, null otherwise
Throws:
ExternalException - if an internal error occurs
See Also:
IRelationalOperator.EQUALS, IRelationalOperator.NOT_EQUALS

getFact

IFact getFact(IConcept lhsConcept,
              IAttribute lhsAttribute,
              int relop,
              java.lang.String value)
              throws ExternalException
Find the fact using the specified parameters and return the fact if found, null if the fact was not found.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact
lhsAttribute - the left hand side IAttribute in the requested fact
relop - the relational operator in the requested fact
value - the right hand side String or symbol value in the requested fact
Returns:
IFact if the matching fact is found, null otherwise
Throws:
ExternalException - if an internal error occurs
See Also:
IRelationalOperator.EQUALS, IRelationalOperator.NOT_EQUALS

getFact

IFact getFact(IConcept lhsConcept,
              IAttribute lhsAttribute,
              int relop,
              IConcept value)
              throws ExternalException
Find the fact using the specified parameters and return the fact if found, null if the fact was not found.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact
lhsAttribute - the left hand side IAttribute in the requested fact
relop - the relational operator in the requested fact
value - the right hand side IConcept value in the requested fact
Returns:
IFact if the matching fact is found, null otherwise
Throws:
ExternalException - if an internal error occurs
See Also:
IRelationalOperator.EQUALS, IRelationalOperator.NOT_EQUALS

getFact

IFact getFact(IConcept lhsConcept,
              IAttribute lhsAttribute,
              int relop,
              IUnknown value)
              throws ExternalException
Find the fact using the specified parameters and return the fact if found, null if the fact was not found.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact
lhsAttribute - the left hand side IAttribute in the requested fact
relop - the relational operator in the requested fact
value - the right hand side 'unknown' value in the requested fact
Returns:
IFact if the matching fact is found, null otherwise
Throws:
ExternalException - if an internal error occurs
See Also:
IRelationalOperator.EQUALS, IRelationalOperator.NOT_EQUALS, IUnknown.UNKNOWN

getFact

IFact getFact(IConcept lhsConcept,
              IRelation relation,
              IConcept rhsConcept,
              int truthValue)
              throws ExternalException
Find the fact using the specified parameters and return the fact if found, null if the fact was not found.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact
relation - the IRelation in the requested fact
rhsConcept - the right hand side IConcept in the requested fact
truthvalue - the truth value in the requested fact (TRUE, FALSE, UNKNOWN)
Returns:
IFact if the matching fact is found, null otherwise
Throws:
ExternalException - if an internal error occurs
See Also:
ITruthValue.TRUE, ITruthValue.FALSE, ITruthValue.UNKNOWN

getFact

IFact getFact(IConcept lhsConcept,
              IRelation relation,
              IUnknown rhsConcept,
              int truthValue)
              throws ExternalException
Find the fact using the specified parameters and return the fact if found, null if the fact was not found.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact
relation - the IRelation in the requested fact
rhsConcept - the right hand side 'unknown' value in the requested fact
truthvalue - the truth value in the requested fact (TRUE, FALSE, UNKNOWN)
Returns:
IFact if the matching fact is found, null otherwise
Throws:
ExternalException - if an internal error occurs
See Also:
IUnknown.UNKNOWN, ITruthValue.TRUE, ITruthValue.FALSE, ITruthValue.UNKNOWN

getFacts

java.util.Enumeration getFacts(IConcept lhsConcept,
                               IAttribute lhsAttribute)
                               throws ExternalException
Returns a list of all the facts that have the specified concept and attribute on their left hand side regardless of their relational operator or value.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact(s)
lhsAttribute - the left hand side IAttribute in the requested fact(s)
Returns:
Enumeration a list of IFact's
Throws:
ExternalException - if an internal error occurs

getFacts

java.util.Enumeration getFacts(IConcept lhsConcept,
                               IAttribute lhsAttribute,
                               int relop)
                               throws ExternalException
Returns a list of all the facts that have the specified concept and attribute on their left hand side and that use the specified relational operator.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact(s)
lhsAttribute - the left hand side IAttribute in the requested fact(s)
relop - the relational operator in the requested fact(s)
Returns:
Enumeration a list of IFact's
Throws:
ExternalException - if an internal error occurs
See Also:
IRelationalOperator.EQUALS, IRelationalOperator.NOT_EQUALS

getFacts

java.util.Enumeration getFacts(IRelation relation)
                               throws ExternalException
Returns a list of all the facts that have the specified relation regardless of their left and right hand side concept.

Parameters:
relation - the IRelation in the requested fact(s)
Returns:
Enumeration a list of IFact's
Throws:
ExternalException - if an internal error occurs

getFacts

java.util.Enumeration getFacts(IConcept lhsConcept,
                               IRelation relation)
                               throws ExternalException
Returns a list of all the facts that have the specified left hand side concept and relation regardless of their right hand side concept.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact(s)
relation - the IRelation in the requested fact(s)
Returns:
Enumeration a list of IFact's
Throws:
ExternalException - if an internal error occurs

getFacts

java.util.Enumeration getFacts(IConcept lhsConcept,
                               IRelation relation,
                               int truthValue)
                               throws ExternalException
Returns a list of all the facts that have the specified left hand side concept, relation and truth value regardless of their right hand side concept.

Parameters:
lhsConcept - the left hand side IConcept in the requested fact(s)
relation - the IRelation in the requested fact(s)
truthValue - the truth value in the requested fact(s) (TRUE, FALSE, UNKNOWN)
Returns:
Enumeration a list of IFact's
Throws:
ExternalException - if an internal error occurs
See Also:
ITruthValue.TRUE, ITruthValue.FALSE, ITruthValue.UNKNOWN

getFacts

java.util.Enumeration getFacts(IRelation relation,
                               IConcept rhsConcept,
                               int truthValue)
                               throws ExternalException
Returns a list of all the facts that have the specified relation and right hand side concept, and truth value regardless of their left hand side concept.

Parameters:
relation - the IRelation in the requested fact(s)
rhsConcept - the right hand side IConcept in the requested fact(s)
truthValue - the truth value in the requested fact(s) (TRUE, FALSE, UNKNOWN)
Returns:
Enumeration a list of IFact's
Throws:
ExternalException - if an internal error occurs
See Also:
ITruthValue.TRUE, ITruthValue.FALSE, ITruthValue.UNKNOWN

getFacts

java.util.Enumeration getFacts(IRelation relation,
                               IUnknown rhsConcept,
                               int truthValue)
                               throws ExternalException
Returns a list of all the facts that have the specified relation, as right hand side 'unknown', and the specified truth value regardless of their left hand side concept.

Parameters:
relation - the IRelation in the requested fact(s)
rhsConcept - the right hand side 'unknown' value in the requested fact(s)
truthValue - the truth value in the requested fact(s) (TRUE, FALSE, UNKNOWN)
Returns:
Enumeration a list of IFact's
Throws:
ExternalException - if an internal error occurs
See Also:
IUnknown.UNKNOWN, ITruthValue.TRUE, ITruthValue.FALSE, ITruthValue.UNKNOWN