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.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
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.
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.
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. |
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. |
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. |
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. |
Type: private
interface
Interface to be triggered when a PendingResult is completed.
Type: private
class
CoordinatedPendingResult<T
extends
Result>
extends
Wrapper of PendingResult so the coordinator class is notified when an operation completes.
Parameter Name | Description |
---|---|
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
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