CompletionEvent
events are
callbacks you receive when updates made to
DriveFile
objects, such
as file creation or edits to existing files, are propagated to the server. These
events are received even when the application is not running.
You can use completion events to take actions upon notification that changes have been propagated to the server or if a change has failed to be applied. For example, you can delete the local version of a file to free up disk space once you know changes to the file have successfully propagated to the server.
To receive a CompletionEvent
, you must request it
when calling the
DriveResourceClient.commitContents
method to commit your changes. Also
you must create a service extending the
DriveEventService
and
override its
onCompletion
method, where you handle the CompletionEvent
.
Implement completion events
Completion events must be requested and handled once returned.
Request completion events
Create an ExecutionOptions
object and call its setNotifyOnCompletion
method with the value true
. Then
pass the ExecutionOptions
object to your
DriveResourceClient.commitContents
method call.
Handle completion events
Create a class that extends DriveEventService
and overrides the
DriveEventService.onCompletion
method. This is where you will receive the
notification of the action’s completion and handle the result which may be
either success, failure or conflict.
Define your DriveEventService
in your AndroidManifest.xml file as a child of
the application element.
Handling the completion event status
Completion events can return one of three status types:
Success
This status indicates that the action associated with this event has been applied to the server successfully.
Failure
This status indicates that the action associated with this event has
permanently failed to be applied to the server. The content or metadata that
failed to be applied to the server can be retrieved using the
CompletionEvent.getModifiedContentsInputStream
or
CompletionEvent.getModifiedMetadataChangeSet
methods, allowing you to try to apply them to the server at a later time.
Conflict
This status indicates that the action associated with this event has failed
because of a conflict. The app must resolve the conflict. The
CompletionEvent
provides only the base and modified versions of
the conflicted file; the app can access the current version
on the server in the usual way.
By default, the Drive Android API automatically overwrites the server version
with the local version when there is a conflict. To resolve the conflict in
your app, however, you can use the
ExecutionOptions.Builder.setConflictStrategy
method, passing in ExecutionOptions.CONFLICT_STRATEGY_KEEP_REMOTE
to store
the base and modified versions of the content. When you use
ExecutionOptions.CONFLICT_STRATEGY_KEEP_REMOTE
, you must also request
completion notifications. After Drive detects a conflict, you can use
the CompletionEvent
to access the locally committed changes that caused
the conflict, which then allows you to resolve those conflicts yourself.
Conflict detection requires that you use the
DriveResourceClient.reopenContentsForWrite
method
to commit modifications. You can only call the
DriveResourceClient.reopenContentsForWrite
method on a DriveContents
object that was initially opened in
MODE_READ_ONLY
mode.
As mentioned above conflict detection also requires that you set the conflict
strategy of the ExecutionOptions
object to
ExecutionOptions.CONFLICT_STRATEGY_KEEP_REMOTE
.
A conflict occurs when the local version of the base file contents do not match
the current file contents on the server. In this case, a simple merge is not
possible and a Conflict
status is returned. Your application can use the base,
current, and modified versions to create a new merged version and commit it to
the server.