com.oracle.truffle.api

Class TruffleLogger

java.lang.Object

com.oracle.truffle.api.TruffleLogger

public final class TruffleLogger
extends Object

Support for logging in Truffle languages and instruments.

The logger's Level configuration is done using the Context's options. The level option key has the following format: log.languageId.className.level or log.instrumentId.className.level. The value is either the name of pre-defined Level constant or a numeric Level value. If not explicitly set in Context's options the level is inherited from the parent logger.

The TruffleLogger supports message parameters of primitive types and strings. The object parameters are converted into string value before they are passed to the Handler.

The TruffleLogger instances are safe to be used on compiled code paths as well as from multiple-threads.

Since:

19.0

Method Summary

Modifier and Type	Method and Description
void	config(String message) Logs a message with config level.
void	config(Supplier<String> messageSupplier) Logs a message with config level.
void	entering(String sourceClass, String sourceMethod) Logs entry into method.
void	entering(String sourceClass, String sourceMethod, Object parameter) Logs entry into method with single parameter.
void	entering(String sourceClass, String sourceMethod, Object[] parameters) Logs entry into method with multiple parameters.
void	exiting(String sourceClass, String sourceMethod) Logs a return from method.
void	exiting(String sourceClass, String sourceMethod, Object result) Logs a return from method with result.
void	fine(String message) Logs a message with fine level.
void	fine(Supplier<String> messageSupplier) Logs a message with fine level.
void	finer(String message) Logs a message with finer level.
void	finer(Supplier<String> messageSupplier) Logs a message with finer level.
void	finest(String message) Logs a message with finest level.
void	finest(Supplier<String> messageSupplier) Logs a message with finest level.
static TruffleLogger	getLogger(String id) Find or create a root logger for a given language or instrument.
static TruffleLogger	getLogger(String id, Class<?> forClass) Find or create a logger for a given language or instrument class.
static TruffleLogger	getLogger(String id, String loggerName) Find or create a logger for a given language or instrument.
String	getName() Returns the name of the logger.
TruffleLogger	getParent() Returns the parent TruffleLogger.
void	info(String message) Logs a message with info level.
void	info(Supplier<String> messageSupplier) Logs a message with info level.
boolean	isLoggable(Level level) Checks if a message of the given level would be logged by this logger.
void	log(Level level, String message) Logs a message.
void	log(Level level, String message, Object parameter) Logs a message with single parameter.
void	log(Level level, String message, Object[] parameters) Logs a message with multiple parameters.
void	log(Level level, String message, Throwable thrown) Logs a message with an exception.
void	log(Level level, Supplier<String> messageSupplier) Logs a message.
void	log(Level level, Throwable thrown, Supplier<String> messageSupplier) Logs a message with an exception.
void	logp(Level level, String sourceClass, String sourceMethod, String message) Logs a message, specifying source class and source method.
void	logp(Level level, String sourceClass, String sourceMethod, String message, Object parameter) Logs a message with single parameter, specifying source class and source method.
void	logp(Level level, String sourceClass, String sourceMethod, String message, Object[] parameters) Log a message with multiple parameters, specifying source class and source method.
void	logp(Level level, String sourceClass, String sourceMethod, String message, Throwable thrown) Logs a message with an exception, specifying source class and source method.
void	logp(Level level, String sourceClass, String sourceMethod, Supplier<String> messageSupplier) Logs a message, specifying source class and source method.
void	logp(Level level, String sourceClass, String sourceMethod, Throwable thrown, Supplier<String> messageSupplier) Logs a message with an exception, specifying source class and source method.
void	severe(String message) Logs a message with severe level.
void	severe(Supplier<String> messageSupplier) Logs a message with severe level.
<T extends Throwable> T	throwing(String sourceClass, String sourceMethod, T thrown) Logs throwing an exception.
void	warning(String message) Logs a message with warning level.
void	warning(Supplier<String> messageSupplier) Logs a message with warning level.

Methods inherited from class java.lang.Object

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

Method Detail

getLogger

public static TruffleLogger getLogger(String id)

Find or create a root logger for a given language or instrument. If the root logger for given language or instrument already exists it's returned, otherwise a new root logger is created.

Parameters:

id - the unique id of language or instrument

Returns:

a TruffleLogger

Throws:

NullPointerException - if id is null

IllegalArgumentException - if id is not a valid language or instrument id.

Since:

19.0

getLogger

public static TruffleLogger getLogger(String id,
                                      Class<?> forClass)

