public final class

AppStateClient

extends Object
implements GooglePlayServicesClient
java.lang.Object
   ↳ com.google.android.gms.appstate.AppStateClient

Class Overview

Main public API entry point for the AppState client.

Summary

Nested Classes
class AppStateClient.Builder Builder class for AppStateClient. 
Constants
int STATUS_CLIENT_RECONNECT_REQUIRED The AppStateClient is in an inconsistent state and must reconnect to the service to resolve the issue.
int STATUS_DEVELOPER_ERROR The developer has configured something incorrectly with their application.
int STATUS_INTERNAL_ERROR An unspecified error occurred; no more specific information is available.
int STATUS_NETWORK_ERROR_NO_DATA A network error occurred while attempting to retrieve fresh data, and no data was available locally.
int STATUS_NETWORK_ERROR_OPERATION_DEFERRED A network error occurred while attempting to modify data, but the data was successfully modified locally and will be updated on the network the next time the device is able to sync.
int STATUS_NETWORK_ERROR_OPERATION_FAILED A network error occurred while attempting to perform an operation that requires network access.
int STATUS_NETWORK_ERROR_STALE_DATA A network error occurred while attempting to retrieve fresh data, but some locally cached data was available.
int STATUS_OK The operation was successful.
int STATUS_STATE_KEY_LIMIT_EXCEEDED The application already has data in the maximum number of keys and is attempting to create a new one.
int STATUS_STATE_KEY_NOT_FOUND The requested state key was not found.
int STATUS_WRITE_OUT_OF_DATE_VERSION A version conflict was detected.
int STATUS_WRITE_SIZE_EXCEEDED A write request was submitted which contained too much data for the server.
Public Methods
void connect()
Connect to the app state service.
void deleteState(OnStateDeletedListener listener, int stateKey)
Delete the state data for the current app.
void disconnect()
Closes the connection to Google Play services.
int getMaxNumKeys()
Gets the maximum number of keys that an app can store data in simultaneously.
int getMaxStateSize()
Gets the maximum app state size per state key in bytes.
boolean isConnected()
Checks if the client is currently connected to the service, so that requests to other methods will succeed.
boolean isConnecting()
Checks if the client is attempting to connect to the service.
boolean isConnectionCallbacksRegistered(GooglePlayServicesClient.ConnectionCallbacks listener)
Returns true if the specified listener is currently registered to receive connection events.
boolean isConnectionFailedListenerRegistered(GooglePlayServicesClient.OnConnectionFailedListener listener)
Returns true if the specified listener is currently registered to receive connection failed events.
void listStates(OnStateListLoadedListener listener)
Asynchronously lists all the saved states for the current app.
void loadState(OnStateLoadedListener listener, int stateKey)
Asynchronously loads saved state for the current app.
void reconnect()
Closes the current connection to Google Play services and creates a new connection.
void registerConnectionCallbacks(GooglePlayServicesClient.ConnectionCallbacks listener)
Registers a listener to receive connection events from this GooglePlayServicesClient.
void registerConnectionFailedListener(GooglePlayServicesClient.OnConnectionFailedListener listener)
Registers a listener to receive connection failed events from this GooglePlayServicesClient.
void resolveState(OnStateLoadedListener listener, int stateKey, String resolvedVersion, byte[] resolvedData)
Resolve a previously detected conflict in app state data.
void signOut(OnSignOutCompleteListener listener)
Asynchronously signs the current user out.
void signOut()
Asynchronously signs the current user out.
void unregisterConnectionCallbacks(GooglePlayServicesClient.ConnectionCallbacks listener)
Removes a connection listener from this GooglePlayServicesClient.
void unregisterConnectionFailedListener(GooglePlayServicesClient.OnConnectionFailedListener listener)
Removes a connection failed listener from the GooglePlayServicesClient.
void updateState(int stateKey, byte[] data)
Updates app state for the current app.
void updateStateImmediate(OnStateLoadedListener listener, int stateKey, byte[] data)
Updates app state for the current app.
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.google.android.gms.common.GooglePlayServicesClient

Constants

public static final int STATUS_CLIENT_RECONNECT_REQUIRED

The AppStateClient is in an inconsistent state and must reconnect to the service to resolve the issue. Further calls to the service using the current connection are unlikely to succeed.

Constant Value: 2 (0x00000002)

public static final int STATUS_DEVELOPER_ERROR

The developer has configured something incorrectly with their application. This is a hard error, since retrying will not fix this.

Constant Value: 7 (0x00000007)

public static final int STATUS_INTERNAL_ERROR

An unspecified error occurred; no more specific information is available. The device logs may provide additional data.

Constant Value: 1 (0x00000001)

public static final int STATUS_NETWORK_ERROR_NO_DATA

