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 and 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 java.io.PrintWriter writer) Dumps the process timer entries to the given writer, one entry per line.
@Nullable java.util.Iterator<java.lang.String>	getMessages() Returns an Iterator of tracking entries.
void	log(@NotNull java.lang.String message) Creates an entry with the given message
void	log(@NotNull java.lang.String format, java.lang.Object... args) Creates an entry with a message constructed from the given MessageFormat format evaluated using the given formatting arguments.
void	logTimer(@NotNull java.lang.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 java.lang.String timerName, @NotNull java.lang.String format, java.lang.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 java.lang.String timerName) Starts a named timer.

Method Detail

log

void log(@NotNull
         @NotNull java.lang.String message)

Creates an entry with the given message

Parameters:

message - The message

log

void log(@NotNull
         @NotNull java.lang.String format,
         java.lang.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 java.lang.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 java.lang.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 java.lang.String timerName,
              @NotNull
              @NotNull java.lang.String format,
              java.lang.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 java.util.Iterator<java.lang.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 java.io.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.