CompletionEvent

public final class CompletionEvent extends AbstractSafeParcelable
implements ResourceEvent

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
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.

Constant Value: 3

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.

Constant Value: 2

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.

Constant Value: 1

public static final int STATUS_SUCCESS

Status code indicating that the action referenced by this event has successfully been applied on the server.

Constant Value: 0

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.

public String toString ()

public void writeToParcel (Parcel dest, int flags)