universum.studios.android.officium.sync

Class BaseSyncAdapter

java.lang.Object

android.content.AbstractThreadedSyncAdapter

universum.studios.android.officium.sync.BaseSyncAdapter

public abstract class BaseSyncAdapter
extends android.content.AbstractThreadedSyncAdapter

An AbstractThreadedSyncAdapter implementation that provides simple API for registration of SyncHandlers that are responsible for synchronization tasks handling. Each synchronization handler can be registered via registerTaskHandler(SyncHandler). Every registered handler is mapped within BaseSyncAdapter based on the id (SyncHandler.getTaskId()) of a task for which handling is such handler responsible. Each handler may be responsible only for single task handling. To unregister already registered handler, call unregisterTaskHandler(SyncHandler).

This class is closely connected with SyncTask as instance of BaseSyncAdapter assumes that extras Bundle received in onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) contains data from which can be re-created instance of SyncTask and than that instance of task passed to its associated handler. For simplified synchronization requesting can be used implementation of BaseSyncManager that handles putting of a specific instance of SyncTask into extras Bundle that is than by the Android framework delivered to implementation of this BaseSyncAdapter.

Whenever onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) method is invoked by the Android framework, BaseSyncAdapter checks the received extras Bundle if it contains data for SyncTask instantiation. If yes, an instance of SyncTask is created from that extras and the associated SyncHandler is retrieved and requested to handle synchronization via SyncHandler.handleSync(Context, SyncOperation) with that instance of SyncTask. If the received extras Bundle does not contain data for SyncTask or contains data for task with default id (SyncTask.DEFAULT_ID), onPerformGlobalSync(SyncOperation) method is invoked to perform global synchronization. Handler that should handle this global synchronization can be specified via setGlobalSyncHandler(SyncHandler).

Sync task state change listening

To listen for changes in state of SyncTasks within the sync adapter implementation, register OnSyncTaskStateChangeListener via setOnTaskStateChangeListener(OnSyncTaskStateChangeListener) where this listener will be notified whenever a state of a particular sync task is changed within the adapter.

Sync events dispatching

By default BaseSyncAdapter does not dispatch/notify any state about the current running synchronization process however there can be specified an instance of BaseSyncAdapter.EventDispatcher that can be used for such dispatching. If this dispatcher is specified via setEventDispatcher(EventDispatcher) BaseSyncAdapter will dispatch instances of SyncEvent as described below:

• onPerformGlobalSync(SyncOperation)

  - dispatches SyncEvent type of SyncEvent.START with default task id SyncTask.DEFAULT_ID along with account

• onGlobalSyncFinished(SyncOperation)

  - dispatches SyncEvent type of SyncEvent.FINISH with default task id SyncTask.DEFAULT_ID along with account

• onGlobalSyncFailed(SyncOperation, Exception)

  - dispatches SyncEvent type of SyncEvent.ERROR with default task id SyncTask.DEFAULT_ID along with occurred error and account

• onPerformSync(SyncOperation)

  - dispatches SyncEvent type of SyncEvent.START with id of the specified task along with account

• onSyncFinished(SyncOperation)

  - dispatches SyncEvent type of SyncEvent.FINISH with id of the specified task along with account

• onSyncFailed(SyncOperation, Exception)

  - dispatches SyncEvent type of SyncEvent.ERROR with id of the specified task along with occurred error and account

Dispatching of synchronization events type of SyncEvent.PROGRESS is responsibility of each specific SyncHandler implementation.

Author:

Martin Albedinsky

See Also:

BaseSyncManager, SyncHandler, SyncEvent

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	BaseSyncAdapter.EventDispatcher Interface used by BaseSyncAdapter to dispatch occurred synchronization events.

Field Summary

Fields inherited from class android.content.AbstractThreadedSyncAdapter

LOG_SYNC_DETAILS

Constructor Summary

Constructors

Constructor and Description
BaseSyncAdapter(android.content.Context context, boolean autoInitialize) Same as BaseSyncAdapter(Context, boolean, boolean) with allowParallelSyncs parameter set to false.
BaseSyncAdapter(android.content.Context context, boolean autoInitialize, boolean allowParallelSyncs) Creates a new instance of BaseSyncAdapter with the specified context and configuration flags.

Method Summary

