Add SAF directory observation

.github/workflows/build.yml

@@ -1,29 +1,45 @@
 name: Build source
 
+permissions:
+  contents: read
+
 on:
   workflow_dispatch:
   pull_request:
     types: [ opened, synchronize, reopened ]
     paths:
       - "dfc/**"
+      - "app/**"
+      - ".github/workflows/build.yml"
+      - "*.gradle"
+      - "gradle/**"
+      - "gradle.properties"
   push:
     branches: [ master ]
     paths:
       - "dfc/**"
+      - "app/**"
+      - ".github/workflows/build.yml"
+      - "*.gradle"
+      - "gradle/**"
+      - "gradle.properties"
 
 jobs:
   build:
+    name: Build
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
 
       - name: Set up JDK
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4
         with:
           distribution: "temurin"
           java-version: "17"
           cache: "gradle"
 
-      - name: Build DFC
-        run: ./gradlew :dfc:assemble
+      - name: Build project
+        run: ./gradlew :dfc:assemble :dfc:assembleDebugAndroidTest :app:assembleDebug

README.md

@@ -21,6 +21,7 @@ do not keep paying for the same queries again and again.
 - Raw `File` access via `fromFile(...)`.
 - Common `DocumentFile`-style methods and getters.
 - Faster directory listing and metadata access.
+- Event-driven observation of a directory's direct children.
 - Custom projections for lighter queries.
 - Convenience APIs like `count()`, `copyTo(destination)`, and `copyFrom(source)`.
 
@@ -70,6 +71,32 @@ Other entry points:
 Additional helpers like `count()`, `copyTo(destination)`, `copyFrom(source)`, and
 `listFiles(projection)` are available when you need them.
 
+### Observe a directory
+
+`observe()` watches the direct children of a SAF tree directory without polling:
+
+```kotlin
+val observer = directory.observe { event, document ->
+    println("$event: ${document.name}")
+}
+
+observer.startWatching(
+    onError = { error -> println("Observation stopped: $error") },
+    onReady = { println("Initial snapshot is ready") },
+)
+
+// Later, from the owning lifecycle:
+observer.close()
+```
+
+Files found during the initial scan aren't emitted. `onReady` runs after that scan, and `onError`
+reports why watching stopped. Callbacks run on a worker thread; close the observer with its
+lifecycle.
+
+Observation depends on provider change notifications. Each refresh scans all direct children, and
+rapid changes may be combined. Move events require stable document IDs; otherwise renames arrive as
+delete and create events, which rename tracking should also handle.
+
 ## Performance
 
 The sample app includes simple comparisons against AndroidX `DocumentFile`. Results depend on the

app/src/main/AndroidManifest.xml

@@ -18,6 +18,12 @@
         android:theme="@style/Theme.FileCompat"
         tools:ignore="AllowBackup">
 
+        <activity
+            android:name=".ObserverActivity"
+            android:exported="false"
+            android:label="@string/observer_title"
+            android:parentActivityName=".MainActivity" />
+
         <activity
             android:name=".MainActivity"
             android:exported="true"

app/src/main/java/com/lazygeniouz/filecompat/example/MainActivity.kt

@@ -26,6 +26,7 @@ class MainActivity : AppCompatActivity(R.layout.activity_main) {
     private lateinit var buttonDir: Button
     private lateinit var buttonFile: Button
     private lateinit var buttonProjections: Button
+    private lateinit var buttonObserver: Button
 
     private lateinit var textView: TextView
     private lateinit var progress: ProgressBar
@@ -44,6 +45,7 @@ class MainActivity : AppCompatActivity(R.layout.activity_main) {
                         buttonDir.isVisible = false
                         buttonFile.isVisible = false
                         buttonProjections.isVisible = false
+                        buttonObserver.isVisible = false
 
                         val generationResult = TestFileGenerator.generateTestFiles(
                             this@MainActivity, documentUri, selectedFileCount
@@ -53,6 +55,7 @@ class MainActivity : AppCompatActivity(R.layout.activity_main) {
                         buttonDir.isVisible = true
                         buttonFile.isVisible = true
                         buttonProjections.isVisible = true
+                        buttonObserver.isVisible = true
                         textView.text = generationResult
                     }
                 }
@@ -71,6 +74,7 @@ class MainActivity : AppCompatActivity(R.layout.activity_main) {
                         buttonDir.isVisible = false
                         buttonFile.isVisible = false
                         buttonProjections.isVisible = false
+                        buttonObserver.isVisible = false
                         val performanceResult = withContext(Dispatchers.IO) {
                             Performance.calculateDirectoryPerformance(
                                 this@MainActivity, documentUri
@@ -81,6 +85,7 @@ class MainActivity : AppCompatActivity(R.layout.activity_main) {
                         buttonDir.isVisible = true
                         buttonFile.isVisible = true
                         buttonProjections.isVisible = true
+                        buttonObserver.isVisible = true
                         textView.text = performanceResult
                     }
                 }
@@ -120,6 +125,7 @@ class MainActivity : AppCompatActivity(R.layout.activity_main) {
                         buttonDir.isVisible = false
                         buttonFile.isVisible = false
                         buttonProjections.isVisible = false
+                        buttonObserver.isVisible = false
 
                         val performanceResult = withContext(Dispatchers.IO) {
                             Performance.calculateProjectionPerformance(
@@ -131,6 +137,7 @@ class MainActivity : AppCompatActivity(R.layout.activity_main) {
                         buttonDir.isVisible = true
                         buttonFile.isVisible = true
                         buttonProjections.isVisible = true
+                        buttonObserver.isVisible = true
                         textView.text = performanceResult
                     }
                 }
@@ -143,6 +150,7 @@ class MainActivity : AppCompatActivity(R.layout.activity_main) {
         buttonDir = findViewById(R.id.buttonDir)
         buttonFile = findViewById(R.id.buttonFile)
         buttonProjections = findViewById(R.id.buttonProjections)
+        buttonObserver = findViewById(R.id.buttonObserver)
         textView = findViewById(R.id.fileNames)
         progress = findViewById(R.id.progress)
 
@@ -159,6 +167,10 @@ class MainActivity : AppCompatActivity(R.layout.activity_main) {
         buttonProjections.setOnClickListener {
             projectionResultLauncher.launch(getStorageIntent())
         }
+
+        buttonObserver.setOnClickListener {
+            startActivity(Intent(this, ObserverActivity::class.java))
+        }
     }
 
     override fun onCreateOptionsMenu(menu: Menu): Boolean {