ALox  V. 2402 R. 0
Home ALox for C++ ALox for C# ALox for Java Download
Public Static Fields | Public Static Methods | Protected Static Fields | Private Static Fields | List of all members
ALox Class Referenceabstract
Collaboration diagram for ALox:
[legend]

Class Description


This is a 100% static class that holds constants and 'global' methods of the ALox Logging Library.

Public Static Fields

static VariableDecl AUTO_SIZES
 
static Configuration config =null
 
static AString configCategoryName = new AString( "ALOX" )
 
static VariableDecl CONSOLE_LIGHT_COLORS
 
static VariableDecl CONSOLE_TYPE
 
static VariableDecl DOMAIN_SUBSTITUTION
 
static VariableDecl DUMP_STATE_ON_EXIT
 
static VariableDecl FORMAT
 
static VariableDecl FORMAT_DATE_TIME
 
static VariableDecl FORMAT_MULTILINE
 
static VariableDecl FORMAT_TIME_DIFF
 
static final String INTERNAL_DOMAINS ="$/"
 
static VariableDecl MAX_ELAPSED_TIME
 
static VariableDecl PREFIXES
 
static VariableDecl REPLACEMENTS
 
static final int revision =0
 
static VariableDecl USE_SYSTEM_OUT_PRINT
 
static VariableDecl VERBOSITY
 
static final int version =2402
 

Public Static Methods

static Lox get (String name)
 
static synchronized Lox get (String name, Create create)
 
static void init ()
 
static void init (Configuration config)
 
static void init (String[] args)
 
static Verbosity readVerbosity (Substring src)
 
static synchronized void register (Lox lox, ContainerOp operation)
 
static void reset ()
 
static AString toString (Scope scope, int packageLevel, AString target)
 
static AString toString (Verbosity verbosity, int priority, AString target)
 

Protected Static Fields

static boolean isInitialized = false
 

Private Static Fields

static ArrayList< Loxloxes = new ArrayList<Lox>()
 

Member Function Documentation

◆ get() [1/2]

static Lox get ( String  name)
static

Overloaded version of get providing value Create.ifNotExistent as default for parameter create.

Parameters
nameThe name of the Lox to search and optionally to create.
Returns
The Lox found, null in case of failure.

◆ get() [2/2]

static synchronized Lox get ( String  name,
Create  create 
)
static

Returns the Lox with the given name. A lox is only found if it was created and registered with ALox using register. If not found, and parameter create is true (the default), a new Lox is created, registered and returned.

Parameters
nameThe name of the Lox to search and optionally to create. Comparison is case insensitive.
createDenotes whether a Lox that was not found is created. Optional and defaults to Create.NEVER.
Returns
The Lox found, null in case of failure.

◆ init() [1/3]

static void init ( )
static

Parameterless variant of method init. No command line args are set with default configuration.

Returns
Returns true if ALox was initialized before, false if not.

◆ init() [2/3]

static void init ( Configuration  config)
static

Variant of method init, accepting a configuration. This will be stored in field config and used for loading and storing ALox variables.

Parameters
configThe configuration object to use.
Returns
Returns true if ALox was initialized before, false if not.

◆ init() [3/3]

static void init ( String[]  args)
static

This method must be called prior to using ALox, e.g. at the beginning of the main() method of an application. It is OK, to call this method more than once, which allows independent code blocks (e.g. libraries) to bootstrap ALox independently. However, only the first invocation is effective.

The very first invocation should not be interrupted by a parallel invocation of a second thread. Consequently, with more complex applications it is recommended to explicitly invoke this method once when the software is bootstrapped.

Note
This method invokes ALIB.init and passes the Configuration object created. Hence, no explicit initialization of underlying ALib is needed.
If a different configuration object is to be used with ALib, then ALIB.Init needs to be called explicitly prior to this method.

If command line parameters should be used for configuring ALox, then the very first call to this method has to provide the argc and argv parameters. Subsequent calls to this method with different parameters do not change the setup.

If other, custom configuration data sources should be used already with this method (to read the configuration variables as described in ALIB.init), use overloaded method ALox.init(Configuration).