Find or create a logger for a given language or instrument class. If a logger for the class already exists it's returned, otherwise a new logger is created.

Parameters:

id - the unique id of language or instrument

forClass - the Class to create a logger for

Returns:

a TruffleLogger

Throws:

NullPointerException - if id or forClass is null

IllegalArgumentException - if id is not a valid language or instrument id.

Since:

19.0

getLogger

public static TruffleLogger getLogger(String id,
                                      String loggerName)

Find or create a logger for a given language or instrument. If a logger with given name already exists it's returned, otherwise a new logger is created.

Parameters:

id - the unique id of language or instrument

loggerName - the the name of a TruffleLogger, if a loggerName is null or empty a root logger for language or instrument is returned

Returns:

a TruffleLogger

Throws:

NullPointerException - if id is null

IllegalArgumentException - if id is not a valid language or instrument id.

Since:

19.0

config

public void config(String message)

Logs a message with config level.

If the logger is enabled for the config level the message is sent to the Handler registered in the current Context.

Parameters:

message - the message to log

Since:

19.0

config

public void config(Supplier<String> messageSupplier)

Logs a message with config level. The message is constructed only when the logger is enabled for the config level.

If the logger is enabled for the config level the message is sent to the Handler registered in the current Context.

Parameters:

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

entering

public void entering(String sourceClass,
                     String sourceMethod)

Logs entry into method.

This method can be used to log entry into a method. A LogRecord with message "ENTRY" and the given sourceMethod and sourceClass is logged with finer level.

Parameters:

sourceClass - the entered class

sourceMethod - the entered method

Since:

19.0

entering

public void entering(String sourceClass,
                     String sourceMethod,
                     Object parameter)

Logs entry into method with single parameter.

This method can be used to log entry into a method. A LogRecord with message "ENTRY", the given sourceMethod and sourceClass and given parameter is logged with finer level.

Parameters:

sourceClass - the entered class

sourceMethod - the entered method

parameter - the method parameter

Since:

19.0

entering

public void entering(String sourceClass,
                     String sourceMethod,
                     Object[] parameters)

Logs entry into method with multiple parameters.

This method can be used to log entry into a method. A LogRecord with message "ENTRY", the given sourceMethod and sourceClass and given parameters is logged with finer level.

Parameters:

sourceClass - the entered class

sourceMethod - the entered method

parameters - the method parameters

Since:

19.0

exiting

public void exiting(String sourceClass,
                    String sourceMethod)

Logs a return from method.

This method can be used to log return from a method. A LogRecord with message "RETURN" and the given sourceMethod and sourceClass is logged with finer level.

Parameters:

sourceClass - the exiting class

sourceMethod - the exiting method

Since:

19.0

exiting

public void exiting(String sourceClass,
                    String sourceMethod,
                    Object result)

Logs a return from method with result.

This method can be used to log return from a method. A LogRecord with message "RETURN", the given sourceMethod and sourceClass and method result is logged with finer level.

Parameters:

sourceClass - the exiting class

sourceMethod - the exiting method

result - the return value

Since:

19.0

fine

public void fine(String message)

Logs a message with fine level.

If the logger is enabled for the fine level the message is sent to the Handler registered in the current Context.

Parameters:

message - the message to log

Since:

19.0

fine

public void fine(Supplier<String> messageSupplier)

Logs a message with fine level. The message is constructed only when the logger is enabled for the fine level.

If the logger is enabled for the fine level the message is sent to the Handler registered in the current Context.

Parameters:

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

finer

public void finer(String message)

Logs a message with finer level.

If the logger is enabled for the finer level the message is sent to the Handler registered in the current Context.

Parameters:

message - the message to log

Since:

19.0

finer

public void finer(Supplier<String> messageSupplier)

Logs a message with finer level. The message is constructed only when the logger is enabled for the finer level.

If the logger is enabled for the finer level the message is sent to the Handler registered in the current Context.

Parameters:

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

finest

public void finest(String message)

Logs a message with finest level.

If the logger is enabled for the finest level the message is sent to the Handler registered in the current Context.

Parameters:

message - the message to log

Since:

19.0

finest

public void finest(Supplier<String> messageSupplier)

Logs a message with finest level. The message is constructed only when the logger is enabled for the finest level.

If the logger is enabled for the finest level the message is sent to the Handler registered in the current Context.

Parameters:

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

info

public void info(String message)

Logs a message with info level.

If the logger is enabled for the info level the message is sent to the Handler registered in the current Context.

Parameters:

message - the message to log

