Share via

ReliableCollectionsActorStateProvider Class

  • Reference
Package:
microsoft.servicefabric.actors.runtime

public class ReliableCollectionsActorStateProvider implements ActorStateProvider

Constructor Summary

Constructor Description
ReliableCollectionsActorStateProvider()
ReliableCollectionsActorStateProvider(ReliableStateManagerConfiguration stateManagerConfig)
ReliableCollectionsActorStateProvider(ReliableStateManagerConfiguration stateManagerConfig, int actorStateMapCount, int reminderMapCount)

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<?> actorActivatedAsync(ActorId actorId, CancellationToken cancellationToken)

This method is invoked as part of the activation process of the actor with the specified Id.
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.

CompletableFuture<Boolean> containsStateAsync(ActorId actorId, String stateName, CancellationToken cancellationToken)

Checks whether actor state provider contains an actor state with specified state name.
CompletableFuture<?> deleteReminderAsync(ActorId actorId, String reminderName, CancellationToken cancellationToken)

Deletes the specified actor reminder if it exists.
CompletableFuture<?> deleteRemindersAsync(Map<ActorId, Collection<String>> reminderNames, CancellationToken cancellationToken)

Deletes the specified set of reminders
CompletableFuture<List<String>> enumerateStateNamesAsync(ActorId actorId, CancellationToken cancellationToken)

Creates an enumerable of all the state names associated with specified actor.

Remarks:The enumerator returned from actor state provider is safe to use concurrently with reads and writes to the state provider. It represents a snapshot consistent view of the state provider.

CompletableFuture<PagedResult<ActorId>> getActorsAsync(int numItemsToReturn, ContinuationToken continuationToken, CancellationToken cancellationToken)

Gets ActorIds from the State Provider.

Remarks: The

void initialize(ActorTypeInformation actorTypeInformation)

Initializes the actor state provider with type information of the actor type associated with it.
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<ActorReminderCollection> loadRemindersAsync(CancellationToken cancellationToken)

Loads all the reminders contained in the actor state provider.
<T> CompletableFuture<T> loadStateAsync(ActorId actorId, String stateName, CancellationToken cancellationToken)

Loads the actor state associated with the specified state name.
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<?> reminderCallbackCompletedAsync(ActorId actorId, ActorReminder reminder, CancellationToken cancellationToken)

Invoked when a reminder fires and finishes executing its callback receiveReminderAsync(String reminderName, byte[] context, Duration timeSpan, Duration period) successfully

CompletableFuture<?> removeActorAsync(ActorId actorId, CancellationToken cancellationToken)

Removes all the existing states and reminders associated with specified actor atomically.
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
CompletableFuture<?> saveReminderAsync(ActorId actorId, ActorReminder reminder, CancellationToken cancellationToken)

Saves the specified actor reminder. If an actor reminder with given name does not exist, it adds the actor reminder otherwise existing actor reminder with same name is updated.
CompletableFuture<?> saveStateAsync(ActorId actorId, List<ActorStateChange> stateChanges, CancellationToken cancellationToken)

Saves the specified set of actor state changes atomically.

Remarks: The collection of state changes should contain only one item for a given state name. The save operation will fail on trying to add an actor state which already exists or update/remove an actor state which does not exist.

void setOnDataLossCallback(Function<CancellationToken, CompletableFuture<Boolean>> onDataLossAsync)

Function called during suspected data-loss

Inherited Members

microsoft.servicefabric.actors.runtime.ActorStateProviderInternal.currentReplicaRole() microsoft.servicefabric.actors.runtime.ActorStateProviderInternal.traceId() microsoft.servicefabric.actors.runtime.ActorStateProviderInternal.traceType() microsoft.servicefabric.actors.runtime.ActorStateProviderInternal.transientErrorRetryDelay()

Constructor Details

ReliableCollectionsActorStateProvider

public ReliableCollectionsActorStateProvider()

ReliableCollectionsActorStateProvider

public ReliableCollectionsActorStateProvider(ReliableStateManagerConfiguration stateManagerConfig)

Parameters:

stateManagerConfig

ReliableCollectionsActorStateProvider

public ReliableCollectionsActorStateProvider(ReliableStateManagerConfiguration stateManagerConfig, int actorStateMapCount, int reminderMapCount)

Parameters:

stateManagerConfig
actorStateMapCount
reminderMapCount

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.

Overrides:

ReliableCollectionsActorStateProvider.abort()

actorActivatedAsync

public CompletableFuture actorActivatedAsync(ActorId actorId, CancellationToken cancellationToken)

This method is invoked as part of the activation process of the actor with the specified Id.

Overrides:

ReliableCollectionsActorStateProvider.actorActivatedAsync(ActorId actorId, CancellationToken cancellationToken)

Parameters:

actorId - ID of the actor that is activated.
cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous Actor activation notification processing.

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.

Overrides:

ReliableCollectionsActorStateProvider.backupAsync(BackupOption option, Duration timeout, CancellationToken cancellationToken, BiFunction<BackupInfo, CancellationToken, CompletableFuture<Boolean>> backupCallback)

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.

Overrides:

ReliableCollectionsActorStateProvider.backupAsync(BiFunction<BackupInfo, CancellationToken, CompletableFuture<Boolean>> backupCallback)

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.

Overrides:

ReliableCollectionsActorStateProvider.changeRoleAsync(ReplicaRole newRole, CancellationToken cancellationToken)

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.

Overrides:

ReliableCollectionsActorStateProvider.closeAsync(CancellationToken cancellationToken)

Parameters:

cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

Task that represents the asynchronous close operation.

containsStateAsync

public CompletableFuture containsStateAsync(ActorId actorId, String stateName, CancellationToken cancellationToken)

Checks whether actor state provider contains an actor state with specified state name.

Overrides:

ReliableCollectionsActorStateProvider.containsStateAsync(ActorId actorId, String stateName, CancellationToken cancellationToken)

Parameters:

actorId - ID of the actor for which to check state existence.
stateName - Name of the actor state to check for existence.
cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous check operation. The value of TResult parameter is true if state with specified name exists otherwise false.

deleteReminderAsync

public CompletableFuture deleteReminderAsync(ActorId actorId, String reminderName, CancellationToken cancellationToken)

Deletes the specified actor reminder if it exists.

Overrides:

ReliableCollectionsActorStateProvider.deleteReminderAsync(ActorId actorId, String reminderName, CancellationToken cancellationToken)

Parameters:

actorId - ID of the actor for which to delete the reminder.
reminderName - Name of the reminder to delete.
cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous delete operation.

deleteRemindersAsync

public CompletableFuture deleteRemindersAsync(Map> reminderNames, CancellationToken cancellationToken)

Deletes the specified set of reminders

Overrides:

ReliableCollectionsActorStateProvider.deleteRemindersAsync(Map<ActorId, Collection<String>> reminderNames, CancellationToken cancellationToken)

Parameters:

reminderNames - The set of reminders to delete
cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous delete operation.

enumerateStateNamesAsync

public CompletableFuture> enumerateStateNamesAsync(ActorId actorId, CancellationToken cancellationToken)

Creates an enumerable of all the state names associated with specified actor.

Remarks:The enumerator returned from actor state provider is safe to use concurrently with reads and writes to the state provider. It represents a snapshot consistent view of the state provider.

Overrides:

ReliableCollectionsActorStateProvider.enumerateStateNamesAsync(ActorId actorId, CancellationToken cancellationToken)

Parameters:

actorId - ID of the actor for which to create enumerable.
cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous enumeration operation. The value of TResult parameter is an enumerable of all state names associated with specified actor.

getActorsAsync

public CompletableFuture> getActorsAsync(int numItemsToReturn, ContinuationToken continuationToken, CancellationToken cancellationToken)

Gets ActorIds from the State Provider.

Remarks: The

Overrides:

ReliableCollectionsActorStateProvider.getActorsAsync(int numItemsToReturn, ContinuationToken continuationToken, CancellationToken cancellationToken)

Parameters:

numItemsToReturn - Number of items requested to be returned.
continuationToken - A continuation token to start querying the results from. A null value of continuation token means start returning values form the beginning.
cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous operation of call to server.

initialize

public void initialize(ActorTypeInformation actorTypeInformation)

Initializes the actor state provider with type information of the actor type associated with it.

Overrides:

ReliableCollectionsActorStateProvider.initialize(ActorTypeInformation actorTypeInformation)

Parameters:

actorTypeInformation - Type information of the actor class

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.

