Package org.apache.sis.util.logging
Class MonolineFormatter
A formatter writing log messages on a single line. Compared to the JDK Configuration from
The format can also be set from a
SimpleFormatter,
this formatter uses only one line per message instead of two. For example, messages formatted by
MonolineFormatter may look like:
By default,
Logging example 00:01CONFIG[MyApplication] Read configuration from “my-application/setup.xml”.00:03INFO[EPSGFactory] Connected to the EPSG database version 9.1 on Derby 10.14.00:12WARNING[NetcdfStore] Read “foo.nc” in 0.2 second.
MonolineFormatter shows only the level and the message. One or two additional
fields can be inserted between the level and the message if the setTimeFormat(String) or
setSourceFormat(String) methods are invoked with o non-null argument. Examples:
setTimeFormat("HH:mm:ss")for formatting the time like00:00:04", as time elapsed since theMonolineFormattercreation time.setSourceFormat("logger:long")for formatting the full logger name (e.g."org.apache.sis.storage.netcdf").setSourceFormat("class:short")for formatting the short class name, without package (e.g."NetcdfStore").
Configuration from logging.properties
The format can also be set from a logging.properties file.
For example, user can cut and paste the following properties into logging.properties:
See########################################################################### # Properties for the apache.sis.org MonolineFormatter. # By default, MonolineFormatter displays only the log level # and the message. Additional options can be specified here: # # time: If set, writes the time elapsed since initialization. # The argument specifies the output pattern. For example, # the "HH:mm:ss.SSSS" pattern displays the hours, minutes, # seconds and milliseconds. # # source: If set, writes the source logger name or the source class name. # Valid argument values are "none", "logger:short", "logger:long", # "class:short", "class:long" and "class.method". ########################################################################### org.apache.sis.util.logging.MonolineFormatter.time = HH:mm:ss.SSS org.apache.sis.util.logging.MonolineFormatter.source = class:short
setTimeFormat(String) and setSourceFormat(String) for more information about the
above time and source properties. Encoding and logging level are configured separately,
typically on the JDK ConsoleHandler like below:
java.util.logging.ConsoleHandler.encoding = UTF-8 java.util.logging.ConsoleHandler.level = FINE
Thread safety
The sameMonolineFormatter instance can be safely used by many threads without synchronization
on the part of the caller. Subclasses should make sure that any overridden methods remain safe to call
from multiple threads.- Since:
- 0.3
- See Also:
Defined in the sis-utility module
-
Constructor Summary
ConstructorsConstructorDescriptionConstructs a defaultMonolineFormatter.MonolineFormatter(Handler handler) Constructs aMonolineFormatterconfigured for the given handler. -
Method Summary
Modifier and TypeMethodDescriptionformat(LogRecord record) Formats the given log record and returns the formatted string.formatMessage(LogRecord record) Returns the localized message from the given log record.Returns the string to write on the left side of the first line of every log records, ornullif none.getLevelColor(Level level) Returns the color used for the given level, ornullif none.Returns the format for the source, ornullis the source is not shown.Returns the format for elapsed time, ornullif the time is not shown.static MonolineFormatterinstall()Installs aMonolineFormatterfor the root logger, or returns the existing instance if any.static MonolineFormatterInstalls aMonolineFormatterfor the specified logger, or returns the existing instance if any.voidresetLevelColors(boolean enabled) Resets the colors setting to its default value.voidsetHeader(String header) Sets the string to write on the left side of the first line of every log records.voidsetLevelColor(Level level, String color) Sets the color to use for the given level, ornullfor removing colorization.voidsetSourceFormat(String format) Sets the format for displaying the source, or hides the source field.voidsetTimeFormat(String pattern) Sets the format for elapsed time, or hides the time field.
-
Constructor Details
-
MonolineFormatter
public MonolineFormatter()Constructs a defaultMonolineFormatter. This no-argument constructor is invoked by the logging system if thelogging.propertiesfile contains the following line:java.util.logging.ConsoleHandler.formatter = org.apache.sis.util.logging.MonolineFormatter
- Since:
- 1.0
-
MonolineFormatter
Constructs aMonolineFormatterconfigured for the given handler.Auto-configuration from the handler
Formatters are often associated to a particular handler. If this handler is known, giving it at construction time can help this formatter to configure itself. This handler is only a hint - it will not be modified, and no reference to that handler will be kept by this constructor.- Parameters:
handler- The handler to be used with this formatter, ornullif unknown.- See Also:
-
-
Method Details
-
getHeader
Returns the string to write on the left side of the first line of every log records, ornullif none. This is a string to be shown just before the level.- Returns:
- the string to write on the left side of the first line of every log records, or
nullif none.
-
setHeader
Sets the string to write on the left side of the first line of every log records.- Parameters:
header- The string to write on the left side of the first line of every log records, ornullif none.
-
getTimeFormat
Returns the format for elapsed time, ornullif the time is not shown. This method returns the pattern specified by the last call to thesetTimeFormat(String)method, or the patten specified by theorg.apache.sis.util.logging.MonolineFormatter.timeproperty in thejre/lib/logging.propertiesfile.- Returns:
- the time pattern, or
nullif elapsed time is not formatted.
-
setTimeFormat
Sets the format for elapsed time, or hides the time field. The pattern must matches the format specified inSimpleDateFormat, but for the time part only (no date).Example: The"HH:mm:ss.SSS"pattern will display the elapsed time in hours, minutes, seconds and milliseconds.- Parameters:
pattern- the time pattern, ornullto disable time formatting.- Throws:
IllegalArgumentException- if the given pattern is invalid.
-
getSourceFormat
Returns the format for the source, ornullis the source is not shown. This method returns the source format specified by the last call to thesetSourceFormat(String)method, or the format specified by theorg.apache.sis.util.logging.MonolineFormatter.sourceproperty in thejre/lib/logging.propertiesfile.- Returns:
- the source format, or
nullif source is not formatted.
-
setSourceFormat
Sets the format for displaying the source, or hides the source field. The given format can be any of the following values, from more verbose to less verbose:nullfor hiding the source field."class:long"for the source class name"logger:long"for the logger name"class:short"for the source class name without the package part."logger:short"for the logger name without the package part."class.method"for the short class name followed by the source method name
- Parameters:
format- the format for displaying the source, ornullif the source shall not be formatted.- Throws:
IllegalArgumentException- if the given argument is not one of the recognized format names.
-
getLevelColor
Returns the color used for the given level, ornullif none. The current set of supported colors are"red","green","yellow","blue","magenta","cyan"and"gray". This set may be extended in any future SIS version.- Parameters:
level- the level for which to get the color.- Returns:
- the color for the given level, or
nullif none.
-
setLevelColor
Sets the color to use for the given level, ornullfor removing colorization. This method should be invoked only if this formatter is associated to aHandlerwriting to a terminal supporting ANSI escape codes (a.k.a. ECMA-48, ISO/IEC 6429 and X3.64 standards).The given
colorargument shall be one of the values documented in thegetLevelColor(Level)method.- Parameters:
level- the level for which to set a new color.color- the case-insensitive new color, ornullif none.- Throws:
IllegalArgumentException- if the given color is not one of the recognized values.
-
resetLevelColors
public void resetLevelColors(boolean enabled) Resets the colors setting to its default value.- If
enabledistrue, then this method defines a default set of colors. - If
enabledisfalse, then this method resets the formatting to plain text.
- Parameters:
enabled-truefor defining a default set of colors, orfalsefor removing all colors.
- If
-
format
Formats the given log record and returns the formatted string. See the class javadoc for information on the log format. -
formatMessage
Returns the localized message from the given log record. First this method gets the raw message from the given record. Then there is choices:- If the given record specifies a resource bundle, then the message is used as a key for fetching the localized resources in the given bundle.
- If the given record specifies one or more parameters
and if the message seems to use the
MessageFormatsyntax, then the message is formatted byMessageFormat.
- Overrides:
formatMessagein classFormatter- Parameters:
record- The log record from which to get a localized message.- Returns:
- the localized message.
-
install
Installs aMonolineFormatterfor the root logger, or returns the existing instance if any. This method performs the following choices:- If a
ConsoleHandleris associated to the root logger, then:- If that handler already uses a
MonolineFormatter, then the existing formatter is returned. - Otherwise the
ConsoleHandlerformatter is replaced by a newMonolineFormatterinstance, and that new instance is returned. We perform this replacement in order to avoid sending twice the same records to the console.
- If that handler already uses a
- Otherwise a new
ConsoleHandlerusing a newMonolineFormatteris created and added to the root logger.
Implementation note: The current implementation does not check for duplicatedConsoleHandlerinstances, and does not check if any child logger has aConsoleHandler.- Returns:
- the new or existing
MonolineFormatter. The formatter output can be configured using thesetTimeFormat(String)andsetSourceFormat(String)methods. - Throws:
SecurityException- if this method does not have the permission to install the formatter.
- If a
-
install
@Debug @Configuration public static MonolineFormatter install(Logger logger, Level level) throws SecurityException Installs aMonolineFormatterfor the specified logger, or returns the existing instance if any. This method performs the following steps:- If a
ConsoleHandleris associated to the given logger, then:- If that handler already uses a
MonolineFormatter, then the existing formatter is returned. - Otherwise the
ConsoleHandlerformatter is replaced by a newMonolineFormatterinstance, and that new instance is returned. We perform this replacement in order to avoid sending twice the same records to the console.
- If that handler already uses a
- Otherwise:
- The
Logger.setUseParentHandlers(boolean)flag is set tofalsefor avoiding duplicated loggings if aConsoleHandlerinstance exists in the parent handlers. - Parent handlers that are not
ConsoleHandlerinstances are added to the given logger in order to preserve similar behavior as before the call tosetUseParentHandlers(false). - A new
ConsoleHandlerusing a newMonolineFormatteris created and added to the given logger.
- The
Implementation note: The current implementation does not check for duplicatedConsoleHandlerinstances, and does not check if any child logger has aConsoleHandler.Specifying a log level
This method can opportunistically set the handler level. If the given level is non-null, then theConsoleHandlerusing theMonolineFormatterwill be set to that level. This is mostly a convenience for temporary increase of logging verbosity for debugging purpose. This functionality should not be used in production environment, since it overwrite user's level setting.- Parameters:
logger- the base logger to apply the change on.level- the desired level, ornullif no level should be set.- Returns:
- the new or existing
MonolineFormatter. The formatter output can be configured using thesetTimeFormat(String)andsetSourceFormat(String)methods. - Throws:
SecurityException- if this method does not have the permission to install the formatter.
- If a
-