uwcse.location.objects
Class PhysicalObjectDatabase

java.lang.Object
  |
  +--uwcse.location.objects.PhysicalObjectDatabase

public class PhysicalObjectDatabase

extends Object

A class to store and manage PhysicalObjects and Trackers in such as way that they may be grouped into a hierarchical forest of compound objects with only one Tracker stored per tree.

Version:

$Revision: 1.47 $

Author:

Jeffrey Hightower

See Also:

PhysicalObject, Tracker

Nested Class Summary
static class	PhysicalObjectDatabase.PersistentDescriptor           The PersistentDescriptor contains constants written along with persistent snapshots to identify the version and other pertinant information.
static class	PhysicalObjectDatabase.PersistentObjectData           The PersistentObjectData class contains the information written about PhysicalObjects in persistent database snapshots.

 

Field Summary
protected  MultiReadSingleWriteLock	m_lock
protected  Map	m_nameToNodeMap
protected  Random	m_random
protected  DefaultMutableTreeNode	m_rootNode
protected  String	m_rootNodeName
protected  DefaultTreeModel	m_treeModel
protected  WorldMap	m_worldMap

 

Constructor Summary
protected	PhysicalObjectDatabase()           Internal constructor to create an unitialized physical object database with no map or objects.
	PhysicalObjectDatabase(File directory)           Create a physical object database by initializing from the given filesystem database snapshot directory using the load() method.
	PhysicalObjectDatabase(WorldMap worldMap)           Create an empty physical object database for the given map.

 

Method Summary
void	add(PhysicalObject obj)           Add the given physical object to the database and allocate a new Tracker for this object.
void	add(PhysicalObject obj, String parentObjectName)           Add the given physical object to the database as a child of the named physical object using the existing Tracker of the parent for this object.
PhysicalObject	getObject(String objectName)           Get a physical object by name.
Tracker	getRandomTracker()           Get a random tracker.
PhysicalObject	getRootObject(String objectName)           Lookup the object at the root of the given object's grouping tree.
Tracker	getTracker(String objectName)           Get the tracker for the physical object with the given name.
WorldMap	getWorldMap()           Get the world map.
void	link(String childObjectName, String parentObjectName)           Hierarchically link the existing physical objects as child and parent.
void	load(File directory)           Load a database summary snapshot from persistent storage anchored at the given filesystem directory.
static void	main(String[] args)           Regression tests for the database not used during normal operation.
Collection	queryNames()           Perform a query to return a Collection of all object name Strings.
Collection	queryNamesByGroup(String inObjectName)           Perform a query to return a Collection of object name Strings.
Collection	queryNamesByType(Class typeClass)           Perform a query to return a Collection of object name Strings.
Collection	queryNamesByType(String typeName)           Perform a query to return a Collection of object name Strings.
Collection	queryNamesByTypeAndGroup(String typeName, String inObjectName)           Perform a conjunctive query to return a Collection of object name Strings.
void	remove(String objectName)           Remove the named physical object from the database.
void	removeGroup(String objectName)           Remove the named physical object and all child objects from the database.
void	save(File directory)           Save a database summary snapshot to persistent storage anchored at the given filesystem directory.
String	toString()           Overridden to print the internal tree structure, database hash index, and world map.
void	unlink(String objectName)           Logically unlink the given existing physical object from its parent.

 

Methods inherited from class java.lang.Object

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

 

Field Detail

m_lock

protected MultiReadSingleWriteLock m_lock

m_nameToNodeMap

protected Map m_nameToNodeMap

m_rootNode

protected DefaultMutableTreeNode m_rootNode

m_treeModel

protected DefaultTreeModel m_treeModel

m_worldMap

protected WorldMap m_worldMap

m_random

protected Random m_random

m_rootNodeName

protected String m_rootNodeName

PhysicalObjectDatabase

public PhysicalObjectDatabase(File directory)
                       throws PhysicalObjectDatabaseException

