Package 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:

  • Field Details

    • SUPPORTED_ARCHIVE_VERSIONS

      static final Set<Integer> SUPPORTED_ARCHIVE_VERSIONS
      Set of archive versions that are supported by this version of the product.

  • Method Details

    • 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