com.ptc.windchill.upgrade.directives
Interface Migrator

All Known Implementing Classes:

CabinetKeyMigration, CabinetMigrator, ChangeKeyMigratorR7, CheckoutLinkCleanupMigrator, ControlBranchIteratedColumnsMigrator, EPMAsStoredChildNameR62, EPMDocTypeMigrator, EPMDocumentMasterCadNameMigrator, EPMDocumentMasterKeyMigratorR4ToR5, EPMReferenceDesignatorMigratorR6, EPMWorkspaceKeyR5ToR6, FolderLinkMigrator, MergeAndDeleteForums_R8, MergeForums_R8, MigrateContainerRefR7_R8, MigrateHierarchyDisplayName, MigrateHotlistR7_PDML_PJL, MigrateLCRoutingFlag_R7, MigrateMeetingActionItem_PL60ToPL61, MigrateNotebookContentR6_R7, MigrateNotebookContentR7_R8, MigrateNotebookFolderNamesR7_R8, MigrateNotebookForumIntoDomain_R7, MigrateRegProperties_PL60ToPL61, MigrateSite_R40ToR60, MigrateSite_R50ToR60, MigrateSite_R51ToR60, MigrateTeamAndTemplate_R62To70, MigrateTopicNamesR7_R8, MigrateTypeDefinitionName, MigrateWfEventsR7_R8, MigrateWfProcess_R4ToR5, OrganizationOwnedMigratorR7, PopulateSubjectRef_R8, QMLWTUserMigratorR5ToR6, RenameClassReferencesMigrator, ReparentDomainsMigrator, StreamedMigrationForUfid, upgrade3to4, UpgradeDerivedImageContent5to6, UpgradeDerivedImageDefRep5to6, UpgradeDerivedImageKey5to6, UpgradeEffContextKey, UpgradeWTMarkupType5to6, URLDataDescriptionMigrator, URLDataVisualizerMigrator, WTUserAndGroupToLDAPMigrator, WTUserToProxyUserMigrator

public interface Migrator

Migration of data in a new schema can occur in two ways. One is via SQL scripts the other is programatically. This interface can be implemented by programmatic migration applications and then be run in a controlled manner by the Update Tool.

Once you develop a Migrator consult the ADG or Development Library Cookbook for information on authoring incremental updates for the Update Tool.

Note about exceptions

The interface declares that it throws Throwable. This allows migrators to conveniently not handle unexpected errors and let the MigratorRunner do so. If, for some reason, you decide to catch them inside the migrator, it will be helpful for diagnosis, to write them to the log using the syntax:

    ...
    catch(SomeException ex)
    {
       ex.printStackTrace(log_writer);
    }
 

Example - Using the POM

When using the POM you may need to use an access controller (e.g. for queries). The code below shows how to create an AccessControllerAdapter if the need arises.

    public boolean runMigration(Connection windchill_database_connection, PersistentObjectManager pom, PrintWriter log_writer)
       throws wt.pom.PersistenceException,
          wt.query.QueryException,
          wt.util.WTPropertyVetoException
    {
       // To use the POM you will need to instantiate an AccessController.
       // This one does no checks.
       wt.pds.AccessControllerAdapter aca = new wt.pds.AccessControllerAdapter();
  
       // perform the work (e.g. query some objects and change them)
       wt.query.QuerySpec qs = new wt.query.QuerySpec(...);
       QueryResult result = pom.query(qs, aca); // notice the required use of aca
       while(result.hasMoreElements())
       {
          ... // do the migration work
       }
  
       // return success
       return true;
    }
 

See Also:

MigratorRunner

Method Summary

boolean

runMigration(Connection windchill_database_connection, PersistentObjectManager pom, PrintWriter log_writer) Run the migration.

Method Detail

runMigration

public boolean runMigration(Connection windchill_database_connection,
                            PersistentObjectManager pom,
                            PrintWriter log_writer)
                     throws Throwable

Run the migration.

Migrators should log all output to the given PrintWriter. This is the log that is created by RunMigrators. It is an autoflush writer.

Migrators should return true if they successfully completed migration and false otherwise. It is the migrator's responsibility to log failure reasons to the log.

Migrators should not concern themselves with committing the work on the connection. The MigratorRunner will commit the connection work after running each Migrator.

Parameters:

windchill_database_connection - an open connection to the Windchill database

pom - a persistent object manager against the Windchill database

log_writer - an autoflush printwriter for logging any and all output

Throws:

Throwable - declared so that migrators can let exceptions contibuting to failure pass out of the method. The migrator runner will handle these by logging them.