Collaboration diagram for Log:

Class Description

This is a simple, 100% static wrapper of class Lox. In other words, this class incorporates one static singleton of Lox and mirrors the whole non static interface of Lox into a static one.

The exclusive use of this class covers the vast majority of all debug logging scenarios. For release logging, remote logging and similar scenarios, the use of a dedicated instance of class Lox is needed.

Use your preferred java byte code processing tool (e.g. Proguard) to remove all method invocations to this class from your release code.

This class is flagged 'abstract' to prevent instance creation.

Public Static Fields
static TextLogger	debugLogger =null
	The debug logger created by AddDebugLogger.

static ALoxReportWriter	debugReportWriter =null

static Lox	LOX =new Lox("Log", true)

Public Static Methods
static void	addALibReportWriter (Lox lox)

static void	addDebugLogger ()

static void	addDebugLogger (Lox lox)

static void	Assert (boolean condition, Object... logables)

static void	entry (String domain, Verbosity verbosity, Object... logables)

static void	error (Object... logables)

static Logger	getLogger (String loggerName)

static void	getState (AString buf, int flags)

static void	If (boolean condition, String domain, Verbosity verbosity, Object... logables)

static void	If (boolean condition, Verbosity verbosity, Object... logables)

static void	info (Object... logables)

static void	mapThreadName (String threadName)

static void	mapThreadName (String threadName, long id)

static void	once (Object logables)

static void	once (Object logables, int quantity)

static void	once (Object logables, int quantity, Scope scope)

static void	once (Object logables, int quantity, Scope scope, int pkgLevel)

static void	once (Object logables, int quantity, String group)

static void	once (String domain, Verbosity verbosity, Object logables)

static void	once (String domain, Verbosity verbosity, Object logables, int quantity)

static void	once (String domain, Verbosity verbosity, Object logables, Scope scope)

static void	once (String domain, Verbosity verbosity, Object logables, Scope scope, int pkgLevel)

static void	once (String domain, Verbosity verbosity, Object logables, Scope scope, int pkgLevel, int quantity)

static void	once (String domain, Verbosity verbosity, Object logables, String group)

static void	once (String domain, Verbosity verbosity, Object logables, String group, int quantity)

static void	once (String domain, Verbosity verbosity, Object logables, String group, Scope scope)

static void	once (String domain, Verbosity verbosity, Object logables, String group, Scope scope, int pkgLevel)

static void	once (String domain, Verbosity verbosity, Object logables, String group, Scope scope, int pkgLevel, int quantity)

static void	removeALibReportWriter ()

static void	removeDebugLogger ()

static void	removeDebugLogger (Lox lox)

static boolean	removeLogger (Logger logger)

static Logger	removeLogger (String loggerName)

static void	removeThreadDomain (String scopeDomain, Scope scope)

static void	removeThreadDomain (String scopeDomain, Scope scope, Thread thread)

static void	reset ()

static Object	retrieve ()

static Object	retrieve (Scope scope)

static Object	retrieve (Scope scope, int pkgLevel)

static Object	retrieve (String key)

static Object	retrieve (String key, Scope scope)

static Object	retrieve (String key, Scope scope, int pkgLevel)

static void	setDomain (String scopeDomain, Scope scope)

static void	setDomain (String scopeDomain, Scope scope, int packageLevel)

static void	setDomain (String scopeDomain, Scope scope, Thread thread)

static void	setDomainSubstitutionRule (String domainPath, String replacement)

static void	setPrefix (Object logable)

static void	setPrefix (Object logable, Scope scope, Thread thread)

static void	setPrefix (Object logable, String domain)

static void	setPrefix (Object logable, String domain, Inclusion otherPLs)

static void	setPrefix (Object prefix, Scope scope)

static void	setPrefix (Object prefix, Scope scope, int packageLevel)

static void	setStartTime ()

static void	setStartTime (Date startTime)

static void	setStartTime (Date startTime, String loggerName)

static void	setVerbosity (Logger logger, Verbosity verbosity)

static void	setVerbosity (Logger logger, Verbosity verbosity, String domain)

static void	setVerbosity (Logger logger, Verbosity verbosity, String domain, int priority)

static void	setVerbosity (String loggerName, Verbosity verbosity)

static void	setVerbosity (String loggerName, Verbosity verbosity, String domain)

static void	setVerbosity (String loggerName, Verbosity verbosity, String domain, int priority)

static void	state (String domain, Verbosity verbosity, String headLine)

static void	state (String domain, Verbosity verbosity, String headLine, int flags)

