Inheritance diagram for Lox:

Collaboration diagram for Lox:

Class Description

This class acts as a container for Loggers and provides a convenient interface to logging. Fore information how to use this class, checkout the ALox tutorials and the ALox User Manual.

Inner Classes
class	DomainSubstitutionRule

enum	DSRType

Public Static Fields
static final int	STATE_INFO_ALL = ~0
	All information available.

static final int	STATE_INFO_BASIC = 1 << 0
	Name and number of log calls.

static final int	STATE_INFO_DOMAINS = 1 << 3
	Domains currently registered.

static final int	STATE_INFO_DSR = 1 << 6
	Domain substitution rules.

static final int	STATE_INFO_INTERNAL_DOMAINS = 1 << 4
	Internal domains.

static final int	STATE_INFO_LOG_DATA = 1 << 9
	Log data objects.

static final int	STATE_INFO_LOGGERS = 1 << 2
	Loggers.

static final int	STATE_INFO_ONCE = 1 << 8
	Log once counters.

static final int	STATE_INFO_PREFIX_LOGABLES = 1 << 7
	Prefix logables.

static final int	STATE_INFO_SCOPE_DOMAINS = 1 << 5
	Scope domains.

static final int	STATE_INFO_THREAD_MAPPINGS = 1 << 10
	Named threads.

static final int	STATE_INFO_VERSION = 1 << 1
	Library Version and thread safeness.

Public Fields
int	cntLogCalls = 0

Vector< String >	omittablePackagePrefixes

Public Fields inherited from ThreadLock
int	recursionWarningThreshold = 10

int	waitWarningTimeLimitInMillis = 1000

Public Static Methods
static TextLogger	createConsoleLogger ()

static TextLogger	createConsoleLogger (String name)

Public Methods
	Lox (String name)

	Lox (String name, boolean doRegister)

void	acquire ()

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

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

void	entryDetectDomain (Verbosity verbosity, Object... logables)

void	error (Object... logables)

Logger	getLogger (String loggerName)

String	getName ()

void	getState (AString buf, int flags)

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

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

void	info (Object... logables)

boolean	isRegistered ()

void	mapThreadName (String threadName)

void	mapThreadName (String threadName, long id)

void	once (Object logables)

void	once (Object logables, int quantity)

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

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

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

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

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

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

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

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

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

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

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

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

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

void	release ()

boolean	removeLogger (Logger logger)

Logger	removeLogger (String loggerName)

void	removeThreadDomain (String scopeDomain, Scope scope)

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

Object	retrieve ()

Object	retrieve (Scope scope)

Object	retrieve (Scope scope, int pkgLevel)

Object	retrieve (String key)

Object	retrieve (String key, Scope scope)

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

void	setDomain (String scopeDomain, Scope scope)

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

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

void	setDomainSubstitutionRule (String domainPath, String replacement)

void	setPrefix (Object logable)

void	setPrefix (Object logable, String domain)

void	setPrefix (Object prefix, Scope scope)

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

void	setPrefix (Object prefix, Scope scope, Thread thread)

void	setPrefix (Object prefix, String domain, Inclusion otherPLs)

void	setStartTime ()

void	setStartTime (Date startTime)

void	setStartTime (Date startTime, String loggerName)

void	setVerbosity (Logger logger, Verbosity verbosity)

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

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

void	setVerbosity (String loggerName, Verbosity verbosity)

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

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

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

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

void	store (Object data)

void	store (Object data, Scope scope)

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

void	store (Object data, String key)

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

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

void	verbose (Object... logables)

void	warning (Object... logables)

Public Methods inherited from ThreadLock
	ThreadLock ()

	ThreadLock (LockMode lockMode)

	ThreadLock (LockMode lockMode, Safeness safeness)

int	dbgCountAcquirements (Thread thread)

LockMode	getMode ()

Safeness	getSafeness ()

void	setSafeness (Safeness safeness)

String	toString ()

boolean	willRelease ()

Protected Static Fields
static final String	noKeyHashKey = "$"

Protected Fields
boolean[]	booleanOutputParam = new boolean[1]

