Package org.apache.sling.api.request

# Interface RequestProgressTracker

@ProviderType public interface RequestProgressTracker
The `RequestProgressTracker` class provides the functionality to track the progress of request processing. Instances of this class are provided through the `SlingHttpServletRequest.getRequestProgressTracker()` method.

The following functionality is provided:

1. Track the progress of request processing through the `log(String)` and `log(String, Object...)` methods.
2. Ability to measure and track processing times of parts of request processing through the `startTimer(String)`, `logTimer(String)` and `logTimer(String, String, Object...)` methods.
3. Dumping the recording messages through the `dump(PrintWriter)` method.
4. Return the log messages through the `getMessages()` method.

Tracking Request Processing

As the request being processed, certain steps may be tracked by calling either of the `log` methods. A tracking entry consists of a time stamp managed by this class and a tracking message noting the actual step being tracked.

Timing Processing Steps

Certain steps during request processing may need to be timed in that the time required for processing should be recorded. Instances of this class maintain a map of named timers. Each timer is started (initialized or reset) by calling the `startTimer(String)` method. This method just records the starting time of the named timer and adds a tracking entry with the timer name as the message.

To record the number of milliseconds elapsed since a timer has been started, the `logTimer(String)` or `logTimer(String, String, Object...)` method may be called. This method logs a tracking entry with a message consisting of the name of the timer and the number of milliseconds elapsed since the timer was last `started`. The `logTimer` methods may be called multiple times to record several timed steps.

Calling the `startTimer(String)` method with the name of timer which already exists, resets the start time of the named timer to the current system time.

Retrieving Tracking Entries

The `dump(PrintWriter)` method may be used to write the tracking entries to the given `PrintWriter` to for example log them in a HTML comment. Alternatively the tracking entries may be retrieved as an iterator of messages through the `getMessages()` method. The formatting of the tracking entries is implementation specific.

## Method Summary

Modifier and Type
Method
Description
`void`
`done()`
Call this when done processing the request - only the first call of this method is processed, all further calls to this method are ignored.
`void`
`dump(@NotNull PrintWriter writer)`
Dumps the process timer entries to the given writer, one entry per line.
`default long`
`getDuration()`
Get the duration in nano seconds.
`@Nullable Iterator<String>`
`getMessages()`
Returns an `Iterator` of tracking entries.
`void`
`log(@NotNull String message)`
Creates an entry with the given message
`void`
`log(@NotNull String format, Object... args)`
Creates an entry with a message constructed from the given `MessageFormat` format evaluated using the given formatting arguments.
`void`
`logTimer(@NotNull String timerName)`
Logs an entry with the message set to the name of the timer and the number of milliseconds elapsed since the timer start.
`void`
`logTimer(@NotNull String timerName, @NotNull String format, Object... args)`
Logs an entry with the message constructed from the given `MessageFormat` pattern evaluated using the given arguments and the number of milliseconds elapsed since the timer start.
`void`
`startTimer(@NotNull String timerName)`
Starts a named timer.

## Method Details

### log

void log(@NotNull @NotNull String message)
Creates an entry with the given message

Parameters:
  `message` - The message

### log

void log(@NotNull @NotNull String format, Object... args)
Creates an entry with a message constructed from the given `MessageFormat` format evaluated using the given formatting arguments.

Parameters:
  `format` - The message
  `args` - Arguments for the message

### startTimer

void startTimer(@NotNull @NotNull String timerName)
Starts a named timer. If a timer of the same name already exists, it is reset to the current time.

Parameters:
  `timerName` - the name of the timer

### logTimer

void logTimer(@NotNull @NotNull String timerName)
Logs an entry with the message set to the name of the timer and the number of milliseconds elapsed since the timer start.

Parameters:
  `timerName` - the name of the timer

### logTimer

void logTimer(@NotNull @NotNull String timerName, @NotNull @NotNull String format, Object... args)
Logs an entry with the message constructed from the given `MessageFormat` pattern evaluated using the given arguments and the number of milliseconds elapsed since the timer start.

Parameters:
  `timerName` - the name of the timer
  `format` - The message
  `args` - Arguments for the message

### getMessages

@Nullable @Nullable Iterator<String> getMessages()
Returns an `Iterator` of tracking entries. If there are no messages `null` is returned.

Returns:
  An iterator with the messages or `null`

### dump

void dump(@NotNull @NotNull PrintWriter writer)
Dumps the process timer entries to the given writer, one entry per line.

Parameters:
  `writer` - Writer to dump to

### done

void done()
Call this when done processing the request - only the first call of this method is processed, all further calls to this method are ignored.

### getDuration

default long getDuration()
Get the duration in nano seconds.

Returns:
  The duration in nano seconds
Since:
  2.6.0 (Sling API Bundle 2.25.0)