Parameters
argsParameters taken from standard Java method main() (the list of command line arguments). Accepts null to ignore command line parameters.

◆ readVerbosity()

static Verbosity readVerbosity ( Substring  src)
static

Interprets given src as a verbosity. A case insensitive comparison of only the first (!) character of the start of the string is performed (against 'v', 'i', 'w' and 'e'). If no match is found, Verbosity.Off is returned.

Parameters
srcThe string to 'parse'.
Returns
The verbosity read.

◆ register()

static synchronized void register ( Lox  lox,
ContainerOp  operation 
)
static

Registers or un-registers a Lox object statically with ALox. Once registered, any code entity of the same process is enabled to retrieve the Lox using get.
No two objects with the same name must be registered. If this is done, the latter will not be registered and not be found by get. In debug-compilations, an ALib error report is written (by default raises 'assert') if a name is registered twice.
Note that name comparison is performed case in-sensitive.

If debug-logging is enabled (depends on compilation symbols) and used, the singleton of type % Lox provided for debug-logging is registered. This uses the name "Log"

Registration is not mandatory but done by default by the constructor of class Lox. Therefore, to keep a Lox private, an optional parameter is available.

Parameters
loxThe Lox to register.
operationIf ContainerOp.REMOVE, the given Lox is deregistered. Defaults to ContainerOp.INSERT.

◆ reset()

static void reset ( )
static

Resets this object. Concretely the following steps are performed:

  • All Lox objects are removed.
  • If the debug lox singleton exists, it is deleted.
Attention
This method was introduced to support resetting ALox in the unit tests. In real applications, this method should NOT be used. Side effects might appear using this method and it is not tested otherwise than used in tests!

◆ toString() [1/2]

static AString toString ( Scope  scope,
int  packageLevel,
AString  target 
)
static

Provides a string representation of the Scope enums.

Parameters
scopeThe enum value to retrieve a string representation for.
packageLevelThe package level.
targetThe target string.
Returns
A string representation of the provided Scope value.

◆ toString() [2/2]

static AString toString ( Verbosity  verbosity,
int  priority,
AString  target 
)
static

Writes a string representation of the Verbosity and priority into the given AString.

Parameters
verbosityThe enum value to retrieve a string representation for.
priorityThe priority of the verbosity setting.
targetThe target to write into.
Returns
target to allow concatenated calls.

Member Data Documentation

◆ AUTO_SIZES

VariableDecl AUTO_SIZES
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_AUTO_SIZES",
null,
'\0', null, Variable.FORMAT_HINT_NONE,
"Auto size values of last run of Logger '%1' (generated and temporary values)."
)

Attributes of corresponding configuration variable used by TextLogger.

◆ config

Configuration config =null
static

The configuration used by ALox. This is received or created with overloaded init methods. It might be shared with other libraries or can be an instance explicitly dedicated to the ALox library.
The option to use an exclusive one may be used to store ALox configuration variables in different configuration files, e.g. to reduce "clutter" of an applications' then "main" configuration file.
Changes should only be made at very initial, single threaded bootstrap code, with the invocation of the according method init(Configuration).

See also
Field configCategoryName.

◆ configCategoryName

AString configCategoryName = new AString( "ALOX" )
static

The name of the configuration category of configuration variables used by ALox.
Defaults to "ALOX".
This value can be changed to avoid conflicts between applications (especially in respect to environment variable settings). Changes should be placed at very initial bootstrap code, before the invocation of init.
See also ALIB.configCategoryName.

◆ CONSOLE_LIGHT_COLORS

VariableDecl CONSOLE_LIGHT_COLORS
static
Initial value:
= new VariableDecl(
configCategoryName, null, "CONSOLE_LIGHT_COLORS",
"",
'\0', null, Variable.FORMAT_HINT_NONE,
"Evaluated by colorful loggers that dispose about light and dark colors. Those may\n" +
"adjust their foreground and background color accordingly. If not given, under Windows OS\n" +
"the right value is detected. Otherwise the value defaults to \"foreground\". In some\n" +
"occasions, the (detected or set) runtime environment might also indicate a different\n" +
"default value. Possible values are 'foreground', 'background' and 'never'."
)

