How Import Works
To import objects from XML files in a jar file, import application must do the following:
1. Create a tool to read the imported jar file and extract the list of XML files that are contained in the jar file. Please see the class IXBJarReader for an implementation example.
2. Prepare the String ruleFileName to be passed into an instance of the class Importer. The String ruleFileName can be obtained from an IxbStreamer, from the user, assigned the value null or obtained from somewhere else, depending on the structure of the import application.
3. Process policyFile (if it is not null) to create an XSL StreamSource that contains the import policy.
4. Create an Application Import Handler appHandler. This is an instance of any class that either implements the interface ApplicationImportHandler or extends the abstract class ApplicationImportHandlerTemplate.
5. Create an instance of the class Importer (importer).
6. Get the list of XML files in the jar file.
7. Create IxbDocuments from those XML files.
8. With each IxbDocument, do the following:
◦ If there is an action name passed to the application and the policyFile is null, apply the action name into the IxbDocument. If the policyFile is not null, apply action name and action information in the policyFile into the IxbDocument.
◦ Feed them to the importer one by one by calling the import process:
▪ importer.doImport(IxbDocument Doc);
▪ importer.finalizeImport();
9. Clean up (if needed).
10. Send log messages to client.
The methods
doImport(...), doImportImpl(...) and the inner class
ImportHandler in the
StandardIXBService are an example of one import application. Please see the
Import Application for details.
Versioned objects can be imported in any of ten different manners decided by action name and action information that are written to the IxbDocument fileXML of each importing object. Developers who write import applications must know about action names and their meanings to apply them correctly, but object handlers don’t have to worry about the Actor classes. A list of all available action names can be found in the file <Windchill>\codebase\registry\ixb\handlers\actor.xml.
All of the actions are different from each other in three crucial methods: previewObject, createObject and storeObject. In the classes ClassExporterImporterTemplate and ExpImpForVersionedObject, based on action name and action information that are passed into the IxbDocument fileXML, appropriate actor will be created and this actor’s methods will be called to serve the purpose of previewing, creating and storing versioned objects.
Here is the list by actor names for information.
1. PickExistingObject : Find if an object with the same ufid or same (name, number, version, iteration) with the object in XML file exists in database. If such an object exists, the framework will update the object if the actor believes the object is candidate for update, or do nothing. Otherwise, import the object in XML file.
2. NewIteration : Import object in XML file as the next available iteration in the database.
◦ For example: If there is no version/iteration in the database for the object which is in the XML file, the imported object will get the version / iteration specified in the XML file. If the latest version / iteration of the object in the database is B.2, the imported object will be B.3.
3. NewVersion : Import objects from the XML file as the next available version in the database.
◦ For example: If there is no version / iteration in the database for the object which is in the XML file, the imported object will get the version / iteration specified in the XML file. If the latest version / iteration of the object in the database is B.2, the imported object will be C.1.
4. CheckOut : Find any version/iteration of the object in the XML file (Check the existence of the master object in the database). If there is no version of the object in the XML file, throw an error. Otherwise, find an instance of the object in the database that has the same version (iteration can be different) as the object in the XML file. If such an object exists, check out the latest iteration of the object in the database, update it with information from the XML file. I agree Otherwise, throw an error. It is now checked in
5. ImportNonVersionedAttr : Find an object with the same ufid or same (name, number, version, iteration) with the object in the XML file. If such an object exists, update it with information from the XML file. Otherwise, throw an error.
6. UpdateInPlace : Find an object with the same ufid or same (name, number, version, iteration) with the object in XML file exists in database. If such an object exists AND it is checked out, update it with information from the XML file. Otherwise, throw an error.
7. UnlockAndIterate : Find an object in the database with the same ufid or same (name, number, version, iteration) as the object in the XML file. If such an object exists AND it is locked, unlock and iterate it, then update it with information from the XML file. Otherwise, throw an error.
8. CreateNewObject : Create a brand new object with new name, new number, new version, new iteration provided in Import Policy file. Other information will be extracted from the XML file. This functionality cannot be used alone.
|
|
This option cannot work without a policy file to specify the new object identities.
|
The format of new information that must be provided in ImportPolicy file is:
The following is a sample of a well-formed xsl. In the cases, where there are no specific actions to be performed, nothing needs to be done, which is achieved by the following:
|
|
• <actionInfo> must always exist.
• Criteria can be any valid attribute of the object in XML file.
• Between <xsl:choose>, there can be many <xsl: when test ....> with different criteria and different action names.
• Only CreateNewObject and SubstituteObject can have action params, and there are only four action params <newName>, <newNumber>, <newVersion>, <newIteration>, all of them must be provided.
• SubstituteObject: Substitute the object in the XML file for an object in the database that has the name, number, version, and iteration provided in the ImportPolicy file. If such an object doesn't exist, throw an exception. Format of tag and params for this case is exactly the same with CreateNewObject, but the <action> is SubstituteObject.
• Ignore: Do not import the object in the XML file. This action doesn't require any actor.
|