static void	store (Object data)

static void	store (Object data, Scope scope)

static void	store (Object data, Scope scope, int pkgLevel)

static void	store (Object data, String key)

static void	store (Object data, String key, Scope scope)

static void	store (Object data, String key, Scope scope, int pkgLevel)

static void	verbose (Object... logables)

static void	warning (Object... logables)

Member Function Documentation

◆ addALibReportWriter()

static void addALibReportWriter ( Lox lox )

static

In the case that the original ALib ReportWriterStdIO is still in place, Report.pushWriter is invoked to provide a ReportWriter of type ALoxReportWriter.

Note: This method is effective only in debug compilations. Usually it is invoked indirectly by using method addDebugLogger. Applications that do not use that method (e.g. because they are using release logging exclusively), should invoke this method on bootstrap providing their (release) lox. In this case, the Verbosity of the internal domain used by class ALoxReportWriter has to be set for the the logger(s) in given lox in question.

Parameters

lox	The lox that the ALoxReportWriter created will be using.

◆ addDebugLogger() [1/2]

static void addDebugLogger ( )

static

This method invokes addDebugLogger(Lox) providing the static debug instance LOX. for parameter lox.

◆ addDebugLogger() [2/2]

static void addDebugLogger ( Lox lox )

static

This method creates an adequate/default debug logger using Lox.createConsoleLogger and attaches it to the debug instance of class Lox. Of-course, alternatively to using this method, a suitable set of debug loggers can be created manually. Also, before/after using this method additional debug loggers may be created.

The name of the Logger created is "DEBUG_LOGGER". It will be registered with the standard Lox used for debug-logging, by setting Verbosities

Verbosity.VERBOSE for the root domain '/' and
Verbosity.WARNING for internal domains.

Finally, this method invokes addALibReportWriter.

Parameters

lox	The lox to add the debug logger(s) to. If null, the static debug object LOX is used. Defaults to null

◆ Assert()

static void Assert	(	boolean	condition,
		Object...	logables
	)

static

Logs a list of Logables only if parameter condition is not true. For this, Lox.Assert is invoked on static object LOX used for debug logging.

Note: This Method's name starts with capital letter, as 'assert' is a Java keyword.

Parameters

condition	If `false`, the Log Statement is executed.
logables	The list of Logables, optionally including a domain name at the start.

◆ entry()

static void entry	(	String	domain,
		Verbosity	verbosity,
		Object...	logables
	)

static

Logs a list of Logables using the given Verbosity.

This method is usually not used directly. Instead, methods info, verbose, warning and error provide simpler interfaces.

Hence, the use of this method is recommended only if the verbosity of a log statement is is evaluated only at runtime.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The verbosity.
logables	The objects to log.

◆ error()

static void error ( Object... logables )

static

Logs a list of Logables using Verbosity.ERROR. For this, Lox.error is invoked on static object LOX used for debug logging.

Parameters

logables The list of Logables, optionally including a domain name at the start.

◆ getLogger()

static Logger getLogger ( String loggerName )

static

Retrieves an instance of a Logger by its name. This might be useful when access to a Logger is needed to change its configuration.

Parameters

loggerName The name of the Logger to search for (case insensitive).

Returns: The logger, null if not found.

◆ getState()

static void getState	(	AString	buf,
		int	flags
	)

static

This method collects state information about this lox in a formatted multi-line AString. Parameter flags is a bit field with bits defined in constants of class Lox prefixed with "STATE_INFO_", e.g. STATE_INFO_LOGGERS.

Parameters

buf	The target string.
flags	Flag bits that define which state information is collected.

◆ If() [1/2]

static void If	(	boolean	condition,
		String	domain,
		Verbosity	verbosity,
		Object...	logables
	)

static

Logs a list of Logables only if the parameter condition is true. For this, Lox.If is invoked on static object LOX used for debug logging.

Note: This Method's name starts with capital letter, as 'if' is a Java keyword.

Parameters

condition	If `false`, the Log Statement is executed.
domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The verbosity.
logables	The objects to log.

◆ If() [2/2]

static void If	(	boolean	condition,
		Verbosity	verbosity,
		Object...	logables
	)

static

Logs a list of Logables only if the parameter condition is true. For this, Lox.If is invoked on static object LOX used for debug logging. This overloaded version omits parameter domain.

Note: This Method's name starts with capital letter, as 'if' is a Java keyword.

Parameters

condition	If `false`, the Log Statement is executed.
verbosity	The verbosity.
logables	The objects to log.

