#94: improve documentation and logging (#242)

cli/src/main/java/com/devonfw/tools/ide/io/FileAccess.java

@@ -1,6 +1,7 @@
 package com.devonfw.tools.ide.io;
 
 import java.nio.file.Path;
+import java.util.List;
 import java.util.function.Consumer;
 import java.util.function.Predicate;
 
@@ -213,4 +214,13 @@ default void extract(Path archiveFile, Path targetDir, Consumer<Path> postExtrac
    */
   Path findFirst(Path dir, Predicate<Path> filter, boolean recursive);
 
+  /**
+   * @param dir the {@link Path} to the directory where to list the children.
+   * @param filter the {@link Predicate} used to {@link Predicate#test(Object) decide} which children to include (if
+   * {@code true} is returned).
+   * @return all children of the given {@link Path} that match the given {@link Predicate}. Will be the empty list of
+   * the given {@link Path} is not an existing directory.
+   */
+  List<Path> listChildren(Path dir, Predicate<Path> filter);
+
 }

cli/src/main/java/com/devonfw/tools/ide/io/FileAccessImpl.java

@@ -763,4 +763,27 @@ private Path findFirstRecursive(Path dir, Predicate<Path> filter, boolean recurs
     return null;
   }
 
+  @Override
+  public List<Path> listChildren(Path dir, Predicate<Path> filter) {
+
+    if (!Files.isDirectory(dir)) {
+      return List.of();
+    }
+    List<Path> children = new ArrayList<>();
+    try (Stream<Path> childStream = Files.list(dir)) {
+      Iterator<Path> iterator = childStream.iterator();
+      while (iterator.hasNext()) {
+        Path child = iterator.next();
+        if (filter.test(child)) {
+          this.context.trace("Accepted file {}", child);
+          children.add(child);
+        } else {
+          this.context.trace("Ignoring file {} according to filter", child);
+        }
+      }
+    } catch (IOException e) {
+      throw new IllegalStateException("Failed to find children of directory " + dir, e);
+    }
+    return children;
+  }
 }