gov.nasa.arc.brahms.vm.rt
Class VMConceptualInstanceCtx

java.lang.Object
  gov.nasa.arc.brahms.common.rt.BrahmsObjectCtx
      gov.nasa.arc.brahms.common.rt.ConceptCtx
          gov.nasa.arc.brahms.common.rt.ConceptualInstanceCtx
              gov.nasa.arc.brahms.vm.rt.VMConceptualInstanceCtx

All Implemented Interfaces:

IBrahmsObjectCtx, IConceptCtx, IConceptualInstanceCtx, IRuntimeConstants, gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement, IRuntimeConceptCtx, java.io.Serializable

public class VMConceptualInstanceCtx
extends ConceptualInstanceCtx
implements IRuntimeConceptCtx, gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

The VMConceptualInstanceCtx is the runtime representation of conceptual instances defined in a Brahms model with extensions for use in the virtual machine. The conceptual instance context manages the creation and deletion time of the conceptual instances. The conceptual instance context also manages the list of sub aggregates or parts of the conceptual instance and the parent aggregates of the conceptual instance.

Version:

$Revision: 1.5 $ $Date: 2008/02/28 19:46:51 $ $Author: rvhoof $

Author:

Ron van Hoof

See Also:

ConceptualInstanceCtx, Serialized Form

Field Summary

Fields inherited from interface gov.nasa.arc.brahms.common.rt.IRuntimeConstants

ABORTED, ACTIVE, ACTIVITY, AVAILABLE, COMPLETED, CONSEQUENCE, DETECTABLE, ENDED, ENGINE, EXTERNAL_AGENT, FROM, IMPASSED, INITIAL, INTERRUPTED, JAVA_PROPERTY, sABORTED, sACTIVE, sAVAILABLE, sCOMPLETED, sENDED, sIMPASSED, sINTERRUPTED, sUNAVAILABLE, TO, TRANSFER, UNAVAILABLE

Constructor Summary

VMConceptualInstanceCtx(ConceptualInstance ci)
Constructor, creates a new context for the specified conceptual instance.

Method Summary

void	addDeletedListener(gov.nasa.arc.brahms.vm.memory.IDeletedListener listener) Registers the specified listener to be notified when this element was deleted.
void	addEventReference(gov.nasa.arc.brahms.vm.events.DiscreteEvent evt) Adds the specified DiscreteEvent as an event in which this element is referenced.
void	addFrameBindingReference(ActiveInstance refHolder, gov.nasa.arc.brahms.vm.engine.rsn.RSNFrameNode frame, gov.nasa.arc.brahms.vm.engine.rsn.RSNFrameNode.FrameBinding binding) Adds the specified FrameBinding as a binding in which this element was used in a variable in the completed execution of the frame defined by the RSNFrameNode executed by the specified ActiveInstance.
gov.nasa.arc.brahms.vm.memory.HardReference	addHardReference(ActiveInstance refHolder, long time) Adds the specified refHolder as an ActiveInstance holding a hard reference to this concept.
gov.nasa.arc.brahms.vm.memory.SoftReference	addSoftReference(ActiveInstance refHolder, long time) Adds the specified refHolder as an ActiveInstance holding a soft reference to this concept.
void	addStatementReference(ActiveInstance refHolder, VMStatementCtx statement, long time) Adds the specified VMStatementCtx as a statement in which this element is referenced, either on the left or right hand side asserted by the specified ActiveInstance.
PartCtx	createAggregateRelation(ConceptualInstance oCO, long time, gov.nasa.arc.brahms.vm.controller.VMController vmc) Creates the aggregate relationship between this conceptual instance and the specified conceptual instance where the specified conceptual instance is a sub aggregate of this conceptual instance.
PartCtx	createAggregateRelation(ObjectInstance oObject, long time, gov.nasa.arc.brahms.vm.controller.VMController vmc) Creates the aggregate relationship between this conceptual instance and the specified object instance where the specified object instance is a part of this conceptual instance.
void	finalizeDelete(long time) Finalizes the deletes of this element from memory, cleaning up any internal structures kept for this element and marking the element as deleted.
protected Relation	getConceptualObjectOfRelation() Returns the relation used to specify the aggregate relations between conceptual objects and other conceptual objects or object instances in facts and beliefs.
ModelElement	getElement() Returns the model element for which its memory is being managed.
java.util.List<gov.nasa.arc.brahms.vm.memory.SoftReference>	getSoftReferences() Returns a list of all the actors holding a soft reference to this element.
boolean	hasEventReferences() Indicates whether any events hold references to this element.
boolean	hasSoftReferences() Indicates whether there are any actors that hold a soft reference to this element.
void	initialize(gov.nasa.arc.brahms.vm.controller.VMController vmc, long time) Initializes the concept for use in a virtual machine controller by the specified virtual machine controller.
void	initiateDelete(long time) Initiates the deletion of this element from memory causing the element to be marked as in the process of being deleted and causing the retraction of the facts referencing the element.
boolean	isDeleted() Indicates whether the element was deleted.
boolean	isDeleteInitiated() Indicates whether the process to start the deletion of the element was started.
boolean	isMarkedForGC() Indicates whether the element is marked for garbage collection.
void	removeEventReference(gov.nasa.arc.brahms.vm.events.DiscreteEvent evt) Removes the specified DiscreteEvent as an event in which this element is referenced.
void	removeFrameBindingReference(ActiveInstance refHolder, gov.nasa.arc.brahms.vm.engine.rsn.RSNFrameNode frame, gov.nasa.arc.brahms.vm.engine.rsn.RSNFrameNode.FrameBinding binding) Removes the specified FrameBinding as a binding in which this element was used in a variable in the completed execution of the frame defined by the RSNFrameNode executed by the specified ActiveInstance.
void	removeHardReference(ActiveInstance refHolder, long time) Removes the specified refHolder as an ActiveInstance holding a hard reference to this concept.
void	removeSoftReference(ActiveInstance refHolder, long time) Removes the specified refHolder as an ActiveInstance holding a soft reference to this concept.
void	removeStatementReference(ActiveInstance refHolder, VMStatementCtx statement, long time) Removes the specified VMStatementCtx as a statement in which the element is referenced, either on the left or right hand side retracted by the specified ActiveInstance.
void	reset() Resets this context, removing any references to other contexts
void	setMarkedForGC(boolean marked) Sets whether the element is marked for garbage collection.