◆ info()

static void info ( Object... logables )

static

Logs a list of Logables using Verbosity.INFO. For this, Lox.info is invoked on static object LOX used for debug logging.

Parameters

logables The list of Logables, optionally including a domain name at the start.

◆ mapThreadName() [1/2]

static void mapThreadName ( String threadName )

static

This method sets a human readable name to the current thread which is optionally included in each log entry.

Parameters

threadName The name of the thread as it should be displayed in the logs.

◆ mapThreadName() [2/2]

static void mapThreadName	(	String	threadName,
		long	id
	)

static

This method sets a human readable name to the given thread ID (or current thread) which is optionally included in each log entry.

Parameters

threadName	The name of the thread as it should be displayed in the logs.
id	Parameter providing the thread ID. Defaults to `-1` which uses the current thread.

◆ once() [1/15]

static void once ( Object logables )

static

Overloaded version of once.

Parameters

logables The object(s) to log. (Multiple objects may be provided as an Object[].)

◆ once() [2/15]

static void once	(	Object	logables,
		int	quantity
	)

static

Overloaded version of once.

Parameters

logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.

◆ once() [3/15]

static void once	(	Object	logables,
		int	quantity,
		Scope	scope
	)

static

Overloaded version of once.

Parameters

logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
scope	The Scope that the group or counter is bound to.

◆ once() [4/15]

static void once	(	Object	logables,
		int	quantity,
		Scope	scope,
		int	pkgLevel
	)

static

Overloaded version of once.

Parameters

logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
scope	The Scope that the group or counter is bound to.
pkgLevel	Used only if parameter scope equals Scope.PACKAGE to reference parent packages. Optional and defaults to `0`.

◆ once() [5/15]

static void once	(	Object	logables,
		int	quantity,
		String	group
	)

static

Overloaded version of once.

Parameters

logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.

◆ once() [6/15]

static void once	(	String	domain,
		Verbosity	verbosity,
		Object	logables
	)

static

Overloaded version of once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)

◆ once() [7/15]

static void once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		int	quantity
	)

static

Overloaded version of once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.

◆ once() [8/15]

static void once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		Scope	scope
	)

static

Overloaded version of once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
scope	The Scope that the group or counter is bound to.

◆ once() [9/15]

static void once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		Scope	scope,
		int	pkgLevel
	)

static

Overloaded version of once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
scope	The Scope that the group or counter is bound to.
pkgLevel	Used only if parameter scope equals Scope.PACKAGE to reference parent packages. Optional and defaults to `0`.

◆ once() [10/15]

static void once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		Scope	scope,
		int	pkgLevel,
		int	quantity
	)

static

Overloaded version of once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
scope	The Scope that the group or counter is bound to.
pkgLevel	Used only if parameter scope equals Scope.PACKAGE to reference parent packages. Optional and defaults to `0`.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.

◆ once() [11/15]

static void once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		String	group
	)

static

Overloaded version of once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.

◆ once() [12/15]

static void once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		String	group,
		int	quantity
	)

static

Overloaded version of once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.

◆ once() [13/15]

static void once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		String	group,
		Scope	scope
	)

static

Overloaded version of once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
scope	The Scope that the group or counter is bound to.

◆ once() [14/15]

static void once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		String	group,
		Scope	scope,
		int	pkgLevel
	)

static

Overloaded version of once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
scope	The Scope that the group or counter is bound to.
pkgLevel	Used only if parameter scope equals Scope.PACKAGE to reference parent packages. Optional and defaults to `0`.

◆ once() [15/15]

static void once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		String	group,
		Scope	scope,
		int	pkgLevel,
		int	quantity
	)

static

Logs given logables once, up to quantity times or every n-th time. In its simplest overloaded version, the counter is bound to the source code line, hence, only the first execution of this exact Log Statement is executed.

Using parameter group, a set of Log Statements that share the same group key, can be grouped and of such set, only the one which is first executed actually logs.
Alternatively, when key is omitted (or null or empty), but a Scope is given with parameter scope, then the counter is associated with the scope.
Finally, parameters key and scope can also be used in combination. The key is then unique in respect to the Scope provided.

Using, none, one or both of the parameters group and scope, among others, the following use cases can be achieved.

Log a specific statement up to n-times.
Log only the first n of a group of statements.
Log only the first n statements within a method.
Log only the first n statements belonging to the same group and method .
Log only the first n statements within any method of
- a class
- a package
- a parent package with all sub-packages
Log only the first n statements which belong to the same group and are placed within any method of
- a class
- a package
- a parent package with all sub-packages
Log a Log Statement n-times per new thread.
Log only the first n statements of a group of statements executed by a specific thread.