Since:

19.0

info

public void info(Supplier<String> messageSupplier)

Logs a message with info level. The message is constructed only when the logger is enabled for the info level.

If the logger is enabled for the info level the message is sent to the Handler registered in the current Context.

Parameters:

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

severe

public void severe(String message)

Logs a message with severe level.

If the logger is enabled for the severe level the message is sent to the Handler registered in the current Context.

Parameters:

message - the message to log

Since:

19.0

severe

public void severe(Supplier<String> messageSupplier)

Logs a message with severe level. The message is constructed only when the logger is enabled for the severe level.

If the logger is enabled for the severe level the message is sent to the Handler registered in the current Context.

Parameters:

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

throwing

public <T extends Throwable> T throwing(String sourceClass,
                                        String sourceMethod,
                                        T thrown)

Logs throwing an exception.

This method can be used to log exception thrown from a method. A LogRecord with message "THROW",the given sourceMethod and sourceClass and thrown is logged with finer level.

Parameters:

sourceClass - the class throwing an exception

sourceMethod - the method throwing an exception

thrown - the thrown exception

Since:

19.0

warning

public void warning(String message)

Logs a message with warning level.

If the logger is enabled for the warning level the message is sent to the Handler registered in the current Context.

Parameters:

message - the message to log

Since:

19.0

warning

public void warning(Supplier<String> messageSupplier)

Logs a message with warning level. The message is constructed only when the logger is enabled for the warning level.

If the logger is enabled for the warning level the message is sent to the Handler registered in the current Context.

Parameters:

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

log

public void log(Level level,
                String message)

Logs a message.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

message - the message to log

Since:

19.0

log

public void log(Level level,
                Supplier<String> messageSupplier)

Logs a message. The message is constructed only when the logger is enabled for the given level.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

log

public void log(Level level,
                String message,
                Object parameter)

Logs a message with single parameter.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

message - the message to log

parameter - the log message parameter

Since:

19.0

log

public void log(Level level,
                String message,
                Object[] parameters)

Logs a message with multiple parameters.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

message - the message to log

parameters - the log message parameters

Since:

19.0

log

public void log(Level level,
                String message,
                Throwable thrown)

Logs a message with an exception.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

message - the message to log

thrown - the exception to log

Since:

19.0

log

public void log(Level level,
                Throwable thrown,
                Supplier<String> messageSupplier)

Logs a message with an exception. The message is constructed only when the logger is enabled for the given level.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

thrown - the exception to log

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String message)

Logs a message, specifying source class and source method.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

sourceClass - the class issued the logging request

sourceMethod - the method issued the logging request

message - the message to log

Since:

19.0

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 Supplier<String> messageSupplier)

Logs a message, specifying source class and source method. The message is constructed only when the logger is enabled for the given level.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

sourceClass - the class issued the logging request

sourceMethod - the method issued the logging request

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String message,
                 Object parameter)

Logs a message with single parameter, specifying source class and source method.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

sourceClass - the class issued the logging request

sourceMethod - the method issued the logging request

message - the message to log

parameter - the log message parameter

Since:

19.0

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String message,
                 Object[] parameters)

Log a message with multiple parameters, specifying source class and source method.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

sourceClass - the class issued the logging request

sourceMethod - the method issued the logging request

message - the message to log

parameters - the log message parameters

Since:

19.0

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String message,
                 Throwable thrown)

Logs a message with an exception, specifying source class and source method.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

sourceClass - the class issued the logging request

sourceMethod - the method issued the logging request

message - the message to log

thrown - the exception to log

Since:

19.0

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 Throwable thrown,
                 Supplier<String> messageSupplier)

Logs a message with an exception, specifying source class and source method. The message is constructed only when the logger is enabled for the given level.

If the logger is enabled for the given level the message is sent to the Handler registered in the current Context.

Parameters:

level - the required Level

sourceClass - the class issued the logging request

sourceMethod - the method issued the logging request

thrown - the exception to log

messageSupplier - the Supplier called to produce the message to log

Since:

19.0

getName

public String getName()

Returns the name of the logger.

Returns:

the logger name

Since:

19.0

getParent

public TruffleLogger getParent()

Returns the parent TruffleLogger.

Returns:

the parent TruffleLogger or null when the TruffleLogger has no parent.

Since:

19.0

isLoggable

public boolean isLoggable(Level level)

Checks if a message of the given level would be logged by this logger.

Parameters:

level - the required logging level

Returns:

true if message is loggable by this logger

Since:

19.0