Mapper Classes
Windchill ESI mapping capabilities are provided by the classes shown in the figure Windchill ESI Mapper Classes. None of the classes are serializable. Therefore, they are not available to Windchill GUI clients.
ESIMapManager
ESIMapManager maintains a collection of ESIMap objects. The map manager maintains the ESIMap objects in a cache so that they only have to be retrieved once from external storage. Once retrieved, the map information is not re-read from the disk until the java virtual machine is restarted.
 | An exception to what is stated above occurs when the value of the responseMetaInfoPath attribute on a given distribution target is modified. This will result in the contents of the newly specified ESI response meta information file to be read in as soon as the distribution target is modified and saved. A new entry will be created as well in the map manager, for the modified version of the response meta information file. Retrieval of information from the file also occurs if a given distribution target is made inactive, saved and made active once again. |
The class follows the Singleton design pattern to ensure that only one instance exists in a java virtual machine. All users of ESIMap objects are expected to obtain them from the map manager.
<<Static>> instance() : ESIMapManager
Gets the value of the _instance attribute. If it is null, create an instance and store it in the attribute before returning the result.
<<final>> getMap(id : String) : ESIMap
Returns the ESIMap identified by the id argument. If the input ID exists as a key in maps, the method simply returns the corresponding value. Otherwise, a null is returned after logging an error message.
| | This method works only for ESIMap objects that figure in the ESI response meta information file; for those objects that are represented by map files (e.g., ESITarget.map), use the overloaded version that takes in a File instance instead. |
<<final>> getMap(file : File) : ESIMap
Returns the ESIMap object identified by the input argument. If the name of the input file exists as a key in maps, this method simply returns the corresponding value. Otherwise, it creates a new ESIMap instance, initializes it with the contents of the input map file, and returns the resulting object, besides creating an entry for the newly created object in maps.
ESIMap
Windchill ESI maps are objects that represent the contents of the Map elements in the ESI response meta information file. A Map element may have one or more child elements named attributeMapping, each of which represents a pair of source and target attribute names and optionally a default value for the attribute. Each attributeMapping entry in the file takes the following form:
<esi:attributeMapping sourceAttribute="Source_Name" defaultValue="Default">Target_Name</esi:attributeMapping>
• Source_Name is an instruction describing where to find the data that is to be extracted. This section of the entry is required.
◦ If the object being mapped is an Info*Engine element object, Source_Name is the name of an Info*Engine Att object on that element object.
◦ If the object being mapped is not an Info*Engine element, Source_Name is the name of a "getter method" to invoke on the object. The value supplied for Source_Name is pre-pended with the characters, "get", and the resulting string is used as a method name. The mapper only invokes methods that take no arguments and have a name that begins with "get".
◦ The mapper is able to navigate object structures. If Source_Name contains periods, the periods are interpreted as method delimiters. The mapper invokes the "getter method" identified by the first segment of the Source_Name on the object being mapped. If that method returns a result, the mapper invokes the second segment of the Source_Name on the result. The mapper continues to obtain the result for each section of Source_Name.
Example: This is the Source_Name value from one of the attributeMapping entries used by the Windchill ESI BOM component renderer: Quantity.Amount. The mapper executes the getQuantity() method on the object being mapped. If the result is not null, the mapper executes the getAmount() method on the object obtained by the getQuantity() method. If getAmount() returns a value, the mapper assigns that value to the output.
• Target_Name is the name to give to the output Att object that is created by the mapper. This section of the entry is required.
• Default is the value to assign to the output if the value is not available from the source. This section of the entry is optional.
These are the available methods of the class:
ESIMap(fileName : String)
Loads the map file identified by the fileName argument. This constructor is used only when the ESI map is to be created from a map file. See the Note at the end of this section for more information on map files.
ESIMap(mapID : String, attributes : List<Entry>)
Creates a new ESIMap instance, setting its attributes id and entries to the input values. This constructor is invoked by the API that parses the ESI response meta information file.
getID() : String
Returns the value of the attribute id.
getSourceAttributes() : Collection
Returns a collection of Strings that represent the names of the source attributes.
getTargetAttributes() : Collection
Returns a collection of Strings that represent the names of the target attributes.
iterator() : java.util.Iterator
Returns an iterator for the Collection in the entries attribute.
| | The ESIMap instance holds a list of Entry instances, each of which represents a given attributeMapping entry of a given Map element in the ESI response meta information file. The "entries" above refers to the said list of Entry instances. |
| | While most ESI map objects are populated using the contents of the ESI response meta information file, there are certain others that are populated from map files such ESITarget.map, ESIReleaseActivities.map etc. The map files are ASCII text files. Each entry in a map file is expected to have the following format: Source_Name = Target_Name|Default Where Source_Name, Target_Name and Default have the same meanings as described earlier in this section. |
ESIMapper
ESIMapper objects contain the logic to interpret ESIMap object contents. They also create output. ESIMapper objects provide three public methods. The methods are:
map(object : Object, map : ESIMap) : Element
This method creates a mapped Info*Engine element object from the Object argument.
map(inputElement : Element, map : ESIMap) : Element
This method creates a mapped Info*Engine element object from another Info*Engine element object.
map(inputElement : Element, map : ESIMap, includeEmptyAttributes : boolean) : Element
This method creates a mapped Info*Engine element object from another Info*Engine element object. If a false was passed in for includeEmptyAttributes, only those Atts having a value will be returned with the output element. The behaviour of this method is identical to map(inputElement : Element, map : ESIMap) if a true was passed in for includeEmptyAttributes.
map(inputElement : Element, persistedObject : Persistable, map : ESIMap) : Element
This method creates a mapped Info*Engine element object from another Info*Engine element object. If the source element object does not have the value specified in Source_Name of the attributeMapping (or map file) entry, the mapper attempts to obtain the value from the Persistable object in the second method argument.
map(object : Object, map : ESIMap, softTypes : Map) : Element
This method creates a mapped Info*Engine element object from the Object argument. If the method is unable to fetch the value of a given source attribute in the passed ESIMap instance, it creates an entry in the output Map (softTypes) with the relevant source and target attribute names as the key and value. The output Map thus ends up having entries for all the soft attributes that were added to the given object. The caller will then be able to process this Map and proceed to map those soft attributes as appropriate.
Mapper Class Collaboration
The following sequence diagram shows how an object uses the Windchill ESI Mapper:
1. The requesting object obtains an ESIMap object from the Windchill ESI map manager. The value of the id attribute (for which to obtain the ESIMap object) is fetched from the group name that is relevant for the mapping process for the currently processed distribution target, and for the type of the requesting object.
2. The map manager examines its cache and returns the appropriate ESIMap object. If the ESIMap object does not exist in the cache, the map manager creates it and adds it to the cache.
3. The requesting object creates an ESIMapper object and calls the appropriate map method.
4. The ESIMapper object obtains an iterator from the Windchill ESI map. For each entry identified by the iterator:
a. The ESIMapper obtains the Source_Name.
b. The ESIMapper obtains the value for that attribute from the source and adds it to the output.