Class Scanner

All Implemented Interfaces:
Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle

public class Scanner extends ContainerLifeCycle
Scanner Utility for scanning a directory for added, removed and changed files and reporting these events via registered Listeners. The scanner operates on the Path.toRealPath(LinkOption...) of the files scanned and can be configured to follow symlinks.
  • Field Details

    • DEFAULT_SCAN_DEPTH

      public static final int DEFAULT_SCAN_DEPTH
      When walking a directory, a depth of 1 ensures that the directory's descendants are visited, not just the directory itself (as a file).
      See Also:
    • MAX_SCAN_DEPTH

      public static final int MAX_SCAN_DEPTH
      See Also:
  • Constructor Details

    • Scanner

      public Scanner()
    • Scanner

      public Scanner(Scheduler scheduler)
    • Scanner

      public Scanner(Scheduler scheduler, boolean reportRealPaths)
      Parameters:
      scheduler - The scheduler to use for scanning.
      reportRealPaths - If true, the Scanner.Listeners are called with the real path of scanned files.
  • Method Details

    • getScanInterval

      public int getScanInterval()
      Get the scan interval
      Returns:
      interval between scans in seconds
    • setScanInterval

      public void setScanInterval(int scanInterval)
      Set the scan interval
      Parameters:
      scanInterval - pause between scans in seconds, or 0 for no scan after the initial scan.
    • setScanDirs

      public void setScanDirs(List<Path> dirs)
    • addFile

      public void addFile(Path path)
      Add a file to be scanned. The file must not be null, and must exist.
      Parameters:
      path - the Path of the file to scan.
    • addDirectory

      public IncludeExcludeSet<PathMatcher,Path> addDirectory(Path p)
      Add a directory to be scanned. The directory must not be null and must exist.
      Parameters:
      p - the directory to scan.
      Returns:
      an IncludeExcludeSet to which the caller can add PathMatcher patterns to match
    • setFilenameFilter

      @Deprecated public void setFilenameFilter(FilenameFilter filter)
      Deprecated.
      Apply a filter to files found in the scan directory. Only files matching the filter will be reported as added/changed/removed.
      Parameters:
      filter - the filename filter to use
    • getFilenameFilter

      @Deprecated public FilenameFilter getFilenameFilter()
      Deprecated.
      Get any filter applied to files in the scan dir.
      Returns:
      the filename filter
    • getScannables

      public Set<Path> getScannables()
    • getScanDepth

      public int getScanDepth()
      Get the scanDepth.
      Returns:
      the scanDepth
    • setScanDepth

      public void setScanDepth(int scanDepth)
      Set the scanDepth.
      Parameters:
      scanDepth - the scanDepth to set
    • isAutoStartScanning

      public boolean isAutoStartScanning()
      Test if scanning should start automatically with Scanner.AbstractLifeCycle.start()
      Returns:
      true if scanning should start automatically, false to have scanning is deferred to a later manual call to startScanning()
    • setAutoStartScanning

      public void setAutoStartScanning(boolean autostart)
      Flag to control scanning auto start feature.

      If choosing to defer the automatic scanning, a future call to startScanning() is required to initiate this Scanner so that it can begin report files in the setScanDirs(List)

      Parameters:
      autostart - true if scanning should start automatically, false to defer start of scanning to a later call to startScanning()
    • setReportExistingFilesOnStartup

      public void setReportExistingFilesOnStartup(boolean reportExisting)
      Whether or not an initial scan will report all files as being added.
      Parameters:
      reportExisting - if true, all files found on initial scan will be reported as being added, otherwise not
    • getReportExistingFilesOnStartup

      public boolean getReportExistingFilesOnStartup()
    • setReportDirs

      public void setReportDirs(boolean dirs)
      Set if found directories should be reported.
      Parameters:
      dirs - true to report directory changes as well
    • getReportDirs

      public boolean getReportDirs()
    • addListener

      public void addListener(Scanner.Listener listener)
      Add an added/removed/changed listener
      Parameters:
      listener - the listener to add
    • removeListener

      public void removeListener(Scanner.Listener listener)
      Remove a registered listener
      Parameters:
      listener - the Listener to be removed
    • doStart

      public void doStart() throws Exception
      Start the scanning action.
      Overrides:
      doStart in class ContainerLifeCycle
      Throws:
      AbstractLifeCycle.StopException - If thrown, the lifecycle will immediately be stopped.
      Exception - If there was a problem starting. Will cause a transition to FAILED state
    • startScanning

      public void startScanning()
      Start scanning.

      This will perform the initial scan of the directories setScanDirs(List) and schedule future scans, following all of the configuration of the scan (eg: setReportExistingFilesOnStartup(boolean))

    • doStop

      public void doStop() throws Exception
      Stop the scanning.
      Overrides:
      doStop in class ContainerLifeCycle
      Throws:
      Exception - If there was a problem stopping. Will cause a transition to FAILED state
    • reset

      public void reset()
      Clear the list of scannables. The scanner must first be in the stopped state.
    • exists

      public boolean exists(String path)
      Parameters:
      path - tests if the path exists
      Returns:
      true if the path exists in one of the scandirs
    • nudge

      public void nudge()
      Hint to the scanner to perform a scan cycle as soon as possible. NOTE that the scan is not guaranteed to have happened by the time this method returns.
    • scan

      public void scan(Callback complete)
      Get the scanner to perform a scan cycle as soon as possible and call the Callback when the scan is finished or failed.
      Parameters:
      complete - called when the scan cycle finishes or fails.