Module: file‐management

One of the useful module file-management helps you manage and handle files easier. There are two main types in this module.

• FileUtils: the basic file management, not recommended for Android 11+
• SAFUtils: the file management using Storage Access Framework (SAF)

Remember permissions are required to be set in AndroidManifest.xml.

<!-- optional for SAF -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

Before starting to use the utils, please first declare the instances in your program.

// Kotlin
val file = FileUtils() // optional
val saf = SAFUtils(this)

// Java
FileUtils file = new FileUtils();
SAFUtils saf = new SAFUtils(this);

Examples

Basic

Display the real file path of given Uri.

Warning: Not recommended to abuse toRealFilePath() or toRealFilePathFromDocumentTree() for handling files. Please use Uri instead.

// Kotlin
// for file
val path = uri.toRealFilePath()

// for directory (from document tree)
val path = uri.toRealFilePathFromDocumentTree()

// Java
// for file
String path = FileExtKt.toRealFilePath(uri);

// for directory (from document tree)
String path = FileExtKt.toRealFilePathFromDocumentTree(uri);

Storage Access Framework (SAF)

Ask to grant All File Access permission

// Kotlin
if (saf.isGrantedExternalStorageAccess()) {
    // actions to do when the permission is granted
} else saf.requestAllFileAccess()

// Java
if (saf.isGrantedExternalStorageAccess()) {
    // actions to do when the permission is granted
} else saf.requestAllFileAccess(true)

Note: if current SDK is lower than API 30 (Android 11), the requestAllFileAccess() will be replaced by requestWritePermission().

Set permanent access

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    super.onActivityResult(requestCode, resultCode, data)
    saf.setPermanentAccess(data)
}

// Java
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    saf.setPermanentAccess(data);
}

Select a file and do actions

// Kotlin
val intent = saf.intentOpenDocument
saf.registerActivityResultLauncher(this) { uri ->
    // actions to do after selected file
}.launch(intent)

// Java
Intent intent = saf.getIntentOpenDocument();
saf.registerActivityResultLauncher(this, uri -> {
    // actions to do after selected file
    return null;
}).launch(intent);

List directories of external storage (storage/emulated/0)

// Kotlin
val files = saf.listExternalStorage()

// Java
List<DocumentFile> files = saf.listExternalStorage();

List directories

// Kotlin
val files = saf.listDirectories(uri)

// Java
List<DocumentFile> files = saf.listDirectories(uri);

List directories with filter e.g. list only files

you can also use saf.listOnlyFiles(uri).

// Kotlin
val files = saf.listDirectories(uri).filter { it.isFile }

// Java
List<DocumentFile> files = saf.listDirectories(uri).stream().filter(DocumentFile::isFile);