StateProviderReplica Interface

Package:

microsoft.servicefabric.data

public interface StateProviderReplica

Defines methods a reliable state provider replica must implement for Service Fabric to interact with it.

Method Summary

Modifier and Type	Method and Description
void	abort() Forcefully abort the state provider replica. Remarks:This generally occurs when a permanent fault is detected on the node, or when Service Fabric cannot reliably manage the replica's lifecycle due to internal failures.
CompletableFuture<?>	backupAsync(BackupOption option, Duration timeout, CancellationToken cancellationToken, BiFunction<BackupInfo, CancellationToken, CompletableFuture<Boolean>> backupCallback) Performs a full backup of all reliable state managed by this ReliableStateManager. Remarks: A FULL backup will be performed with a one-hour timeout. Boolean returned by the backupCallback indicate whether the service was able to successfully move the backup folder to an external location. If false is returned, BackupAsync throws UnsupportedOperationException with the relevant message indicating backupCallback returned false. Also, backup will be marked as unsuccessful.
CompletableFuture<?>	backupAsync(BiFunction<BackupInfo, CancellationToken, CompletableFuture<Boolean>> backupCallback) Performs a full backup of all reliable state managed by this ReliableStateManager. Remarks: A FULL backup will be performed with a one-hour timeout. Boolean returned by the backupCallback indicate whether the service was able to successfully move the backup folder to an external location. If false is returned, BackupAsync throws UnsupportedOperationException with the relevant message indicating backupCallback returned false. Also, backup will be marked as unsuccessful.
CompletableFuture<?>	changeRoleAsync(ReplicaRole newRole, CancellationToken cancellationToken) Notify the state provider replica that its role is changing, for example to Primary or Secondary.
CompletableFuture<?>	closeAsync(CancellationToken cancellationToken) Gracefully close the state provider replica. Remarks:This generally occurs when the replica's code is being upgrade, the replica is being moved due to load balancing, or a transient fault is detected.
void	initialize(StatefulServiceInitializationParameters initializationParameters) Initialize the state provider replica using the service initialization information. Remarks:No complex processing should be done during Initialize. Expensive or long-running initialization should be done in OpenAsync.
CompletableFuture<Replicator>	openAsync(ReplicaOpenMode openMode, StatefulServicePartition partition, CancellationToken cancellationToken) Open the state provider replica for use. Remarks:Extended state provider initialization tasks can be started at this time.
CompletableFuture<?>	restoreAsync(String backupFolderPath) Restore a backup taken. Remarks:A safe restore will be performed, meaning the restore will only be completed if the data to restore is ahead of state of the current replica.
CompletableFuture<?>	restoreAsync(String backupFolderPath, RestorePolicy restorePolicy, Duration timeout, CancellationToken cancellationToken) Restore a backup taken
void	setOnDataLossCallback(Function<CancellationToken, CompletableFuture<Boolean>> onDataLossAsync) Function called during suspected data-loss

Method Details

abort

public void abort()

Forcefully abort the state provider replica.

Remarks:This generally occurs when a permanent fault is detected on the node, or when Service Fabric cannot reliably manage the replica's lifecycle due to internal failures.

backupAsync

public CompletableFuture backupAsync(BackupOption option, Duration timeout, CancellationToken cancellationToken, BiFunction> backupCallback)

Performs a full backup of all reliable state managed by this ReliableStateManager.

Remarks: A FULL backup will be performed with a one-hour timeout. Boolean returned by the backupCallback indicate whether the service was able to successfully move the backup folder to an external location. If false is returned, BackupAsync throws UnsupportedOperationException with the relevant message indicating backupCallback returned false. Also, backup will be marked as unsuccessful.

Parameters:

option - The type of backup to perform.

timeout - The timeout for this operation.

cancellationToken - The token to monitor for cancellation requests.

backupCallback - Callback to be called when the backup folder has been created locally and is ready to be moved out of the node

Returns:

Task that represents the asynchronous backup operation.

backupAsync

public CompletableFuture backupAsync(BiFunction> backupCallback)

Performs a full backup of all reliable state managed by this ReliableStateManager.

Remarks: A FULL backup will be performed with a one-hour timeout. Boolean returned by the backupCallback indicate whether the service was able to successfully move the backup folder to an external location. If false is returned, BackupAsync throws UnsupportedOperationException with the relevant message indicating backupCallback returned false. Also, backup will be marked as unsuccessful.

Parameters:

backupCallback - Callback to be called when the backup folder has been created locally and is ready to be moved out of the node

Returns:

Task that represents the asynchronous backup operation.

changeRoleAsync

public CompletableFuture changeRoleAsync(ReplicaRole newRole, CancellationToken cancellationToken)

Notify the state provider replica that its role is changing, for example to Primary or Secondary.

Parameters:

newRole - The new replica role, such as primary or secondary.

cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

Task that represents the asynchronous change role operation.

closeAsync

public CompletableFuture closeAsync(CancellationToken cancellationToken)

Gracefully close the state provider replica.

Remarks:This generally occurs when the replica's code is being upgrade, the replica is being moved due to load balancing, or a transient fault is detected.

Parameters:

cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

Task that represents the asynchronous close operation.

initialize

public void initialize(StatefulServiceInitializationParameters initializationParameters)

Initialize the state provider replica using the service initialization information.

Remarks:No complex processing should be done during Initialize. Expensive or long-running initialization should be done in OpenAsync.

Parameters:

initializationParameters - Service initialization information such as service name, partition id, replica id, and code package information.

openAsync

public CompletableFuture openAsync(ReplicaOpenMode openMode, StatefulServicePartition partition, CancellationToken cancellationToken)

Open the state provider replica for use.

Remarks:Extended state provider initialization tasks can be started at this time.

Parameters:

openMode - Indicates whether this is a new or existing replica.

partition - The partition this replica belongs to.

cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

Task that represents the asynchronous open operation. The result contains the replicator responsible for replicating state between other state provider replicas in the partition.

restoreAsync

public CompletableFuture restoreAsync(String backupFolderPath)

Restore a backup taken.

Remarks:A safe restore will be performed, meaning the restore will only be completed if the data to restore is ahead of state of the current replica.

Parameters:

backupFolderPath - The directory where the replica is to be restored from. This parameter cannot be null, empty or contain just whitespace. UNC paths may also be provided.

Returns:

Task that represents the asynchronous restore operation.

restoreAsync

public CompletableFuture restoreAsync(String backupFolderPath, RestorePolicy restorePolicy, Duration timeout, CancellationToken cancellationToken)

Restore a backup taken

Parameters:

backupFolderPath - The directory where the replica is to be restored from. This parameter cannot be null, empty or contain just whitespace. UNC paths may also be provided.

restorePolicy - The restore policy.

timeout - The timeout for this operation.

cancellationToken - The token to monitor for cancellation requests.

Returns:

Task that represents the asynchronous restore operation.

setOnDataLossCallback

public void setOnDataLossCallback(Function> onDataLossAsync)

Function called during suspected data-loss

Parameters:

onDataLossAsync - TODO. Function called as part of suspected data loss processing. Function takes in CancellationToken and returns a CompletableFuture that represents the asynchronous processing of the event. Returning true, indicates that the replica's state has been restored. False indicates that the replica's state has not been changed.