com.plumtree.server
Interface IPTMigrationManager

public interface IPTMigrationManager

This interface manages the Import and Export of migration packages of Plumtree objects into/out of a system. It also provides methods used by the UI to perform various queries related to migration.

Version:

2.0

Author:

Arvind Seshan

Method Summary

void	BulkSetMigratedStatusByUUID(java.lang.Object[] iaUUIDs) Sets the status of the objects to MIGRATED.
void	BulkSetMigrationStatus(int nClassID, int[] iaObjectIDs, int nMigrationStatus, java.lang.String strMigrationComment) Sets the migration status of the specified objects to have the passed-in migration status.
void	CancelImport() Cancel PerformImport, an in-progress migration import.
boolean	CheckObjectCreationRights() Checks whether or not the calling user has sufficient activity rights to create all objects contained in the package.
IPTMigrationElement	CreateEmptyMigrationElement() Creates an empty IPTMigrationElement.
void	EndExport() Writes and closes the migration package file.
void	EndImport() Closes the migration package currently open for import.
IPTMigrationElement	ExportObject(int nClassID, int nObjectID, com.plumtree.openfoundation.util.IXPPropertyBag pMigrationConfigBag) Exports a single object into an IPTMigrationElement.
java.lang.String	GenerateNewUUID() Generates a new Universally Unique Identifier (UUID).
com.plumtree.openfoundation.util.XPHashtable	GetMWSRemoteData() Retrieve all MWS REMOTEDATA elements.
int	GetObjectClassIndex(int nClassID) Returns the index in the PT_MIGRATION_CLASSES.SUPPORTED_CLASSES array, given a classID.
int	GetObjectCount(int nClassID) Returns the count of objects of the specified classID in the currently loaded migration package.
java.lang.String	GetPackageSourcePortalUUID() Returns the source portal UUID where the currently loaded migration package was created.
java.lang.String	GetPackageSourcePortalVersion() Returns the portal version of the portal on which the currently loaded migration package was created.
IPTMigrationProvider	GetProvider(int nWebServiceID) Creates and initializes an IPTMigrationProvider based on the web service ID.
void	ImportMigrationWebServices() Imports all items in the MWSDataArray.
IPTMigratable	InflateObjectForImport(IPTMigrationElement pMigrationElement, com.plumtree.openfoundation.util.IXPPropertyBag pMigrationConfigBag, boolean bResolveObject) Populates an in-memory instance of an object using the passed in IPTMigrationElement.
void	InitializeForExport(java.lang.String strMigrationPackagePath) Initializes the migration manager for export and opens an empty migration package at the specified file system path.
void	InitializeForImport(byte[] _barMigrationPackage) Initializes the migration manager for import.
void	InitializeForImport(java.lang.String strMigrationPackagePath) Initializes the migration manager for import.
java.lang.String	LookupMappingInProfile(java.lang.String strSourcePortalUUID, java.lang.String strSourceUUID) Retrieves a migration mapping from the database, if it exists.
boolean	ObjectExistsInPackage(java.lang.String strUUID) Checks whether or not the object with the specified UUID exists in the currently loaded migration package.
boolean	ObjectExistsInSystem(IPTMigrationElement ptME) Checks whether or not the object serialized in the specified IPTMigrationElement already exists in the portal system.
java.lang.String	ObjectIDToUUID(int nClassID, int nObjectID) Looks up an object's UUID based on its class ID and object ID
void	PerformImport(com.plumtree.openfoundation.util.XPArrayList[] _xparObjsToMigrate, boolean _bCreateNewObjectInstances, boolean _bImportACLs, boolean _bOverwriteRemoteServers, boolean _bRememberDependencySettings) Performs the actual import of objects passed in as arguments.
void	PurgeMigrationProfile(java.lang.String strSourcePortalUUID) Clears all migration mappings associated with the specified portal UUID from the database.
IPTQueryResult	QueryMigrationHistory(int nClassID, int nObjectID) Queries the migration history for a specified object.
int	QueryMigrationStatus(int nClassID, int nObjectID) Queries migration status for a specified object.
IPTQueryResult	QueryObjectsByStatus(int nClassID, int nStatus, int nSkipRows, int nMaxRows, java.lang.Object[][] arQueryFilter) This function returns a QueryResult with PT_PROPID_NAME, PT_PROPID_DESCRIPTION, PT_PROPID_ISLOCALIZED, PT_PROPID_CLASSID, PT_PROPID_OBJECTID, PT_PROPID_UUID, PT_PROPID_MIGRATION_DATE, and PT_PROPID_MIGRATION_COMMENT for all objects with the passed in values nClassID and nStatus.
IPTQueryResult	QueryObjectsByStatusCount(int nStatus, java.lang.Object[][] arQueryFilter) This function returns a QueryResult with PT_PROPID_NAME, PT_PROPID_DESCRIPTION, PT_PROPID_ISLOCALIZED, PT_PROPID_CLASSID, PT_PROPID_OBJECTID, PT_PROPID_UUID, PT_PROPID_MIGRATION_DATE, and PT_PROPID_MIGRATION_COMMENT for all objects with the passed in value of nStatus.
IPTQueryResult	QueryStatusForMigrationRequestor(int nClassID, int nSkipRows, int nMaxRows) Queries migration status of all objects for which the calling user requested migration.
IPTQueryResult	QueryStatusForMigrationRequestorCount() Queries the count of all objects for which the calling user requested migration, grouped by classID.
java.lang.String	ReadUserDataItemFromPackage(java.lang.String strName) Reads a user-specified metadata item from the currently loaded migration package.
int	ResolveObject(IPTMigrationElement spME, boolean bResolveObject) Resolves the IPTMigrationElement and returns its object ID.
java.lang.String[]	RetrieveAllUserDataNames() Retrieves an array of all user-specified metadata names.
IPTMigrationElement	RetrieveObjectFromImportPackage(int nIndex, int nClassID) Retrieves a single IPTMigrationElement from the migration package.
void	StoreMappingInProfile(java.lang.String strSourcePortalUUID, java.lang.String strSourceUUID, java.lang.String strMappedUUID) Stores a migration mapping in the database.
void	StoreObjectInExportPackage(IPTMigrationElement ptME) Stores an IPTMigrationElement into the migration package.
void	UpdateHistory(IPTMigrationElement pMigrationElement) Adds a history item to the migration history for the specified object.
java.lang.Object[]	UUIDToObjectID(java.lang.String strUUID) Converts a UUID to its (classID, objectID) equivalent on the local system, if it exists.
void	WriteMWSDataItemToPackage(int intWSID, java.lang.String strValue) Writes a Migration Web Service item to the migration package.
void	WriteUserDataItemToPackage(java.lang.String strName, java.lang.String strValue) Writes a user-specified metadata item to the migration package.

