DocumentFile

public abstract class DocumentFile

Representation of a document backed by either a android.provider.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 android.provider.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 ACTION_OPEN_DOCUMENT or ACTION_GET_CONTENT. If you want to let the user pick multiple files, add EXTRA_ALLOW_MULTIPLE. If you only need the user to save a single file, use ACTION_CREATE_DOCUMENT. If you use these APIs, you can pass the resulting getData into fromSingleUri to work with that document.

If you really do need full access to an entire subtree of documents, start by launching ACTION_OPEN_DOCUMENT_TREE to let the user pick a directory. Then pass the resulting getData into fromTreeUri 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 openInputStream, etc.

To simplify your code on devices running KITKAT or earlier, you can use fromFile which emulates the behavior of a android.provider.DocumentsProvider.

See also
DocumentsProvider
DocumentsContract

Summary

Public methods
abstract boolean

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

Indicates whether the current context is allowed to write to this file.
abstract @Nullable DocumentFile

Create a new directory as a direct child of this directory.
abstract @Nullable DocumentFile
createFile(@NonNull String mimeType, @NonNull String displayName)

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

Deletes this file.
abstract boolean

Returns a boolean indicating whether this file can be found.
@Nullable DocumentFile
findFile(@NonNull String displayName)

Search through listFiles for the first document matching the given display name.
static @NonNull DocumentFile

Create a DocumentFile representing the filesystem tree rooted at the given File.
static @Nullable DocumentFile
fromSingleUri(@NonNull Context context, @NonNull Uri singleUri)

Create a DocumentFile representing the single document at the given Uri.
static @Nullable DocumentFile
fromTreeUri(@NonNull Context context, @NonNull Uri treeUri)

Create a DocumentFile representing the document tree rooted at the given Uri.
abstract @Nullable String

Return the display name of this document.
@Nullable DocumentFile

Return the parent file of this document.
abstract @Nullable String

Return the MIME type of this document.
abstract @NonNull Uri

Return a Uri for the underlying document represented by this file.
abstract boolean

Indicates if this file represents a directory.
static boolean

Test if given Uri is backed by a android.provider.DocumentsProvider.
abstract boolean

Indicates if this file represents a file.
abstract boolean

Indicates if this file represents a virtual document.
abstract long

Returns the time when this file was last modified, measured in milliseconds since January 1st, 1970, midnight.
abstract long

Returns the length of this file in bytes.
abstract @NonNull DocumentFile[]

Returns an array of files contained in the directory represented by this file.
abstract boolean
renameTo(@NonNull String displayName)

Renames this file to displayName.

Public methods

canRead

Added in 1.0.0
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

Added in 1.0.0
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
COLUMN_FLAGS
FLAG_SUPPORTS_DELETE
FLAG_SUPPORTS_WRITE
FLAG_DIR_SUPPORTS_CREATE

createDirectory

Added in 1.0.0
public abstract @Nullable DocumentFile createDirectory(@NonNull String displayName)

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

Parameters
@NonNull String displayName

name of new directory
Returns
@Nullable DocumentFile

file representing newly created directory, or null if failed
Throws
java.lang.UnsupportedOperationException

when working with a single document created from fromSingleUri.
See also
createDocument

createFile

Added in 1.0.0
public abstract @Nullable DocumentFile createFile(@NonNull String mimeType, @NonNull String displayName)

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

Parameters
@NonNull String mimeType

MIME type of new document, such as image/png or audio/flac
@NonNull String displayName

name of new document, without any file extension appended; the underlying provider may choose to append the extension
Returns
@Nullable DocumentFile

file representing newly created document, or null if failed
Throws
java.lang.UnsupportedOperationException

when working with a single document created from fromSingleUri.
See also
createDocument

delete

Added in 1.0.0
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
deleteDocument

exists

Added in 1.0.0
public abstract boolean exists()

Returns a boolean indicating whether this file can be found.

Returns
boolean

true if this file exists, false otherwise.

findFile

Added in 1.0.0
public @Nullable DocumentFile findFile(@NonNull String displayName)

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

Throws
java.lang.UnsupportedOperationException

when working with a single document created from fromSingleUri.

fromFile

Added in 1.0.0
public static @NonNull DocumentFile fromFile(@NonNull 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.

fromSingleUri

Added in 1.0.0
public static @Nullable DocumentFile fromSingleUri(@NonNull Context context, @NonNull Uri singleUri)

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

Parameters
@NonNull Uri singleUri

the getData from a successful ACTION_OPEN_DOCUMENT or ACTION_CREATE_DOCUMENT request.

fromTreeUri

Added in 1.0.0
public static @Nullable DocumentFile fromTreeUri(@NonNull Context context, @NonNull Uri treeUri)

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

Parameters
@NonNull Uri treeUri

the getData from a successful ACTION_OPEN_DOCUMENT_TREE request.

getName

Added in 1.0.0
public abstract @Nullable String getName()

Return the display name of this document.

See also
COLUMN_DISPLAY_NAME

getParentFile

Added in 1.0.0
public @Nullable 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 android.provider.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.

getType

Added in 1.0.0
public abstract @Nullable String getType()

Return the MIME type of this document.

See also
COLUMN_MIME_TYPE

getUri

Added in 1.0.0
public abstract @NonNull 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 to test if the returned Uri is backed by a android.provider.DocumentsProvider.

See also
setData
setClipData
openInputStream
openOutputStream
openFileDescriptor

isDirectory

Added in 1.0.0
public abstract boolean isDirectory()

Indicates if this file represents a directory.

Returns
boolean

true if this file is a directory, false otherwise.
See also
MIME_TYPE_DIR

isDocumentUri

Added in 1.0.0
public static boolean isDocumentUri(@NonNull Context context, @Nullable Uri uri)

Test if given Uri is backed by a android.provider.DocumentsProvider.

isFile

Added in 1.0.0
public abstract boolean isFile()

Indicates if this file represents a file.

Returns
boolean

true if this file is a file, false otherwise.
See also
COLUMN_MIME_TYPE

isVirtual

Added in 1.0.0
public abstract boolean isVirtual()

Indicates if this file represents a virtual document.

Returns
boolean

true if this file is a virtual document.
See also
FLAG_VIRTUAL_DOCUMENT

lastModified

Added in 1.0.0
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
COLUMN_LAST_MODIFIED

length

Added in 1.0.0
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
COLUMN_SIZE

listFiles

Added in 1.0.0
public abstract @NonNull DocumentFile[] listFiles()

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

Returns
@NonNull DocumentFile[]

an array of files.
Throws
java.lang.UnsupportedOperationException

when working with a single document created from fromSingleUri.
See also
buildChildDocumentsUriUsingTree

renameTo

Added in 1.0.0
public abstract boolean renameTo(@NonNull 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
@NonNull String displayName

the new display name.
Returns
boolean

true on success.
Throws
java.lang.UnsupportedOperationException

when working with a single document created from fromSingleUri.
See also
renameDocument