Package org.metricshub.winrm

Class RemoteDirectoryListing

java.lang.Object
org.metricshub.winrm.RemoteDirectoryListing
public final class RemoteDirectoryListing extends Object
A listing of a remote directory being prepared, created by RemoteFile.list(): set the filters, then collect the result with execute() or stream it with stream(). 

 RemoteFileList logs = client.file("C:\\inetpub\\logs")
 	.list()
 	.glob("*.log")
 	.recursive()
 	.filesOnly()
 	.modifiedAfter(Instant.now().minus(Duration.ofDays(1)))
 	.execute();

The directory is walked on the host by a small PowerShell script, and every filter is evaluated there: only the matching entries travel. Without recursive(), only the directory's own entries are listed. With it, every subdirectory is traversed — whatever the filters, which select what is reported, not where the walk goes — except reparse points (junctions, symbolic links, mount points), which are reported but never descended into, so a junction looping back to its parent terminates. A subdirectory that cannot be read (typically access denied) does not stop the walk: its path is reported through onInaccessible(Consumer) and RemoteFileList.inaccessible().

A request is not thread-safe; configure it and call its terminals from one thread.

  • Method Details

    • glob

      public RemoteDirectoryListing glob(String glob)
      Report only the entries whose name (not path) matches the given Windows wildcard pattern: * matches any sequence of characters (including none), ? exactly one character, and every other character only itself, case-insensitively. The whole name must match: *.log matches app.log, not app.log.1 (unlike dir, which also matches 8.3 short names). With recursive(), every directory is still traversed; the pattern only selects what is reported.
      Parameters:
      glob - the pattern, e.g. *.log or u_ex??????.log
      Returns:
      this request

    • recursive

      public RemoteDirectoryListing recursive()
      List the whole tree below the directory instead of its own entries only, depth-first. Reparse points are reported but never descended into.
      Returns:
      this request

    • maxDepth

      public RemoteDirectoryListing maxDepth(int maxDepth)
      List recursively, down to the given depth: 1 is the directory's own entries (the same as a non-recursive listing), 2 adds the entries of its subdirectories, and so on. Implies recursive().
      Parameters:
      maxDepth - the deepest level listed (at least 1)
      Returns:
      this request

    • filesOnly

      public RemoteDirectoryListing filesOnly()
      Report files only (directories are still traversed with recursive()). Replaces directoriesOnly().
      Returns:
      this request

    • directoriesOnly

      public RemoteDirectoryListing directoriesOnly()
      Report directories only. Replaces filesOnly().
      Returns:
      this request

    • modifiedAfter

      public RemoteDirectoryListing modifiedAfter(Instant instant)
      Report only the entries last modified strictly after the given instant.
      Parameters:
      instant - the exclusive lower bound
      Returns:
      this request

    • modifiedBefore

      public RemoteDirectoryListing modifiedBefore(Instant instant)
      Report only the entries last modified strictly before the given instant.
      Parameters:
      instant - the exclusive upper bound
      Returns:
      this request

    • minSize

      public RemoteDirectoryListing minSize(long bytes)
      Report only the files of at least the given size. Directories have no size and are not filtered by it: combine with filesOnly() to leave them out.
      Parameters:
      bytes - the smallest size, inclusive
      Returns:
      this request

    • maxSize

      public RemoteDirectoryListing maxSize(long bytes)
      Report only the files of at most the given size. Directories have no size and are not filtered by it: combine with filesOnly() to leave them out.
      Parameters:
      bytes - the largest size, inclusive
      Returns:
      this request

    • onInaccessible

      public RemoteDirectoryListing onInaccessible(Consumer<String> consumer)
      Be told of each directory that could not be read (typically access denied): its path is given to the consumer as soon as the host reports it, and the walk goes on. Applies to both terminals; execute() also collects the paths in RemoteFileList.inaccessible(). The directory being listed is not concerned: when it cannot be read, the listing fails.
      Parameters:
      consumer - receives the path of each directory that could not be read
      Returns:
      this request

    • timeout

      public RemoteDirectoryListing timeout(Duration timeout)
      Override the client's timeout for this request. For execute() it is a wall-clock deadline for the whole listing; for stream() it is an inactivity timeout. The host signals it is alive every second while it walks, so the inactivity timeout only trips when the host is unresponsive — or when reading a single directory takes longer.
      Parameters:
      timeout - the timeout (at least one millisecond)
      Returns:
      this request

    • execute

      public RemoteFileList execute()
      List the directory and collect the result.
      Returns:
      the matching entries and the directories that could not be read
      Throws:
      WinRMClientException - when the directory cannot be listed (not found, a file, access denied, PowerShell unavailable or constrained)
      WinRMTimeoutException - when the timeout elapses first

    • stream

      public Stream<RemoteFileInfo> stream()
      List the directory and stream the entries as the host reports them: memory stays bounded whatever the size of the tree. 
      
 try (Stream<RemoteFileInfo> tree = client.file("D:\\data").list().recursive().stream()) {
 	tree.filter(RemoteFileInfo::isDirectory).forEach(System.out::println);
 }

      The stream must be closed — use try-with-resources. It holds the client's connection until it is exhausted or closed; closing it early stops the remote walk. The listing starts here, and the failures below are thrown from the stream's operations, when the host reports them. The timeout is an inactivity timeout (see timeout(Duration)).

      Returns:
      a lazy, sequential stream of entries, to use with try-with-resources
      Throws:
      WinRMClientException - when the directory cannot be listed
      WinRMTimeoutException - when the host does not answer in time