Create a physical object database by initializing from the given filesystem database snapshot directory using the load() method.

Throws:

PhysicalObjectDatabaseException

See Also:

load(File)

PhysicalObjectDatabase

public PhysicalObjectDatabase(WorldMap worldMap)

Create an empty physical object database for the given map.

PhysicalObjectDatabase

protected PhysicalObjectDatabase()

Internal constructor to create an unitialized physical object database with no map or objects.

save

public void save(File directory)
          throws PhysicalObjectDatabaseException

Save a database summary snapshot to persistent storage anchored at the given filesystem directory. Any existing snapshot in the given directory is overwritten. The following items are saved:

1. The world map.
2. The hierarchical tree structure of all object groups.
3. The most likely State of each object group.

Parameters:

directory - the directory to which to save. Must not be null.

Throws:

DatabaseSaveException - if the save is unsuccessful

PhysicalObjectDatabaseException

See Also:

load(File), PhysicalObjectDatabase(File)

load

public void load(File directory)
          throws PhysicalObjectDatabaseException

Load a database summary snapshot from persistent storage anchored at the given filesystem directory. The following items are loaded:

1. A world map.
2. A hierarchical tree structure of object groups.
3. A most likely State of each object group (optional).

Parameters:

directory - the directory from which to load. Must not be null.

Throws:

PhysicalObjectDatabaseException

See Also:

save(File), PhysicalObjectDatabase(File)

add

public void add(PhysicalObject obj)
         throws DuplicatePhysicalObjectException

Add the given physical object to the database and allocate a new Tracker for this object.

Note that if this object is to be immediately assigned a parent using link(obj.getName(), parentName), consider using the add(obj, parentName) method to avoid the overhead of allocating a tracker to this object and then immediately merging it into the parent.

Throws:

DuplicatePhysicalObjectException - if an object with the same name as the given object already exists in the database

See Also:

add(PhysicalObject,String), link(String,String), Tracker

add

public void add(PhysicalObject obj,
                String parentObjectName)
         throws DuplicatePhysicalObjectException,
                NoSuchPhysicalObjectException

Add the given physical object to the database as a child of the named physical object using the existing Tracker of the parent for this object. As an example, the parent may be a human being and this object being added is a sensor worn by the person which should update the person's tracker instead of its own.

Although semantically equivalent, using this routine is more efficient then calling add(obj) followed immediately by link(obj.getName(), parentName) because it avoids allocating a tracker to this object only to immediately merge it with the parent.

Throws:

NoSuchPhysicalObjectException - if the named parent object does not exist in the database

DuplicatePhysicalObjectException - if an object with the same name as the given object already exists in the database

See Also:

add(PhysicalObject), link(String,String), Tracker

remove

public void remove(String objectName)
            throws NoSuchPhysicalObjectException

Remove the named physical object from the database. Any children of this object are split off and assigned their own Trackers which are initialized by copying this object's particle filter and restoring the child's deafault motion model. For example, if the object being removed from the database is a human wearing several child sensor badges, each badge begins being tracked individually using a copy of the human's particle filter and the badge's default (most likely stationary) motion model.

Throws:

NoSuchPhysicalObjectException - if the named object does not exist in the database

See Also:

Tracker

removeGroup

public void removeGroup(String objectName)
                 throws NoSuchPhysicalObjectException

Remove the named physical object and all child objects from the database. Any children of this object also removed. To preserve children by copying the removed object's tracker to each child use the remove() method instead.

Throws:

NoSuchPhysicalObjectException - if the named object does not exist in the database

See Also:

remove(String), Tracker

link

public void link(String childObjectName,
                 String parentObjectName)
          throws NoSuchPhysicalObjectException

Hierarchically link the existing physical objects as child and parent. The Tracker of the child is merged into that of the parent. As an example, the parent may be a human being and the child a wearable sensor badge which should subsequently be used to update the person's Tracker.

Throws:

NoSuchPhysicalObjectException - if either the named parent or child object do not exist in the database

See Also:

