IBM Rational Functional Tester
Version 8.2.1
IBM Rational Functional Tester API Reference

Project Version 2.3

com.rational.test.ft.object.map
Class ObjectMap

java.lang.Object
  extended by 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
protected static class ObjectMap.ScoreOptions
          This class allows the merge algorithm to be customized to work for the various merge types.
 
Field Summary
protected static com.rational.test.ft.util.FtDebug debug
           
protected static java.lang.String MERGEDMAPID
           
 
Constructor Summary
ObjectMap()
          Construct an object map with no shared map characteristics.
ObjectMap(com.rational.test.ft.object.map.ObjectMapSet mtoSet, long nextElementId, long safeElementId, com.rational.test.ft.object.map.ObjectMapTopLevelIdSet topLevelIds, com.rational.test.ft.sys.HashtableEx attributes, com.rational.test.ft.object.map.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
 void addElement(com.rational.test.ft.object.map.IMappedTestObject element)
          Add a IMappedTestObject object to the map.
 void addElement(com.rational.test.ft.object.map.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.
 com.rational.test.ft.object.map.IMappedTestObject find(java.lang.String id)
          Find an IMappedTestObject by identifier in the map.
protected  com.rational.test.ft.object.map.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.
 com.rational.test.ft.object.map.ObjectMapPropertySet getMapProperties()
          This method returns the set of properties associated with the ObjectMap.
 java.lang.String getMergedToMto(com.rational.test.ft.object.map.IMappedTestObject mto)
          When a "from" mto is merged into this map, the merged id is cached in the "from" mto for fast lookup.
protected  com.rational.test.ft.object.map.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.
 com.rational.test.ft.sys.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.
 com.rational.test.ft.object.map.SpyMappedTestObject getSharedInstance(com.rational.test.ft.object.map.IMappedTestObject node)
          This method crates a global reference for a local mapped test object that can be viewed in another process.
 com.rational.test.ft.object.map.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  com.rational.test.ft.object.map.ObjectMapTopLevelIdSet getTopLevelIdSet()
          This method is for internal use ONLY.
 com.rational.test.ft.object.map.IMappedTestObject[] getTopLevelObjects()
          Return a list of registered top level IMappedTestObject objects, including owned top level objects.
 com.rational.test.ft.object.map.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 toBeMerged)
           
 void merge(ObjectMap ancestor, ObjectMap source)
           
 void merge(ObjectMap ancestor, ObjectMap fromMap, com.rational.test.ft.object.map.ObjectMapSet usedLeafNodes, ObjectMap.ScoreOptions scoreOptions)
           
 void merge(ObjectMap fromMap, com.rational.test.ft.object.map.ObjectMapSet usedLeafNodes, ObjectMap.ScoreOptions scoreOptions)
          This is the root of the internal map merging algorithm.
 void merge(com.rational.test.ft.sys.SpyMap mtoCache)
          This method merges the results of a recorder shared map into an object map.
 com.rational.test.ft.object.map.IMappedTestObject mergeThisToThat(com.rational.test.ft.object.map.IMappedTestObject sourceMto, com.rational.test.ft.object.map.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, com.rational.test.ft.object.map.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(com.rational.test.ft.object.map.IMappedTestObject targetMto, com.rational.test.ft.object.map.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(com.rational.test.ft.object.map.IMappedTestObject targetMto, com.rational.test.ft.object.map.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 com.rational.test.ft.util.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(com.rational.test.ft.object.map.ObjectMapSet mtoSet,
                 long nextElementId,
                 long safeElementId,
                 com.rational.test.ft.object.map.ObjectMapTopLevelIdSet topLevelIds,
                 com.rational.test.ft.sys.HashtableEx attributes,
                 com.rational.test.ft.object.map.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 com.rational.test.ft.object.map.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(com.rational.test.ft.object.map.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(com.rational.test.ft.object.map.IMappedTestObject element,
                       boolean defineGuidMapId)

find

public com.rational.test.ft.object.map.IMappedTestObject find(java.lang.String id)
                                                       throws ObjectNotInMapException
Find an IMappedTestObject by identifier in the map.

Throws:
ObjectNotInMapException

findLocal

protected com.rational.test.ft.object.map.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 com.rational.test.ft.object.map.IMappedTestObject[] getTopLevelObjects()
Return a list of registered top level IMappedTestObject objects, including owned top level objects.


getTopLevelObjects

public com.rational.test.ft.object.map.IMappedTestObject[] getTopLevelObjects(boolean includeOwned)
Return a list of registered top level IMappedTestObject objects.


getSharedInstance

public com.rational.test.ft.object.map.SpyMappedTestObject getSharedInstance(com.rational.test.ft.object.map.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 com.rational.test.ft.object.map.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 com.rational.test.ft.sys.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(com.rational.test.ft.object.map.IMappedTestObject targetMto,
                                       com.rational.test.ft.object.map.IMappedTestObject mergedMto)

updateMergedProperties

public static void updateMergedProperties(com.rational.test.ft.object.map.IMappedTestObject targetMto,
                                          com.rational.test.ft.object.map.IMappedTestObject mergedMto)

mergeThisToThat

public com.rational.test.ft.object.map.IMappedTestObject mergeThisToThat(com.rational.test.ft.object.map.IMappedTestObject sourceMto,
                                                                         com.rational.test.ft.object.map.IMappedTestObject targetMto)
Merge two mapped test objects together


merge

public void merge(com.rational.test.ft.sys.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,
                             com.rational.test.ft.object.map.IMappedTestObject element)

locateFile

public static java.io.File locateFile(java.lang.String datastore,
                                      java.lang.String mapName)

merge

public void merge(ObjectMap fromMap,
                  com.rational.test.ft.object.map.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 toBeMerged)

merge

public void merge(ObjectMap ancestor,
                  ObjectMap source)

merge

public void merge(ObjectMap ancestor,
                  ObjectMap fromMap,
                  com.rational.test.ft.object.map.ObjectMapSet usedLeafNodes,
                  ObjectMap.ScoreOptions scoreOptions)

getMergedToMto

public java.lang.String getMergedToMto(com.rational.test.ft.object.map.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 com.rational.test.ft.object.map.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 com.rational.test.ft.object.map.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)