An event delivered after the client requests a completion notification using
setNotifyOnCompletion(boolean)
and that action has either succeeded or failed on
the server.
Refer to DriveEvent
for additional information about event listeners and subscriptions.
Completion events are only delivered to the application that committed the original request. If the original change modified the metadata or content of the file and the action failed to complete on the server, this class provides access to the modified versions of the metadata and content that could not be committed.
Once the event has been handled by the application, dismiss()
should be called so the Drive API can release any associated resources. Drive will delete
this data after dismiss()
has been called or the device reboots, so if an application requires longer term access to
this data (for example, persistence of data across device reboot), the app must copy and
persist any data they want to keep. One way to persist this data is to save it in a file
using the Drive API.
Multiple actions by the same application on the same resource may be collapsed by the
Drive API. In this case the event may refer to multiple collapsed actions. The InputStream
provided
by
getBaseContentsInputStream()
will be the very first base version of the content
and the InputStream
provided
by
getModifiedContentsInputStream()
will be the very last written version of the
content. The tags returned by
getTrackingTags()
will all be values provided to
commitContents(com.google.android.gms.drive.DriveContents, MetadataChangeSet,
ExecutionOptions)
through the ExecutionOptions
parameter, following the same order in which actions were applied.
For every event received the client must call either dismiss()
or snooze()
in order to release the event instance. Dismiss indicates that the application has finished
interacting with the event. Snooze indicates that the application could not process the event
at the current time and wants to be notified again of the same event in the future.
If neither dismiss()
nor snooze()
is invoked within a short period of time after event notification, it is assumed that the
event was not delivered to the client. In such a situation, the event may be notified again
later. In order to observe a reliable notification behavior, the client must always dismiss
or snooze every event received.
Constant Summary
int | STATUS_CANCELED | Status code indicating that the action referenced by this event was canceled. |
int | STATUS_CONFLICT | Status code indicating that the action referenced by this event has failed to be applied on the server because of a conflict. |
int | STATUS_FAILURE | Status code indicating that the action referenced by this event has permanently failed to be applied on the server. |
int | STATUS_SUCCESS | Status code indicating that the action referenced by this event has successfully been applied on the server. |
Inherited Constant Summary
Field Summary
public static final Creator<CompletionEvent> | CREATOR |
Public Method Summary
void |
dismiss()
Indicates to the Drive API that the caller has finished interacting with this
event and any related resources should be cleaned up.
|
String |
getAccountName()
Returns the account name that was used by the
GoogleSignInAccount that requested this notification, or
null if the default account was used.
|
InputStream |
getBaseContentsInputStream()
Returns an
InputStream
for the initial contents of a file, in the case of a notification with status
STATUS_CONFLICT .
|
DriveId |
getDriveId()
Returns the id of the Drive resource that triggered the event.
|
InputStream |
getModifiedContentsInputStream()
Returns an
InputStream
for the modified contents that generated this event.
|
MetadataChangeSet |
getModifiedMetadataChangeSet()
Returns the
MetadataChangeSet
that was committed during the update that generated this event.
|
int |
getStatus()
Returns a status indicating the result of the action that generated this event.
|
List<String> |
getTrackingTags()
Returns a
List of
tracking tags provided through
setTrackingTag(String) .
|
void |
snooze()
Indicates that the client could not process the event at the current time, for
example because of connectivity issues.
|
String |
toString()
|
void |
writeToParcel(Parcel dest, int
flags)
|
Inherited Method Summary
Constants
public static final int STATUS_CANCELED
Status code indicating that the action referenced by this event was canceled. A canceled action was not applied on the server and was reverted locally.
public static final int STATUS_CONFLICT
Status code indicating that the action referenced by this event has failed to be
applied on the server because of a conflict. A conflict originates from
commitContents(DriveContents, MetadataChangeSet)
.
When this status code is provided, the metadata and contents that were changed in
the original action (if applicable) will be provided through
getModifiedMetadataChangeSet()
and
getModifiedContentsInputStream()
, respectively, so that the client can
retrieve the data that has failed to upload.
This event provides the context in which a conflict originated, so it can be fixed by the application that caused it. File conflicts are only delivered to the application that committed a change resulting in a conflict, and that application is responsible for resolving the conflict (or the conflicting changes will not be committed).
This class provides access to the base content of the file (the content at the time the file was opened to make the changes in the commit) and the modified metadata and content (that could not be committed due to the conflict). The current metadata and content (the newer values that conflicted with the modified metadata and content) can be obtained using the standard Drive API.
A conflict can be fixed by committing the metadata or content again, possibly with
modified further changes that resulted from analyzing the information provided by this
class.
commitContents(DriveContents, MetadataChangeSet)
should be used to commit a
conflict resolution. If no such commit is made, the original changes that produced the
conflict will be dropped and the current metadata and contents will remain
unchanged.
Once the conflict has been fixed by the application,
dismiss()
should be called so the Drive API can release conflicting
resources. If an application requires longer term access to this conflict data (for
example persistence of the conflict data across device reboot), the app should handle
the persistence of any conflict data provided here, since Drive will delete this
conflict data after
dismiss()
has been called.
Multiple commits by the same application on the same resource may be collapsed by
the Drive API. In this case the conflict may refer to multiple collapsed commits. The
InputStream
provided by
getBaseContentsInputStream()
will be the very first base version of the
content and the InputStream
provided by
getModifiedContentsInputStream()
will be the very last written version of
the content.
public static final int STATUS_FAILURE
Status code indicating that the action referenced by this event has permanently
failed to be applied on the server. When this status code is provided, the metadata and
contents that were changed in the original action (if applicable) will be provided
through
getModifiedMetadataChangeSet()
and
getModifiedContentsInputStream()
, respectively, so that the client can
retrieve the data that has failed to upload.
public static final int STATUS_SUCCESS
Status code indicating that the action referenced by this event has successfully been applied on the server.
Fields
public static final Creator<CompletionEvent> CREATOR
Public Methods
public void dismiss ()
Indicates to the Drive API that the caller has finished interacting with this event and any related resources should be cleaned up. The client may not continue using this event instance after dismissing.
public String getAccountName ()
Returns the account name that was used by the GoogleSignInAccount
that requested this notification, or null
if the default account was
used.
This method is provided so that when a completion event is delivered, the correct
GoogleSignInAccount
can be built to work with the file.
public InputStream getBaseContentsInputStream ()
Returns an InputStream
for
the initial contents of a file, in the case of a notification with status
STATUS_CONFLICT
. Returns null
for any other status but
STATUS_CONFLICT
.
This version of the file content is not the current version anymore. In order to get
the current version during conflict resolution, the normal flow to read contents should
be used. This method may only be called once per CompletionEvent
instance.
This can be used in conjunction with
getModifiedContentsInputStream()
in order to compute the incremental changes
that conflicted, so those can be reapplied on top of the current version.
The returned InputStream
can
be used until
dismiss()
or snooze()
is called.
public DriveId getDriveId ()
Returns the id of the Drive resource that triggered the event.
public InputStream getModifiedContentsInputStream ()
Returns an InputStream
for
the modified contents that generated this event. If the status of this event is not
STATUS_SUCCESS
, note that the modified contents provided by this method have
not been applied on the server. This method may only be called once per CompletionEvent
instance.
The returned InputStream
can
be used until
dismiss()
or snooze()
is called.
public MetadataChangeSet getModifiedMetadataChangeSet ()
Returns the MetadataChangeSet
that was committed during the update that generated this event. The value may be
null
if the action didn't contain metadata changes. The current metadata
can be obtained using asDriveFile()
and
getMetadata(com.google.android.gms.drive.DriveResource)
and be compared with
this MetadataChangeSet
.
If the event has a status other than
STATUS_SUCCESS
, note that the changes in this change set have not been
applied on the server and have been reverted locally.
Modifying the returned MetadataChangeSet
will not have any effect unless the set is committed through
commitContents(DriveContents, MetadataChangeSet)
.
public int getStatus ()
Returns a status indicating the result of the action that generated this event. May
be one of
STATUS_SUCCESS
,
STATUS_CONFLICT
,
STATUS_FAILURE
,
STATUS_CANCELED
.
public List<String> getTrackingTags ()
Returns a List
of tracking
tags provided through
setTrackingTag(String)
. The application can use these tags to relate this
event with the specific method execution that generated it.
If the list contains multiple elements, the ordering of the elements is guaranteed
to be the one in which the collapsed modifications were applied. Elements in the
returned list may not be null
.
public void snooze ()
Indicates that the client could not process the event at the current time, for example because of connectivity issues. The client will be notified again of the same event in the future. The client may not continue using this event instance after snoozing.