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:

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
  • dropped minSdkVersion to 10
  • added disk synchronization when copying to files
  • added getExtension()
  • added file support in fromSingleUri()
• v0.1.1: initial release