Projects Asteroid Docs SnapshotCoordinator

Snapshots

Type: public class SnapshotCoordinator implements

The SnapshotCoordinator is used to overcome some dangerous behavior when using Saved Game API (aka Snapshots). The problem is caused by the not having way to prevent having the same file opened multiple overlapping times. Also there is no way to stop the incorrect reusing of the Snapshot contained in the OpenSnapshotResult object. It should be used once to write or be closed. Multiple commits using the same snapshot will result in unrecoverable conflicts.

This class is used to encapsulate the access to the Snapshots API and enforce these semantics of exclusive file access and one-time committing of metadata.

How to use this class

This class can be used as a drop-in replacement for Games.Snapshots. If the usage of the API is inconsistent with enforced rules (any file can be open only once before closing it, and snapshot data can only be committed once per open), then an IllegalStateException is thrown.

NOTE:The one exception to the drop-in replacement is that each call that returns a PendingResult, that PendingResult MUST be processed by setting the ResultCallback or bycalling await(). This is important to make sure the open/closed book-keeping is accurate.

To make it easier to use Snapshots correctly, you should call SnapshotCoordinator.waitForClosed() to obtain a PendingResult which will be resolved when the file is ready to be opened again.

getInstance

Type: public static SnapshotCoordinator

Singleton for coordinating the Snapshots API. This is important since we need to coordinate all operations through the same instance in order to detect usages that would cause data corruption.

Returned Value: the singleton

isAlreadyOpen

Type: public synchronized boolean

Returns true if the named file is already opened. This is a synchronized operation since it is highly likely that multiple threads are involved via AsyncTasks.

Parameter Name Description
filename - the filename to check

Returned Value: true if opened.

isAlreadyClosing

Type: public synchronized boolean

Returns true if the named file is in the process of closing. This is a synchronized operation since it is highly likely that multiple threads are involved via AsyncTasks.

Parameter Name Description
filename - the filename to check

Returned Value: true if closing.

setIsClosing

Type: private synchronized void

Records the fact that the named file is closing (which also includes committing the data). This is a synchronized operation since it is highly likely that multiple threads are involved via AsyncTasks.

Parameter Name Description
filename - the filename of interest.

setClosed

Type: private synchronized void

Records the fact that the named file is closed. This is a synchronized operation since it is highly likely that multiple threads are involved via AsyncTasks.

Parameter Name Description
filename - the filename of interest.

setIsOpening

Type: private synchronized void

Records the fact that the named file is opening. This is a synchronized operation since it is highly likely that multiple threads are involved via AsyncTasks.

Parameter Name Description
filename - the filename of interest.

waitForClosed

Type: public PendingResult<Result>

Blocking wait for the given file to be closed. Returns immediately if the file is not open.

Parameter Name Description
filename - the file name in question.

ResultListener

Type: private interface

Interface to be triggered when a PendingResult is completed.

PendingResult

Type: private class CoordinatedPendingResult<T extends Result> extends

Wrapper of PendingResult so the coordinator class is notified when an operation completes.

Parameter Name Description

doInBackground

Type: @Override protected Void

Override this method to perform a computation on a background thread. The specified parameters are the parameters passed to by the caller of this task.

This method can call to publish updates on the UI thread.

Parameter Name Description
params The parameters of the task.

Returned Value: A result, defined by the subclass of this task.

Reference: #onPreExecute()

#onPostExecute

#publishProgress

doInBackground

Type: @Override protected Void

Override this method to perform a computation on a background thread. The specified parameters are the parameters passed to by the caller of this task.

This method can call to publish updates on the UI thread.

Parameter Name Description
params The parameters of the task.

Returned Value: A result, defined by the subclass of this task.

Reference: #onPreExecute()

#onPostExecute

#publishProgress