Method Detail

QueryObjectsByStatus

IPTQueryResult QueryObjectsByStatus(int nClassID,
                                    int nStatus,
                                    int nSkipRows,
                                    int nMaxRows,
                                    java.lang.Object[][] arQueryFilter)

This function returns a QueryResult with PT_PROPID_NAME, PT_PROPID_DESCRIPTION, PT_PROPID_ISLOCALIZED, PT_PROPID_CLASSID, PT_PROPID_OBJECTID, PT_PROPID_UUID, PT_PROPID_MIGRATION_DATE, and PT_PROPID_MIGRATION_COMMENT for all objects with the passed in values nClassID and nStatus. Used by the UI, requires admin access.

Parameters:

nClassID - the class of interest, from PT_CLASSIDS

nStatus - the status of interest, from PT_MIGRATION_STATUS_TYPES

nSkipRows - number of rows to skip at the beginning, or 0 for none

nMaxRows - maximum number of rows to return, or -1 for all

arQueryFilter - is a 2D array with 3 columns. The first column holds the property id, from PT_PROPIDS. The second column holds the operator, from PT_FILTEROPS. The third column holds the value to be matched.

Returns:

IPTQueryResult containing the records of interest

See Also:

PT_CLASSIDS, PT_MIGRATION_STATUS_TYPES, PT_PROPIDS, PT_ORDERBY_SETTINGS