Modifier and Type	Method and Description
protected SyncTask	createTaskFromExtras(android.os.Bundle extras) Called to create instance of SyncTask from the given extras whenever onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) is invoked.
protected void	dispatchSyncEvent(Object event) Invoked whenever this sync adapter wants to dispatch the given synchronization event to its clients.
protected BaseSyncAdapter.EventDispatcher	getEventDispatcher() Returns the event dispatcher specified for this sync adapter.
protected SyncHandler	getGlobalSyncHandler() Returns the sync handler that is responsible for global synchronization handling.
protected void	onGlobalSyncFailed(SyncOperation syncOperation, Exception error) Invoked whenever onPerformGlobalSync(SyncOperation) is invoked and there is thrown the given error exception during its execution.
protected void	onGlobalSyncFinished(SyncOperation syncOperation) Invoked whenever onPerformGlobalSync(SyncOperation) finishes without any error.
protected void	onPerformGlobalSync(SyncOperation syncOperation) Invoked whenever onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) is invoked and the extras Bundle does not contain data for a specific SyncTask but rather for a global SyncTask.
void	onPerformSync(android.accounts.Account account, android.os.Bundle extras, String authority, android.content.ContentProviderClient provider, android.content.SyncResult syncResult)
protected void	onPerformSync(SyncOperation syncOperation) Invoked whenever onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) is invoked and the extras Bundle does contain data for a specific SyncTask.
protected void	onSyncFailed(SyncOperation syncOperation, Exception error) Invoked whenever onPerformSync(SyncOperation) is invoked and there is thrown the given error exception during its execution.
protected void	onSyncFinished(SyncOperation syncOperation) Invoked whenever onPerformSync(SyncOperation) finishes without any error.
protected void	registerTaskHandler(SyncHandler handler) Registers a sync handler that will be used by this sync adapter for synchronization handling of a SyncTask associated with the given handler via SyncHandler.getTaskId().
protected void	setEventDispatcher(BaseSyncAdapter.EventDispatcher dispatcher) Sets an dispatcher that is used by this sync adapter to dispatch synchronization events.
protected void	setGlobalSyncHandler(SyncHandler handler) Sets a sync handler that is responsible for global synchronization handling.
protected void	setOnTaskStateChangeListener(OnSyncTaskStateChangeListener listener) Registers a callback to be invoked whenever a state is changed for a particular SyncTask within this sync adapter.
protected void	unregisterTaskHandler(SyncHandler handler) Un-registers previously registered sync handler.

Methods inherited from class android.content.AbstractThreadedSyncAdapter

getContext, getSyncAdapterBinder, onSecurityException, onSyncCanceled, onSyncCanceled

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BaseSyncAdapter

public BaseSyncAdapter(android.content.Context context,
                       boolean autoInitialize)

Same as BaseSyncAdapter(Context, boolean, boolean) with allowParallelSyncs parameter set to false.

BaseSyncAdapter

public BaseSyncAdapter(android.content.Context context,
                       boolean autoInitialize,
                       boolean allowParallelSyncs)

Creates a new instance of BaseSyncAdapter with the specified context and configuration flags.

See AbstractThreadedSyncAdapter.AbstractThreadedSyncAdapter(Context, boolean, boolean) for more information.

Method Detail

setOnTaskStateChangeListener

protected final void setOnTaskStateChangeListener(OnSyncTaskStateChangeListener listener)

Registers a callback to be invoked whenever a state is changed for a particular SyncTask within this sync adapter.

Parameters:

listener - The desired listener callback. May be null to clear the current one.

See Also:

SyncTask.getState()

setEventDispatcher

protected final void setEventDispatcher(BaseSyncAdapter.EventDispatcher dispatcher)

Sets an dispatcher that is used by this sync adapter to dispatch synchronization events.

See class description for events that are dispatched by this adapter.

Parameters:

dispatcher - The desired event dispatcher. May be null to not dispatch any events.

See Also:

getEventDispatcher(), dispatchSyncEvent(Object)

getEventDispatcher

protected final BaseSyncAdapter.EventDispatcher getEventDispatcher()

Returns the event dispatcher specified for this sync adapter.

Returns:

This adapter's event dispatcher.

See Also:

setEventDispatcher(EventDispatcher)

registerTaskHandler

protected void registerTaskHandler(SyncHandler handler)

Registers a sync handler that will be used by this sync adapter for synchronization handling of a SyncTask associated with the given handler via SyncHandler.getTaskId().

The given handler will be used to perform synchronization whenever onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) is invoked with extras Bundle that contains data for the associated SyncTask (mainly its id). Instance of such SyncTask is created from the delivered extras and passed to the registered handler via SyncHandler.handleSync(Context, SyncOperation).

Note, that if there is already registered sync handler with the same task id, such handler will be replaced by the new one.

Parameters:

handler - The desired sync handler to be registered.

