object
Class ReferenceTable

java.lang.Object
  object.ReferenceTable

public class ReferenceTable
extends java.lang.Object

A ReferenceTable is a mechanism for accessing and tracking strong references to PublicObjects in the local Java Virtual Machine. The purpose of this is to allow the local model to lazily perform object deletion. As soon as all strong references to a locally registered PublicObject have disappeared, a call to getDeadReferences will return a list containing the handle of the object. This can be used to send explicit delete messages to the rest of the federation. NOTE: it is easy to missuse this facility. For example, a model keeps a list of chess pieces, removing the piece from the list whenever it is captured. If this is the only existing reference to the piece, everything is fine and it will become finalizeable. However, if a strong reference to the piece exists in, for eg. planners, display surfaces, loggers, etc. then the garbage collection will not take place and the functioning of the ReferenceTable with which the object is registered will be undermined. For this reason it is strongly recommended that PublicObject instances only exist in a single datastructure in a model if lazy deletion is to be used. Any representations elsewhere should clone the object or, preferrably, refer back to this single datastructure when needed (eg. one might use a wrapper class ChessPiceDisplayable with a reference back to a ChessPieceList instance in order to graphically display pieces without creating unecessary strong references to them). Complicated models in which this generates lots of messy code should consider disabling lazy deletion and using explicit deletion instead.

Author:

Rob Minson

See Also:

ObjectLookup.localDelete(PublicObject)

Constructor Summary

ReferenceTable()

Method Summary

java.util.Set<java.lang.Integer>	allHandles()
void	deregister(PublicObject ob) Removes the reference to the given object from the ReferenceTable.
java.util.List<LookupReference>	getDeadReferences() Returns a list of LookupReferences corresponding to all locally registered PublicObjects which have been garbage collected since the method was last called.
PublicObject	getObject(int ID) Get the PublicObject specified by the given handle.
static void	main(java.lang.String[] args)
void	register(PublicObject ob) Insert a PublicObject in to the ReferenceTable.

Methods inherited from class java.lang.Object

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

Constructor Detail

ReferenceTable

public ReferenceTable()

Method Detail

getDeadReferences

public java.util.List<LookupReference> getDeadReferences()

Returns a list of LookupReferences corresponding to all locally registered PublicObjects which have been garbage collected since the method was last called. Typically this will be used to determine which locally registered shared objects can now be explicitly deleted throughout the rest of the federation (eg. via calling deleteObjectInstance(...) on the local RTIambassador) having already been implicitly deleted by the local model.

Returns:

the list of references to finalizeable objects.

getObject

public PublicObject getObject(int ID)
                       throws ObjectDeletedException,
                              ObjectNotFoundException

Get the PublicObject specified by the given handle.

Parameters:

ID - the RTI-assigned handle of the required object

Returns:

the corresponding PublicObject

Throws:

ObjectNotFoundException - if the object has not been placed in the lookup

ObjectDeletedException - if the object has been garbage collected by the local JVM prior to this call.

register

public void register(PublicObject ob)

Insert a PublicObject in to the ReferenceTable. A reference to the object can then be regained by a call to getObject. If a PublicObject with the same handle exists in the Lookup it will be overwritten by this object (this works fine assuming the RTI provides unique IDs).

Parameters:

ob - the PublicObject to register with this ReferenceTable

deregister

public void deregister(PublicObject ob)
                throws ObjectNotFoundException

Removes the reference to the given object from the ReferenceTable. This disables reference tracking for this object. It will still be possible to refer to strong references of this object elsewhere in calling code, however, if the object becomes finalizable, the rest of the federation will not be automatically informed of its deletion.

Parameters:

ob - the PublicObject which should no longer be tracked by this ReferenceTable

Throws:

ObjectNotFoundException - if the given object is not currently registered with this ReferenceTable

allHandles

public java.util.Set<java.lang.Integer> allHandles()

main

public static void main(java.lang.String[] args)