DriveResourceClient

public abstract class DriveResourceClient extends GoogleApi<Drive.ConnectionlessDriveOptions>

The contract for any DriveResource (i.e. DriveFile or DriveFolder).

Public Method Summary

abstract Task<ListenerToken>	addChangeListener(DriveResource resource, OnChangeListener listener) Adds the specified `listener` to be notified of changes to the specified `resource`.
abstract Task<Void>	addChangeSubscription(DriveResource resource) Adds a subscription for this `resource` that will deliver events to the application's `DriveEventService` subclass when changes to this resource are visible to the client.
abstract Task<Boolean>	cancelOpenFileCallback(ListenerToken token) Cancels callback passed into `openFile(DriveFile, int, OpenFileCallback)` with the `ListenerToken` returned from the `open()` call.
abstract Task<Void>	commitContents(DriveContents contents, MetadataChangeSet changeSet) Commits the `contents` and updates its metadata to `changeSet` (if provided).
abstract Task<Void>	commitContents(DriveContents contents, MetadataChangeSet changeSet, ExecutionOptions executionOptions) Commits the `contents` and updates its metadata to `changeSet` (if provided).
abstract Task<DriveContents>	createContents() Creates a new `DriveContents` instance that can be used to provide initial contents for a new `DriveFile`.
abstract Task<DriveFile>	createFile(DriveFolder folder, MetadataChangeSet changeSet, DriveContents driveContents, ExecutionOptions executionOptions) Creates a new binary `DriveFile` within `folder`, with the initial metadata provided in `changeSet`, initial contents provided in `driveContents`, and method execution options provided in `executionOptions`.
abstract Task<DriveFile>	createFile(DriveFolder folder, MetadataChangeSet changeSet, DriveContents driveContents) Creates a new binary `DriveFile` within `folder`, with the initial metadata provided in `changeSet` and initial contents provided in `driveContents`.
abstract Task<DriveFolder>	createFolder(DriveFolder folder, MetadataChangeSet changeSet) Creates a new `DriveFolder` within `folder`, with the initial metadata provided in `changeSet`.
abstract Task<Void>	delete(DriveResource resource) Permanently deletes this `resource`, bypassing trash.
abstract Task<Void>	discardContents(DriveContents contents) Discards `contents` and any changes that were performed on it.
abstract Task<DriveFolder>	getAppFolder() Returns the app folder.
abstract Task<Metadata>	getMetadata(DriveResource resource) Retrieves the `Metadata` associated with this `resource`.
abstract Task<DriveFolder>	getRootFolder() Returns the root folder.
abstract Task<MetadataBuffer>	listChildren(DriveFolder folder) Retrieves a collection of metadata for the direct children, including both files and folders, of `folder`.
abstract Task<MetadataBuffer>	listParents(DriveResource resource) Retrieves the collection of metadata for all of the parents of this `resource` that the calling app has been authorized to view.
abstract Task<DriveContents>	openFile(DriveFile file, int openMode) Opens the `DriveContents` that are associated with this `file` in the requested `openMode`.
abstract Task<ListenerToken>	openFile(DriveFile file, int openMode, OpenFileCallback callback) Opens the `DriveContents` that are associated with this `file` in the requested `openMode`.
abstract Task<MetadataBuffer>	query(Query query) Retrieves a collection of metadata for the files and folders that match the restrictions specified in `query`.
abstract Task<MetadataBuffer>	queryChildren(DriveFolder folder, Query query) Retrieves a collection of metadata for the files and folders that match the restrictions specified in `query` and are direct children of `folder`.
abstract Task<Boolean>	removeChangeListener(ListenerToken token) Removes the `OnChangeListener` associated with this `token` from listening to changes to the associated `DriveResource`.
abstract Task<Void>	removeChangeSubscription(DriveResource resource) Removes the existing Change subscription for this `resource`.
abstract Task<DriveContents>	reopenContentsForWrite(DriveContents contents) Closes the `contents` and returns a new `DriveContents` opened in `MODE_WRITE_ONLY`.
abstract Task<Void>	setParents(DriveResource resource, Set<DriveId> parentIds) Sets the parents of `resource` to the `DriveId` instances defined in `parentIds`.
abstract Task<Void>	trash(DriveResource resource) Moves the `resource` to trash.
abstract Task<Void>	untrash(DriveResource resource) Moves the `resource` out of the trash.
abstract Task<Metadata>	updateMetadata(DriveResource resource, MetadataChangeSet changeSet) Updates the `Metadata` that is associated with this `resource` with the changes defined in `changeSet`.