GetObjectCount

int GetObjectCount(int nClassID)

Returns the count of objects of the specified classID in the currently loaded migration package.

Parameters:

nClassID - - The classID of objects to count.

Returns:

The count of objects.

PurgeMigrationProfile

void PurgeMigrationProfile(java.lang.String strSourcePortalUUID)

Clears all migration mappings associated with the specified portal UUID from the database.

Parameters:

strSourcePortalUUID - - The portal UUID to clear mappings for.

ObjectExistsInSystem

boolean ObjectExistsInSystem(IPTMigrationElement ptME)

Checks whether or not the object serialized in the specified IPTMigrationElement already exists in the portal system.

Parameters:

ptME - - The IPTMigrationElement being imported.

Returns:

true if the object already exists, false otherwise.

ObjectExistsInPackage

boolean ObjectExistsInPackage(java.lang.String strUUID)

Checks whether or not the object with the specified UUID exists in the currently loaded migration package.

Parameters:

strUUID - - The UUID to check cor.

Returns:

true if the object exists in the package, false otherwise.

CreateEmptyMigrationElement

IPTMigrationElement CreateEmptyMigrationElement()

Creates an empty IPTMigrationElement.

Returns:

IPTMigrationElement

UUIDToObjectID

java.lang.Object[] UUIDToObjectID(java.lang.String strUUID)

Converts a UUID to its (classID, objectID) equivalent on the local system, if it exists.

Parameters:

strUUID - - The UUID to look up.

Returns:

A 1-D array containing the objectID and classID, can be indexed using values from the PT_MIGRATION_OBJECT_COLS enumeration.

QueryObjectsByStatusCount

IPTQueryResult QueryObjectsByStatusCount(int nStatus,
                                         java.lang.Object[][] arQueryFilter)

This function returns a QueryResult with PT_PROPID_NAME, PT_PROPID_DESCRIPTION, PT_PROPID_ISLOCALIZED, PT_PROPID_CLASSID, PT_PROPID_OBJECTID, PT_PROPID_UUID, PT_PROPID_MIGRATION_DATE, and PT_PROPID_MIGRATION_COMMENT for all objects with the passed in value of nStatus. Used by the UI.

Parameters:

nStatus - the status of interest, from PT_MIGRATION_STATUS_TYPES

arQueryFilter - is a 2D array with 3 columns. The first column holds the property id, from PT_PROPIDS. The second column holds the operator, from PT_FILTEROPS. The third column holds the value to be matched.

Returns:

IPTQueryResult containing the records of interest

See Also:

PT_MIGRATION_STATUS_TYPES, PT_PROPIDS, PT_ORDERBY_SETTINGS

InitializeForExport

void InitializeForExport(java.lang.String strMigrationPackagePath)

Initializes the migration manager for export and opens an empty migration package at the specified file system path.

Parameters:

strMigrationPackagePath - - The full path to the migration package file.

StoreObjectInExportPackage

void StoreObjectInExportPackage(IPTMigrationElement ptME)

Stores an IPTMigrationElement into the migration package. For use on export only.

Parameters:

ptME - The IPTMigrationElement to store.

EndExport

void EndExport()

Writes and closes the migration package file. This method should be called once all objects have been added to the migration package; otherwise the file will not be written. For use on export only.

ExportObject

IPTMigrationElement ExportObject(int nClassID,
                                 int nObjectID,
                                 com.plumtree.openfoundation.util.IXPPropertyBag pMigrationConfigBag)

Exports a single object into an IPTMigrationElement. For use on export only.

Parameters:

nClassID - - The classID of the object to export.

nObjectID - - The objectID of the object to export.