Domain	domains

ArrayList< DomainSubstitutionRule >	domainSubstitutions = new ArrayList<DomainSubstitutionRule>()

Domain	internalDomains

AString	intMsg = new AString( 256 )

ArrayList< ArrayList< Object > >	logableLists = new ArrayList<ArrayList<Object>>()

boolean	loggerAddedSinceLastDebugState =false

int	maxDomainPathLength = 0

int	maxLoggerNameLength = 0

boolean	oneTimeWarningCircularDS =false

AString	resDomain = new AString( 32 )

AString	resDomainInternal = new AString( 32 )

ScopeStore< AString >	scopeDomains

ScopeInfo	scopeInfo

ScopeStore< HashMap< AString, Object > >	scopeLogData

ScopeStore< HashMap< AString, int[]> >	scopeLogOnce

ScopeStore< Object >	scopePrefixes

AString	tmpAS = new AString( 64 )

AString	tmpComments = new AString( 128 )

AString	tmpSubstitutionPath = new AString( 64 )

AString	tmpSubstitutionPathInternalDomains = new AString( 64 )

Protected Fields inherited from ThreadLock
int	cntAcquirements

boolean	createOwnerStackTrace = false

LockMode	lockMode

Object	mutex

Thread	owner

Exception	ownerException

Ticks	waitTime = new Ticks()

Protected Static Methods
static void	insertLogables (ArrayList< Object > list, Object logable)

Protected Methods
void	construct (String name, boolean doRegister)

void	dumpStateOnLoggerRemoval ()

Domain	evaluateResultDomain (String domainPath)

void	getAllVerbosities (Logger logger, Domain dom, Variable cfgResult)

void	getDomainPrefixFromConfig (Domain dom)

void	getVerbosityFromConfig (Logger logger, Domain dom, Variable variable)

boolean	isThreadRelatedScope (Scope scope)

void	log (Domain dom, Verbosity verbosity, Object[] logables, Inclusion prefixes)

void	logInternal (Verbosity verbosity, String subDomain, AString logable)

void	logStateCollectPrefixes (Domain domain, int indentSpaces, AString target)

void	logStateDomainRecursive (Domain domain, AString buf)

void	logStateDomainsWithDiffVerb (Domain domain, int loggerNo, ArrayList< Domain > results)

void	setDomainImpl (String scopeDomain, Scope scope, int packageLevel, boolean removeNTRSD, Thread thread)

void	setPrefixImpl (Object prefix, Scope scope, int packageLevel, Thread thread)

void	verbositySettingToVariable (Domain domain, int loggerNo, Variable variable)

void	writeVerbositiesOnLoggerRemoval (Logger logger)

Package Access Methods
Domain	findDomain (Domain domainSystem, AString domainPath)

Package Access Methods inherited from ThreadLock
void	constructor (LockMode lockMode, Safeness safeness)

Constructor & Destructor Documentation

◆ Lox() [1/2]

Lox	(	String	name,
		boolean	doRegister
	)

Constructs a new, empty Lox with the given name. The name is immutable and all Lox objects registered with ALox must be unique. Lower case letters in the name are converted to upper case. The name "Log" is reserved for the internal default singleton used for debug-logging.

If parameter register is true (the default), static method ALox.register is invoked and the object will be retrievable with static method ALox.get. In some situations, such 'registration' may not be wanted.

Parameters

name	The name of the Lox. Will be converted to upper case.
doRegister	If `true`, this object is registered with static class ALox. Optional and defaults to `true`.

◆ Lox() [2/2]

Lox ( String name )

Overloaded constructor providing value true for parameter doRegister.

Parameters

name	The name of the Lox. Will be converted to upper case.

Member Function Documentation

◆ acquire()

void acquire ( )

Acquires the lock and stores scope information

Reimplemented from ThreadLock.

◆ Assert()

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

Logs a list of Logables only if parameter condition is not true.

If executed, Verbosity.ERROR is used.

The first logable provided may be a domain name. All values are passed to entryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

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.

◆ construct()

void construct	(	String	name,
		boolean	doRegister
	)