Note: Unlike other methods of this class which accept more than one logable, this method and its overloaded variants accept only one object. To supply several objects at once, an Object[] may be passed with parameter logables, like in the following sample:
Log.once( new Object[] {"One - {} - {}!", "two", 3} );

Note

Due to the limitations of the Java language to dissolve ambiguities when invoking overloaded methods, most of the overloads provided await parameters domain and verbosity at the start. This is in difference to ALox for C++ and ALox forC#, where overloaded methods always default these parameters to null respectively Verbosity.INFO.
Fortunate exceptions are

once(Object logable) and
once(Object logable, int quantity).

Furthermore, to to cover the most frequent use cases, methods

once(Object logable, int quantity, String group),
once(Object logable, int quantity, Scope scope, int pkgLevel) and
once(Object logable, int quantity, Scope scope)

have been added. While their parameter order is 'wrong' and therefore need quantity to be specified, still they are nice shortcuts.

When parameter quantity is a negative value, the log statement is executed every n-th time instead n-times. E.g, if quantity is -5, the first statement is executed and afterwards every fifth invocation.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
scope	The Scope that the group or counter is bound to.
pkgLevel	Used only if parameter scope equals Scope.PACKAGE to reference parent packages. Optional and defaults to `0`.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.

◆ removeALibReportWriter()

static void removeALibReportWriter ( )

static

Removes the report writer created with addALibReportWriter.

◆ removeDebugLogger() [1/2]

static void removeDebugLogger ( )

static

This method invokes removeDebugLogger(Lox) providing the static debug instance LOX.

◆ removeDebugLogger() [2/2]

static void removeDebugLogger ( Lox lox )

static

Removes the Logger(s) which was/were created by addDebugLogger. This method also invokes Report.popWriter(null) to install a default ReportWriter for ALib.

Parameters

lox	The lox to remove the debug logger from. If null, the static debug object::LOX is used.

◆ removeLogger() [1/2]

static boolean removeLogger ( Logger logger )

static

Removes a logger from this container.

Note: To (temporarily) disable a logger without removing it, a call to setVerbosity( logger, Verbosity.OFF ) can be used.

Parameters

logger The logger to be removed.

Returns: true, if the Logger was found and removed, false otherwise.

◆ removeLogger() [2/2]

static Logger removeLogger ( String loggerName )

static

Removes logger named loggerName from this container.

Note: To (temporarily) disable a logger without removing it, a call to setVerbosity( logger, Verbosity.OFF ) can be used.

Parameters

loggerName The name of the Logger(s) to be removed (case insensitive).

Returns: The logger that was removed, null if not found.

◆ removeThreadDomain() [1/2]

static void removeThreadDomain	(	String	scopeDomain,
		Scope	scope
	)

static

Overload version providing default value for parameter thread.

Parameters

scopeDomain	The domain path to register.
scope	Either Scope.THREAD_OUTER and Scope.THREAD_INNER. With other values, an internal error is logged.

◆ removeThreadDomain() [2/2]

static void removeThreadDomain	(	String	scopeDomain,
		Scope	scope,
		Thread	thread
	)

static

This method is used to remove an explicitly given domain path from the list of domain paths set for Scope.THREAD_OUTER and Scope.THREAD_INNER.

To remove the most recently added domain path from such thread-related Scope, use one of the overloaded methods setDomain and provide an empty or nulled value for parameter scopeDomain (the same as how domain paths of other Scopes are removed).

Note: The long name of the method already indicates that this method is a little special. Only seldom, more than one Scope Domain is needed to be added. And if this is needed, then such Scope Domains usually get removed in reverse order of their definition, with is performed using the standard interface that allows 'removing' any other Scope Domain. (Passing an empty or nulled domain path to method setDomain.)

Parameters

scopeDomain	The domain path to register.
scope	Either Scope.THREAD_OUTER and Scope.THREAD_INNER. With other values, an internal error is logged.
thread	The thread to set/unset a thread-related Scope Domains for. Defaults to the current thread.

◆ reset()

static void reset ( )

static

This method should not be used in standard applications. It was added to support clean unit testing. This method disposes the internal static Lox and with it all loggers, preferences and stuff and replaces it with a fresh one.

◆ retrieve() [1/6]

static Object retrieve ( )

static

Overloaded version of retrieve which omits parameters.