pMigrationConfigBag - - A configuration propertybag containing parameters that specify whether or not to include ACL information and EOD information, for example, in the serialized IPTMigrationElement.

Returns:

IPTMigrationElement representing the object.

InitializeForImport

void InitializeForImport(java.lang.String strMigrationPackagePath)

Initializes the migration manager for import. Loads the package at the specified file system path.

Parameters:

strMigrationPackagePath - - The full path to the package to be imported.

InitializeForImport

void InitializeForImport(byte[] _barMigrationPackage)

Initializes the migration manager for import. Loads the package with the given byte array XML representation.

Parameters:

byte[] - byte array of XML representation

StoreMappingInProfile

void StoreMappingInProfile(java.lang.String strSourcePortalUUID,
                           java.lang.String strSourceUUID,
                           java.lang.String strMappedUUID)

Stores a migration mapping in the database.

Parameters:

strSourcePortalUUID - - The UUID of the portal where the source object came from.

strSourceUUID - - The UUID of the object to be mapped.

strMappedUUID - - The UUID of the replacement object on the local system.

LookupMappingInProfile

java.lang.String LookupMappingInProfile(java.lang.String strSourcePortalUUID,
                                        java.lang.String strSourceUUID)

Retrieves a migration mapping from the database, if it exists.

Parameters:

strSourcePortalUUID - - The UUID of the portal where the source object came from.

strSourceUUID - - The UUID of the object to be mapped.

Returns:

The UUID of the replacement object on the local system.

RetrieveObjectFromImportPackage

IPTMigrationElement RetrieveObjectFromImportPackage(int nIndex,
                                                    int nClassID)

Retrieves a single IPTMigrationElement from the migration package. For use on import only.

Parameters:

nIndex - - The index of the object in the array. The upper bound for this is obtained using the GetObjectCount(nClassID) call.

nClassID - - The classID of the object.

Returns:

IPTMigrationElement

EndImport

void EndImport()

Closes the migration package currently open for import. For use on import only.

CheckObjectCreationRights

boolean CheckObjectCreationRights()

Checks whether or not the calling user has sufficient activity rights to create all objects contained in the package.

Returns:

true if the user has all the needed activity rights, false otherwise.

InflateObjectForImport

IPTMigratable InflateObjectForImport(IPTMigrationElement pMigrationElement,
                                     com.plumtree.openfoundation.util.IXPPropertyBag pMigrationConfigBag,
                                     boolean bResolveObject)

Populates an in-memory instance of an object using the passed in IPTMigrationElement. The parameters of this process are controlled by the passed in IXPPropertyBag that containst configuration information.

Parameters:

pMigrationElement - - The IPTMigrationElement to use to populate the object.

pMigrationConfigBag - - The configuration Propertybag.

bResolveObject - - True if the migration manager should attempt to look to see if this object already exists in the database. False if you want a new object to be created (used for Creating New Object Instances. Need to make sure object is assigned a new UUID before passing to this method.).

Returns:

IPTMigratable

GetPackageSourcePortalUUID

java.lang.String GetPackageSourcePortalUUID()

Returns the source portal UUID where the currently loaded migration package was created. For use on import only.

Returns:

The source portal's UUID.

GetPackageSourcePortalVersion

java.lang.String GetPackageSourcePortalVersion()

Returns the portal version of the portal on which the currently loaded migration package was created. For use on import only.

Returns:

The version string

BulkSetMigrationStatus

void BulkSetMigrationStatus(int nClassID,
                            int[] iaObjectIDs,
                            int nMigrationStatus,
                            java.lang.String strMigrationComment)

Sets the migration status of the specified objects to have the passed-in migration status. The permissions on this method are checked as follows: Admins have rights to set any object to any status. Non-admins can set objects to the following access levels given the constraints: PT_MIGRATION_STATUS_NONE - only if the calling user was the last migration requestor, and the current status of the object is *not* PT_MIGRATION_STATUS_APPROVED PT_MIGRATION_STATUS_APPROVAL_REQUESTED - if the calling user has Edit access on the objects being marked for the request PT_MIGRATION_STATUS_APPROVED, PT_MIGRATION_STATUS_DENIED, and PT_MIGRATION_STATUS_MIGRATED can only be set on objects by users with admin access.

