Summary: Methods | Inherited Methods

DocumentFile

Kotlin |Java

public abstract class DocumentFile
extends Object

java.lang.Object
↳	androidx.documentfile.provider.DocumentFile

---

Representation of a document backed by either a DocumentsProvider or a raw file on disk. This is a utility class designed to emulate the traditional File interface. It offers a simplified view of a tree of documents, but it has substantial overhead. For optimal performance and a richer feature set, use the DocumentsContract methods and constants directly.

There are several differences between documents and traditional files:

• Documents express their display name and MIME type as separate fields, instead of relying on file extensions. Some documents providers may still choose to append extensions to their display names, but that's an implementation detail.
• A single document may appear as the child of multiple directories, so it doesn't inherently know who its parent is. That is, documents don't have a strong notion of path. You can easily traverse a tree of documents from parent to child, but not from child to parent.
• Each document has a unique identifier within that provider. This identifier is an opaque implementation detail of the provider, and as such it must not be parsed.

Before using this class, first consider if you really need access to an entire subtree of documents. The principle of least privilege dictates that you should only ask for access to documents you really need. If you only need the user to pick a single file, use Intent.ACTION_OPEN_DOCUMENT or Intent.ACTION_GET_CONTENT. If you want to let the user pick multiple files, add Intent.EXTRA_ALLOW_MULTIPLE. If you only need the user to save a single file, use Intent.ACTION_CREATE_DOCUMENT. If you use these APIs, you can pass the resulting Intent.getData() into fromSingleUri(Context, Uri) to work with that document.

If you really do need full access to an entire subtree of documents, start by launching Intent.ACTION_OPEN_DOCUMENT_TREE to let the user pick a directory. Then pass the resulting Intent.getData() into fromTreeUri(Context, Uri) to start working with the user selected tree.

As you navigate the tree of DocumentFile instances, you can always use getUri() to obtain the Uri representing the underlying document for that object, for use with ContentResolver.openInputStream(Uri), etc.

To simplify your code on devices running Build.VERSION_CODES.KITKAT or earlier, you can use fromFile(File) which emulates the behavior of a DocumentsProvider.

See also:

• DocumentsProvider
• DocumentsContract

Summary

Public methods
abstract boolean	canRead() Indicates whether the current context is allowed to read from this file.
abstract boolean	canWrite() Indicates whether the current context is allowed to write to this file.
abstract DocumentFile	createDirectory(String displayName) Create a new directory as a direct child of this directory.
abstract DocumentFile	createFile(String mimeType, String displayName) Create a new document as a direct child of this directory.
abstract boolean	delete() Deletes this file.
abstract boolean	exists() Returns a boolean indicating whether this file can be found.
DocumentFile	findFile(String displayName) Search through listFiles() for the first document matching the given display name.
static DocumentFile	fromFile(File file) Create a DocumentFile representing the filesystem tree rooted at the given File.
static DocumentFile	fromSingleUri(Context context, Uri singleUri) Create a DocumentFile representing the single document at the given Uri.
static DocumentFile	fromTreeUri(Context context, Uri treeUri) Create a DocumentFile representing the document tree rooted at the given Uri.
abstract String	getName() Return the display name of this document.
DocumentFile	getParentFile() Return the parent file of this document.
abstract String	getType() Return the MIME type of this document.
abstract Uri	getUri() Return a Uri for the underlying document represented by this file.
abstract boolean	isDirectory() Indicates if this file represents a directory.
static boolean	isDocumentUri(Context context, Uri uri) Test if given Uri is backed by a DocumentsProvider.
abstract boolean	isFile() Indicates if this file represents a file.
abstract boolean	isVirtual() Indicates if this file represents a virtual document.
abstract long	lastModified() Returns the time when this file was last modified, measured in milliseconds since January 1st, 1970, midnight.
abstract long	length() Returns the length of this file in bytes.
abstract DocumentFile[]	listFiles() Returns an array of files contained in the directory represented by this file.
abstract boolean	renameTo(String displayName) Renames this file to displayName.

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

Public methods

canRead

public abstract boolean canRead ()

Indicates whether the current context is allowed to read from this file.

Returns
boolean	true if this file can be read, false otherwise.

canWrite

public abstract boolean canWrite ()

Indicates whether the current context is allowed to write to this file.

Returns
boolean	true if this file can be written, false otherwise.

See also:

• DocumentsContract.Document.COLUMN_FLAGS
• DocumentsContract.Document.FLAG_SUPPORTS_DELETE
• DocumentsContract.Document.FLAG_SUPPORTS_WRITE
• DocumentsContract.Document.FLAG_DIR_SUPPORTS_CREATE

createDirectory

public abstract DocumentFile createDirectory (String displayName)

Create a new directory as a direct child of this directory.

Parameters
displayName	String: name of new directory

Returns
DocumentFile	file representing newly created directory, or null if failed

Throws
UnsupportedOperationException	when working with a single document created from fromSingleUri(Context, Uri).

See also:

• DocumentsContract.createDocument(ContentResolver, Uri, String, String)

createFile

public abstract DocumentFile createFile (String mimeType, 
                String displayName)

Create a new document as a direct child of this directory.

Parameters
mimeType	String: MIME type of new document, such as image/png or audio/flac
displayName	String: name of new document, without any file extension appended; the underlying provider may choose to append the extension

Returns
DocumentFile	file representing newly created document, or null if failed

Throws
UnsupportedOperationException	when working with a single document created from fromSingleUri(Context, Uri).

See also:

• DocumentsContract.createDocument(ContentResolver, Uri, String, String)

