gov.nasa.arc.brahms.vm.api.jsvc
Class AbstractExternalService

java.lang.Object
  extended by gov.nasa.arc.brahms.vm.api.jsvc.AbstractExternalService
All Implemented Interfaces:
IExternalService
Direct Known Subclasses:
AbstractAsynchronousEventService, AbstractSynchronousEventService

public abstract class AbstractExternalService
extends java.lang.Object
implements IExternalService

The AbstractExternalService is the class to be extended from by external services that require interaction with the virtual machine. THe abstract external service provides access to the virtual machine controller's interface to make the virtual machine's public internal services accessible.

See Also:
IExternalService

Constructor Summary
AbstractExternalService()
           
 
Method Summary
protected  void assertFact(IFact fact)
          Schedules the assertion of the specified fact into the world state including the distribution of the fact to all agents and objects.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, boolean value, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a boolean.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, double value, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a double.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, IConcept value, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is an IConcept.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, int value, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is an integer.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, IUnknown value, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is the value 'unknown'.
 IFact conclude(IConcept concept, IAttribute attribute, int relop, java.lang.String value, boolean symbol, int factcertainty)
          Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a String.
 IFact conclude(IConcept lhsConcept, IRelation relation, IConcept rhsConcept, int factcertainty)
          Concludes a new IFact of the form concept relation concept.
 IFact conclude(IConcept lhsConcept, IRelation relation, IConcept rhsConcept, int truthValue, int factcertainty)
          Concludes a new IFact of the form concept relation concept with the specified truth value.
 IFact conclude(IConcept lhsConcept, IRelation relation, IUnknown rhsConcept, int factcertainty)
          Concludes a new IFact of the form concept relation concept.
 IFact conclude(IConcept lhsConcept, IRelation relation, IUnknown rhsConcept, int truthValue, int factcertainty)
          Concludes a new IFact of the form concept relation concept with the specified truth value.
protected  IContext getContext()
          Returns this service's context
abstract  java.lang.String getID()
          Returns the unique identifier for the service
protected  IModel getModel()
          Returns a reference to the model loaded in the virtual machine.
abstract  java.lang.String getName()
          Returns the name of the service
 IVMController getVMController()
          Returns the interface to the the virtual machine's controller.
protected  IWorldState getWorldState()
          Returns a reference to the world state managing the fact set.
abstract  void init()
          Initializes the service
 boolean isValidTruthValue(int truth)
          Checks whether the specified value is a valid truth value.
protected  void retractFact(IFact fact)
          Schedules the retraction of the specified fact from the world state including the notification of the retraction to all agents and objects.
protected  void send(IBelief[] beliefs, IActiveInstance agent)
          Sends the specified set of beliefs to the specified agent, causing the assertion of the beliefs in the specified agent's belief set.
protected  void send(IBelief belief, IActiveInstance agent)
          Sends the specified belief to the specified agent, causing the assertion of the belief in the specified agent's belief set.
protected  void send(IBelief belief, IActiveInstance[] agents)
          Sends the specified belief to the specified agents, causing the assertion of the belief in the belief set of every agent in the list of agents.
 void setProperties(java.util.Properties p)
          Sets the properties for the activity.
abstract  void start()
          Starts the service
abstract  void stop()
          Ends the service
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractExternalService

public AbstractExternalService()
Method Detail

setProperties

public final void setProperties(java.util.Properties p)
                         throws ExternalException
Sets the properties for the activity. The properties specify the allowed capabilities of the external activity. This method is called by the virtual machine and can not be called in the doActivity method.

Parameters:
p - the Properties set by the virtual machine.
Throws:
ExternalException - if the properties were already set.

getVMController

public final IVMController getVMController()
Returns the interface to the the virtual machine's controller.

Returns:
IVMController the virtual machine's controller

getContext

protected final IContext getContext()
Returns this service's context

Returns:
IContext the context for this service

getModel

protected final IModel getModel()
                         throws ExternalException
Returns a reference to the model loaded in the virtual machine.

Returns:
IModel the model loaded in the virtual machine.
Throws:
ExternalException - is an internal error occurs.

getWorldState

protected final IWorldState getWorldState()
                                   throws ExternalException
Returns a reference to the world state managing the fact set.

Returns:
IWorldState the virtual machine's world state
Throws:
ExternalException - if an internal error occurs.

isValidTruthValue

public final boolean isValidTruthValue(int truth)
Checks whether the specified value is a valid truth value.

Parameters:
truth - the truth value to be tested
Returns:
true if the truth value is valid, false otherwise

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            IUnknown value,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is the value 'unknown'.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the value 'unknown' to be assigned to the attribute
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.
See Also:
IUnknown.UNKNOWN

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            int value,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is an integer. The attribute's type must be int or double.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the integer value to be assigned to the attribute
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            double value,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a double. The attribute's type must be double.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the double value to be assigned to the attribute
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            boolean value,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a boolean. The attribute's type must be boolean.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the boolean value to be assigned to the attribute
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            java.lang.String value,
                            boolean symbol,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is a String. The attribute's type must be symbol or string.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the String value to be assigned to the attribute
symbol - indicates if the value is a symbol or string
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept concept,
                            IAttribute attribute,
                            int relop,
                            IConcept value,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept.attribute relop value where relop is one of EQUALS or NOT_EQUALS and the value is an IConcept. The attribute's type must be an IMetaType or IConcept. The attribute name must not be 'location'. The 'location' attribute's value is managed by the virtual machine.