Parameters:

nClassID - - ClassID of the objects, from the PT_CLASSIDS enumeration.

iaObjectIDs - - Array of objectIDs of the objects to set migration status for.

nMigrationStatus - - The migration status to set, from the PT_MIGRATION_STATUS_TYPES enumeration.

strMigrationComment - - The migration comment to use for the objects. Ignored when setting status to PT_MIGRATION_STATUS_NONE or PT_MIGRATION_STATUS_MIGRATED.

QueryMigrationStatus

int QueryMigrationStatus(int nClassID,
                         int nObjectID)

Queries migration status for a specified object.

Parameters:

nClassID - - The classID of the object to query, from PT_CLASSIDS.

nObjectID - - The objectID of the object to query.

Returns:

A value from the PT_MIGRATION_STATUS_TYPES enumeration describing the migration status.

QueryMigrationHistory

IPTQueryResult QueryMigrationHistory(int nClassID,
                                     int nObjectID)

Queries the migration history for a specified object.

Parameters:

nClassID - - The classID of the object to query, from PT_CLASSIDS.

nObjectID - - The objectID of the object to query.

Returns:

IPTQueryResult containing PT_PROPID_NAME, PT_PROPID_DESCRIPTION, PT_PROPID_ISLOCALIZED, PT_PROPID_OBJECTID, PT_PROPID_CLASSID, PT_PROPID_UUID, PT_PROPID_MIGRATION_STATUS, PT_PROPID_MIGRATION_COMMENT, PT_PROPID_MIGRATION_DATE, PT_PROPID_MIGRATION_SOURCEPORTALUUID.

See Also:

PT_PROPIDS

UpdateHistory

void UpdateHistory(IPTMigrationElement pMigrationElement)

Adds a history item to the migration history for the specified object.

Parameters:

pMigrationElement - - The migration element containing object metadata and history (migration comment).

QueryStatusForMigrationRequestor

IPTQueryResult QueryStatusForMigrationRequestor(int nClassID,
                                                int nSkipRows,
                                                int nMaxRows)

Queries migration status of all objects for which the calling user requested migration.

Parameters:

nClassID - - The classID of objects to query, from the PT_CLASSIDS enumeration.

nSkipRows - - The number of rows to skip. Pass 0 to start at the beginning.

nMaxRows - - The maximum row index to return, pass in -1 to return all rows.

Returns:

IPTQueryResult with PT_PROPID_NAME, PT_PROPID_DESCRIPTION, PT_PROPID_CLASSID, PT_PROPID_OBJECTID, PT_PROPID_UUID, PT_MIGRATION_STATUS, PT_MIGRATION_DATE, PT_MIGRATION_COMMENT for all objects of the given ClassID for which the calling user is listed as the last Migration Requestor.

QueryStatusForMigrationRequestorCount

IPTQueryResult QueryStatusForMigrationRequestorCount()

Queries the count of all objects for which the calling user requested migration, grouped by classID.

Returns:

IPTQueryResult with PT_PROPID_CLASSID, PT_PROPID_OBJECTCOUNT.

ReadUserDataItemFromPackage

java.lang.String ReadUserDataItemFromPackage(java.lang.String strName)

Reads a user-specified metadata item from the currently loaded migration package. For use on import only.

Parameters:

strName - - The name of the metadata item to retrieve.

Returns:

The associated value.

WriteUserDataItemToPackage

void WriteUserDataItemToPackage(java.lang.String strName,
                                java.lang.String strValue)

Writes a user-specified metadata item to the migration package. For use on export only.

Parameters:

strName - - The name of the metadata item to store.

strValue - - The value to associate.

RetrieveAllUserDataNames