Attributes of corresponding configuration variable used by colorful specializations of class TextLogger.

◆ CONSOLE_TYPE

VariableDecl CONSOLE_TYPE
static
Initial value:
= new VariableDecl(
configCategoryName, null, "CONSOLE_TYPE",
"default",
'\0', null, Variable.FORMAT_HINT_NONE,
"Influences the type of console logger to be created by method\n" +
"Lox.CreateConsoleLogger which is also used by Log.AddDebugLogger\n" +
"Possible values are: default, plain, ansi, windows"
)

Attributes of corresponding configuration variable used by Lox.createConsoleLogger.

◆ DOMAIN_SUBSTITUTION

VariableDecl DOMAIN_SUBSTITUTION
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_DOMAIN_SUBSTITUTION",
null,
';', "->", Variable.FORMAT_HINT_MULTILINE,
""
)

Attributes of corresponding configuration variable used by Lox.

◆ DUMP_STATE_ON_EXIT

VariableDecl DUMP_STATE_ON_EXIT
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_DUMP_STATE_ON_EXIT",
"none, verbosity=info, domain=/ALOX",
',', null, Variable.FORMAT_HINT_NONE,
"Log information about lox \"%1\" on exit. Comma separated list of arguments define\n" +
"verbosity, domain and content of output. Possible values content arguments are:\n" +
" All, Basic, Version, SPTR, Loggers, Domains, InternalDomains\n" +
" ScopeDomains, DSR, PrefixLogablesOnce, LogData, ThreadMappings,\n" +
" CompilationFlags. If NONE is given nothing is dumped"
)

Attributes of corresponding configuration variable used by Lox.

◆ FORMAT

VariableDecl FORMAT
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_FORMAT",
null,
',', null, Variable.FORMAT_HINT_MULTILINE,
"Meta info format of text logger \"%1\", including signatures for verbosity strings and\n" +
"an optional string added to the end of each log statement.\n" +
" Format: metaInfoFormat [, Error [, Warning [, Info [, Verbose [, MsgSuffix ]]]]]"
)

Attributes of corresponding configuration variable used by TextLogger.

◆ FORMAT_DATE_TIME

VariableDecl FORMAT_DATE_TIME
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_FORMAT_DATE_TIME",
null,
',', null, Variable.FORMAT_HINT_NONE,
"Meta info date and time format of text logger \"%1\".\n" +
" Format: DateFormat [, TimeOfDayFormat [, TimeElapsedDays ]]]"
)

Attributes of corresponding configuration variable used by TextLogger.

◆ FORMAT_MULTILINE

VariableDecl FORMAT_MULTILINE
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_FORMAT_MULTILINE",
null,
',', null, Variable.FORMAT_HINT_NONE,
"Multi-line format of text logger \"%1\".\n" +
" Format: MultiLineMsgMode [, FmtMultiLineMsgHeadline [, FmtMultiLinePrefix [, FmtMultiLineSuffix\n" +
" [, MultiLineDelimiter [, MultiLineDelimiterRepl ]]]]]"
)

Attributes of corresponding configuration variable used by TextLogger.

◆ FORMAT_TIME_DIFF

VariableDecl FORMAT_TIME_DIFF
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_FORMAT_TIME_DIFF",
null,
',', null, Variable.FORMAT_HINT_NONE,
"Meta info time difference entities of text logger \"%1\".\n" +
" Format: TimeDiffMinimum [, TimeDiffNone [, TimeDiffNanos [, TimeDiffMicros [, TimeDiffMillis \n" +
" [, TimeDiffSecs [, TimeDiffMins [, TimeDiffHours [, TimeDiffDays ]]]]]]]]"
)

Attributes of corresponding configuration variable used by TextLogger.

◆ INTERNAL_DOMAINS

final String INTERNAL_DOMAINS ="$/"
static

