universum.studios.android.officium.sync

Class SyncHandler<Request extends SyncTask.Request,Result>

java.lang.Object

universum.studios.android.officium.sync.SyncHandler<Request,Result>

Type Parameters:

Request - Type of the request that the SyncHandler implementation needs to perform its specific synchronization process.

Result - Type of the result returned by the SyncHandler implementation whenever handleSync(Context, SyncOperation) finishes without any error.

public abstract class SyncHandler<Request extends SyncTask.Request,Result>
extends Object

Base class for handlers that are used by BaseSyncAdapter to handle synchronization process for a specific SyncTasks. Each implementation of SyncHandler must be associated with its corresponding SyncTask via SyncHandler(int) and SyncTask.getId(). Additionally if a specific SyncHandler implementation needs/accepts for its synchronization logic some additional data, these can be specified via SyncTask.Builder.request(SyncTask.Request). The specified synchronization request will be parsed whenever handleSync(Context, SyncOperation) is called via SyncTask.getRequest(Class) using the request class specified in SyncHandler(int, Class).

Each SyncHandler implementation must implement at least onHandleSync(Context, SyncOperation, SyncTask.Request) method to which will be passed all data needed to perform for that handler specific synchronization logic. In case of failed synchronization execution of onHandleSync(Context, SyncOperation, SyncTask.Request) will be invoked onSyncError(Context, SyncOperation, SyncTask.Request, Exception) method all internally by SyncHandler class. Any exception thrown further from onSyncError(Context, SyncOperation, SyncTask.Request, Exception) method will be dispatched to the calling synchronization context (by default BaseSyncAdapter).

Author:

Martin Albedinsky

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SyncHandler(int taskId) Same as SyncHandler(int, Class) without classOfRequest specified.
protected	SyncHandler(int taskId, Class<Request> classOfRequest) Creates a new instance of SyncHandler with the specified taskId and classOfRequest.

Method Summary

Modifier and Type	Method and Description
int	getTaskId() Returns id of the associated synchronization task.
Result	handleSync(Context context, SyncOperation syncOperation) Called to perform synchronization process that is specific for this handler.
protected abstract Result	onHandleSync(Context context, SyncOperation syncOperation, Request syncRequest) Invoked whenever handleSync(Context, SyncOperation) is called to perform synchronization specific for this handler.
protected void	onSyncError(Context context, SyncOperation syncOperation, Request syncRequest, Exception error) Invoked whenever onHandleSync(Context, SyncOperation, SyncTask.Request) is invoked and there is thrown the given error exception during its execution.

Methods inherited from class java.lang.Object

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

Constructor Detail

SyncHandler

protected SyncHandler(int taskId)

Same as SyncHandler(int, Class) without classOfRequest specified.

This constructor should be used only for synchronization handlers that do not accept any request to perform synchronization. This means that such handlers can perform synchronization without any request data sent from a client.

Parameters:

taskId - Id of the SyncTask associated with this handler.

SyncHandler

protected SyncHandler(int taskId,
                      @Nullable
                      Class<Request> classOfRequest)

Creates a new instance of SyncHandler with the specified taskId and classOfRequest.

Parameters:

taskId - Id of the SyncTask associated with this handler.

classOfRequest - The class that is used to parse synchronization request delivered by instance of associated SyncTask whenever handleSync(Context, SyncOperation) is called. May be null if SyncTask.EmptyRequest is used.

See Also:

SyncTask.getRequest(Class)

Method Detail

getTaskId

public final int getTaskId()

Returns id of the associated synchronization task.

Returns:

Id of the SyncTask for which can this handler perform synchronization.

See Also:

handleSync(Context, SyncOperation)

handleSync

@Nullable
public final Result handleSync(@NonNull
                                          Context context,
                                          @NonNull
                                          SyncOperation syncOperation)

Called to perform synchronization process that is specific for this handler. Each synchronization handler may perform synchronization in a different way. It is completely depends on a specific implementation of this SyncHandler class.

If this handler accepts synchronization request needed to perform synchronization process, that request should be delivered to this handler by the given syncOperation.

Note, that any exceptions thrown during synchronization are handled internally by this handler, however this handler may throw some additional exceptions in case those exceptions should be dispatched to clients that requested this synchronization.

Parameters:

context - Context that may be used to access application data and services needed to perform requested synchronization.

syncOperation - Operation describing the synchronization request.

Returns:

Synchronization result specific for this handler. May be null if this handler does not return any result or synchronization has failed and this handler did not throw any additional exceptions.

onHandleSync

@Nullable
protected abstract Result onHandleSync(@NonNull
                                                  Context context,
                                                  @NonNull
                                                  SyncOperation syncOperation,
                                                  @Nullable
                                                  Request syncRequest)
                                           throws Exception

Invoked whenever handleSync(Context, SyncOperation) is called to perform synchronization specific for this handler.

Any Exception thrown by this method will be handled by this handler and passed to onSyncError(Context, SyncOperation, SyncTask.Request, Exception).

Parameters:

context - Context that may be used to access application data and services needed to perform requested synchronization.

syncOperation - Operation describing the synchronization request.

syncRequest - Synchronization request that has been specified for SyncTask passed to handleSync(Context, SyncOperation) method via SyncOperation. The request is parsed via SyncTask.getRequest(Class) using the request class specified for this handler. If this handler does not have its request class specified or the delivered SyncTask does not contain any request body to parse request from, the request parameter will be null.

Returns:

Synchronization result specific for this handler. May be null if this handler does not return any result.

Throws:

Exception - The exception occurred during synchronization handling specific for this handler.

onSyncError

protected void onSyncError(@NonNull
                           Context context,
                           @NonNull
                           SyncOperation syncOperation,
                           @Nullable
                           Request syncRequest,
                           @NonNull
                           Exception error)

Invoked whenever onHandleSync(Context, SyncOperation, SyncTask.Request) is invoked and there is thrown the given error exception during its execution.

Note, that any additional exception thrown from this method should be handled by the calling synchronization service/context. By default, if used with BaseSyncAdapter, that sync adapter will handle the thrown exception and will dispatch it to the clients that requested this synchronization.

Parameters:

context - Context passed to this handler during synchronization request.

syncOperation - Operation describing the synchronization request.

syncRequest - Synchronization request for which has synchronization failed. May be null if this handler does not accept any request.

error - The error exception thrown by onHandleSync(Context, SyncOperation, SyncTask.Request).