DocumentFile
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:
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 |
static
DocumentFile
|
fromFile(File file)
Create a |
static
DocumentFile
|
fromSingleUri(Context context, Uri singleUri)
Create a |
static
DocumentFile
|
fromTreeUri(Context context, Uri treeUri)
Create a |
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
|
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 |
Inherited methods | |
---|---|
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. |
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) . |
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) . |
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. |
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 |
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 |
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 |
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:
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. |
isVirtual
public abstract boolean isVirtual ()
Indicates if this file represents a virtual document.
Returns | |
---|---|
boolean |
true if this file is a 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. |
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:
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) . |
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) . |