protected

Protected constructor helper method

Parameters

name	The name of the Lox. Will be converted to upper case.
doRegister	If `true`, this object is registered with static class ALox. Optional and defaults to `true`.

◆ createConsoleLogger() [1/2]

static TextLogger createConsoleLogger ( )

static

Overloaded method providing default parameter null.

Returns: The TextLogger that was chosen.

◆ createConsoleLogger() [2/2]

static TextLogger createConsoleLogger ( String name )

static

This static method creates an adequate/default console logger. Currently, there is no detection mechanism implemented in the Java implementation of ALox. This might change in the future.

Hence, unless configuration variable ALOX_CONSOLE_TYPE is set, this method creates a logger of type ConsoleLogger.

Parameters

name	The name of the Logger. A value of null implies standard logger names defined in the Logger sub-classes.

Returns: The TextLogger that was chosen.

◆ dumpStateOnLoggerRemoval()

void dumpStateOnLoggerRemoval ( )

protected

Implements functionality for configuration variable LOXNAME_DUMP_STATE_ON_EXIT. Is called when a logger is removed.

◆ entry()

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

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.

◆ entryDetectDomain()

void entryDetectDomain	(	Verbosity	verbosity,
		Object...	logables
	)

Logs a list of Logables with the given Verbosity.

If more than one Logable is given and the first one is of string type and comprises a valid domain name, then this first argument is interpreted as a the domain name! Valid domain names are strings that consists only of characters of the following set:

upper case letters,
numbers,
hyphen ('-') and
underscore ('_').

If a first Logable could be misinterpreted as being a domain name, an empty string (the "neutral" domain) has to be added as a first argument. Alternatively, a character which is illegal in respect to domain names could be added to the first argument, for example a simple space at the end of an output string.

Note: This method allows a consistent interface of overloaded methods Info, Error, etc, without introducing a separate version which excepts a then mandatory domain parameter. The little drawback of the auto detection is the possibility of ambiguous invocations.

Parameters

verbosity	The verbosity.
logables	The logables with optionally a detectable domain name as a first argument.

◆ error()

void error ( Object... logables )

Logs a list of Logables using Verbosity.ERROR.

The first logable provided may be a domain name. All values are passed to entryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

Parameters

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

◆ evaluateResultDomain()

Domain evaluateResultDomain ( String domainPath )

protected

Assembles the resulting domain from the given domainPath and the Scope Domain paths (see setDomain) according to the scope identified by scopeInfo. The resulting full domain string is assembled from inner to outer scope. If domainPath, respectively as soon as any of the scope levels' Scope Domain paths starts with the character defined in Domain.PATH_SEPARATOR, the evaluation is stopped (the path is interpreted as absolute).

Parameters

domainPath The domain path. If starting with the character defined in Domain.PATH_SEPARATOR, no Scope Domains are applied.

Returns: The resulting Domain.

◆ findDomain()

Domain findDomain	(	Domain	domainSystem,
		AString	domainPath
	)

package

Invokes Find on the given domain and logs internal message when the domain was not known before.

Parameters

domainSystem	The domain system. Either the standard or the internal one.
domainPath	The domain path.

Returns: The resulting Domain.

◆ getAllVerbosities()

void getAllVerbosities	(	Logger	logger,
		Domain	dom,
		Variable	cfgResult
	)

protected

Reads the verbosity for the given logger and domain from the ALib configuration system. This internal method is used when a new logger is added. Walks recursively for all existing domains.

Parameters

logger	The logger to set the verbosity for.
dom	The domain to set the verbosity for.
cfgResult	The result of the search for the variable to set verbosities from.

◆ getDomainPrefixFromConfig()

void getDomainPrefixFromConfig ( Domain dom )

protected

Reads a prefix string from the ALib configuration system. This internal method is used when a new domain is created,

Parameters

dom	The domain to set the verbosity for.

◆ getLogger()

Logger getLogger ( String loggerName )

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.

◆ getName()

String getName ( )

Returns the name of this Lox. The name user defined, provided in the constructor, converted to upper case and otherwise immutable.

