Package com.complexible.common.base

# Class ProgressMonitor

java.lang.Object
com.complexible.common.base.ProgressMonitor

All Implemented Interfaces:
  `Progress`, `ProgressReporter`, `AutoCloseable`

Direct Known Subclasses:
  `ProgressMonitor.DelegatingProgressMonitor`, `ProgressMonitor.ReportingProgressMonitor`

public abstract class ProgressMonitor extends Object implements ProgressReporter
A multi-thread safe progress monitor implementation that prints progress percent and elapsed time at specified percent increments. The monitor starts at a progress value of 0 and continue until progress value reaches a specified maximum value. Current progress value is incremented by the user causing the monitor to print a progress message. The interface is designed to be very minimal so that implementations will not incur any unnecessary overhead.

Author:
  Evren Sirin

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ProgressMonitor.Builder`
  Builder class for a customizable progress monitor
  `static class`
  `ProgressMonitor.DefaultProgressFormatter`
  `static class`
  `ProgressMonitor.DelegatingProgressMonitor`
  `static interface`
  `ProgressMonitor.ProgressFormatter`
  `static class`
  `ProgressMonitor.ReportingProgressMonitor`
  Chain more than one monitor / reporter

  ## Nested classes/interfaces inherited from interface com.complexible.common.base.Progress

  `Progress.Default`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ProgressMonitor()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static ProgressMonitor.Builder`
  `builder(String name)`
  `static ProgressMonitor`
  `create(String name, long maxProgress, PrintStream theOut)`
  Creates a default progress monitor that prints progress at every percent increments.
  `static ProgressMonitor`
  `fixedIntervalMonitor(String taskName, String elementName, long interval, PrintStream out)`
  Returns a progress monitor that prints status at fixed intervals and does not have a notion of `maxProgress`.
  `static ProgressMonitor`
  `minimal(String name, OutputStream output)`
  Returns a monitor that does not track progress value but prints a message at the beginning and at the end.
  `static ProgressMonitor`
  `newBufferedMonitor(ProgressMonitor monitor, long limit)`
  A non thread-safe progress monitor that propagates progress in batches to another progress monitor.
  `static ProgressMonitor`
  `newMultiplyingMonitor(ProgressMonitor monitor, int multiplier)`
  A progress monitor that multiples the progress by a constant amount before passing it to another progress monitor.
  `abstract void`
  `print()`
  Print the current progress, implementations may implement this as a no-op
  `static ProgressMonitor`
  `silent()`
  Returns a monitor that does absolutely nothing.
  `abstract void`
  `stop()`
  Stops the current progress monitor causing it to print a final message
  `static ProgressMonitor.ProgressFormatter`
  `tpsFormatter(long theTripleCount)`
  Returns a message format that appends the tps (triples/sec) metric at the end of default progress message regardless of what progress unit is used for the underlying progress monitor.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface com.complexible.common.base.Progress

  `current, hasProgress, maxProgress, stage`

  ### Methods inherited from interface com.complexible.common.base.ProgressReporter

  `close, increment, incrementMaxProgress, stage`

- ## Constructor Details

  - ### ProgressMonitor

    public ProgressMonitor()

- ## Method Details

  - ### print

    public abstract void print()
    Description copied from interface: `ProgressReporter`
    Print the current progress, implementations may implement this as a no-op
    Specified by:
      `print` in interface `ProgressReporter`

  - ### stop

    public abstract void stop()
    Stops the current progress monitor causing it to print a final message
    Specified by:
      `stop` in interface `ProgressReporter`

  - ### tpsFormatter

    public static ProgressMonitor.ProgressFormatter tpsFormatter(long theTripleCount)
    Returns a message format that appends the tps (triples/sec) metric at the end of default progress message regardless of what progress unit is used for the underlying progress monitor.

  - ### silent

    public static ProgressMonitor silent()
    Returns a monitor that does absolutely nothing. No progress is tracked and no messages are printed.

  - ### create

    public static ProgressMonitor create(String name, long maxProgress, PrintStream theOut)
    Creates a default progress monitor that prints progress at every percent increments.

  - ### builder

    public static ProgressMonitor.Builder builder(String name)

  - ### minimal

    public static ProgressMonitor minimal(String name, OutputStream output)
    Returns a monitor that does not track progress value but prints a message at the beginning and at the end.

  - ### fixedIntervalMonitor

    public static ProgressMonitor fixedIntervalMonitor(String taskName, String elementName, long interval, PrintStream out)
    Returns a progress monitor that prints status at fixed intervals and does not have a notion of `maxProgress`. This class is *NOT* thread-safe.
    Parameters:
      `taskName` - name of the task used at the beginning of each line
      `elementName` - name of the elements that are being processed (e.g. triples, literals, etc.)
      `interval` - number of elements to process before reporting progress
    Returns:
      progress monitor

  - ### newMultiplyingMonitor

    public static ProgressMonitor newMultiplyingMonitor(ProgressMonitor monitor, int multiplier)
    A progress monitor that multiples the progress by a constant amount before passing it to another progress monitor. If a progress monitor is tracking two distinct tasks where processing a single element is N time slower in one task then this monitor can be used so each time an element is processed in the slow task the progress will be incremented by N. The values of N typically come from empirical results.
    Parameters:
      `monitor` - delegated monitor
      `multiplier` - amount which progress will be multiplied
    Returns:
      new multiplying progress monitor

  - ### newBufferedMonitor

    public static ProgressMonitor newBufferedMonitor(ProgressMonitor monitor, long limit)
    A non thread-safe progress monitor that propagates progress in batches to another progress monitor. The default implementation of the progress monitor is thread-safe and incrementing the progress requires updating atomic counters and such. This progress monitor buffers progress in a local simple counter until the specified limit and then updates the progress in the delegating monitor decreasing the overall overhead.
    Parameters:
      `monitor` - delegated monitor
      `limit` - until which progress will be buffered locally
    Returns:
      new buffered progress monitor