ObjectMap (HCL OneTest UI)

java.lang.Object
- com.rational.test.ft.object.map.ObjectMap

```
public class ObjectMap
extends java.lang.Object
```
A persistent (XML-based) data structure containing a collection of objects organized into a network. For many objects, they will be organized into a hierarchical structure by a combination of parent and child properties.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`ObjectMap.ScoreOptions` This class allows the merge algorithm to be customized to work for the various merge types.

Field Summary

Fields
Modifier and Type Field and Description

protected static FtDebug debug

protected static java.lang.String MERGEDMAPID

Fields
Modifier and Type	Field and Description
`protected static FtDebug`	`debug`
`protected static java.lang.String`	`MERGEDMAPID`

Constructor Summary

Constructors
Constructor and Description
`ObjectMap()` Construct an object map with no shared map characteristics.
`ObjectMap(ObjectMapSet mtoSet, long nextElementId, long safeElementId, ObjectMapTopLevelIdSet topLevelIds, HashtableEx attributes, ObjectMapPropertySet mapProps)` This method is required for internal use only and should not be used for purposes other then rectituting an object map.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addElement(IMappedTestObject element)` Add a `IMappedTestObject` object to the map.
`void`	`addElement(IMappedTestObject element, boolean defineGuidMapId)`
`void`	`cleanup()` Break up an object map to help teh garbage collector reclaim memory.
`void`	`clearPropertyCache()`
`void`	`clearState()` Clear the `IMappedTestObject` state of every node in the map.
`boolean`	`containsId(java.lang.String id)` Return `true` if the specified map id is present in this map.
`static void`	`copyMapFile(java.io.File fromFile, java.io.File toFile)` Copy 'from' file to 'to' file and clear any state setting found in the original map.
`static ObjectMap`	`createLocalMapFromSharedMap(java.lang.String datastore, java.lang.String localMapName, java.lang.String sharedMapName)` This method can be used to construct a local map from an existing shared map.
`static void`	`deleteObjectMapState(java.lang.String datastore, java.lang.String mapName)` Delete off any local cache files associated with this instance of an object map.
`static void`	`deletePersistantState(java.lang.String datastore, java.lang.String mapName)`
`java.util.Enumeration`	`elements()` Return an enumerator for the `IMappedTestObject` elements in the map.
`IMappedTestObject`	`find(java.lang.String id)` Find an `IMappedTestObject` by identifier in the map.
`protected IMappedTestObject`	`findLocal(java.lang.String id)` Find an `IMappedTestObject` by identifier in the map.
`void`	`freeObjectMap()` This method frees all assets held by an allocated object map.
`void`	`freeSharedMemory()` This method frees all shared memory associated with this map.
`java.lang.Object`	`getAttribute(java.lang.String name)` This method returns an attribute from the object map.
`java.util.Enumeration`	`getAttributeNames()` This method returns an enumeration for the attributes associated with an object map.
`protected long`	`getCurrentSafeElementId()` This method is for internal use ONLY.
`java.io.File`	`getFile()` This method returns the file name used to load the object map originally.
`static java.io.File`	`getFile(java.lang.String datastore, java.lang.String mapBaseName, boolean isLocalMap)` This method constructs an appropriate file name from the supplied parts.
`ObjectMapPropertySet`	`getMapProperties()` This method returns the set of properties associated with the ObjectMap.
`java.lang.String`	`getMergedToMto(IMappedTestObject mto)` When a "from" mto is merged into this map, the merged id is cached in the "from" mto for fast lookup.
`protected ObjectMapSet`	`getMtoSet()` This method is for internal use ONLY.
`protected long`	`getNextElementId()` This method is for internal use ONLY.
`static java.lang.String`	`getPrivateMapName(java.lang.String script)` This method constructs an appropriate project relative transient map file name from the supplied parts.
`HashtableEx`	`getPropertyCache()` Return a cache of properties used in this map with a default value for the property.
`protected long`	`getSafeElementId()` This method is for internal use ONLY.
`SpyMappedTestObject`	`getSharedInstance(IMappedTestObject node)` This method crates a global reference for a local mapped test object that can be viewed in another process.
`SpyMappedTestObject`	`getSharedInstance(java.lang.String id)` This method crates a global reference for a local mapped test object that can be viewed in another process.
`java.lang.String[]`	`getTopLevelIds()` Return a list of identifiers for the registered top level `IMappedTestObject` objects.
`protected ObjectMapTopLevelIdSet`	`getTopLevelIdSet()` This method is for internal use ONLY.
`IMappedTestObject[]`	`getTopLevelObjects()` Return a list of registered top level `IMappedTestObject` objects, including owned top level objects.
`IMappedTestObject[]`	`getTopLevelObjects(boolean includeOwned)` Return a list of registered top level `IMappedTestObject` objects.
`java.util.Hashtable`	`getUserModifiedIds()` Set a map id as having been modified directly by a user.
`java.util.Hashtable`	`getUserRemovedIds()` Return an enumerator for the elements deleted from the map.
`boolean`	`isUserModified(java.lang.String id)` Set a map id as having been modified directly by a user.
`static ObjectMap`	`load(java.io.File file)` This method loads an object map from the specified file.
`static ObjectMap`	`loadFromStream(java.io.InputStream input)`
`static void`	`loadPersistantState(java.io.File mapFile, ObjectMap objectMap)` This method takes a datastore relative map names and updates it with any cached persistent state.
`static java.io.File`	`locateFile(java.lang.String datastore, java.lang.String mapName)`
`void`	`merge(ObjectMap ancestor, ObjectMap source)`
`void`	`merge(ObjectMap ancestor, ObjectMap fromMap, ObjectMapSet usedLeafNodes, ObjectMap.ScoreOptions scoreOptions)`
`void`	`merge(ObjectMap fromMap, ObjectMapSet usedLeafNodes, ObjectMap.ScoreOptions scoreOptions)` This is the root of the internal map merging algorithm.
`void`	`merge(SpyMap mtoCache)` This method merges the results of a recorder shared map into an object map.
`IMappedTestObject`	`mergeThisToThat(IMappedTestObject sourceMto, IMappedTestObject targetMto)` Merge two mapped test objects together
`void`	`registerTopLevelObject(java.lang.String id)` Add a `IMappedTestObject` object to the list of top level ids.
`void`	`remove(java.lang.String id, boolean removeChildren, boolean removeOwned)` Remove the specified element from the map.
`void`	`removeTopLevelObject(java.lang.String id)` Remove a `IMappedTestObject` object from the list of top level ids.
`void`	`setAttribute(java.lang.String name, java.lang.Object value)` This method adds an attribute to the object map.
`void`	`setMtoSetElement(java.lang.String id, IMappedTestObject element)`
`void`	`setUserModified(java.lang.String id)` Set a map id as having been modified directly by a user.
`void`	`setUserRemoved(java.lang.String id)`
`int`	`size()` Return a count of the number of elements in the map.
`static void`	`store(ObjectMap objectMap, java.io.File file)`
`static void`	`store(ObjectMap objectMap, java.io.File file, boolean silent)` This method stores an object map to the specified file.
`static void`	`storePersistantState(ObjectMap objectMap, java.io.File mapFile, boolean refreshIDE)`
`static void`	`storeToStream(ObjectMap objectmap, java.io.OutputStream boStream)`
`static void`	`updateMergedProperties(IMappedTestObject targetMto, IMappedTestObject mergedMto)`
`void`	`updateSafeElementId()` The merge algorithm needs to keep track of the safe element id so that shared map nodes can be properly separated from new nodes.
`void`	`updateThisToThatProperties(IMappedTestObject targetMto, IMappedTestObject mergedMto)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - debug
```
protected static FtDebug debug
```
  - MERGEDMAPID