Parameters:
concept - the IConcept for which an attribute value is specified
attribute - the IAttribute defined for the concept to which to assign a value
relop - the relational operator, one of IRelationalOperator.EQUALS or IRelationalOperator.NOT_EQUALS.
value - the IConcept value to be assigned to the attribute
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the value does not match with the attribute's type, the attribute is not specified for the given concept. if an invalid relational operator is specified or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept lhsConcept,
                            IRelation relation,
                            IConcept rhsConcept,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept relation concept. The truth-value is set to true.

Parameters:
lhsConcept - the IConcept for which the relation is specified
relation - the IRelation defined for the concept
rhsConcept - the IUnknown value to be related to the lhsConcept
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the rhsConcept does not match with the relation's type, the relation is not specified for the given lhsConcept or if the fact certainty is less than 0 or more than 100.
See Also:
IUnknown.UNKNOWN

conclude

public final IFact conclude(IConcept lhsConcept,
                            IRelation relation,
                            IUnknown rhsConcept,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept relation concept. The truth-value is set to true.

Parameters:
lhsConcept - the IConcept for which the relation is specified
relation - the IRelation defined for the concept
rhsConcept - the 'unknown' value to be related to the lhsConcept
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the rhsConcept does not match with the relation's type, the relation is not specified for the given lhsConcept or if the fact certainty is less than 0 or more than 100.

conclude

public final IFact conclude(IConcept lhsConcept,
                            IRelation relation,
                            IUnknown rhsConcept,
                            int truthValue,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept relation concept with the specified truth value.

Parameters:
lhsConcept - the IConcept for which the relation is specified
relation - the IRelation defined for the concept
rhsConcept - the IUnknown value to be related to the lhsConcept
truthValue - the truth value of the relationship (TRUE, FALSE, UNKNOWN)
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the rhsConcept does not match with the relation's type, the relation is not specified for the given lhsConcept or if the fact certainty is less than 0 or more than 100.
See Also:
IUnknown.UNKNOWN, ITruthValue.TRUE, ITruthValue.FALSE, ITruthValue.UNKNOWN

conclude

public final IFact conclude(IConcept lhsConcept,
                            IRelation relation,
                            IConcept rhsConcept,
                            int truthValue,
                            int factcertainty)
                     throws ExternalException
Concludes a new IFact of the form concept relation concept with the specified truth value.

Parameters:
lhsConcept - the IConcept for which the relation is specified
relation - the IRelation defined for the concept
rhsConcept - the IConcept to be related to the lhsConcept
truthValue - the truth value of the relationship (TRUE, FALSE, UNKNOWN)
factcertainty - the percentage certainty that the fact indeed is created
Returns:
IFact either a wrapper for the created fact that was asserted to the world state or null if no fact was created and asserted due to the fact certainty.
Throws:
ExternalException - if the rhsConcept does not match with the relation's type, the relation is not specified for the given lhsConcept or if the fact certainty is less than 0 or more than 100.
See Also:
ITruthValue.TRUE, ITruthValue.FALSE, ITruthValue.UNKNOWN

assertFact

protected final void assertFact(IFact fact)
                         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
Throws:
ExternalException - if an internal error occurs

retractFact

protected final void retractFact(IFact fact)
                          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
Throws:
ExternalException - if an internal error occurs

send

protected final void send(IBelief belief,
                          IActiveInstance agent)
                   throws ExternalException
Sends the specified belief to the specified agent, causing the assertion of the belief in the specified agent's belief set. The transmission of the belief is scheduled and is therefor not guaranteed to immeditiately be available in the agent's belief set.

Note: If multiple beliefs are to be transmitted to a remote agent use the send method to which multiple beliefs can be passed to reduce communication overhead. The beliefs will be bundled in one communication package in that case, while with this method for each belief a communication package is created.

Parameters:
belief - the IBelief to be send to the specified agent
agent - the IActiveInstance to which to send the belief
Throws:
ExternalException - if an internal error occurs

send

protected final void send(IBelief belief,
                          IActiveInstance[] agents)
                   throws ExternalException
Sends the specified belief to the specified agents, causing the assertion of the belief in the belief set of every agent in the list of agents. The transmission of the belief is scheduled and is therefor not guaranteed to immeditiately be available in the belief sets of the agents.

Note: If multiple beliefs are to be transmitted to remote agents use the send method to which multiple beliefs can be passed to reduce communication overhead. The beliefs will be bundled in one communication package in that case, while with this method for each belief a communication package is created.

Parameters:
belief - the IBelief to be send to the specified agent
agents - the list of IActiveInstance to which to send the belief
Throws:
ExternalException - if an internal error occurs

send

protected final void send(IBelief[] beliefs,
                          IActiveInstance agent)
                   throws ExternalException
Sends the specified set of beliefs to the specified agent, causing the assertion of the beliefs in the specified agent's belief set. The transmission of the beliefs is scheduled and is therefor not guaranteed to immeditiately be available in the agent's belief set.

Note: If multiple beliefs are to be transmitted to a remote agent this method should be used to reduce communication overhead. The beliefs will be bundled in one communication package.

Parameters:
beliefs - the list of IBelief to be send to the specified agent
agent - the IActiveInstance to which to send the belief
Throws:
ExternalException - if an internal error occurs

getName

public abstract java.lang.String getName()
Returns the name of the service

Specified by:
getName in interface IExternalService
Returns:
String the name of the service

getID

public abstract java.lang.String getID()
Returns the unique identifier for the service

Specified by:
getID in interface IExternalService
Returns:
String the identifier

init

public abstract void init()
Initializes the service

Specified by:
init in interface IExternalService

start

public abstract void start()
Starts the service

Specified by:
start in interface IExternalService

stop

public abstract void stop()
Ends the service

Specified by:
stop in interface IExternalService