A network error occurred while attempting to retrieve fresh data, and no data was available locally.

Constant Value: 4 (0x00000004)

public static final int STATUS_NETWORK_ERROR_OPERATION_DEFERRED

A network error occurred while attempting to modify data, but the data was successfully modified locally and will be updated on the network the next time the device is able to sync.

Constant Value: 5 (0x00000005)

public static final int STATUS_NETWORK_ERROR_OPERATION_FAILED

A network error occurred while attempting to perform an operation that requires network access. The operation may be retried later.

Constant Value: 6 (0x00000006)

public static final int STATUS_NETWORK_ERROR_STALE_DATA

A network error occurred while attempting to retrieve fresh data, but some locally cached data was available. The data returned may be stale and/or incomplete.

Constant Value: 3 (0x00000003)

public static final int STATUS_OK

The operation was successful.

Constant Value: 0 (0x00000000)

public static final int STATUS_STATE_KEY_LIMIT_EXCEEDED

The application already has data in the maximum number of keys and is attempting to create a new one. This is a hard error. Subsequent writes to this same key will only succeed after some number of keys have been deleted.

Constant Value: 2003 (0x000007d3)

public static final int STATUS_STATE_KEY_NOT_FOUND

The requested state key was not found. This means that the server did not have data for us when we successfully made a network request.

Constant Value: 2002 (0x000007d2)

public static final int STATUS_WRITE_OUT_OF_DATE_VERSION

A version conflict was detected. This means that we have a local version of the data which is out of sync with the server.

Constant Value: 2000 (0x000007d0)

public static final int STATUS_WRITE_SIZE_EXCEEDED

A write request was submitted which contained too much data for the server. This should only occur if we change the app state size restrictions, or if someone is modifying their database directly.

Constant Value: 2001 (0x000007d1)

Public Methods

public void connect ()

Connect to the app state service. This method will return immediately, and onConnected(Bundle) will be called if the connection is successful.

See Also

public void deleteState (OnStateDeletedListener listener, int stateKey)

Delete the state data for the current app. This method will delete all data associated with the provided key, as well as removing the key itself.

Note that this API is not version safe. This means that it is possible to accidentally delete a user's data using this API. For a version safe alternative, consider using updateState(int, byte[]) with null data instead.

Parameters
listener the listener that is called when the load is complete. This listener is required to be non-null. The listener is called on the main thread.
stateKey The key to clear data for. Must be a non-negative integer less than getMaxNumKeys().

public void disconnect ()

Closes the connection to Google Play services. No calls can be made on this object after calling this method.

public int getMaxNumKeys ()

Gets the maximum number of keys that an app can store data in simultaneously.

If the service cannot be reached for some reason, this will return STATUS_CLIENT_RECONNECT_REQUIRED. In this case, no further operations should be attempted until after the client has reconnected.

Returns
  • The maximum number of keys that an app can use for data.

public int getMaxStateSize ()

Gets the maximum app state size per state key in bytes. Guaranteed to be at least 128 KB. May increase in the future.

If the service cannot be reached for some reason, this will return STATUS_CLIENT_RECONNECT_REQUIRED. In this case, no further operations should be attempted until after the client has reconnected.

Returns
  • The maximum state size that can be stored with a given state key in bytes.

public boolean isConnected ()

Checks if the client is currently connected to the service, so that requests to other methods will succeed. Applications should guard client actions caused by the user with a call to this method.

Returns
  • true If the client is connected to the service.

public boolean isConnecting ()

Checks if the client is attempting to connect to the service.

Returns
  • true If the client is attempting to connect to the service.

public boolean isConnectionCallbacksRegistered (GooglePlayServicesClient.ConnectionCallbacks listener)

Returns true if the specified listener is currently registered to receive connection events.

Parameters
listener The listener to check for.
Returns
  • true If the specified listener is currently registered to receive connection events.

public boolean isConnectionFailedListenerRegistered (GooglePlayServicesClient.OnConnectionFailedListener listener)

Returns true if the specified listener is currently registered to receive connection failed events.

Parameters
listener The listener to check for.
Returns
  • true If the specified listener is currently registered to receive connection failed events.

public void listStates (OnStateListLoadedListener listener)

Asynchronously lists all the saved states for the current app.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener the listener that is called when the load is complete. This listener is required to be non-null. The listener is called on the main thread.

public void loadState (OnStateLoadedListener listener, int stateKey)

Asynchronously loads saved state for the current app.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener the listener that is called when the load is complete. This listener is required to be non-null. The listener is called on the main thread.
stateKey The key to load data for. Must be a non-negative integer less than getMaxNumKeys().

public void reconnect ()

Closes the current connection to Google Play services and creates a new connection.