Returns: The object, null if nothing was found.

◆ retrieve() [2/6]

static Object retrieve ( Scope scope )

static

Overloaded version of retrieve which omits parameters.

Parameters

scope The Scope that the data is bound to.

Returns: The object, null if nothing was found.

◆ retrieve() [3/6]

static Object retrieve	(	Scope	scope,
		int	pkgLevel
	)

static

Overloaded version of retrieve which omits parameters.

Parameters

scope	The Scope that the data is bound to.
pkgLevel	Used only if parameter scope equals Scope.PACKAGE to reference parent packages. Optional and defaults to `0`.

Returns: The object, null if nothing was found.

◆ retrieve() [4/6]

static Object retrieve ( String key )

static

Overloaded version of retrieve which omits parameters.

Parameters

key	The optional key to the data. If omitted (or empty or null), the data is bound to the Scope provided. If omitted and scope is Scope.GLOBAL, then the data is unique to the Lox.

Returns: The object, null if nothing was found.

◆ retrieve() [5/6]

static Object retrieve	(	String	key,
		Scope	scope
	)

static

Overloaded version of retrieve which omits parameters.

Parameters

key	The optional key to the data. If omitted (or empty or null), the data is bound to the Scope provided. If omitted and scope is Scope.GLOBAL, then the data is unique to the Lox.
scope	The Scope that the data is bound to.

Returns: The object, null if nothing was found.

◆ retrieve() [6/6]

static Object retrieve	(	String	key,
		Scope	scope,
		int	pkgLevel
	)

static

Retrieves an object which was previously stored using store. Optional parameters key and scope offer various possibilities to reference such objects.

Note: Log Data is a feature provided by ALox to support debug-logging. It is not advised to use Log Data to implement application logic.

Parameters

key	The optional key to the data. If omitted (or empty or null), the data is bound to the Scope provided. If omitted and scope is Scope.GLOBAL, then the data is unique to the Lox.
scope	The Scope that the data is bound to.
pkgLevel	Used only if parameter scope equals Scope.PACKAGE to reference parent packages. Optional and defaults to `0`.

Returns: The object, null if nothing was found.

◆ setDomain() [1/3]

static void setDomain	(	String	scopeDomain,
		Scope	scope
	)

static

Overloaded version of setDomain providing default value 0 for parameter packageLevel.

Parameters

scopeDomain	The domain path to register.
scope	The scope that should the given domain be registered for. Available Scope definitions are platform/language dependent.

◆ setDomain() [2/3]

static void setDomain	(	String	scopeDomain,
		Scope	scope,
		int	packageLevel
	)

static

The given scopeDomain becomes the default domain path for given scope. This means, that any subsequent log invocations (from within this same scope) can omit the domain parameter, or if they provide one, this Scope Domain path is prepended. If subsequent log calls specify a domain name with a leading '/' character, then the Scope Domain of the scope is ignored.
Furthermore, if the given scope is an inner scope, outer scopes are prepended to the given scopeDomain when the resulting domain of a log invocation is evaluated. Again, this behavior can be overruled by prepending a leading '/' character to scopeDomain.

To remove a previously set Scope Domain a nulled or empty string has to be passed with parameter scopeDomain.

For Scope.THREAD_OUTER and Scope.THREAD_INNER, passing an empty or nulled string removes the most recently added domain path. For removing an explicitly named domain path of Scope.THREAD_OUTER and Scope.THREAD_INNER use method removeThreadDomain.

Parameters

scopeDomain	The domain path to register.
scope	The scope that should the given domain be registered for. Available Scope definitions are platform/language dependent.
packageLevel	Used only with Scope.PACKAGE. Cuts the given number of package parts (separated with '.') from the end of the packages. Optional and defaults to `0`.

◆ setDomain() [3/3]

static void setDomain	(	String	scopeDomain,
		Scope	scope,
		Thread	thread
	)

static

This overloaded version of setDomain is applicable only for Scope.THREAD_OUTER and Scope.THREAD_INNER and allows to specify the thread that the setting should be associated with.

If scopeDomain is null or empty, the most recently added domain path is removed. For removing an explicitly named domain associated with a thread use method removeThreadDomain.

Parameters

scopeDomain	The domain path to register.
scope	Either Scope.THREAD_OUTER or Scope.THREAD_INNER. With other values, an internal error is logged.
thread	The thread to set/unset a thread-related Scope Domains for.

◆ setDomainSubstitutionRule()

static void setDomainSubstitutionRule	(	String	domainPath,
		String	replacement
	)

