1. Introduction

Domain Substitution is a concept of ALox that allows to manipulate the effective domain of Log Statements without changing neither these statements nor the Scope Domains that apply to them. Therefore, Domain Substitution is useful when those changes can not be performed (e.g. because the corresponding ALox code is residing in a library) or because a temporary "redirect" of certain domains is wanted.

As with Scope Domain settings, the concept of Domain Substitution in general should not be 'overused'. Otherwise, things might get complicated.

The rules are set and removed with method Lox.SetDomainSubstitutionRule (C++, C#, Java), which accepts two parameters:

domainPath:
The domain path (substring) that is to be searched and replaced. For the search, a simple 'wildcard' mechanism is aplied: It is allowed to use character '*' at the beginning and/or the end of the search string. As a result, four 'types' of rules can be created
- Exact match (no * given)
- Prefix match (* at the end of domainPath)
- Suffix match (* at the start of domainPath)
- Substring match (* at both, start and the end of domainPath)
replacement:
This is the string that replaces the string in domainPath when the rule matches. If this is empty (or nulled), the rule is removed from the Lox.

If for any reason, all rules should be deleted at once, invoke method Lox.SetDomainSubstitutionRule with providing a nulled or empty string for domainPath. There is no explicit other method for clearing the rules given, because the designers of ALox do not see a use case for doing this.

2. How Class Lox Processes the Rules

Rules for Domain Substitution are applied after any other evaluation of the resulting domain is performed. The rules are applied in the order of their definition. Therefore, rules that are passed from configuration files (or command line, etc.) are applied first. Rules might influence each other, hide each oder or even be circular. When setting the rules, ALox does not check for such (sometimes wanted) dependencies of the rules. It might happen, that a rule that was defined earlier than a different one, would be effective only after the second rule was applied. Therefore, ALox repeats the application of all rules as long as at least one of the rules matched. Because of the possibility of having circular dependencies, a maximum amount of ten loops is performed. After that, ALox stops processing Domain Substitution and writes a Log Statement of Verbosity.Error to the internal domain. The error message is only issued once. However the flag is reset when all rules are cleared (by providing a nulled string value for parameter domainPath of method Lox.SetDomainSubstitutionRule (C++, C#, Java)).

This amount of loops should be more than enough for all major use cases. Even a third loop is necessary very seldom.

3. Substitution Rules and External Configuration

3.1 Using External Configuration

Setting Domain Substitution Rules 'from within the source code' is easy and straightforward. However, when working in a team such changes might not be appreciated by other team members. In this and other situations it is advisable to retrieve Domain Substitution Rules from external configuration data, command-line parameters or other sources at runtime.

For Domain Substitution Rules and also other configuration data, ALox leverages the configuration facility provided by underlying utility library ALib.

Note: For general information on ALox configuration variables consult I - Configuration Variables.
For information on how to pass configuration data from custom sources to ALox, refer to namespace documentation aworx::lib::config (C++, C#, Java).

The constructor of class Lox tries to read a configuration variable named ALOX_LOXNAME_DOMAIN_SUBSTITUTION. When setting the variable, the substring 'LOXNAME' needs to be replaced by the name of the Lox in question. The variable itself may contain a list of Domain Substitution Rules separated by semicolons ';'. Each rule consists of two strings which correspond to the two parameters of method Lox.SetDomainSubstitutionRule (C++, C#, Java). These two strings are to be separated by '->'.

As an example, an INI file of an application might have the following sub-section:

[ALOX]
MYLOX_DOMAIN_SUBSTITUTION= /A_DOM -> /BETTER_NAME   ; \
                           /UI    -> /LIBS/UI

With variable ALOX_MYLOX_DOMAIN_SUBSTITUTION set in the INI file, a Lox named 'MYLOX' would receive the two rules specified.

3.2 Preventing The Use Of External Configuration

Sometimes it might be wanted that Domain Substitution Rules are not manipulable externally. A reason could be that by the nature of these rules, unauthorized users are enabled to change the Log Domains and hence also to change their Verbosity, which otherwise can be prevented for protection (see 13 - External Verbosity Configuration).

ALox does not provide an explicit interface to prevent reading the rules from the configuration. The simple way out, is to delete all rules after the creation of the lox:

myLox= new Lox( "MyLox" ); // name will be converted to upper case

myLox.SetDomainSubstitutionRule( null, null ); // clear rules eventually read in constructor

4. Final Remarks

Domain Substitution rules are always applied to all Loggers within a Lox.

As noted already, Domain Substitution should be used with care and in case of doubt, thought well. Different alternatives to setting a Domain Substitution exist. For example, to manipulate the domain of methods executed within a library, a thread-related Scope Domain setting may be set prior to invoking library methods.

Prefix Logables that have been set for a domain that gets substituted, of-course do not apply to the substitution domain. In contrast, a Log Statement whose resulting domain gets substituted works just as it was using the new domain within its invocation and Scope Domain setting. Therefore, Domain Substitution settings - if at all - should be made at the beginning of a processes life-cycle and then should not be altered. In this case, also Prefix Logables will be 'transferred' to the substitution domain, providing that the commands that are setting them use relative domain paths.

Domain Substitution may not be used to substitute Log Domains of the standard domain tree with those of the internal tree or vice versa.

Next chapter: 16 - Colorful Loggers Back to index