This method closes the current connection then returns immediately and reconnects to the service in the background.

This method will call onDisconnected() followed by either onConnected(Bundle) if the connection is successful or onConnectionFailed(ConnectionResult) on a failure.

public void registerConnectionCallbacks (GooglePlayServicesClient.ConnectionCallbacks listener)

Registers a listener to receive connection events from this GooglePlayServicesClient. If we are already connected, the listener's onConnected(Bundle) method will be called immediately. Applications should balance calls to this method with calls to unregisterConnectionCallbacks(ConnectionCallbacks) to avoid leaking resources.

If the specified listener is already registered to receive connection events, this method will not add a duplicate entry for the same listener, but will still call the listener's onConnected(Bundle) method if currently connected.

Note that the order of messages received here may not be stable, so clients should not rely on the order that multiple listeners receive events in.

Parameters
listener the listener where the results of the asynchronous connect() call are delivered.

public void registerConnectionFailedListener (GooglePlayServicesClient.OnConnectionFailedListener listener)

Registers a listener to receive connection failed events from this GooglePlayServicesClient. Unlike registerConnectionCallbacks(GooglePlayServicesClient.ConnectionCallbacks), if we are not already connected, the listener's onConnectionFailed(ConnectionResult) method will not be called immediately. Applications should balance calls to this method with calls to unregisterConnectionFailedListener(OnConnectionFailedListener) to avoid leaking resources.

If the specified listener is already registered to receive connection failed events, this method will not add a duplicate entry for the same listener.

Note that the order of messages received here may not be stable, so clients should not rely on the order that multiple listeners receive events in.

Parameters
listener the listener where the results of the asynchronous connect() call are delivered.

public void resolveState (OnStateLoadedListener listener, int stateKey, String resolvedVersion, byte[] resolvedData)

Resolve a previously detected conflict in app state data. Note that it is still possible to receive a conflict callback after this call. This will occur if data on the server continues to change. In this case, resolution should be retried until a successful status is returned.

The value of resolvedVersion passed here must correspond to the value provided in the onStateConflict(int, String, byte[], byte[]) call.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener the listener that is called when the operation is complete. This listener is required to be non-null. The listener is called on the main thread.
stateKey The key to resolve data for. Must be a non-negative integer less than getMaxNumKeys().
resolvedVersion version code from previous onStateConflict call.
resolvedData data to submit as the current data. null is a valid value here. May be a maximum of getMaxStateSize() bytes.

public void signOut (OnSignOutCompleteListener listener)

Asynchronously signs the current user out.

The listener is called when sign-out is complete. If disconnect() is called before sign-out is complete, the listener will not be called.

Parameters
listener the listener that is called when sign-out is complete. This listener is required to be non-null. The listener is called on the main thread.

public void signOut ()

Asynchronously signs the current user out.

public void unregisterConnectionCallbacks (GooglePlayServicesClient.ConnectionCallbacks listener)

Removes a connection listener from this GooglePlayServicesClient. Note that removing a listener does not generate any callbacks.

If the specified listener is not currently registered to receive connection events, this method will have no effect.

Parameters
listener the listener to unregister.

public void unregisterConnectionFailedListener (GooglePlayServicesClient.OnConnectionFailedListener listener)

Removes a connection failed listener from the GooglePlayServicesClient. Note that removing a listener does not generate any callbacks.

If the specified listener is not currently registered to receive connection failed events, this method will have no effect.

Parameters
listener the listener to unregister.

public void updateState (int stateKey, byte[] data)

Updates app state for the current app. The data provided here is developer-specified and can be in any format appropriate for the app. This method updates the local copy of the app state and syncs the changes to the server. If the local data conflicts with the data on the server, this will be indicated the next time you call loadState(OnStateLoadedListener, int).

This is the fire-and-forget form of the API. Use this form if you don't need to know the results of the operation immediately. For most applications, this will be the preferred API to use. See updateStateImmediate(OnStateLoadedListener, int, byte[]) if you need the results delivered to your application.

Parameters
stateKey The key to update data for. Must be a non-negative integer less than getMaxNumKeys().
data the data to store. May be a maximum of getMaxStateSize() bytes.

public void updateStateImmediate (OnStateLoadedListener listener, int stateKey, byte[] data)

Updates app state for the current app. The data provided here is developer-specified and can be in any format appropriate for the app. This method will attempt to update the data on the server immediately. The results of this operation will be delivered on the provided listener's onStateLoaded(int, int, byte[]) method.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener the listener that is called when the write operation is complete. This listener is required to be non-null. The listener is called on the main thread.
stateKey The key to update data for. Must be a non-negative integer less than getMaxNumKeys().
data the data to store. May be a maximum of getMaxStateSize() bytes.