CWAC-Document: A Better DocumentFile

This library contains a fork of the Android Support Library's DocumentFile and related classes. Whereas DocumentFile only supports working with document Uri values on API Level 19+, DocumentFileCompat supports other Uri values and older Android devices.

Installation

The artifact for this library is distributed via the CWAC repository, so you will need to configure that in your module's build.gradle file, along with your implementation or api statement:

repositories {
    maven {
        url "https://s3.amazonaws.com/repo.commonsware.com"
    }
}

dependencies {
    implementation 'com.commonsware.cwac:document:0.5.0'
}

Basic Usage

The core API for DocumentFileCompat is the same as for DocumentFile. Just switch your import statement to pull in com.commonsware.cwac.document.DocumentFileCompat.

There are three static methods on both DocumentFile and DocumentFileCompat for creating your initial instance: fromFile(), fromSingleUri(), and fromTreeUri(). DocumentFileCompat extends fromSingleUri() support to older devices and non-document Uri values. Also, fromSingleUri() on DocumentFileCompat supports Uri values with file schemes, where those Uri values point to a single file.

DocumentFileCompat also adds a number of convenience methods:

openInputStream() and openOutputStream(), to return an InputStream and OutputStream on the content, respectively
copyTo(OutputStream), copyTo(File), and copyTo(DocumentFileCompat), to copy this object's content to some other location
copyFrom(InputStream), copyFrom(File), copyFrom(DocumentFileCompat), and copyFromAsset(Context, String) to populate this object's content from some other source
getExtension() will try to return a usable file extension, either from the filesystem path or based on the MIME type

JavaDocs are available for your JavaDocing pleasure.

What Is Supported

In effect, there are four types of DocumentFileCompat:

One created via fromFile()
One created via fromTreeUri()
One created via fromSingleUri(), and where the app is running on API Level 19+ and the Uri is a document Uri
One created via fromSingleUri(), where either the app is running on an older device or the Uri is not a document Uri (but is one that supports the OpenableColumns, such as one retrieved from an activity supporting CATEGORY_OPENABLE, or has a file scheme)

The last bullet is the scenario added by DocumentFileCompat, over what is supported by DocumentFile.

However, the DocumentFile/DocumentFileCompat API is not uniformly implemented. Unsupported methods for a given DocumentFileCompat will thrown an UnsupportedOperationException. The following table outlines what is and is not supported for a given DocumentFileCompat type, where "yes" and "no" indicate if the method is supported, and bold values indicated the method is supported with a fixed return value:

Method	`fromFile()`	`fromTreeUri()`	`fromSingleUri()` (19+ document)	`fromSingleUri()` (other)
`canRead()`	yes	yes	yes	yes
`canWrite()`	yes	yes	yes	yes
`createDirectory()`	yes	yes	no	no
`createFile()`	yes	yes	no	no
`delete()`	yes	yes	yes	no
`exists()`	yes	yes	yes	yes (returns `canRead()`)
`getExtension()`	yes	yes	yes	yes
`getName()`	yes	yes	yes	yes
`getParentFile()`	yes	yes	yes	yes
`getType()`	yes	yes	yes	yes
`getUri()`	yes	yes	yes	yes
`isDirectory()`	yes	yes	yes	false
`isFile()`	yes	yes	yes	true
`isVirtual()`	false	yes	yes	false
`lastModified()`	yes	yes	yes	no
`length()`	yes	yes	yes	yes
`listFiles()`	yes	yes	no	no
`openInputStream()`	yes	no	yes	yes
`openOutputStream()`	yes	no	yes	yes
`renameTo()`	yes	yes	yes (API Level 21+)	no

findFile() is supported if listFiles() is supported.

Dependencies

This library depends upon androidx.annotation:annotation. Otherwise, it has no external dependencies.

Version

The current version is 0.5.0.

Demo

See the instrumentation test cases for examples of how to use this.

License

All of the code in this repository is licensed under the Apache Software License 2.0. Look to the headers of the Java source files to determine the actual copyright holder, as it is a mix of the Android Open Source Project and CommonsWare, LLC.

Questions

If you have questions regarding the use of this code, please post a question on Stack Overflow tagged with commonsware-cwac and android after searching to see if there already is an answer. Be sure to indicate what CWAC module you are having issues with, and be sure to include source code and stack traces if you are encountering crashes.

If you have encountered what is clearly a bug, or if you have a feature request, please read the contribution guidelines, then post an issue. Be certain to include complete steps for reproducing the issue. If you believe that the issue you have found represents a security bug, please follow the instructions in the contribution guidelines.

You are also welcome to join the CommonsWare Community and post questions and ideas to the CWAC category.

Do not ask for help via social media.

Release Notes

v0.5.0: migrated to AndroidX, fixed null pointer issue
v0.4.1: restored renameTo() for SingleDocumentFile
v0.4.0: bug fix, to allow listFiles() on a tree to return proper DocumentFileCompat objects based on the document's type (regular or tree)
v0.3.0: updated to current dependencies, raised minSdkVersion back to 14
v0.2.0
v0.1.1: initial release

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

commonsguy / cwac-document

Programming Languages