Inherited Method Summary

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()

Public Methods

public abstract Task<ListenerToken> addChangeListener (DriveResource resource, OnChangeListener listener)

Adds the specified listener to be notified of changes to the specified resource.

The listener will remain active for the duration of the process or until removeChangeListener(ListenerToken) is called with the same ListenerToken returned by this method.

public abstract Task<Void> addChangeSubscription (DriveResource resource)

Adds a subscription for this resource that will deliver events to the application's DriveEventService subclass when changes to this resource are visible to the client.

The application's DriveEventService subclass should implement onChange(ChangeEvent) in order to handle the incoming ChangeEvent objects.

The subscription is persistent and will remain active until the next device reboot or until removeChangeSubscription(DriveResource) is called. The client is responsible for registering the subscription again after a device reboot if it is still desired.

public abstract Task<Boolean> cancelOpenFileCallback (ListenerToken token)

Cancels callback passed into openFile(DriveFile, int, OpenFileCallback) with the ListenerToken returned from the open() call.

Note: The Callback is cancelled for you after onContents(DriveContents) or onError(Exception) is called.

Returns

true if callback was cancelled, false if callback was already cancelled or not registered in the first place.

public abstract Task<Void> commitContents (DriveContents contents, MetadataChangeSet changeSet)

Commits the contents and updates its metadata to changeSet (if provided). This method should only be used on DriveContents that are already associated to a particular DriveFile, obtained through openFile(DriveFile, int).

This method will commit contents using the default CONFLICT_STRATEGY_OVERWRITE_REMOTE strategy, will not notify for a CompletionEvent, and will have no tracking tags. If you'd like to specify different options, use commitContents(DriveContents, MetadataChangeSet, ExecutionOptions) instead.

After this method returns, contents will be closed and no longer usable.

Throws

IllegalStateException	if one of the following is true: `contents` is opened in `MODE_READ_ONLY` `contents` is not associated to a file

public abstract Task<Void> commitContents (DriveContents contents, MetadataChangeSet changeSet, ExecutionOptions executionOptions)

Commits the contents and updates its metadata to changeSet (if provided). Extra settings for this action, such as a conflict resolution strategy or completion notification request, can be specified in executionOptions. See ExecutionOptions for a complete list of options. This method should only be used on DriveContents that are already associated to a particular DriveFile, obtained through openFile(DriveFile, int).

