SakerLog

public class SakerLog

saker.build.runtime.execution.SakerLog

java.lang.Object

Logging utility class for printing formatted data to the specified output.

The class can be used in a builder pattern, instantiated by one of the static methods based on severity, and then calling println() for finishing. The instances are reusable.

The class defines a severity, which specifies the error level of the printed message. Each error message with a given severity will begin with an appropriate word for it. E.g. "Error".

The logger will print the messages to the specified output, or to a default stream when unspecified. The default stream is based on the current task (if any), else it will be printed to the current standard output of the process. In case it is necessary, the message will be encoded using UTF-8.

A path can be specified for the log messages, which will be prepended to the printed line.

Line and line positions can be specified for the log messages, which will be written out after the path. Line positions are only printed when a path was set.

The printed output has the following format:
The phrases between brackets are hierarchically optional.

 [path][:line][:posstart][-posend]: [severity]: [message]

Line number information is only present if a path was specified. Line position is only present, if line number is present. Intermediate ": " is omitted if no phrase comes after it.

This class also contains some utility functions for formatting other logging information.

Note: Functionality that automatically prints on the task standard output without a specified TaskContext as the output relies on an internal inheritable thread local variable. If you use your own threading implementation and don't inherit thread locals, make sure to explicitly call out(TaskContext) if you intend to write the output to the task output streams.

Nested types

public enum	CommonExceptionFormat Common ExceptionFormat implementation enumeration.
public interface	ExceptionFormat Interface for defining how a given exception should be displayed to the stream.

Fields

public static final int	SEVERITY_ERROR = 3 Severity for errors.
public static final int	SEVERITY_INFO = 1 Severity about generic information.
public static final int	SEVERITY_PLAIN = 0 Severity representing no severity.
public static final int	SEVERITY_SUCCESS = 4 Severity for representing success.
public static final int	SEVERITY_WARNING = 2 Severity for warnings.

Methods

public static SakerLog	error() Creates a logger with severity of SEVERITY_ERROR.
public static SakerLog	info() Creates a logger with severity of SEVERITY_INFO.
public SakerLog	line(int line) Sets the display line for this logger instance.
public static SakerLog	log() Creates a logger with severity of SEVERITY_PLAIN.
public SakerLog	out(PrintStream out) Sets the display output for this logger instance.
public SakerLog	out(TaskContext taskcontext) Sets the display output task for this logger instance.
public SakerLog	path(SakerPath path) Sets the path to display for this logger.
public SakerLog	position(int linestart, int lineend) Sets the range in the line for this logger instance.
public static void	printFormatException(ExceptionView exc) Prints a formatted exception view to the standard error with the default exception format.
public static void	printFormatException(ExceptionView exc, PrintStream ps) Prints a formatted exception view to the specified stream with the default exception format.
public static void	printFormatException(ExceptionView exc, PrintStream ps, SakerPath workingdir, ExceptionFormat format) Prints a formatted exception view to the specified stream with the specified exception format.
public static void	printFormatException(ExceptionView exc, PrintStream ps, ExceptionFormat format) Prints a formatted exception view to the specified stream with the specified exception format.
public static void	printFormatException(ExceptionView exc, Appendable ps) Prints a formatted exception view to the specified output with the default exception format.
public static void	printFormatException(ExceptionView exc, Appendable ps, SakerPath workingdir, ExceptionFormat format) Prints a formatted exception view to the specified output with the specified exception format.
public static void	printFormatException(ExceptionView exc, Appendable ps, ExceptionFormat format) Prints a formatted exception view to the specified output with the specified exception format.
public static void	printFormatException(ExceptionView exc, StringBuilder ps) Prints a formatted exception view to the specified string builder with the default exception format.
public static void	printFormatException(ExceptionView exc, StringBuilder ps, SakerPath workingdir, ExceptionFormat format) Prints a formatted exception view to the specified string builder with the specified exception format.
public static void	printFormatException(ExceptionView exc, StringBuilder ps, ExceptionFormat format) Prints a formatted exception view to the specified string builder with the specified exception format.
public static void	printFormatException(ExceptionView exc, SakerPath workingdir) Prints a formatted exception view to the standard error with the default exception format.
public static void	printFormatException(ExceptionView exc, SakerPath workingdir, PrintStream ps) Prints a formatted exception view to the specified stream with the default exception format.
public static void	printFormatException(ExceptionView exc, SakerPath workingdir, Appendable ps) Prints a formatted exception view to the specified output with the default exception format.
public static void	printFormatException(ExceptionView exc, SakerPath workingdir, StringBuilder ps) Prints a formatted exception view to the specified string builder with the default exception format.
public static void	printFormatException(ExceptionView exc, SakerPath workingdir, ExceptionFormat format) Prints a formatted exception view to the standard error with the specified exception format.
public static void	printFormatException(ExceptionView exc, ExceptionFormat format) Prints a formatted exception view to the standard error with the specified exception format.
public static void	printFormatExceptions(Iterable<? extends ExceptionView> exceptions, PrintStream ps, SakerPath workingdir, ExceptionFormat format) Prints multiple formatted exception views to the specified stream with the specified exception format.
public static void	printFormatExceptions(Iterable<? extends ExceptionView> exceptions, Appendable ps, SakerPath workingdir, ExceptionFormat format) Prints multiple formatted exception views to the specified output with the specified exception format.
public static void	printFormatExceptions(Iterable<? extends ExceptionView> exceptions, StringBuilder ps, SakerPath workingdir, ExceptionFormat format) Prints multiple formatted exception views to the specified string builder with the specified exception format.
public void	println() Prints a line with empty message.
public void	println(Object text) Prints a line with the argument object as a message.
public static SakerLog	severity(int severity) Creates a new logger with the specified severity.
public static SakerLog	success() Creates a logger with severity of SEVERITY_SUCCESS.
public SakerLog	taskScriptPosition(TaskContext taskcontext) Modifies the logger to print its contents using the given task context and have the path and positional information of it.
public SakerLog	verbose() Sets the display output for this logger instance to be verbose.
public static SakerLog	warning() Creates a logger with severity of SEVERITY_WARNING.