```
protected static final java.lang.String MERGEDMAPID
```
    See Also:
    Constant Field Values
- Constructor Detail
  - ObjectMap
```
public ObjectMap()
```
    Construct an object map with no shared map characteristics.
  - ObjectMap
```
public ObjectMap(ObjectMapSet mtoSet,
         long nextElementId,
         long safeElementId,
         ObjectMapTopLevelIdSet topLevelIds,
         HashtableEx attributes,
         ObjectMapPropertySet mapProps)
```
    This method is required for internal use only and should not be used for purposes other then rectituting an object map.
- Method Detail
  - cleanup
```
public void cleanup()
```
    Break up an object map to help teh garbage collector reclaim memory.
  - loadFromStream
```
public static ObjectMap loadFromStream(java.io.InputStream input)
```
  - load
```
public static ObjectMap load(java.io.File file)
```
    This method loads an object map from the specified file.
  - storeToStream
```
public static void storeToStream(ObjectMap objectmap,
                 java.io.OutputStream boStream)
```
  - store
```
public static void store(ObjectMap objectMap,
         java.io.File file)
```
  - store
```
public static void store(ObjectMap objectMap,
         java.io.File file,
         boolean silent)
```
    This method stores an object map to the specified file.
  - getFile
```
public static java.io.File getFile(java.lang.String datastore,
                   java.lang.String mapBaseName,
                   boolean isLocalMap)
```
    This method constructs an appropriate file name from the supplied parts.
  - getFile