static

Adds a Domain Substitution Rule. Domain Substitution is performed as a last step when evaluating the domain path of a Log Statement, taking Scope Domains and the optional parameter domain of the statement into account.

Wildcards
Parameter domainPath supports 'wildcard' character '*' at its beginning and at its end (or both). This allows to have four types of rules:

Exact match
Prefix match (* at the end of domainPath)
Suffix match (* at the start of domainPath)
Substring match (* at both, start and the end of domainPath)

Only minimal checks are performed, e.g. if an exact match is requested, but domainPath does not start with character '/'. In this and some other cases, the rule is not stored and an internal warning is logged. Further checks, for example for illegal domain path characters are not performed (those will be eliminated when the resulting domain path is to be created internally).

Circular Dependencies
If the given rules have circular dependencies, only a limited number (ten) replacements are performed. If this number of replacements for one Log Statement is exceeded, an internal warning message is logged. This is done only once over the life-time of a Logger.

Application of Rules
Rules are applied in the order of their definition. After all rules have been applied this is repeated as long as at least one rule matched (up to ten times).

Deletion of Rules To delete a rule, invoke the method with same parameter domainPath and a 'nulled' or empty string for parameter replacement. To delete all rules, invoke the method with parameter domainPath 'nulled' or empty.

Final remarks Domain substitution is useful to permanently change ('redirect') domain paths of 3rd party code (e.g. libraries using ALox) or log statements that must not be changed for other reasons. It is advised to not 'overuse' this feature, as side effects are inherent to the concept of Domain Substitution. For example, an unwanted side effect might be that Prefix Logables are not applicable to the substituted domain, while other Prefix Logables are bound to the resulting domain.

For Lox objects that should be protected of external manipulation, it is advisable, to remove all Domain Substitution Rules right after the Lox was created by invoking this method with a nulled value for parameter domainPath. The reason is, that otherwise, through configuration files or command line parameters, domains of the Lox can be substituted and then the resulting domains Verbosities be overwritten using further configuration variables. Any prioritized 'internal' setting of Verbosities this way could be circumvented!

For more information consult the ALox User Manual.

Parameters

domainPath	The path to search. Has to start with either `'/'` or `'*'`.
replacement	The replacement path.

◆ setPrefix() [1/6]

static void setPrefix ( Object logable )

static

Overloaded version of setPrefix providing default value Inclusion.INCLUDE for parameter otherPLs and default value null for parameter domain.

Parameters

logable The Prefix Logable to set.

◆ setPrefix() [2/6]

static void setPrefix	(	Object	logable,
		Scope	scope,
		Thread	thread
	)

static

This overloaded version of setPrefix is applicable only for Scope.THREAD_OUTER and Scope.THREAD_INNER and allows to specify the thread that the setting should be associated with.

If logable is null, the most recently added Prefix Logable is removed.

Parameters

logable	The Prefix Logable to set.
scope	Either Scope.THREAD_OUTER or Scope.THREAD_INNER. With other values, an internal error is logged.
thread	The thread to set/unset a thread-related Prefix Logable for.

◆ setPrefix() [3/6]

static void setPrefix	(	Object	logable,
		String	domain
	)

static

Overloaded version of setPrefix providing default value Inclusion.INCLUDE for parameter otherPLs.

Parameters

logable	The Prefix Logable to set.
domain	The domain path. Defaults to `null`, resulting in evaluated Scope Domain path.

◆ setPrefix() [4/6]

static void setPrefix	(	Object	logable,
		String	domain,
		Inclusion	otherPLs
	)

static

The given logable becomes a Prefix Logable associated to the given Log Domain. Prefix Logables associated with the Log Domain are added to the list of Logables right before the main Logable of the Log Statement itself. Multiple Prefix Logables can be added per Log Domain.

To remove the most recently added Prefix Logable associated with a Log Domain, null has to be passed with parameter logable.

Attention: The same as with most interface methods of this class, the given domain parameter is combined with Scope Domains set for the callers' Scope. To suppress this, an absolute domain path can be used. (Still any Scope Domain of Scope.THREAD_INNER will be applied). The default value of parameter domain is "" which addresses the domain evaluated for the current scope.

Parameters

logable	The Prefix Logable to set.
domain	The domain path. Defaults to `null`, resulting in evaluated Scope Domain path.
otherPLs	If set to `Inclusion.Exclude`, scope-related Prefix Logables are ignored and only domain-related Prefix Logables are passed to the Loggers. Defaults to `Inclusion.Include`.