java.lang.String[] RetrieveAllUserDataNames()

Retrieves an array of all user-specified metadata names. The associated values can be retrieved by iterating through the array and calling ReadUserDataItemFromPackage on the desired items.

Returns:

1-D Array of strings.

GenerateNewUUID

java.lang.String GenerateNewUUID()

Generates a new Universally Unique Identifier (UUID).

Returns:

The UUID as a string.

ObjectIDToUUID

java.lang.String ObjectIDToUUID(int nClassID,
                                int nObjectID)

Looks up an object's UUID based on its class ID and object ID

Parameters:

nClassID -

nObjectID -

Returns:

The UUID as a string.

BulkSetMigratedStatusByUUID

void BulkSetMigratedStatusByUUID(java.lang.Object[] iaUUIDs)

Sets the status of the objects to MIGRATED.

Parameters:

iaUUIDs -

GetProvider

IPTMigrationProvider GetProvider(int nWebServiceID)

Creates and initializes an IPTMigrationProvider based on the web service ID.

Parameters:

ptSession -

nWebServiceID -

Returns:

IPTMigrationProvider

WriteMWSDataItemToPackage

void WriteMWSDataItemToPackage(int intWSID,
                               java.lang.String strValue)

Writes a Migration Web Service item to the migration package. For use on export only.

Parameters:

intWSID - Migration Web Service ID

strValue - Package Data returned by finalize() from the MWS SCI Service

ImportMigrationWebServices

void ImportMigrationWebServices()

Imports all items in the MWSDataArray. For use on import only.

PerformImport

void PerformImport(com.plumtree.openfoundation.util.XPArrayList[] _xparObjsToMigrate,
                   boolean _bCreateNewObjectInstances,
                   boolean _bImportACLs,
                   boolean _bOverwriteRemoteServers,
                   boolean _bRememberDependencySettings)

Performs the actual import of objects passed in as arguments.

Parameters:

_xparObjsToMigrate - array of XPArrayLists containing IPTMigrationElements to import, indexed by classID.

_bCreateNewObjectInstances -

_bImportACLs -

_bOverwriteRemoteServers -

_bRememberDependencySettings -

GetObjectClassIndex

int GetObjectClassIndex(int nClassID)

Returns the index in the PT_MIGRATION_CLASSES.SUPPORTED_CLASSES array, given a classID.

Parameters:

nClassID - - The classid to lookup, from PT_CLASSIDS.

Returns:

- The index in the PT_MIGRATION_CLASSES.SUPPORTED_CLASSES array.

ResolveObject

int ResolveObject(IPTMigrationElement spME,
                  boolean bResolveObject)

Resolves the IPTMigrationElement and returns its object ID. Some special-casing for class types, like resolving folders or users.

Parameters:

spME -

Returns:

- Object ID. PT_INTRINSICS.PT_NULL_OBJECTID if not resolvable.

CancelImport

void CancelImport()

Cancel PerformImport, an in-progress migration import. This method should not be used unless PerformImport has been called in a separate thread. This method has no effect if the IPTMigrationManager is not currently importing. This method does not interrupt an in-progress IPTMigratable object import but instead stops before beginning the next object's import. This behavior should prevent corrupt object state. Implementers must guarantee thread safety and should log any exceptions.

GetMWSRemoteData

com.plumtree.openfoundation.util.XPHashtable GetMWSRemoteData()

Retrieve all MWS REMOTEDATA elements. Each String key is the REMOTEDATA element of an MWSDATAARRAY. These UUIDs represent the zip files required for Collaboration or Publisher object import. Each String value is a constant that identifies the MWS by type, either COLLABORATION, PUBLISHER, or UNKNOWN. See PTMigrationConstants for a full list of MWS_REMOTEDATA types. This allows the remote MWS to determine if the zip UUID refers to a Collaboration specific file, for instance.

Returns:

A map of String REMOTEDATA UUIDs as keys to String values representing the type, e.g. COLLABORATION or UNKNOWN. Never returns null.