Returns: The name of this Lox.

◆ getState()

void getState	(	AString	buf,
		int	flags
	)

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.

◆ getVerbosityFromConfig()

void getVerbosityFromConfig	(	Logger	logger,
		Domain	dom,
		Variable	variable
	)

protected

Reads the verbosity for the given logger and domain from the ALib configuration system. This internal method is used in two occasions:

when a new logger is added: recursively for all existing domains (configStr is given)
when a new domain is created on the fly(configStr is not given)

Parameters

logger	The logger to set the verbosity for.
dom	The domain to set the verbosity for.
variable	The (already read) variable to set verbosities from.

◆ If() [1/2]

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

Logs a list of Logables only if the parameter condition is true.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

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]

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

Logs a list of Logables only if the parameter condition is true. This overloaded version omits parameter domain.

The first logable provided may be a domain name. All values are passed to entryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

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()

void info ( Object... logables )

Logs a list of Logables using Verbosity.INFO.

The first logable provided may be a domain name. All values are passed to entryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

Parameters

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

◆ insertLogables()

static void insertLogables	(	ArrayList< Object >	list,
		Object	logable
	)

staticprotected

Simple helper method that inserts a logable at the front of given list. If the logable is an object array, each object will be inserted.

Parameters

list	The logable list
logable	The logable or array of logables.

◆ isRegistered()

boolean isRegistered ( )

Status of registration with ALox. To keep a Lox "private" using parameter doRegister of the constructor, allows to suppress registration. Registered instances of this class can be statically received (by their name) using ALox.get.

Returns: true if this instance was registered with ALox, false if not.

◆ isThreadRelatedScope()

boolean isThreadRelatedScope ( Scope scope )

protected

Checks if given scope is thread-related.

Parameters

scope The scope that is to be checked.

Returns: true if scope is thread-related, false else.

◆ log()

void log	(	Domain	dom,
		Verbosity	verbosity,
		Object[]	logables,
		Inclusion	prefixes
	)

protected

This method is looping over the Loggers, checking their verbosity against the given one, and, if they match, invoke the log method of the Logger. With the first logger identified to be active, the Prefix Objects get collected from the scope store.

Parameters

dom	The domain to log on
verbosity	The verbosity.
logables	The objects to log.
prefixes	Denotes if prefixes should be included or not.

◆ logInternal()

void logInternal	(	Verbosity	verbosity,
		String	subDomain,
		AString	logable
	)

protected

Logs an internal error message using the internal domain tree as defined in ALox.INTERNAL_DOMAINS.

Parameters

verbosity	The verbosity.
subDomain	The sub-domain of the internal domain to log into.
logable	The message.

◆ logStateCollectPrefixes()

void logStateCollectPrefixes	(	Domain	domain,
		int	indentSpaces,
		AString	target
	)

protected

Internal method used by State() to recursively (DFS) log Prefix Logables bound to Log Domains

Parameters

domain	The actual domain to check.
indentSpaces	The number of spaces to write before each line.
target	The target string.

◆ logStateDomainRecursive()

void logStateDomainRecursive	(	Domain	domain,
		AString	buf
	)

protected

Internal method used by State() to recursively log Domain instances.

Parameters

domain	The Domain instance to log out.
buf	The buffer to log to.

◆ logStateDomainsWithDiffVerb()

void logStateDomainsWithDiffVerb	(	Domain	domain,
		int	loggerNo,
		ArrayList< Domain >	results
	)

protected

Internal method used by State() to recursively (DFS) collect Domains of Logger that have a different verbosity than their parent.

Parameters

domain	The actual domain to check.
loggerNo	The logger to collect domains for.
results	The result list.

◆ mapThreadName() [1/2]

void mapThreadName ( String threadName )

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

Parameters

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

◆ mapThreadName() [2/2]

void mapThreadName	(	String	threadName,
		long	id
	)

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

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]

void once ( Object logables )

Overloaded version of once.

Parameters

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

◆ once() [2/15]