See Also:

onPerformSync(SyncOperation), unregisterTaskHandler(SyncHandler)

unregisterTaskHandler

protected void unregisterTaskHandler(SyncHandler handler)

Un-registers previously registered sync handler.

If the given handler has not been registered before this method does nothing.

Parameters:

handler - The desired sync handler to un-register.

See Also:

onPerformSync(SyncOperation)

setGlobalSyncHandler

protected void setGlobalSyncHandler(SyncHandler handler)

Sets a sync handler that is responsible for global synchronization handling.

Parameters:

handler - The desired sync handler. May be null if handling of global synchronization is not desired.

See Also:

onPerformGlobalSync(SyncOperation), getGlobalSyncHandler()

getGlobalSyncHandler

protected SyncHandler getGlobalSyncHandler()

Returns the sync handler that is responsible for global synchronization handling.

Returns:

This adapter's global sync handler.

See Also:

setGlobalSyncHandler(SyncHandler)

onPerformSync

public void onPerformSync(android.accounts.Account account,
                          android.os.Bundle extras,
                          String authority,
                          android.content.ContentProviderClient provider,
                          android.content.SyncResult syncResult)

Specified by:

onPerformSync in class android.content.AbstractThreadedSyncAdapter

See Also:

createTaskFromExtras(Bundle), onPerformGlobalSync(SyncOperation), onPerformSync(SyncOperation)

createTaskFromExtras

protected SyncTask createTaskFromExtras(android.os.Bundle extras)

Called to create instance of SyncTask from the given extras whenever onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) is invoked.

Inheritance hierarchies may override this method to instantiate custom implementations of SyncTasks.

Parameters:

extras - The synchronization extras passed to onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult).

Returns:

New instance of SyncTask with data parsed from the given extras.

onPerformGlobalSync

protected void onPerformGlobalSync(SyncOperation syncOperation)

Invoked whenever onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) is invoked and the extras Bundle does not contain data for a specific SyncTask but rather for a global SyncTask. This is determined whether the extras contains id of that specific synchronization task or not.

Parameters:

syncOperation - Operation describing the global synchronization request. The operation's associated task will always have SyncTask.DEFAULT_ID id.

See Also:

onGlobalSyncFinished(SyncOperation), onGlobalSyncFailed(SyncOperation, Exception)

onGlobalSyncFinished

protected void onGlobalSyncFinished(SyncOperation syncOperation)

Invoked whenever onPerformGlobalSync(SyncOperation) finishes without any error.

Parameters:

syncOperation - Operation describing the global synchronization request.

See Also:

onGlobalSyncFailed(SyncOperation, Exception)

onGlobalSyncFailed

protected void onGlobalSyncFailed(SyncOperation syncOperation,
                                  Exception error)

Invoked whenever onPerformGlobalSync(SyncOperation) is invoked and there is thrown the given error exception during its execution.

Parameters:

syncOperation - Operation describing the global synchronization request.

error - The error exception thrown by onPerformGlobalSync(SyncOperation).

See Also:

onSyncFinished(SyncOperation)

onPerformSync

protected void onPerformSync(SyncOperation syncOperation)

Invoked whenever onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) is invoked and the extras Bundle does contain data for a specific SyncTask. This is determined whether the extras contains id of that specific synchronization task or not.

Parameters:

syncOperation - Operation describing the synchronization request.

See Also:

onSyncFinished(SyncOperation), onSyncFailed(SyncOperation, Exception)

onSyncFinished

protected void onSyncFinished(SyncOperation syncOperation)

Invoked whenever onPerformSync(SyncOperation) finishes without any error.

Parameters:

syncOperation - Operation describing the synchronization request.

See Also:

onSyncFailed(SyncOperation, Exception)

onSyncFailed

protected void onSyncFailed(SyncOperation syncOperation,
                            Exception error)

Invoked whenever onPerformSync(SyncOperation) is invoked and there is thrown the given error exception during its execution.

Parameters:

syncOperation - Operation describing the synchronization request.

error - The error exception thrown by onPerformSync(SyncOperation).

See Also:

onSyncFinished(SyncOperation)

dispatchSyncEvent

protected void dispatchSyncEvent(Object event)

Invoked whenever this sync adapter wants to dispatch the given synchronization event to its clients.

Default implementation uses BaseSyncAdapter.EventDispatcher specified via setEventDispatcher(EventDispatcher) (if any). If there is no dispatcher specified this method does nothing.

See class description for events that are dispatched by this adapter.

Parameters:

event - The synchronization event to be dispatched.