Class Overview

Data Center Migration Importer SPI

Implement this interface to import data that has been exported by an Exporter.

Migration archives are read and written sequentially. Whenever an entry that was written by a corresponding Exporter is encountered the correct callback on this interface is invoked.

There are two different types of entries:

• File entries

  Used to migrate data that has been generated in memory, for example, JSON data.

• Archive entries

  Used to migrate data that already exists on the file system.

Importers are required to be stateless, as they are essentially singletons. State, which should persist over the whole lifetime of a job, can be stored in getAttributeMap(). This data is kept in memory and care should be taken that memory usage in this attribute map does not grow considerably over time.

References to entities during the import

References to entities, such as repositories or projects, are mapped by their export ID to their local ID in an entity mapping. StandardMigrationEntityTypes define mappings for projects and repositories.
Custom entity types should implement the MigrationEntityType interface.

A common pattern to retrieve the Repository from an export ID is this snippet of code:

Optional<Repository>; repo = context.getEntityMapping(StandardMigrationEntityType.REPOSITORY)
     .getLocalId("export ID")
     .map(repositoryService::getById)
 

where "export ID" is the ID generated by an Exporter using the export entity mapping.

Export IDs should be encoded into the path of an entry whenever possible.

Plugin definition

A plugin has to define a <migration-handler> module in its atlassian-plugin.xml for the migration process to include it. Migration handlers always define a pair of exporters and importers. Only entries added by the corresponding Exporter will be consumed by its Importer.

Example module definition:

<migration-handler key="handler" weight="150">
     <exporter class="org.foo.bar.PluginExporter"/>
     <importer class="org.foo.bar.PluginImporter"/>
 </migration-handler>
 

A migration handler's weight defines the order in which it is called in relation to other migration handlers. A higher weight signifies a dependency on a lower weight handler. All core handlers have a weight lower than 100.

Summary

Public Methods
void	finalizeRepositoryImport(ImportContext context, Repository repository) A callback to indicate a repository and any of its dependent entities have been imported.
void	onArchiveEntry(ImportContext importContext, ArchiveSource archiveSource) Called when an archive entry is encountered within an archive.
void	onEnd(ImportContext importContext) Called after the import has finished.
void	onEntry(ImportContext importContext, EntrySource entrySource)
void	onStart(ImportContext importContext) Called after the export is started.