void once	(	Object	logables,
		int	quantity
	)

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]

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

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]

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

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]

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

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]

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

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]

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

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]

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

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]

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

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]

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

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]

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

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]

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

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]

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

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]

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

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]

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

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 for C#, 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`. If negative, the first and every "-quantity-th" statement is executed.

◆ release()

void release ( )

Releases latest scope information and the lock

Reimplemented from ThreadLock.

◆ removeLogger() [1/2]

boolean removeLogger ( Logger logger )

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]

Logger removeLogger ( String loggerName )

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]

void removeThreadDomain	(	String	scopeDomain,
		Scope	scope
	)

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]

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

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.

◆ retrieve() [1/6]

Object retrieve ( )

Overloaded version of retrieve which omits parameters.

Returns: The object, null if nothing was found.

◆ retrieve() [2/6]

Object retrieve ( Scope scope )

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]

Object retrieve	(	Scope	scope,
		int	pkgLevel
	)

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]

Object retrieve ( String key )

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]

Object retrieve	(	String	key,
		Scope	scope
	)

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]

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

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

Note: If no Log Data object is found, an empty object is stored and returned.

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]

void setDomain	(	String	scopeDomain,
		Scope	scope
	)

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]

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

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 if parameter scope equals Scope.PACKAGE to reference parent packages. Optional and defaults to `0`.

◆ setDomain() [3/3]

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

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.

◆ setDomainImpl()

void setDomainImpl	(	String	scopeDomain,
		Scope	scope,
		int	packageLevel,
		boolean	removeNTRSD,
		Thread	thread
	)

protected

Implementation of the interface method fetching all possible parameters.

Parameters

scopeDomain	The domain path to register.
scope	The scope that the given domain should be registered for. Available Scope definitions are platform/language dependent.
packageLevel	Used only if parameter scope equals Scope.PACKAGE to reference parent packages. Optional and defaults to `0`.
removeNTRSD	Used to remove thread-related Scope Domains (and is true only when invoked by interface method removeThreadDomain.
thread	The thread to set/unset a thread-related Scope Domain for.

◆ setDomainSubstitutionRule()

void setDomainSubstitutionRule	(	String	domainPath,
		String	replacement
	)

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]

void setPrefix ( Object logable )

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

Parameters

logable The Prefix Logable(s) to set.

◆ setPrefix() [2/6]

void setPrefix	(	Object	logable,
		String	domain
	)

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

Parameters

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

◆ setPrefix() [3/6]

void setPrefix	(	Object	prefix,
		Scope	scope
	)

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() [4/6]

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

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`.

◆ setPrefix() [5/6]

void setPrefix	(	Object	prefix,
		Scope	scope,
		Thread	thread
	)

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

prefix	The Prefix Logable(s) 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() [6/6]

void setPrefix	(	Object	prefix,
		String	domain,
		Inclusion	otherPLs
	)

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.

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 );

Parameters

prefix	The Prefix Logable(s) 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`.

◆ setPrefixImpl()

void setPrefixImpl	(	Object	prefix,
		Scope	scope,
		int	packageLevel,
		Thread	thread
	)

protected

Implementation of the interface method fetching all possible parameters.

Parameters

prefix	The Prefix Logable(s) to set.
scope	The scope that the given logable should 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`.
thread	The thread to set/unset a thread-related Prefix Logable for.

◆ setStartTime() [1/3]

void setStartTime ( )

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

◆ setStartTime() [2/3]

void setStartTime ( Date startTime )

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]

void setStartTime	(	Date	startTime,
		String	loggerName
	)

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]

void setVerbosity	(	Logger	logger,
		Verbosity	verbosity
	)

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]

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

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]

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

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_DEFAULT_VALUES + 1, then this sub-domain will not be affected by future invocations of this method with standard-priority given.

For more information on how to use external configuration variables with priority and on protecting verbosity settings, consult the ALox User Manual.

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.

◆ setVerbosity() [4/6]

void setVerbosity	(	String	loggerName,
		Verbosity	verbosity
	)

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]

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

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]

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

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.

◆ state() [1/2]

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

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]

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

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.

◆ store() [1/6]

void store ( Object data )

Overloaded version of store providing default parameters.

Parameters

data	The data object to store. If `null`, currently stored data will be removed.

◆ store() [2/6]

void store	(	Object	data,
		Scope	scope
	)

Overloaded version of store providing default parameters.

Parameters

data	The data object to store. If `null`, currently stored data will be removed.
scope	The Scope that the data is bound to.

◆ store() [3/6]

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

Overloaded version of store providing default parameters.

Parameters

data	The data object to store. If `null`, currently stored data will be removed.
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`.