delete

public abstract boolean delete ()

Deletes this file.

Note that this method does not throw IOException on failure. Callers must check the return value.

Returns
boolean	true if this file was deleted, false otherwise.

See also:

• DocumentsContract.deleteDocument(ContentResolver, Uri)

exists

public abstract boolean exists ()

Returns a boolean indicating whether this file can be found.

Returns
boolean	true if this file exists, false otherwise.

findFile

public DocumentFile findFile (String displayName)

Search through listFiles() for the first document matching the given display name. Returns null when no matching document is found.

Parameters
displayName	String

Returns
DocumentFile

Throws
UnsupportedOperationException	when working with a single document created from fromSingleUri(Context, Uri).

fromFile

public static DocumentFile fromFile (File file)

Create a DocumentFile representing the filesystem tree rooted at the given File. This doesn't give you any additional access to the underlying files beyond what your app already has.

getUri() will return file:// Uris for files explored through this tree.

Parameters
file	File

Returns
DocumentFile

fromSingleUri

public static DocumentFile fromSingleUri (Context context, 
                Uri singleUri)

Create a DocumentFile representing the single document at the given Uri. This is only useful on devices running Build.VERSION_CODES.KITKAT or later, and will return null when called on earlier platform versions.

Parameters
context	Context
singleUri	Uri: the Intent.getData() from a successful Intent.ACTION_OPEN_DOCUMENT or Intent.ACTION_CREATE_DOCUMENT request.

Returns
DocumentFile

fromTreeUri

public static DocumentFile fromTreeUri (Context context, 
                Uri treeUri)

Create a DocumentFile representing the document tree rooted at the given Uri. This is only useful on devices running Build.VERSION_CODES.LOLLIPOP or later, and will return null when called on earlier platform versions.

Parameters
context	Context
treeUri	Uri: the Intent.getData() from a successful Intent.ACTION_OPEN_DOCUMENT_TREE request.

Returns
DocumentFile

getName

public abstract String getName ()

Return the display name of this document.

Returns
String

See also:

• DocumentsContract.Document.COLUMN_DISPLAY_NAME

getParentFile

public DocumentFile getParentFile ()

Return the parent file of this document. Only defined inside of the user-selected tree; you can never escape above the top of the tree.

The underlying DocumentsProvider only defines a forward mapping from parent to child, so the reverse mapping of child to parent offered here is purely a convenience method, and it may be incorrect if the underlying tree structure changes.

Returns
DocumentFile

getType

public abstract String getType ()

Return the MIME type of this document.

Returns
String

See also:

• DocumentsContract.Document.COLUMN_MIME_TYPE

getUri

public abstract Uri getUri ()

Return a Uri for the underlying document represented by this file. This can be used with other platform APIs to manipulate or share the underlying content. You can use isDocumentUri(Context, Uri) to test if the returned Uri is backed by a DocumentsProvider.

Returns
Uri

See also:

• Intent.setData(Uri)
• Intent.setClipData(android.content.ClipData)
• ContentResolver.openInputStream(Uri)
• ContentResolver.openOutputStream(Uri)
• ContentResolver.openFileDescriptor(Uri, String)

isDirectory

public abstract boolean isDirectory ()

Indicates if this file represents a directory.

Returns
boolean	true if this file is a directory, false otherwise.

See also:

• DocumentsContract.Document.MIME_TYPE_DIR

isDocumentUri

public static boolean isDocumentUri (Context context, 
                Uri uri)

Test if given Uri is backed by a DocumentsProvider.

Parameters
context	Context
uri	Uri

Returns
boolean

isFile

public abstract boolean isFile ()

Indicates if this file represents a file.

Returns
boolean	true if this file is a file, false otherwise.

See also:

• DocumentsContract.Document.COLUMN_MIME_TYPE

isVirtual

public abstract boolean isVirtual ()

Indicates if this file represents a virtual document.

Returns
boolean	true if this file is a virtual document.

See also:

• DocumentsContract.Document.FLAG_VIRTUAL_DOCUMENT

lastModified

public abstract long lastModified ()

Returns the time when this file was last modified, measured in milliseconds since January 1st, 1970, midnight. Returns 0 if the file does not exist, or if the modified time is unknown.

Returns
long	the time when this file was last modified.

See also:

• DocumentsContract.Document.COLUMN_LAST_MODIFIED

length

public abstract long length ()

Returns the length of this file in bytes. Returns 0 if the file does not exist, or if the length is unknown. The result for a directory is not defined.

Returns
long	the number of bytes in this file.

See also:

• DocumentsContract.Document.COLUMN_SIZE

listFiles

public abstract DocumentFile[] listFiles ()

Returns an array of files contained in the directory represented by this file.

Returns
DocumentFile[]	an array of files or null.

Throws
UnsupportedOperationException	when working with a single document created from fromSingleUri(Context, Uri).

See also:

• DocumentsContract.buildChildDocumentsUriUsingTree(Uri, String)

renameTo

public abstract boolean renameTo (String displayName)

Renames this file to displayName.

Note that this method does not throw IOException on failure. Callers must check the return value.

Some providers may need to create a new document to reflect the rename, potentially with a different MIME type, so getUri() and getType() may change to reflect the rename.

When renaming a directory, children previously enumerated through listFiles() may no longer be valid.

Parameters
displayName	String: the new display name.

Returns
boolean	true on success.

Throws
UnsupportedOperationException	when working with a single document created from fromSingleUri(Context, Uri).

See also:

• DocumentsContract.renameDocument(ContentResolver, Uri, String)

• Classes

  • DocumentFile