Methods inherited from class gov.nasa.arc.brahms.common.rt.ConceptualInstanceCtx

addAggregate, addSubAggregate, getAggregates, getSubAggregates, removeAggregate, removeAllAggregates, removeAllSubAggregates, removeSubAggregate

Methods inherited from class gov.nasa.arc.brahms.common.rt.ConceptCtx

addAttribute, addRelation, getAttribute, getRelation, initAttributeRelationCache, removeAttribute, removeRelation, resetAttributeRelationCache, toString

Methods inherited from class gov.nasa.arc.brahms.common.rt.BrahmsObjectCtx

addNote, getContextFor, getEndTime, getID, getNote, getNotes, getStartTime, removeNote, setContextFor, setEndTime, setID, setStartTime

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface gov.nasa.arc.brahms.common.rt.IBrahmsObjectCtx

addNote, getContextFor, getEndTime, getID, getNote, getNotes, getStartTime, removeNote, setEndTime, setID, setStartTime

Constructor Detail

VMConceptualInstanceCtx

public VMConceptualInstanceCtx(ConceptualInstance ci)

Constructor, creates a new context for the specified conceptual instance.

Parameters:

ci - the ConceptualInstance for which to create a context

Method Detail

initialize

public void initialize(gov.nasa.arc.brahms.vm.controller.VMController vmc,
                       long time)
                throws VMException

Initializes the concept for use in a virtual machine controller by the specified virtual machine controller. The initialization sets up any additional components required for the concept to be used in the virtual machine.

Specified by:

initialize in interface IRuntimeConceptCtx

Parameters:

vmc - the VMController controlling the virtual machine in which this concept is to be used.

time - the time at which the initialization is performed

Throws:

VMException - if an error occurs in initializing the concept

getElement

public ModelElement getElement()
                        throws gov.nasa.arc.brahms.common.exceptions.BrahmsException

Returns the model element for which its memory is being managed.

Specified by:

getElement in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Returns:

ModelElement the model element

Throws:

gov.nasa.arc.brahms.common.exceptions.BrahmsException - if there is an error obtaining the element

addHardReference

public gov.nasa.arc.brahms.vm.memory.HardReference addHardReference(ActiveInstance refHolder,
                                                                    long time)

Adds the specified refHolder as an ActiveInstance holding a hard reference to this concept. A hard reference is a reference held by an ActiveInstance that has behavior (frames) as a result of either creating the concept or as a result of a belief assertion in which the belief references this concept.

Specified by:

addHardReference in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

refHolder - the ActiveInstance holding a reference to this concept

time - the event time at which the reference is added

Returns:

HardReference the HardReference created for the ActiveInstance

removeHardReference

public void removeHardReference(ActiveInstance refHolder,
                                long time)