Tracker.merge(Tracker)

unlink

public void unlink(String objectName)
            throws NoSuchPhysicalObjectException

Logically unlink the given existing physical object from its parent. This object receives a newly allocated Tracker that is a clone of the parent's. As an example, the parent may be a human being and the this object a wearable sensor badge which receives it's own tracker when logically unlinked from the human. This method does nothing if the named object is already a top level object.

Throws:

NoSuchPhysicalObjectException - if the object do not exist in the database

See Also:

Tracker

getTracker

public Tracker getTracker(String objectName)
                   throws NoSuchPhysicalObjectException

Get the tracker for the physical object with the given name. Note that there is no way to retrieve the PhysicalObject directly from the returned tracker. Use getObject() instead to retrieve the PhysicalObject from the database using the object's name. This method has worst case running time of O(h) where h is the height of the object grouping tree.

Throws:

NoSuchPhysicalObjectException - if the named object does not exist in the database

See Also:

getObject(String)

getRandomTracker

public Tracker getRandomTracker()
                         throws NoSuchPhysicalObjectException

Get a random tracker. For example, this method might be invoked by a looping thread to periodically apply a motion update by choosing one at random and updating it during each iteration. This method runs in time O(1).

Throws:

NoSuchPhysicalObjectException - if no trackers exist (i.e. the database is empty)

getWorldMap

public WorldMap getWorldMap()

Get the world map.

getObject

public PhysicalObject getObject(String objectName)
                         throws NoSuchPhysicalObjectException

Get a physical object by name. Note that there is no way to retrieve the Tracker from the returned object. Use getTracker() instead to retrieve the Tracker from the database using the object's name. This method operates in O(1) time.

Throws:

NoSuchPhysicalObjectException - if the named object does not exist in the database

See Also:

getTracker(String)

getRootObject

public PhysicalObject getRootObject(String objectName)
                             throws NoSuchPhysicalObjectException

Lookup the object at the root of the given object's grouping tree.

Throws:

NoSuchPhysicalObjectException

queryNames

public Collection queryNames()

Perform a query to return a Collection of all object name Strings.

Returns:

an Collection of Strings which is the result of the query. The Collection will not be null but may have 0 size if the database is empty.

queryNamesByType

public Collection queryNamesByType(String typeName)

Perform a query to return a Collection of object name Strings. Calling getObject(name) on any names in the returned Collection would retrieve a PhysicalObject with type (or subtype) of the given typeName.

Returns:

an Collection of Strings which is the result of the query. The Collection will not be null but may have 0 size.

queryNamesByType

public Collection queryNamesByType(Class typeClass)

Perform a query to return a Collection of object name Strings. Calling getObject(name) on any names in the returned Collection would retrieve a PhysicalObject with type (or subtype) of the given Class.

Returns:

an Collection of Strings which is the result of the query. The Collection will not be null but may have 0 size.

queryNamesByGroup

public Collection queryNamesByGroup(String inObjectName)

Perform a query to return a Collection of object name Strings. Calling getObject(name) on any names in the returned Collection would retrieve a PhysicalObject contained in the given object group according to the grouping hierarchy.

Returns:

a Collection of Strings which is the result of the query. The Collection will not be null but may have 0 size.

queryNamesByTypeAndGroup

public Collection queryNamesByTypeAndGroup(String typeName,
                                           String inObjectName)

Perform a conjunctive query to return a Collection of object name Strings. Calling getObject(name) on any names in the returned Collection would retrieve a PhysicalObject with type (or subtype) of the given typeName and contained in the given object group according to the grouping hierarchy.

Returns:

a Collection of Strings which is the result of the query. The Collection will not be null but may have 0 size.

toString

public String toString()

Overridden to print the internal tree structure, database hash index, and world map. The time complexity of this method is the same as a depth first search of all PhysicalObject hierarchy trees.

Overrides:

toString in class Object

main

public static void main(String[] args)

Regression tests for the database not used during normal operation.