◆ setPrefix() [5/6]

static void setPrefix	(	Object	prefix,
		Scope	scope
	)

static

Overloaded version of setPrefix providing value 0 as default for parameter packageLevel.

Parameters

prefix	The Prefix Logable(s) to set.
scope	The scope that should the given logable be registered for. Available Scope definitions are platform/language dependent.

◆ setPrefix() [6/6]

static void setPrefix	(	Object	prefix,
		Scope	scope,
		int	packageLevel
	)

static

The given prefix becomes a Prefix Logable provided to loggers with each log statement executed within the given scope. The list of objects received by a logger is sorted from outer scope to inner scope. The logable of the Log Statement itself, is the last in the list, except one or more Prefix Logables of Scope.ThreadInner are set. Those are (similar to how this Scope is used with Scope Domains) appended to the end of the list.

To remove a previously set Prefix Logable, null has to be passed with parameter logable. For Scope.THREAD_OUTER and Scope.THREAD_INNER, passing null removes the most recently added Prefix Logable.

Note: Unlike other methods of this class which accept more than one logable, this method and its overloaded variants accept only one (the prefix). To supply several objects to be prefix logables at once, those may be passed as an Object[] like shown in the following sample:
Log.setPrefix( new Object[] {"One, ", "two, ", 3 }, Scope.GLOBAL );; The word 'prefix' in this methods' name and in the name of ALox feature Prefix Logables is chosen for the fact that with text loggers (which is the most widely applied use case for ALox) such objects are prefixes to the log message. Of-course, with using Scope.THREAD_INNER, this turns into a suffix!
When using ALox to process objects instead of log messages, the concept of Prefix Logables is very useful. Just the name does not fit so well anymore. Think of 'SetContext' and Context Objects instead.

Parameters

prefix	The Prefix Logable(s) to set.
scope	The scope that should the given logable be registered for. Available Scope definitions are platform/language dependent.
packageLevel	Used only with Scope.PACKAGE. Cuts the given number of package parts (separated with '.') from the end of the packages. Optional and defaults to `0`.

◆ setStartTime() [1/3]

static void setStartTime ( )

static

Overloaded version of setStartTime( Date, String ) providing default values null for parameters startTime and loggerName.

◆ setStartTime() [2/3]

static void setStartTime ( Date startTime )

static

Overloaded version of setStartTime( Date, String ) providing default value null for parameter loggerName.

Parameters

startTime Optional parameter with the new start time. Defaults to DateTime.Now if omitted.

◆ setStartTime() [3/3]

static void setStartTime	(	Date	startTime,
		String	loggerName
	)

static

This method is used reset (or to explicitly set) the start time of the Logger(s). The only impact is the output of time differences in the log lines. Hence, it is useful to see some absolute time values when doing basic performance tests using the Logger.

Note: This affects loggers that are registered for at least one standard domain. In other words, loggers that are exclusively attached to the internal domain, will not be affected.

Parameters

startTime	Optional parameter with the new start time. Defaults to current time if omitted.
loggerName	The name of the Logger(s) whose start time is to be set (case insensitive). Defaults to empty string, which indicates that all loggers are to be affected.

◆ setVerbosity() [1/6]

static void setVerbosity	(	Logger	logger,
		Verbosity	verbosity
	)

static

Overloaded version of setVerbosity providing

default value PRIO_SOURCE for parameter priority and
default value '/' for parameter domain.

Parameters

logger	The logger to be to be affected.
verbosity	The 'level of verboseness' to be set.

◆ setVerbosity() [2/6]

static void setVerbosity	(	Logger	logger,
		Verbosity	verbosity,
		String	domain
	)

static

Overloaded version of setVerbosity providing default value PRIO_SOURCE for parameter priority.

Parameters

logger	The logger to be to be affected.
verbosity	The 'level of verboseness' to be set.
domain	The parent (start) domain to be set. The use of absolute paths starting with `'/'` are recommended. Defaults to root domain "/".

◆ setVerbosity() [3/6]

static void setVerbosity	(	Logger	logger,
		Verbosity	verbosity,
		String	domain,
		int	priority
	)

static

Sets the Verbosity of the Log Domain which is evaluated from parameter domain and applicable Scope Domains. The verbosity given, is set recursively for all sub-domains.

With the first invocation of this method for a distinct logger, this Logger is registered with this Lox. In this case, prior to setting the given Verbosity for the evaluated sub-domain, the Verbosity for all domains is set to Verbosity.Off.