Inherited methods
From: Object clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

public static final int SEVERITY_ERROR = 3

Severity for errors.

public static final int SEVERITY_INFO = 1

Severity about generic information.

public static final int SEVERITY_PLAIN = 0

Severity representing no severity.

Will create a message without any severity phrase.

public static final int SEVERITY_SUCCESS = 4

Severity for representing success.

public static final int SEVERITY_WARNING = 2

Severity for warnings.

public static SakerLog error()

Creates a logger with severity of SEVERITY_ERROR.

The created logger.

public static SakerLog info()

Creates a logger with severity of SEVERITY_INFO.

The created logger.

public SakerLog line(int line)

Sets the display line for this logger instance.

The line is 0 (zero) indexed.

Line information is displayed only if there was a path set.

lineThe line. Less than zero to unset it.

this

path(SakerPath)

public static SakerLog log()

Creates a logger with severity of SEVERITY_PLAIN.

The created logger.

public SakerLog out(PrintStream out) throws NullPointerException

Sets the display output for this logger instance.

outThe output to display this log message on.

this

NullPointerExceptionIf the stream is null.

public SakerLog out(TaskContext taskcontext) throws NullPointerException

Sets the display output task for this logger instance.

The logger will use TaskContext.println(String) to print the message, which will therefore redisplayed automatically when the build system skips rerunning the task due to no incremental changes.

Note: this logger instance won't be reusable outside of this task execution, unless the output is reset.

taskcontextThe task context to use for printing.

this

NullPointerExceptionIf the task context is null.

public SakerLog path(SakerPath path)

Sets the path to display for this logger.

The logger will attempt to relativize the path based on the current task information. If this method is called in a context of a build system task, then SakerPathFiles.toRelativeString(SakerPath) will be called on it, which tries to convert it to a relative path based on the current execution configuration.

pathThe path, or null to disable it.

this

public SakerLog position(int linestart, int lineend)

Sets the range in the line for this logger instance.

Parameters are 0 (zero) indexed.

Only affects the output if line(int) is not negative.

If the line end parameter extends beyond the actual end of the line, the range is considered to be multi-line.

If the line start is non-negative, and the line end less than line start, the only the offset in the line is set.

linestartThe range start index in the line. (inclusive)

lineendThe range end index in the line. (inclusive)

this

public static void printFormatException(ExceptionView exc) throws NullPointerException

Prints a formatted exception view to the standard error with the default exception format.

excThe exception view.

NullPointerExceptionIf the exception view is null.