What to expect when a directory is moved?

Problem

If a non-empty directory is moved from one location in the scope of a recursive watch (the source) to another location in the scope (the target), then at least which events should be observable?

• 1. DELETED of the source
• 2. CREATED of the target
• 3. DELETED of each content item of the source
• 4. CREATED of each content item of the target

(A solution to this problem probably becomes more complicated when the content items are themselves non-empty directories, but ignore that "detail" for now...)

Analysis

There is some variety in what currently (main, ec14259) happens, depending on the platform and overflow strategy:

Notes:

• Windows does supports passing modifier ExtendedWatchEventModifier.FILE_TREE to Path.register(...), so the library uses a single file-tree watch (JDKDirectoryWatch where recursive is true). macOS doesn't support this, so the library uses a tree of single-directory watches (JDKFileTreeWatch).
• The "(+3)" in the macOS-DIFF row indicates that, logically, it should also generate DELETED events, but due to a bug, it doesn't. This doesn't affect the bigger point of this issue, though.
• I haven't tested on Linux, but I expect it to be the same as on macOS.

Toward a design

I think the following requirements would make sense:

• "Must":
  • 1+2
  • If 3, then 4
  • If 4, then 3
• "Should":
  • 3+4

Achieving the "should" using a single file-tree watch on Windows seems quite messy. (We would need to do a lot of extra bookkeeping that might defeat the purpose of using the single file-tree watch in the first place.) An alternative path forward could be to always use a tree of single-directory watches. However, even in that case, the issue remains that it would work only for overflow strategy DIFF. Long story short, I don't think there's an easy fix here, and perhaps some more extensive redesign is needed.

Appendix: Experiments

Code

package engineering.swat.watch;

import java.io.IOException;
import java.nio.file.Files;

public class Main {
    public static void main(String[] args) throws IOException, InterruptedException {
        for (var whichFiles : Approximation.values()) {
            System.out.println();
            System.out.println("-- Overflow strategy: " + whichFiles + " --");
            System.out.println();

            // Create file tree
            var parent = Files.createTempDirectory("");
            var child1 = Files.createDirectories(parent.resolve("from"));
            var child2 = Files.createDirectories(parent.resolve("to"));

            // Create directory to be moved
            var directory = Files.createDirectory(child1.resolve("directory"));
            Files.createFile(directory.resolve("file1.txt"));
            Files.createFile(directory.resolve("file2.txt"));

            // Start a watch for the whole file tree
            try (var watch = Watch
                    .build(parent, WatchScope.PATH_AND_ALL_DESCENDANTS)
                    .onOverflow(whichFiles)
                    .on(System.out::println)
                    .start()) {

                // Move directory
                var source = child1.resolve(directory.getFileName());
                var target = child2.resolve(directory.getFileName());
                Files.move(source, target);

                // Wait for events
                Thread.sleep(30000);
            }
        }

        System.exit(0);
    }
}

Data: Windows

-- Overflow strategy: NONE --

WatchEvent[C:\Users\sung-\AppData\Local\Temp\6731006847162901629, MODIFIED, from\directory]
WatchEvent[C:\Users\sung-\AppData\Local\Temp\6731006847162901629, DELETED, from\directory]
WatchEvent[C:\Users\sung-\AppData\Local\Temp\6731006847162901629, CREATED, to\directory]
WatchEvent[C:\Users\sung-\AppData\Local\Temp\6731006847162901629, MODIFIED, to]

-- Overflow strategy: ALL --

WatchEvent[C:\Users\sung-\AppData\Local\Temp\8880121093523188257, MODIFIED, from\directory]
WatchEvent[C:\Users\sung-\AppData\Local\Temp\8880121093523188257, DELETED, from\directory]
WatchEvent[C:\Users\sung-\AppData\Local\Temp\8880121093523188257, CREATED, to\directory]
WatchEvent[C:\Users\sung-\AppData\Local\Temp\8880121093523188257, MODIFIED, to]

-- Overflow strategy: DIFF --

WatchEvent[C:\Users\sung-\AppData\Local\Temp\15514851762373591259, DELETED, from\directory]
WatchEvent[C:\Users\sung-\AppData\Local\Temp\15514851762373591259, CREATED, to\directory]
WatchEvent[C:\Users\sung-\AppData\Local\Temp\15514851762373591259, MODIFIED, to]

Data: macOS

-- Overflow strategy: NONE --

WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/16128028026906265986, CREATED, to/directory]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/16128028026906265986, MODIFIED, from]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/16128028026906265986, DELETED, from/directory]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/16128028026906265986, MODIFIED, to]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/16128028026906265986, OVERFLOW, to/directory]

-- Overflow strategy: ALL --

WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/6607535855848809431, DELETED, from/directory]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/6607535855848809431, MODIFIED, from]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/6607535855848809431, MODIFIED, to]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/6607535855848809431, CREATED, to/directory]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/6607535855848809431, OVERFLOW, to/directory]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/6607535855848809431, CREATED, to/directory/file2.txt]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/6607535855848809431, CREATED, to/directory/file1.txt]

-- Overflow strategy: DIFF --

WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/3395878405261375498, MODIFIED, from]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/3395878405261375498, DELETED, from/directory]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/3395878405261375498, CREATED, to/directory]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/3395878405261375498, MODIFIED, to]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/3395878405261375498, OVERFLOW, to/directory]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/3395878405261375498, CREATED, to/directory/file2.txt]
WatchEvent[/var/folders/k3/fpm2wy9s6l16x1cchqr9k7wh0000gn/T/3395878405261375498, CREATED, to/directory/file1.txt]

JDKDirectoryWatch と JDKFileTreeWatch から始め、次に、関連するプラットフォーム上で、さまざまな Overflow 戦略を用いて付録の Main 実験を実行します。観測された移動イベントを、記載されている Must および Should の要件と比較します。完了とするには、合意された動作と、それに対応する実装または文書化された設計が必要ですが、この issue ではテストが特定されていません。