```
public java.io.File getFile()
```
    This method returns the file name used to load the object map originally. This method will return null for a newly constructed object map.
  - getPrivateMapName
```
public static java.lang.String getPrivateMapName(java.lang.String script)
```
    This method constructs an appropriate project relative transient map file name from the supplied parts.
  - deleteObjectMapState
```
public static void deleteObjectMapState(java.lang.String datastore,
                        java.lang.String mapName)
```
    Delete off any local cache files associated with this instance of an object map.
  - getAttribute
```
public java.lang.Object getAttribute(java.lang.String name)
```
    This method returns an attribute from the object map. Attributes are properties added by support tools and persisted with the object map for future reference.
    
    Parameters:
    name - The name of the attribute.
    
    Returns:
    The data associated with the attribute.
  - setAttribute
```
public void setAttribute(java.lang.String name,
                java.lang.Object value)
```
    This method adds an attribute to the object map. Attributes are properties added by support tools and persisted with the object map for future reference.
    
    Parameters:
    name - The name of the attribute.
    value - The data associated with the attribute.
  - getAttributeNames
```
public java.util.Enumeration getAttributeNames()
```
    This method returns an enumeration for the attributes associated with an object map. Note that the standard attributes are not included in this enumeration.
    
    Returns:
    An enumerator for the attributes associated with an object map.
  - getMapProperties
```
public ObjectMapPropertySet getMapProperties()
```
    This method returns the set of properties associated with the ObjectMap.
  - updateSafeElementId
```
public void updateSafeElementId()
```
    The merge algorithm needs to keep track of the safe element id so that shared map nodes can be properly separated from new nodes. This update is performed by the ClearCase integration when a map is checked out/in.
  - addElement
```
public void addElement(IMappedTestObject element)
```
    Add a IMappedTestObject object to the map. An unique identifier is assigned to the objet when added to the object map. If the object already has an identifier associated with it an appropriate exception is thrown.
  - addElement
```
public void addElement(IMappedTestObject element,
              boolean defineGuidMapId)
```
  - find
```
public IMappedTestObject find(java.lang.String id)
                       throws ObjectNotInMapException
```
    Find an IMappedTestObject by identifier in the map.
    
    Throws:
    
    ObjectNotInMapException
  - findLocal
```
protected IMappedTestObject findLocal(java.lang.String id)
```
    Find an IMappedTestObject by identifier in the map. No exception is thrown by this version of the find.
  - remove
```
public void remove(java.lang.String id,
          boolean removeChildren,
          boolean removeOwned)
            throws ObjectNotInMapException
```
    Remove the specified element from the map. If the specified element is not in the map ObjectNotInMapException is thrown.
    
    Throws:
    
    ObjectNotInMapException
  - setUserRemoved
```
public void setUserRemoved(java.lang.String id)
```
  - getUserRemovedIds
```
public java.util.Hashtable getUserRemovedIds()
```
    Return an enumerator for the elements deleted from the map.
  - setUserModified
