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]

Commencez par JDKDirectoryWatch et JDKFileTreeWatch, puis exécutez l’expérience Main de l’annexe sur les plateformes concernées et avec les différentes stratégies d’Overflow. Comparez les événements de déplacement observés aux exigences Must et Should énoncées ; la tâche ne peut être considérée comme terminée que lorsqu’un comportement convenu ainsi qu’une implémentation correspondante ou une conception documentée existent, mais l’issue n’identifie pas de tests.