Removes the specified refHolder as an ActiveInstance holding a hard reference to this concept. A hard reference is a reference held by an ActiveInstance that has behavior (frames) as a result of either creating the concept or as a result of a belief assertion in which the belief references this concept.

If the specified refHolder is not listed as a concept holding a reference to this concept then this method is a no-op.

Specified by:

removeHardReference in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

refHolder - the ActiveInstance that no longer holds any references to this concept

time - the event time at which the reference is removed

addSoftReference

public gov.nasa.arc.brahms.vm.memory.SoftReference addSoftReference(ActiveInstance refHolder,
                                                                    long time)

Adds the specified refHolder as an ActiveInstance holding a soft reference to this concept. A soft reference is a reference held by an ActiveInstance that has no behavior (no frames) as a result of a belief assertion in which the belief references this concept.

Specified by:

addSoftReference in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

refHolder - the ActiveInstance holding a reference to this concept

time - the event time at which the reference is added

Returns:

SoftReference the SoftReference created for the ActiveInstance

removeSoftReference

public void removeSoftReference(ActiveInstance refHolder,
                                long time)

Removes the specified refHolder as an ActiveInstance holding a soft reference to this concept. A soft reference is a reference held by an ActiveInstance that has no behavior (no frames) as a result of a belief assertion in which the belief references this concept.

If the specified refHolder is not listed as a concept holding a reference to this concept then this method is a no-op.

Specified by:

removeSoftReference in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

refHolder - the ActiveInstance that no longers holds any references to this concept

time - the event time at which the reference is removed

hasSoftReferences

public boolean hasSoftReferences()

Indicates whether there are any actors that hold a soft reference to this element.

Specified by:

hasSoftReferences in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Returns:

boolean true if there are soft references, false otherwise

getSoftReferences

public java.util.List<gov.nasa.arc.brahms.vm.memory.SoftReference> getSoftReferences()

Returns a list of all the actors holding a soft reference to this element.

Specified by:

getSoftReferences in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Returns:

List the list of SoftReferences

addEventReference

public void addEventReference(gov.nasa.arc.brahms.vm.events.DiscreteEvent evt)

Adds the specified DiscreteEvent as an event in which this element is referenced. These references need to maintained to ensure that during the transfer of beliefs these beliefs can be asserted by the recipient before the element is actually deleted. An element could otherwise be deleted before the recipient has had a chance to assert beliefs about it and to claim ownership of a reference to the element.

Specified by:

addEventReference in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

evt - the DiscreteEvent in which the element is referenced

removeEventReference

public void removeEventReference(gov.nasa.arc.brahms.vm.events.DiscreteEvent evt)

Removes the specified DiscreteEvent as an event in which this element is referenced. These references need to maintained to ensure that during the transfer of beliefs these beliefs can be asserted by the recipient before the element is actually deleted. An element could otherwise be deleted before the recipient has had a chance to assert beliefs about it and to claim ownership of a reference to the element.

Specified by:

removeEventReference in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

evt - the DiscreteEvent in which the element is referenced

hasEventReferences

public boolean hasEventReferences()

Indicates whether any events hold references to this element.

Specified by:

hasEventReferences in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Returns:

boolean true if there are event references, false otherwise

addStatementReference

public void addStatementReference(ActiveInstance refHolder,
                                  VMStatementCtx statement,
                                  long time)

Adds the specified VMStatementCtx as a statement in which this element is referenced, either on the left or right hand side asserted by the specified ActiveInstance.

Specified by:

addStatementReference in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

refHolder - the ActiveInstance that asserted the statement referencing this element

statement - the VMStatementCtx to be added

time - the time at which the statement reference is added

removeStatementReference

public void removeStatementReference(ActiveInstance refHolder,
                                     VMStatementCtx statement,
                                     long time)

Removes the specified VMStatementCtx as a statement in which the element is referenced, either on the left or right hand side retracted by the specified ActiveInstance.

Specified by:

removeStatementReference in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

refHolder - the ActiveInstance that retracted the statement referencing this element

statement - the VMStatementCtx to be removed

time - the time at which the statement reference is removed

addFrameBindingReference

public void addFrameBindingReference(ActiveInstance refHolder,
                                     gov.nasa.arc.brahms.vm.engine.rsn.RSNFrameNode frame,
                                     gov.nasa.arc.brahms.vm.engine.rsn.RSNFrameNode.FrameBinding binding)

Adds the specified FrameBinding as a binding in which this element was used in a variable in the completed execution of the frame defined by the RSNFrameNode executed by the specified ActiveInstance. This binding only exists if the frame's repeat property is set to false.

Specified by:

addFrameBindingReference in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

refHolder - the ActiveInstance that executed the frame

