Summary: Constants | Inherited Constants | Fields | Methods | Inherited Methods | [Expand All]
public final class

# CompletionEvent

extends Object
implements SafeParcelable ResourceEvent

java.lang.Object
↳ | com.google.android.gms.drive.events.CompletionEvent

## Class Overview

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 `commit(GoogleApiClient, 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.

## Summary

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

[Expand] Inherited Constants
From interface com.google.android.gms.common.internal.safeparcel.SafeParcelable
String | NULL |
From interface android.os.Parcelable
int | CONTENTS_FILE_DESCRIPTOR |
int | PARCELABLE_WRITE_RETURN_VALUE |

Fields
public static final Creator<CompletionEvent> | CREATOR |

Public Methods
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 GoogleApiClient 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)

[Expand] Inherited Methods
From class java.lang.Object
Object | clone()
boolean | equals(Object arg0)
void | finalize()
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()
From interface com.google.android.gms.drive.events.ResourceEvent
abstract DriveId | getDriveId() Returns the id of the Drive resource that triggered the event.
From interface android.os.Parcelable
abstract int | describeContents()
abstract void | writeToParcel(Parcel arg0, int arg1)

## 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 (0x00000003)

#### 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 `commit(GoogleApiClient, 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. `commit(GoogleApiClient, 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 (0x00000002)

#### 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 (0x00000001)

#### 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 (0x00000000)

## 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 GoogleApiClient 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 `GoogleApiClient` 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 `getFile` and `getMetadata` 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 `commit(GoogleApiClient, 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)