To deregister a Logger with a Lox, use method removeLogger. To 'disable' a Logger, invoke this method with parameters verbosity equaling to Verbosity.Off and domain to "/".

Optional parameter priority defaults to Configuration.PRIO_DEFAULT_VALUES, which is a lower priority than those of the standard plug-ins of external configuration data. Therefore, external configuration by default 'overwrite' settings made from 'within the source code', which simply means by invoking this method.
The parameter can be provided for two main reasons:

To 'lock' a verbosity setting against external manipulation.
to 'break' the standard mechanism that an invocation of this method sets all sub-domains recursively. If a sub-domain was set with a higher priority (e.g. PRIO_SOURCE + 1, then this sub-domain will not be affected by future invocations of this method with standard-priority given.

Attention: The same as with most interface methods of this class, the given domain parameter is combined with Scope Domains set for the callers' Scope. In standard use cases of ALox, the Verbosity of a Domain is set using absolute domain path addressing. Therefore, it is recommended to have any domain path passed to this method starting with '/', which suppresses the concatenation of Scope Domains.
This is why this parameter with this method defaults to '/', while with other methods of this class, it defaults to an empty string.; Even when using an absolute domain path, Scope Domains of Scope.THREAD_INNER, will still apply. This means that from within a thread that has such Scope Domain set, this method is (almost) not usable! This all aligns with the concept (advice), that Loggers and their Verbosity are generally set outside of such scopes, hence in configuration sections of a process.; Consequently, this method may be (mis-) used to modify the 'actual' (default) scope when explicitly giving an empty string with parameter domain. This is useful, to temporarily adjust a scope. But remember: ALox was designed to avoid temporary code lines...

Parameters

logger	The logger to be to be affected (case insensitive).
verbosity	The 'level of verboseness' to be set.
domain	The parent (start) domain to be set. The use of absolute paths starting with `'/'` are recommended. Defaults to root domain "/".
priority	The priority of the setting. Defaults to Configuration.PRIO_DEFAULT_VALUES, which is a lower priority than standard plug-ins of external configuration have.

◆ setVerbosity() [4/6]

static void setVerbosity	(	String	loggerName,
		Verbosity	verbosity
	)

static

Overloaded version of setVerbosity providing

default value PRIO_SOURCE for parameter priority and
default value '/' for parameter domain.

Parameters

loggerName	The logger to be to be affected, identified by its name (case insensitive).
verbosity	The 'level of verboseness' to be set.

◆ setVerbosity() [5/6]

static void setVerbosity	(	String	loggerName,
		Verbosity	verbosity,
		String	domain
	)

static

Overloaded version of setVerbosity providing default value PRIO_SOURCE for parameter priority.

Parameters

loggerName	The logger to be to be affected, identified by its name (case insensitive).
verbosity	The 'level of verboseness' to be set.
domain	The parent (start) domain to be set. The use of absolute paths starting with `'/'` are recommended. Defaults to root domain "/".

◆ setVerbosity() [6/6]

static void setVerbosity	(	String	loggerName,
		Verbosity	verbosity,
		String	domain,
		int	priority
	)

static

Same as setVerbosity but addressing the Logger to manipulate by its name.
This method may only be used after a Logger was once 'registered' with this Lox using setVerbosity.

Parameters

loggerName	The logger to be to be affected, identified by its name (case insensitive).
verbosity	The 'level of verboseness' to be set.
domain	The parent (start) domain to be set. The use of absolute paths starting with `'/'` are recommended. Defaults to root domain "/".
priority	The priority of the setting. Defaults to Configuration.PRIO_DEFAULT_VALUES, which is a lower priority than standard plug-ins of external configuration have.

◆ state() [1/2]

static void state	(	String	domain,
		Verbosity	verbosity,
		String	headLine
	)

static

Overloaded version of state providing default value STATE_INFO_ALL for parameter flags.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The verbosity.
headLine	If given, a separated headline will be logged at first place.

◆ state() [2/2]

static void state	(	String	domain,
		Verbosity	verbosity,
		String	headLine,
		int	flags
	)

static

This method logs the current configuration of this Lox and its encapsulated objects. It uses method getState to assemble the logable string.

Note: As an alternative to (temporarily) adding an invocation of Lox.State to your code, ALox provides configuration variable ALOX_LOXNAME_DUMP_STATE_ON_EXIT. This allows to enable an automatic invocation of this method using external configuration data like command line parameters, environment variables or INI files.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The verbosity.
headLine	If given, a separated headline will be logged at first place.
flags	Flag bits that define which state information is logged.