public interface

Importer

com.atlassian.bitbucket.migration.Importer

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.

Public Methods

public void finalizeRepositoryImport (ImportContext context, Repository repository)

A callback to indicate a repository and any of its dependent entities have been imported. This callback can be used to perform any post-import processing related to the repository. It is preferable to using onEnd(ImportContext) because it is called frequently over the course of an import and allows for for things such as temporary resources to be cleaned shortly after they are no longer needed (rather than leaving them for the duration of the import) or for indexing or additional processing to be performed at each step rather than left to the end where there may be a greater risk of import failure. This callback also provides the certainty that onEnd(ImportContext) cannot (without an Importer tracking state) that a repository has been imported.

Parameters
context the context for the import
repository the repository that was imported

public void onArchiveEntry (ImportContext importContext, ArchiveSource archiveSource)

Called when an archive entry is encountered within an archive.

Parameters
importContext the ImportContext for this import operation
archiveSource provides access to the data in this entry
Throws
ImportException if importing the archive fails

public void onEnd (ImportContext importContext)

Called after the import has finished.

Parameters
importContext the ImportContext for this import operation

public void onEntry (ImportContext importContext, EntrySource entrySource)

Parameters
importContext the ImportContext for this import operation
entrySource provides access to the data in this entry
Throws
ImportException if importing the entry fails

public void onStart (ImportContext importContext)

Called after the export is started.

Parameters
importContext the ImportContext for this import operation