A file conflict happens when the written contents are not applied on top of the file revision that Drive originally provided when the contents were read by the application. A conflict could happen when an application reads contents at revision X, then writes revision X+1 and, by the time X+1 is committed or updated on the server, the file version is not X anymore (because, e.g. another app or a remote change already modified the file to revision X').

After this method returns, contents will be closed and no longer usable.

Throws

IllegalStateException	if one of the following is true: `contents` is opened in `MODE_READ_ONLY` `contents` is not associated to a file `executionOptions` is incompatible with `contents`

public abstract Task<DriveContents> createContents ()

Creates a new DriveContents instance that can be used to provide initial contents for a new DriveFile. The returned contents will be in MODE_WRITE_ONLY and can be used to write the initial contents.

To be persisted, the contents must be saved by being passed as an argument to createFile(DriveFolder, MetadataChangeSet, DriveContents), {@link #createFile(DriveFolder, MetadataChangeSet, DriveContents, ExecutionOptions) or {@link CreateFileActivityOptions.Builder#setInitialDriveContents(DriveContents)}.

public abstract Task<DriveFile> createFile (DriveFolder folder, MetadataChangeSet changeSet, DriveContents driveContents, ExecutionOptions executionOptions)

Creates a new binary DriveFile within folder, with the initial metadata provided in changeSet, initial contents provided in driveContents, and method execution options provided in executionOptions. In order to create the file with empty contents, pass in null for driveContents. It is recommended that files with a mime-type that does not support having a zero-byte file (e.g. an image or PDF) is created as a non-empty file.

Note: setConflictStrategy(int) is not supported for this method.

You must obtain driveContents via createContents(). Once this method returns, driveContents will be persisted and closed. In order to continue editing the file's contents, they must be opened again with openFile(DriveFile, int) or openFile(DriveFile, int, OpenFileCallback).

If you want to use the default ExecutionOptions, call createFile(DriveFolder, MetadataChangeSet, DriveContents) instead.

public abstract Task<DriveFile> createFile (DriveFolder folder, MetadataChangeSet changeSet, DriveContents driveContents)

Creates a new binary DriveFile within folder, with the initial metadata provided in changeSet and initial contents provided in driveContents. In order to create the file with empty contents, pass in null. It is recommended that files with a mime-type that does not support having a zero-byte file (e.g. an image or PDF) is created as a non-empty file.

This method behaves like createFile(DriveFolder, MetadataChangeSet, DriveContents, ExecutionOptions) with {@code null {@link ExecutionOptions}, which means completion event notifications will not be sent and there is no operation tag.

public abstract Task<DriveFolder> createFolder (DriveFolder folder, MetadataChangeSet changeSet)

Creates a new DriveFolder within folder, with the initial metadata provided in changeSet.

Note: At minimum, setTitle(String) must be called.

setMimeType(String) does not need to be called, as the mime-type will automatically be set to MIME_TYPE.

public abstract Task<Void> delete (DriveResource resource)

Permanently deletes this resource, bypassing trash. The user must be the owner. If resource is a DriveFolder, the app must have access to all of its descendants.

For user-visible resources, we recommend using trash(DriveResource) instead to give users the opportunity to restore files they have accidentally removed.

Delete must be used for files in the App Folder as they cannot be trashed. See getAppFolder() for more information.

public abstract Task<Void> discardContents (DriveContents contents)

Discards contents and any changes that were performed on it. Calling this method will not save any changes performed on this object.

After this method returns, contents will be closed and no longer usable.

public abstract Task<DriveFolder> getAppFolder ()

Returns the app folder.

The app folder is a special folder within Drive that is only accessible by your application. Its contents are hidden from the user and from other apps. Although it is hidden from the user, the app folder does count against the user's Drive storage quota.

The app folder can be used to store configuration files, temporary files, etc. that belong to the user but should not be tampered with.

SCOPE_APPFOLDER is required to access this folder; otherwise, it fails with the error status DEVELOPER_ERROR.

See the Storing Application Data guide for more information.

public abstract Task<Metadata> getMetadata (DriveResource resource)

Retrieves the Metadata associated with this resource.

public abstract Task<DriveFolder> getRootFolder ()

Returns the root folder.

SCOPE_FILE is required to access this folder; otherwise, it fails with the error status DEVELOPER_ERROR.

public abstract Task<MetadataBuffer> listChildren (DriveFolder folder)

Retrieves a collection of metadata for the direct children, including both files and folders, of folder.

Be sure to call release() when finished with the result.

public abstract Task<MetadataBuffer> listParents (DriveResource resource)

Retrieves the collection of metadata for all of the parents of this resource that the calling app has been authorized to view.

Be sure to call release() when finished with the result.

public abstract Task<DriveContents> openFile (DriveFile file, int openMode)

Opens the DriveContents that are associated with this file in the requested openMode. The returned contents is a temporary copy available only to this app. The contents must be closed via commitContents(DriveContents, MetadataChangeSet) or discardContents(DriveContents).

Note: To open the file in edit mode, the user must have edit access. See isEditable() for more information.

Availability

The contents are returned when they are available on the device in their entirety. Content is returned from the cache if it is available and up-to-date; otherwise, it will be downloaded from the server.

Note: If the download fails (e.g. due to the device going offline) the cached version will be returned if available.

public abstract Task<ListenerToken> openFile (DriveFile file, int openMode, OpenFileCallback callback)

Opens the DriveContents that are associated with this file in the requested openMode. The provided OpenFileCallback will receive a temporary copy of the contents available only to this app. The contents must be closed via commitContents(DriveContents, MetadataChangeSet) or discardContents(DriveContents). The returned ListenerToken can be used to cancel the download.

Note: To open the file in edit mode, the user must have edit access. See isEditable() for more information.

Note: If the download fails (e.g. due to the device going offline) the cached version will be returned if available.

public abstract Task<MetadataBuffer> query (Query query)

Retrieves a collection of metadata for the files and folders that match the restrictions specified in query.

Be sure to call release() when finished with the result.

public abstract Task<MetadataBuffer> queryChildren (DriveFolder folder, Query query)

Retrieves a collection of metadata for the files and folders that match the restrictions specified in query and are direct children of folder.

Be sure to call release() when finished with the result.

public abstract Task<Boolean> removeChangeListener (ListenerToken token)

Removes the OnChangeListener associated with this token from listening to changes to the associated DriveResource. The token must be the same ListenerToken that was returned by addChangeListener(DriveResource, OnChangeListener).

Returns true if removing the listener was successful.

public abstract Task<Void> removeChangeSubscription (DriveResource resource)

Removes the existing Change subscription for this resource.

public abstract Task<DriveContents> reopenContentsForWrite (DriveContents contents)

Closes the contents and returns a new DriveContents opened in MODE_WRITE_ONLY. The returned contents are usable for conflict detection.

After this method returns, contents will be closed and will no longer be usable

This method is often used in conjunction with commitContents(DriveContents, MetadataChangeSet).

Throws

IllegalStateException	if this method is called on contents that are currently opened in `MODE_WRITE_ONLY` or `MODE_READ_WRITE` or on contents that have been closed

public abstract Task<Void> setParents (DriveResource resource, Set<DriveId> parentIds)

Sets the parents of resource to the DriveId instances defined in parentIds. This will overwrite the current parent IDs with parentIds, so any parent IDs that should remain as parents but also be supplied in the Set. Do NOT modify parentIds after calling this method.

All parent IDs must be associated with DriveFolder resources.

If this resource is in the App Folder or one of its subfolders, all parents must also belong to the App Folder or one of its subfolders. Similarly, if this resource is outside of the App Folder, every parent must also be outside of the App Folder.

public abstract Task<Void> trash (DriveResource resource)

Moves the resource to trash. The user must be the owner. If the resource is a DriveFolder, the app must have access to all of its descendants.

Resources inside the App Folder cannot be trashed. See getAppFolder() for more information.

public abstract Task<Void> untrash (DriveResource resource)

Moves the resource out of the trash. The user must be the owner. If the resource is a DriveFolder, the app must have access to all of its descendants.

Resources inside the App Folder cannot be untrashed (because they cannot be trashed). See getAppFolder() for more information.

public abstract Task<Metadata> updateMetadata (DriveResource resource, MetadataChangeSet changeSet)

Updates the Metadata that is associated with this resource with the changes defined in changeSet.

Note that the user must have edit access to update certain metadata fields. See MetadataChangeSet.Builder for more information.

Note that the metadata of the root folder cannot be updated.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated April 12, 2018.