```
public void setUserModified(java.lang.String id)
```
    Set a map id as having been modified directly by a user.
  - isUserModified
```
public boolean isUserModified(java.lang.String id)
```
    Set a map id as having been modified directly by a user.
  - getUserModifiedIds
```
public java.util.Hashtable getUserModifiedIds()
```
    Set a map id as having been modified directly by a user.
  - elements
```
public java.util.Enumeration elements()
```
    Return an enumerator for the IMappedTestObject elements in the map.
  - size
```
public int size()
```
    Return a count of the number of elements in the map.
  - containsId
```
public boolean containsId(java.lang.String id)
```
    Return true if the specified map id is present in this map.
  - registerTopLevelObject
```
public void registerTopLevelObject(java.lang.String id)
```
    Add a IMappedTestObject object to the list of top level ids. A check is performed to make sure the object does not have a parent and an appropriate exception raised if the parent is non-null.
  - removeTopLevelObject
```
public void removeTopLevelObject(java.lang.String id)
```
    Remove a IMappedTestObject object from the list of top level ids.
  - getTopLevelIds
```
public java.lang.String[] getTopLevelIds()
```
    Return a list of identifiers for the registered top level IMappedTestObject objects.
  - getTopLevelObjects
```
public IMappedTestObject[] getTopLevelObjects()
```
    Return a list of registered top level IMappedTestObject objects, including owned top level objects.
  - getTopLevelObjects
```
public IMappedTestObject[] getTopLevelObjects(boolean includeOwned)
```
    Return a list of registered top level IMappedTestObject objects.
  - getSharedInstance
```
public SpyMappedTestObject getSharedInstance(IMappedTestObject node)
                                      throws ObjectNotInMapException
```
    This method crates a global reference for a local mapped test object that can be viewed in another process. During playback an element needs to be copied to shared memory so that it can be viewed in other processes. The entire parentage of a requested element needs to be copied so that the hierarchy remains intacted and available.
    
    Throws:
    
    ObjectNotInMapException
  - getSharedInstance
```
public SpyMappedTestObject getSharedInstance(java.lang.String id)
                                      throws ObjectNotInMapException
```
    This method crates a global reference for a local mapped test object that can be viewed in another process. During playback an element needs to be copied to shared memory so that it can be viewed in other processes. The entire parentage of a requested element needs to be copied so that the hierarchy remains intacted and available.
    
    Throws:
    
    ObjectNotInMapException
  - clearState
```
public void clearState()
```
    Clear the IMappedTestObject state of every node in the map.
  - freeObjectMap
```
public void freeObjectMap()
```
    This method frees all assets held by an allocated object map.
  - freeSharedMemory
```
public void freeSharedMemory()
```
    This method frees all shared memory associated with this map.
  - createLocalMapFromSharedMap
```
public static ObjectMap createLocalMapFromSharedMap(java.lang.String datastore,
                                    java.lang.String localMapName,
                                    java.lang.String sharedMapName)
```
    This method can be used to construct a local map from an existing shared map. The shared map is copied to the local map and the SharedMapLastId is set in the active script definition for later use when merging the local map back into the shared map.
    
    Parameters:
    datastore - This is the datastore directory that the objects maps are located relative to. Note that they must be defined in the same datastore.
    
    Returns:
    The local object map constructed from a copy of the shared map.
  - copyMapFile
```
public static void copyMapFile(java.io.File fromFile,
               java.io.File toFile)
```
    Copy 'from' file to 'to' file and clear any state setting found in the original map.
  - getPropertyCache
```
public HashtableEx getPropertyCache()
```
    Return a cache of properties used in this map with a default value for the property. This cache is generated on demand and cleared when additional test objects are added to the object map. This cache is used to in the UI to present a set of properties that the user can choose from to create a find filter.
    Note that all the keys in the property cache are String values and the values are all type MappedTestObjectProperty.
  - updateThisToThatProperties
```
public void updateThisToThatProperties(IMappedTestObject targetMto,
                              IMappedTestObject mergedMto)
```
  - updateMergedProperties
```
public static void updateMergedProperties(IMappedTestObject targetMto,
                          IMappedTestObject mergedMto)
```
  - mergeThisToThat