Overrides:

ReliableCollectionsActorStateProvider.initialize(StatefulServiceInitializationParameters initializationParameters)

Parameters:

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

loadRemindersAsync

public CompletableFuture loadRemindersAsync(CancellationToken cancellationToken)

Loads all the reminders contained in the actor state provider.

Overrides:

ReliableCollectionsActorStateProvider.loadRemindersAsync(CancellationToken cancellationToken)

Parameters:

cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous load operation. The value of TResult parameter is a collection of all actor reminders contained in the actor state provider.

loadStateAsync

public CompletableFuture loadStateAsync(ActorId actorId, String stateName, CancellationToken cancellationToken)

Loads the actor state associated with the specified state name.

Overrides:

ReliableCollectionsActorStateProvider.loadStateAsync(ActorId actorId, String stateName, CancellationToken cancellationToken)

Parameters:

actorId - ID of the actor for which to load the state.
stateName - Name of the actor state to load.
cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous load operation. The value of TResult parameter contains value of actor state associated with given state name.

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.

Overrides:

ReliableCollectionsActorStateProvider.openAsync(ReplicaOpenMode openMode, StatefulServicePartition partition, CancellationToken cancellationToken)

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.

reminderCallbackCompletedAsync

public CompletableFuture reminderCallbackCompletedAsync(ActorId actorId, ActorReminder reminder, CancellationToken cancellationToken)

Invoked when a reminder fires and finishes executing its callback receiveReminderAsync(String reminderName, byte[] context, Duration timeSpan, Duration period) successfully

Overrides:

ReliableCollectionsActorStateProvider.reminderCallbackCompletedAsync(ActorId actorId, ActorReminder reminder, CancellationToken cancellationToken)

Parameters:

actorId - ID of the actor which own reminder
reminder - Actor reminder that completed successfully.
cancellationToken - The token to monitor for cancellation requests.

Returns:

A task that represents the asynchronous reminder callback completed notification processing.

removeActorAsync

public CompletableFuture removeActorAsync(ActorId actorId, CancellationToken cancellationToken)

Removes all the existing states and reminders associated with specified actor atomically.

Overrides:

ReliableCollectionsActorStateProvider.removeActorAsync(ActorId actorId, CancellationToken cancellationToken)

Parameters:

actorId - ID of the actor for which to remove state.
cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous remove operation.

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.

Overrides:

ReliableCollectionsActorStateProvider.restoreAsync(String backupFolderPath)

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

Overrides:

ReliableCollectionsActorStateProvider.restoreAsync(String backupFolderPath, RestorePolicy restorePolicy, Duration timeout, CancellationToken cancellationToken)

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.

saveReminderAsync

public CompletableFuture saveReminderAsync(ActorId actorId, ActorReminder reminder, CancellationToken cancellationToken)

Saves the specified actor reminder. If an actor reminder with given name does not exist, it adds the actor reminder otherwise existing actor reminder with same name is updated.

Overrides:

ReliableCollectionsActorStateProvider.saveReminderAsync(ActorId actorId, ActorReminder reminder, CancellationToken cancellationToken)

Parameters:

actorId - ID of the actor for which to save the reminder.
reminder - Actor reminder to save.
cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous save operation.

saveStateAsync

public CompletableFuture saveStateAsync(ActorId actorId, List stateChanges, CancellationToken cancellationToken)

Saves the specified set of actor state changes atomically.

Remarks: The collection of state changes should contain only one item for a given state name. The save operation will fail on trying to add an actor state which already exists or update/remove an actor state which does not exist.

Overrides:

ReliableCollectionsActorStateProvider.saveStateAsync(ActorId actorId, List<ActorStateChange> stateChanges, CancellationToken cancellationToken)

Parameters:

actorId - ID of the actor for which to save the state changes.
stateChanges - Collection of state changes to save.
cancellationToken -

CancellationToken object to indicate the cancellation status of the operation.

Returns:

A task that represents the asynchronous save operation.

setOnDataLossCallback

public void setOnDataLossCallback(Function> onDataLossAsync)

Function called during suspected data-loss

Overrides:

ReliableCollectionsActorStateProvider.setOnDataLossCallback(Function<CancellationToken, CompletableFuture<Boolean>> onDataLossAsync)

Parameters:

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

Applies to