frame - the RSNFrameNode in which the used binding is maintained

binding - the FrameBinding in which the element is referenced

removeFrameBindingReference

public void removeFrameBindingReference(ActiveInstance refHolder,
                                        gov.nasa.arc.brahms.vm.engine.rsn.RSNFrameNode frame,
                                        gov.nasa.arc.brahms.vm.engine.rsn.RSNFrameNode.FrameBinding binding)

Removes the specified FrameBinding as a binding in which this element was used in a variable in the completed execution of the frame defined by the RSNFrameNode executed by the specified ActiveInstance. This binding only exists if the frame's repeat property is set to false.

Specified by:

removeFrameBindingReference in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

refHolder - the ActiveInstance that executed the frame

frame - the RSNFrameNode in which the used binding is maintained

binding - the FrameBinding in which the element is referenced

setMarkedForGC

public void setMarkedForGC(boolean marked)

Sets whether the element is marked for garbage collection. True when the element was added to the garbage collector, false if the element is not yet added to the garbage collector.

Specified by:

setMarkedForGC in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

marked - true if marked, false if not

isMarkedForGC

public boolean isMarkedForGC()

Indicates whether the element is marked for garbage collection. True when the element was added to the garbage collector, false if the element is not yet added to the garbage collector. return boolean true if marked, false if not

Specified by:

isMarkedForGC in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

initiateDelete

public void initiateDelete(long time)

Initiates the deletion of this element from memory causing the element to be marked as in the process of being deleted and causing the retraction of the facts referencing the element.

Specified by:

initiateDelete in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

time - the event time at which the element's deletion is initiated

isDeleteInitiated

public boolean isDeleteInitiated()

Indicates whether the process to start the deletion of the element was started.

Specified by:

isDeleteInitiated in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Returns:

boolean true if the element is in the process of being deleted, false otherwise

finalizeDelete

public void finalizeDelete(long time)

Finalizes the deletes of this element from memory, cleaning up any internal structures kept for this element and marking the element as deleted.

Specified by:

finalizeDelete in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

time - the event time at which the element's deletion is finalized

addDeletedListener

public void addDeletedListener(gov.nasa.arc.brahms.vm.memory.IDeletedListener listener)

Registers the specified listener to be notified when this element was deleted. This listener is automatically deregistered after the listener was notified of the deletion.

Specified by:

addDeletedListener in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Parameters:

listener - the IDeletedListener to be added

isDeleted

public boolean isDeleted()

Indicates whether the element was deleted.

Specified by:

isDeleted in interface gov.nasa.arc.brahms.vm.memory.IMemoryManagedElement

Returns:

boolean true if the element was deleted, false otherwise

createAggregateRelation

public PartCtx createAggregateRelation(ConceptualInstance oCO,
                                       long time,
                                       gov.nasa.arc.brahms.vm.controller.VMController vmc)
                                throws gov.nasa.arc.brahms.common.exceptions.BrahmsException

Creates the aggregate relationship between this conceptual instance and the specified conceptual instance where the specified conceptual instance is a sub aggregate of this conceptual instance.

Parameters:

oCO - the sub aggregate conceptual instance

time - the time at which the relationship is created

vmc - the virtual machine controller

Returns:

PartCtx the relationship between the conceptual object and its part

Throws:

gov.nasa.arc.brahms.common.exceptions.BrahmsException - if an internal error occurs.

createAggregateRelation

public PartCtx createAggregateRelation(ObjectInstance oObject,
                                       long time,
                                       gov.nasa.arc.brahms.vm.controller.VMController vmc)
                                throws gov.nasa.arc.brahms.common.exceptions.BrahmsException

Creates the aggregate relationship between this conceptual instance and the specified object instance where the specified object instance is a part of this conceptual instance.

Parameters:

oObject - the part to be added to this conceptual instance

time - the time at which the relationship is created

vmc - the virtual machine controller

Returns:

PartCtx the relationship between the conceptual object and its part

Throws:

gov.nasa.arc.brahms.common.exceptions.BrahmsException - if an internal error occurs.

getConceptualObjectOfRelation

protected Relation getConceptualObjectOfRelation()
                                          throws gov.nasa.arc.brahms.common.exceptions.BrahmsException

Returns the relation used to specify the aggregate relations between conceptual objects and other conceptual objects or object instances in facts and beliefs.

Returns:

Relation the 'conceptual object of' Relation

Throws:

gov.nasa.arc.brahms.common.exceptions.BrahmsException

reset

public void reset()
           throws VMException

Resets this context, removing any references to other contexts

Specified by:

reset in interface IRuntimeConceptCtx

Throws:

VMException - if in error occurs in resetting the concept