com.atlassian.bitbucket.migration

Interface Importer

public interface Importer

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 ImportContext.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.

Since:

5.13

See Also:

Exporter, ImportContext, ImportContext.getEntityMapping(MigrationEntityType)

Field Summary

Fields

Modifier and Type	Field and Description
static Set<Integer>	SUPPORTED_ARCHIVE_VERSIONS Set of archive versions that are supported by this version of the product.

Method Summary

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

Field Detail

SUPPORTED_ARCHIVE_VERSIONS

static final Set<Integer> SUPPORTED_ARCHIVE_VERSIONS

Set of archive versions that are supported by this version of the product.

Method Detail

finalizeRepositoryImport

default void finalizeRepositoryImport(@Nonnull
                                      ImportContext context,
                                      @Nonnull
                                      com.atlassian.bitbucket.repository.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

onArchiveEntry

default void onArchiveEntry(@Nonnull
                            ImportContext importContext,
                            @Nonnull
                            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:

com.atlassian.bitbucket.migration.ImportException - if importing the archive fails

onEnd

default void onEnd(@Nonnull
                   ImportContext importContext)

Called after the import has finished.

Parameters:

importContext - the ImportContext for this import operation

onEntry

default void onEntry(@Nonnull
                     ImportContext importContext,
                     @Nonnull
                     EntrySource entrySource)

Parameters:

importContext - the ImportContext for this import operation

entrySource - provides access to the data in this entry

Throws:

com.atlassian.bitbucket.migration.ImportException - if importing the entry fails

onStart

default void onStart(@Nonnull
                     ImportContext importContext)

Called after the export is started.

Parameters:

importContext - the ImportContext for this import operation