◆ store() [4/6]

void store	(	Object	data,
		String	key
	)

Overloaded version of store providing default parameters.

Parameters

data	The data object to store. If `null`, currently stored data will be removed.
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.

◆ store() [5/6]

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

Overloaded version of store providing default parameters.

Parameters

data	The data object to store. If `null`, currently stored data will be removed.
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.

◆ store() [6/6]

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

Stores an object which can afterwards be retrieved by invoking retrieve. Optional parameters key and scope offer various possibilities to reference this data later.

To remove data from the store, pass null with parameter data.

Attention: When data objects are 'overwritten', previous objects will be deleted internally. Hence, only pointers to heap-allocated objects (created with new) may be passed!
For more information, consult the ALox User Manual.

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

data	The data object to store. If `null`, currently stored data will be removed.
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`.

◆ verbose()

void verbose ( Object... logables )

Logs a list of Logables using Verbosity.VERBOSE.

The first logable provided may be a domain name. All values are passed to entryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

Parameters

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

◆ verbositySettingToVariable()

void verbositySettingToVariable	(	Domain	domain,
		int	loggerNo,
		Variable	variable
	)

protected

Helper method of dumpStateOnLoggerRemoval to recursively collect domain settings.

Parameters

domain	The actual domain.
loggerNo	The number of the logger
variable	The AString to collect the information.

◆ warning()

void warning ( Object... logables )

Logs a list of Logables using Verbosity.WARNING.

The first logable provided may be a domain name. All values are passed to entryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

Parameters

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

◆ writeVerbositiesOnLoggerRemoval()

void writeVerbositiesOnLoggerRemoval ( Logger logger )

protected

Implements functionality for configuration variable LOXNAME_LOGGERNAME_VERBOSITY. Is called when a logger is removed.

Parameters

logger The logger to write the verbosity for.

Member Data Documentation

◆ booleanOutputParam

boolean [] booleanOutputParam = new boolean[1]

protected

A temporary object following the "create once and reuse" design pattern.

◆ cntLogCalls

int cntLogCalls = 0

A counter for the quantity of calls. The count includes logs that were suppressed by disabled Log Domain and those suppressed by the optional log condition parameter.

◆ domains

Domain domains

protected

The root domain "/". All registered domains become a sub domain of this root. If a Sub-Log Domains' Verbosity is not explicitly set, such sub domain inherits the verbosity of its parent.

◆ domainSubstitutions

ArrayList<DomainSubstitutionRule> domainSubstitutions = new ArrayList<DomainSubstitutionRule>()

protected

The list of domain substitution rules.

◆ internalDomains

Domain internalDomains

protected

The root domain for internal Log Domains.

◆ intMsg

AString intMsg = new AString( 256 )

protected

A temporary AString, following the "create once and reuse" design pattern.

◆ logableLists

ArrayList<ArrayList<Object> > logableLists = new ArrayList<ArrayList<Object>>()

protected

A list of lists of objects. The list is passed to the Loggers. For each recursive call, one list is created.

◆ loggerAddedSinceLastDebugState

boolean loggerAddedSinceLastDebugState =false

protected

Flag used with configuration variable LOXNAME_DUMP_STATE_ON_EXIT.

◆ maxDomainPathLength

int maxDomainPathLength = 0

protected

Used for tabular output of logger lists

◆ maxLoggerNameLength

int maxLoggerNameLength = 0

protected

Used for tabular output of logger lists

◆ noKeyHashKey

final String noKeyHashKey = "$"

staticprotected

A key value used in stores if no key is given (global object).

◆ omittablePackagePrefixes

Vector<String> omittablePackagePrefixes

A list of prefixes of 'packages.classes.methods' on the stack that are ignored when identifying the scope info. Usually this contains "com.aworx.lox" and "com.aworx.lib" and there is no need to change this.

◆ oneTimeWarningCircularDS

boolean oneTimeWarningCircularDS =false

protected

Flag if a warning on circular rule detection was logged.

◆ resDomain

AString resDomain = new AString( 32 )

protected

The resulting domain name.

◆ resDomainInternal

AString resDomainInternal = new AString( 32 )

protected

The resulting domain name for internal logs.

◆ scopeDomains

ScopeStore<AString> scopeDomains

protected

Scope Domains .

◆ scopeInfo

ScopeInfo scopeInfo

protected

Information about the source code, method, thread, etc. invoking a log call

◆ scopeLogData

ScopeStore<HashMap<AString, Object> > scopeLogData

protected

Log Data

◆ scopeLogOnce

ScopeStore<HashMap<AString, int[]> > scopeLogOnce

protected

Log once counters

◆ scopePrefixes

ScopeStore<Object> scopePrefixes

protected

Prefix logables store

◆ tmpAS

AString tmpAS = new AString( 64 )

protected

A temporary AString

◆ tmpComments

AString tmpComments = new AString( 128 )

protected

A temporary AString

◆ tmpSubstitutionPath

AString tmpSubstitutionPath = new AString( 64 )

protected

Temporary string used with domain substitutions.

◆ tmpSubstitutionPathInternalDomains

AString tmpSubstitutionPathInternalDomains = new AString( 64 )

protected

Temporary string used with domain substitutions.

The documentation for this class was generated from the following file:

Lox.java

Class Description

Inner Classes

Public Static Fields

Public Fields

Public Static Methods

Public Methods

Protected Static Fields

Protected Fields

Protected Static Methods

Protected Methods

Package Access Methods

Constructor & Destructor Documentation

◆ Lox() [1/2]

◆ Lox() [2/2]

Member Function Documentation

◆ acquire()

◆ Assert()

◆ construct()

◆ createConsoleLogger() [1/2]

◆ createConsoleLogger() [2/2]

◆ dumpStateOnLoggerRemoval()

◆ entry()

◆ entryDetectDomain()

◆ error()

◆ evaluateResultDomain()

◆ findDomain()

◆ getAllVerbosities()

◆ getDomainPrefixFromConfig()

◆ getLogger()

◆ getName()

◆ getState()

◆ getVerbosityFromConfig()

◆ If() [1/2]

◆ If() [2/2]

◆ info()

◆ insertLogables()

◆ isRegistered()

◆ isThreadRelatedScope()

◆ log()

◆ logInternal()

◆ logStateCollectPrefixes()

◆ logStateDomainRecursive()

◆ logStateDomainsWithDiffVerb()

◆ mapThreadName() [1/2]

◆ mapThreadName() [2/2]

◆ once() [1/15]

◆ once() [2/15]

◆ once() [3/15]

◆ once() [4/15]

◆ once() [5/15]

◆ once() [6/15]

◆ once() [7/15]

◆ once() [8/15]

◆ once() [9/15]

◆ once() [10/15]

◆ once() [11/15]

◆ once() [12/15]

◆ once() [13/15]

◆ once() [14/15]

◆ once() [15/15]

◆ release()

◆ removeLogger() [1/2]

◆ removeLogger() [2/2]

◆ removeThreadDomain() [1/2]

◆ removeThreadDomain() [2/2]

◆ retrieve() [1/6]

◆ retrieve() [2/6]

◆ retrieve() [3/6]

◆ retrieve() [4/6]

◆ retrieve() [5/6]

◆ retrieve() [6/6]

◆ setDomain() [1/3]

◆ setDomain() [2/3]

◆ setDomain() [3/3]

◆ setDomainImpl()

◆ setDomainSubstitutionRule()

◆ setPrefix() [1/6]

◆ setPrefix() [2/6]

◆ setPrefix() [3/6]

◆ setPrefix() [4/6]