com.hazelcast.spi

## Interface MigrationAwareService

- All Known Subinterfaces:
    FragmentedMigrationAwareService
  All Known Implementing Classes:
    AtomicLongService, AtomicReferenceService, CountDownLatchService, LockServiceImpl, SemaphoreService

      public interface MigrationAwareService

  An interface that can be implemented by SPI services to get notified of partition changes; for example, if a `MapService` starts moving its data around because partitions are moving to a different machine.

  Service itself must decide to keep or remove its data for specific partition according to number of backups it's willing to keep and `PartitionMigrationEvent` parameters; partitionId, migration-endpoint, current replica index and new replica index.

  - Migration endpoint shows which endpoint this member is; either `SOURCE` or `DESTINATION`
  - Current replica index denotes the replica index which is currently owned by this member before migration.
  - New replica index denotes the replica index which will be owned by this member after migration.

  On migration source, partition replica will be either removed completely or shifted down to a higher indexed replica. During commit, service should remove either all or some part of its data in this partition and run any other action needed. A sample commit on source will look like;

       public void commitMigration(PartitionMigrationEvent event) {
           if (event.getMigrationEndpoint() == MigrationEndpoint.SOURCE) {
               if (event.getNewReplicaIndex() == -1 || event.getNewReplicaIndex() > configuredBackupCount) {
                   // remove data...
               }
           }
           // run any other task needed
       }

  During rollback, source usually doesn't expected to perform any task. But service implementation may need to execute custom tasks.

  On migration destination, either a fresh partition replica will be received or current replica will be shifted up to a lower indexed replica. During rollback, service should remove either all or some part of its data in this partition and run any other action needed. A sample rollback on destination will look like;

       public void rollbackMigration(PartitionMigrationEvent event) {
            if (event.getMigrationEndpoint() == MigrationEndpoint.DESTINATION) {
                if (event.getCurrentReplicaIndex() == -1 || event.getCurrentReplicaIndex() > configuredBackupCount) {
                    // remove data...
                }
            }
           // run any other task needed
       }

  During commit, destination usually doesn't expected to perform any task. But service implementation may need to execute custom tasks.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `beforeMigration(PartitionMigrationEvent event)` Called before migration process starts, on both source and destination members.
    `void` | `commitMigration(PartitionMigrationEvent event)` Commits the migration process for this service, on both source and destination members.
    `Operation` | `prepareReplicationOperation(PartitionReplicationEvent event)` Returns an operation to replicate service data and/or state for a specific partition replica on another cluster member.
    `void` | `rollbackMigration(PartitionMigrationEvent event)` Rollback the migration process for this service, on both source and destination members.

- - ### Method Detail

    - #### prepareReplicationOperation

          Operation prepareReplicationOperation(PartitionReplicationEvent event)

      Returns an operation to replicate service data and/or state for a specific partition replica on another cluster member.

      This method will be called on source member whenever partitioning system requires to copy/replicate a partition replica. Returned operation will be executed on destination member. If operation fails by throwing exception, migration process will fail and will be rolled back.

      Returning null is allowed and means service does not have anything to replicate.

      Parameters:
        `event` - replication
      Returns:
        replication operation or null if nothing will be replicated

    - #### beforeMigration

          void beforeMigration(PartitionMigrationEvent event)

      Called before migration process starts, on both source and destination members.

      Service can take actions required before migration. Migration process will block until this method returns. If this method fails by throwing an exception, migration process for specific partition will fail and will be rolled back.

      Parameters:
        `event` - migration event

    - #### commitMigration

          void commitMigration(PartitionMigrationEvent event)

      Commits the migration process for this service, on both source and destination members. This method will be called after all replication operations are executed successfully on destination and master member receives success response from all participants.

      Commit is not expected to fail at this point, all exceptions will be suppressed and logged. Implementations of this method must be thread safe as this method may be called concurrently for different migrations on different partitions.

      Parameters:
        `event` - migration event

    - #### rollbackMigration

          void rollbackMigration(PartitionMigrationEvent event)

      Rollback the migration process for this service, on both source and destination members. This method will be called when migration process fails at any moment. Reasons for failure may be an exception thrown on any migration step or failure(s) of any of the migration participants; either master or source or destination.

      Rollback is not expected to fail at this point, all exceptions will be suppressed and logged. Implementations of this method must be thread safe as this method may be called concurrently for different migrations on different partitions.

      Parameters:
        `event` - migration event

Copyright © 2020. All rights reserved.