com.hazelcast.spi.MigrationAwareService Maven / Gradle / Ivy

/*
 * Copyright (c) 2008-2018, Hazelcast, Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.hazelcast.spi;

/**
 * An interface that can be implemented by SPI services to get notified of partition changes; for example, if a
 * {@link com.hazelcast.map.impl.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 {@code PartitionMigrationEvent} parameters; partitionId, migration-endpoint,
 * current replica index and new replica index.
 * 

 * Migration endpoint shows which endpoint this member is; either {@code SOURCE} or {@code 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.
 */
public interface MigrationAwareService {

    /**
     * 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.
     *
     * @param event replication
     * @return replication operation or null if nothing will be replicated
     */
    Operation prepareReplicationOperation(PartitionReplicationEvent 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.
     *
     * @param event migration event
     */
    void beforeMigration(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.
     *
     * @param event migration event
     */
    void commitMigration(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.
     *
     * @param event migration event
     */
    void rollbackMigration(PartitionMigrationEvent event);
}