This is the path for logging to the internal domain. By manipulating this Log Domain's Verbosity, the verbosity of ALox itself can be controlled. For example, with Verbosity.INFO, the 'on the fly' creation of Log Domains are logged, which can be helpful to determine the Log Domains that are created by libraries and larger projects.

The following sub-domains are used by ALox:

Sub-Domain Description
LGR Used when Loggers are registered, retrieved or removed from a Lox and when the Verbosity of a Log Domain for a Logger is changed.
In addition used with method Lox.SetStartTime.
DMN Used when Log Domains are registered (on first use), when Scope Domains are set or removed and when Domain Substitution Rules are set.
PFX Used when Prefix Logables are set or removed.
THR Used with method Lox.MapThreadName.
LGD Used with storing and retrieving Log Data objects.

In addition, class ALoxReportWriter logs into sub-domain 'REPORT'.

Note
For internal logging an separated domain tree is used. This means, that setting the root domain of a Lox to a certain Verbosity does not affect the internal domains. In other words, the Verbosity of the internal domain (or one of its sub-domains) has to be set explicitly.

◆ isInitialized

boolean isInitialized = false
staticprotected

State of initialization, used to avoid double initialization.

◆ loxes

ArrayList<Lox> loxes = new ArrayList<Lox>()
staticprivate

The Lox objects registered with us.

◆ MAX_ELAPSED_TIME

VariableDecl MAX_ELAPSED_TIME
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_MAX_ELAPSED_TIME",
"0, limit=59",
',', null, Variable.FORMAT_HINT_NONE,
"Maximum elapsed time of all runs of Logger '%1'. To reset elapsed time display\n" +
"width, set this to 0 manually. Generated and temporary value.)"
)

Attributes of corresponding configuration variable used by TextLogger.

◆ PREFIXES

VariableDecl PREFIXES
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_PREFIXES",
"",
';', "=", Variable.FORMAT_HINT_MULTILINE,
"Prefix strings for log domains of lox \"%1\".\n" +
" Format: [*]domainpath[*] = prefixstring [, inclusion] [ ; … ] "
)

Attributes of corresponding configuration variable used by Lox.

◆ REPLACEMENTS

VariableDecl REPLACEMENTS
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_REPLACEMENTS",
null,
',', null, Variable.FORMAT_HINT_NONE,
"Pairs of search and replacement strings for text logger \"%1\".\n" +
" Format: search, replacement [, search, replacement] [,...]"
)

Attributes of corresponding configuration variable used by TextLogger.

◆ revision

final int revision =0
static

The revision number of this release. Each ALox version is initially released as revision 0. Pure maintenance releases that do not change the interface of ALox are holding the same version but an increased number in this field.

◆ USE_SYSTEM_OUT_PRINT

VariableDecl USE_SYSTEM_OUT_PRINT
static
Initial value:
= new VariableDecl(
configCategoryName, null, "USE_SYSTEM_OUT_PRINT",
"false",
'\0', null, Variable.FORMAT_HINT_MULTILINE,
"ConsoleLogger uses System.console() to receive a console class object. If this fails or"+
"this variable is 'true' System.out.print() is used instead. (Java only)"
)

Attributes of corresponding configuration variable used by ConsoleLogger.

◆ VERBOSITY

VariableDecl VERBOSITY
static
Initial value:
= new VariableDecl(
configCategoryName, null, "%1_%2_VERBOSITY",
"writeback;",
';', "=", Variable.FORMAT_HINT_MULTILINE,
"The verbosities of logger \"%2\" in lox \"%1\". Use 'writeback [VAR_NAME] ;'\n" +
"to enable automatic writing on application exit."
)

Attributes of corresponding configuration variable ALOX_LOXNAME_LOGGERNAME_VERBOSITY.

◆ version

final int version =2402
static

The version of ALox. The version number follows the scheme YYMM (2-digit year, 2-digit month) of the initial release date. Besides this version number, field revision indicates if this is a revised version of a former release.


The documentation for this class was generated from the following file:
com.aworx.lox.ALox.configCategoryName
static AString configCategoryName
Definition: ALox.java:142