```
public IMappedTestObject mergeThisToThat(IMappedTestObject sourceMto,
                                IMappedTestObject targetMto)
```
    Merge two mapped test objects together
  - merge
```
public void merge(SpyMap mtoCache)
```
    This method merges the results of a recorder shared map into an object map. A recorder shared map associates instance strings to SpyMappedTestObject objects. This method matches those elements to existing elements in this object map or constructs new nodes that represent those nodes. As a side effect of this method identifiers are set in the SpyMappedTestObject objects in the recorder shared map.
  - setMtoSetElement
```
public void setMtoSetElement(java.lang.String id,
                    IMappedTestObject element)
```
  - locateFile
```
public static java.io.File locateFile(java.lang.String datastore,
                      java.lang.String mapName)
```
  - merge
```
public void merge(ObjectMap fromMap,
         ObjectMapSet usedLeafNodes,
         ObjectMap.ScoreOptions scoreOptions)
```
    This is the root of the internal map merging algorithm. Both spy->local and local->shared merges utilize the same merging algorithm. The spy->local merge needs to spoof a local version of an ObjectMap to have the safeElementId set correctly (and have newer nodes pushed out past this id in the spoofed map).
  - merge
```
public void merge(ObjectMap ancestor,
         ObjectMap source)
```
  - merge
```
public void merge(ObjectMap ancestor,
         ObjectMap fromMap,
         ObjectMapSet usedLeafNodes,
         ObjectMap.ScoreOptions scoreOptions)
```
  - getMergedToMto
```
public java.lang.String getMergedToMto(IMappedTestObject mto)
```
    When a "from" mto is merged into this map, the merged id is cached in the "from" mto for fast lookup. Avoid multiple merging by setting state to "merged" and saving the id of the associated node in this map.
  - getMtoSet
```
protected ObjectMapSet getMtoSet()
```
    This method is for internal use ONLY.
  - getNextElementId
```
protected long getNextElementId()
```
    This method is for internal use ONLY.
  - getCurrentSafeElementId
```
protected long getCurrentSafeElementId()
```
    This method is for internal use ONLY.
  - getSafeElementId
```
protected long getSafeElementId()
```
    This method is for internal use ONLY.
  - getTopLevelIdSet
```
protected ObjectMapTopLevelIdSet getTopLevelIdSet()
```
    This method is for internal use ONLY.
  - clearPropertyCache
```
public void clearPropertyCache()
```
  - loadPersistantState
```
public static void loadPersistantState(java.io.File mapFile,
                       ObjectMap objectMap)
```
    This method takes a datastore relative map names and updates it with any cached persistent state.
  - deletePersistantState
```
public static void deletePersistantState(java.lang.String datastore,
                         java.lang.String mapName)
```
  - storePersistantState
```
public static void storePersistantState(ObjectMap objectMap,
                        java.io.File mapFile,
                        boolean refreshIDE)
```

Class ObjectMap

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

debug

MERGEDMAPID

Constructor Detail

ObjectMap

ObjectMap

Method Detail

cleanup

loadFromStream

load

storeToStream

store

store

getFile

getFile

getPrivateMapName

deleteObjectMapState

getAttribute

setAttribute

getAttributeNames

getMapProperties

updateSafeElementId

addElement

addElement

find

findLocal

remove

setUserRemoved

getUserRemovedIds

setUserModified

isUserModified

getUserModifiedIds

elements

size

containsId

registerTopLevelObject

removeTopLevelObject

getTopLevelIds

getTopLevelObjects

getTopLevelObjects

getSharedInstance

getSharedInstance

clearState

freeObjectMap

freeSharedMemory

createLocalMapFromSharedMap

copyMapFile

getPropertyCache

updateThisToThatProperties

updateMergedProperties

mergeThisToThat

merge

setMtoSetElement

locateFile

merge

merge

merge

getMergedToMto

getMtoSet

getNextElementId

getCurrentSafeElementId

getSafeElementId

getTopLevelIdSet

clearPropertyCache

loadPersistantState

deletePersistantState

storePersistantState