vy commented on code in PR #2736:
URL: https://github.com/apache/logging-log4j2/pull/2736#discussion_r1679083961
##########
src/site/antora/modules/ROOT/pages/manual/lookups.adoc:
##########
@@ -16,69 +16,361 @@
////
= Lookups
-Lookups provide a way to add values to the Log4j configuration at
-arbitrary places. They are a particular type of Plugin that implements
-the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
-interface. Information on how to use Lookups in configuration files can
-be found in the xref:manual/configuration.adoc#PropertySubstitution[Property
-Substitution] section of the xref:manual/configuration.adoc[Configuration]
-page.
+Log4j Core provides a flexible and extensible property substitution system.
-[#ContextMapLookup]
-== Context Map Lookup
+[#StrSubstitutor-diagram]
+.Property substitution system
+[plantuml]
+....
+@startuml
+class StrSubstitutor #line.bold {
+ Interpolator interpolator
+ String replace(String input)
+ String replace(LogEvent event, String input)
+}
-The ContextMapLookup allows applications to store data in the Log4j
-ThreadContext Map and then retrieve the values in the Log4j
-configuration. In the example below, the application would store the
-current user's login id in the ThreadContext Map with the key "loginId".
-During initial configuration processing the first '$' will be removed.
-The PatternLayout supports interpolation with Lookups and will then
-resolve the variable for each event. Note that the pattern
-"%X\{loginId}" would achieve the same result.
+StrSubstitutor --> Interpolator
+
+class Interpolator {
+ StrLookup[] lookups
+ String lookup(String key)
+ String lookup(LogEvent event, String key)
+}
+
+Interpolator --> "0..*" StrLookup
+
+class StrLookup {
+ String lookup(String input)
+ String lookup(LogEvent event, String key)
+}
+
+@enduml
+....
+
+The property substitution system is composed of these elements:
+
+* A string interpolation engine
(xref:manual/architecture.adoc#StrSubstitutor[`StrSubstitutor`]) that evaluates
`$+{...}+` expressions.
+These expressions can contain recursive expressions and default values.
++
+See xref:manual/configuration.adoc#property-substitution[property
substitution] for more details.
+
+* The
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/Interpolator.html[`Interpolator`]
+that evaluates simple `$\{name}` expressions.
++
+The Interpolator has two functions:
+
+** If `name` does not contain a colon `:` character, the Interpolator uses the
+xref:manual/configuration.adoc#global-properties[`Properties` configuration
element] to resolve its value.
+
+** If `name` is of the form `prefix:key`, the Interpolator delegates the
lookup to a `StrLookup` associated with `prefix` and falls back to evaluating
`$+{key}+` if the lookup was not successful.
+
+* A set of
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-StrLookup[`StrLookup`]
+plugins, each one associated with a prefix, which retrieve data from external
sources.
+
+`StrLookup` is a simple map-like interface.
+The main difference between a map and `StrLookup` is that the latter can
compute the value of a key programmatically in a global context or in the
context of log event.
Review Comment:
```suggestion
The main difference between a map and `StrLookup` is that the latter can
compute the value of a key dynamically in a global context or in the context of
log event.
```
##########
src/site/antora/modules/ROOT/pages/manual/lookups.adoc:
##########
@@ -16,69 +16,361 @@
////
= Lookups
-Lookups provide a way to add values to the Log4j configuration at
-arbitrary places. They are a particular type of Plugin that implements
-the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
-interface. Information on how to use Lookups in configuration files can
-be found in the xref:manual/configuration.adoc#PropertySubstitution[Property
-Substitution] section of the xref:manual/configuration.adoc[Configuration]
-page.
+Log4j Core provides a flexible and extensible property substitution system.
-[#ContextMapLookup]
-== Context Map Lookup
+[#StrSubstitutor-diagram]
+.Property substitution system
+[plantuml]
+....
+@startuml
+class StrSubstitutor #line.bold {
+ Interpolator interpolator
+ String replace(String input)
+ String replace(LogEvent event, String input)
+}
-The ContextMapLookup allows applications to store data in the Log4j
-ThreadContext Map and then retrieve the values in the Log4j
-configuration. In the example below, the application would store the
-current user's login id in the ThreadContext Map with the key "loginId".
-During initial configuration processing the first '$' will be removed.
-The PatternLayout supports interpolation with Lookups and will then
-resolve the variable for each event. Note that the pattern
-"%X\{loginId}" would achieve the same result.
+StrSubstitutor --> Interpolator
+
+class Interpolator {
+ StrLookup[] lookups
+ String lookup(String key)
+ String lookup(LogEvent event, String key)
+}
+
+Interpolator --> "0..*" StrLookup
+
+class StrLookup {
+ String lookup(String input)
+ String lookup(LogEvent event, String key)
+}
+
+@enduml
+....
+
+The property substitution system is composed of these elements:
+
+* A string interpolation engine
(xref:manual/architecture.adoc#StrSubstitutor[`StrSubstitutor`]) that evaluates
`$+{...}+` expressions.
+These expressions can contain recursive expressions and default values.
++
+See xref:manual/configuration.adoc#property-substitution[property
substitution] for more details.
+
+* The
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/Interpolator.html[`Interpolator`]
+that evaluates simple `$\{name}` expressions.
++
+The Interpolator has two functions:
+
+** If `name` does not contain a colon `:` character, the Interpolator uses the
+xref:manual/configuration.adoc#global-properties[`Properties` configuration
element] to resolve its value.
+
+** If `name` is of the form `prefix:key`, the Interpolator delegates the
lookup to a `StrLookup` associated with `prefix` and falls back to evaluating
`$+{key}+` if the lookup was not successful.
+
+* A set of
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-StrLookup[`StrLookup`]
+plugins, each one associated with a prefix, which retrieve data from external
sources.
+
+`StrLookup` is a simple map-like interface.
+The main difference between a map and `StrLookup` is that the latter can
compute the value of a key programmatically in a global context or in the
context of log event.
+
+[#common-concerns]
+== Common concerns
+
+[#evaluation-contexts]
+=== Evaluation contexts
+
+Each lookup has an associated prefix, and Log4j can evaluate it in one of the
following ways:
+
+[#global-context]
+Global context::
+In a global context Log4j evaluates `$+{prefix:key}+` expressions by calling
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html#lookup(java.lang.String)[`lookup("key")`]
+on the lookup associated to `prefix`.
+The result of this call only takes into account the global state of the system.
++
+The global context is used to expand the attributes of a
+xref:manual/configuration.adoc[configuration file].
+
+[#event-context]
+Log event context::
+In the context of a log event `event`, Log4j evaluates `$+{prefix:key}+`
expressions by calling
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html#lookup(org.apache.logging.log4j.core.LogEvent,java.lang.String)[`lookup(event,
"key")`] on the lookup associated to `prefix`.
+The result of this call might take into account the contents of the log event,
besides the global state of the system.
+
+Some configuration attributes (e.g.,
xref:manual/pattern-layout.adoc#plugin-attr-pattern[the `pattern` attribute of
Pattern Layout]) supports both evaluation contexts:
+
+* During the configuration process the `$+{...}+` expressions are evaluated
using a global context.
+The same process converts escaped `$$+{...}+` expressions to `$+{...}+`
expressions.
+
+* For each log event, the remaining expressions are evaluated, using the log
event as context.
+
+Lookups can choose to react differently depending on the execution context.
+<<DateLookup>> is such an example:
+
+* When used in a global context, it formats the **current** timestamp obtained
through
+https://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/System.html#currentTimeMillis--[`System.currentTimeMillis()`].
+* When used in the context of an event, it formats the **event** timestamp
obtained through
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html#getTimeMillis()[`LogEvent.getTimeMillis()`].
+
+[#lookups-patterns]
+=== Lazy lookups and pattern converters
+
+For historical reasons, the
+xref:manual/pattern-layout.adoc#plugin-attr-pattern[`pattern` attribute of
PatternLayout]
+supports two similar string replacement mechanisms:
+
+* `+${...}+` property expressions.
+* xref:manual/pattern-layout.adoc#converters[`%<name>` pattern converters].
+
+Both lazy `+$${...}+` property expressions and pattern converters have access
to the value of the current `LogEvent` and can provide similar results.
+There is, however, an important difference between them:
Review Comment:
I think we are informing users, but we are not guiding them. This still
creates the impression that one can use lookups as long as they don't mind the
garbage-free features. Is this so? Because I thought one should also prefer PL
directives over lookups. Can we clarify this, please?
##########
src/site/antora/modules/ROOT/pages/manual/lookups.adoc:
##########
@@ -16,69 +16,361 @@
////
= Lookups
-Lookups provide a way to add values to the Log4j configuration at
-arbitrary places. They are a particular type of Plugin that implements
-the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
-interface. Information on how to use Lookups in configuration files can
-be found in the xref:manual/configuration.adoc#PropertySubstitution[Property
-Substitution] section of the xref:manual/configuration.adoc[Configuration]
-page.
+Log4j Core provides a flexible and extensible property substitution system.
-[#ContextMapLookup]
-== Context Map Lookup
+[#StrSubstitutor-diagram]
+.Property substitution system
+[plantuml]
+....
+@startuml
+class StrSubstitutor #line.bold {
+ Interpolator interpolator
+ String replace(String input)
+ String replace(LogEvent event, String input)
+}
-The ContextMapLookup allows applications to store data in the Log4j
-ThreadContext Map and then retrieve the values in the Log4j
-configuration. In the example below, the application would store the
-current user's login id in the ThreadContext Map with the key "loginId".
-During initial configuration processing the first '$' will be removed.
-The PatternLayout supports interpolation with Lookups and will then
-resolve the variable for each event. Note that the pattern
-"%X\{loginId}" would achieve the same result.
+StrSubstitutor --> Interpolator
+
+class Interpolator {
+ StrLookup[] lookups
+ String lookup(String key)
+ String lookup(LogEvent event, String key)
+}
+
+Interpolator --> "0..*" StrLookup
+
+class StrLookup {
+ String lookup(String input)
+ String lookup(LogEvent event, String key)
+}
+
+@enduml
+....
+
+The property substitution system is composed of these elements:
+
+* A string interpolation engine
(xref:manual/architecture.adoc#StrSubstitutor[`StrSubstitutor`]) that evaluates
`$+{...}+` expressions.
+These expressions can contain recursive expressions and default values.
++
+See xref:manual/configuration.adoc#property-substitution[property
substitution] for more details.
+
+* The
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/Interpolator.html[`Interpolator`]
+that evaluates simple `$\{name}` expressions.
++
+The Interpolator has two functions:
+
+** If `name` does not contain a colon `:` character, the Interpolator uses the
+xref:manual/configuration.adoc#global-properties[`Properties` configuration
element] to resolve its value.
+
+** If `name` is of the form `prefix:key`, the Interpolator delegates the
lookup to a `StrLookup` associated with `prefix` and falls back to evaluating
`$+{key}+` if the lookup was not successful.
+
+* A set of
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-StrLookup[`StrLookup`]
+plugins, each one associated with a prefix, which retrieve data from external
sources.
+
+`StrLookup` is a simple map-like interface.
+The main difference between a map and `StrLookup` is that the latter can
compute the value of a key programmatically in a global context or in the
context of log event.
+
+[#common-concerns]
+== Common concerns
+
+[#evaluation-contexts]
+=== Evaluation contexts
+
+Each lookup has an associated prefix, and Log4j can evaluate it in one of the
following ways:
+
+[#global-context]
+Global context::
+In a global context Log4j evaluates `$+{prefix:key}+` expressions by calling
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html#lookup(java.lang.String)[`lookup("key")`]
+on the lookup associated to `prefix`.
+The result of this call only takes into account the global state of the system.
++
+The global context is used to expand the attributes of a
+xref:manual/configuration.adoc[configuration file].
+
+[#event-context]
+Log event context::
+In the context of a log event `event`, Log4j evaluates `$+{prefix:key}+`
expressions by calling
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html#lookup(org.apache.logging.log4j.core.LogEvent,java.lang.String)[`lookup(event,
"key")`] on the lookup associated to `prefix`.
+The result of this call might take into account the contents of the log event,
besides the global state of the system.
+
+Some configuration attributes (e.g.,
xref:manual/pattern-layout.adoc#plugin-attr-pattern[the `pattern` attribute of
Pattern Layout]) supports both evaluation contexts:
+
+* During the configuration process the `$+{...}+` expressions are evaluated
using a global context.
+The same process converts escaped `$$+{...}+` expressions to `$+{...}+`
expressions.
+
+* For each log event, the remaining expressions are evaluated, using the log
event as context.
+
+Lookups can choose to react differently depending on the execution context.
+<<DateLookup>> is such an example:
+
+* When used in a global context, it formats the **current** timestamp obtained
through
+https://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/System.html#currentTimeMillis--[`System.currentTimeMillis()`].
+* When used in the context of an event, it formats the **event** timestamp
obtained through
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html#getTimeMillis()[`LogEvent.getTimeMillis()`].
+
+[#lookups-patterns]
+=== Lazy lookups and pattern converters
+
+For historical reasons, the
+xref:manual/pattern-layout.adoc#plugin-attr-pattern[`pattern` attribute of
PatternLayout]
+supports two similar string replacement mechanisms:
+
+* `+${...}+` property expressions.
+* xref:manual/pattern-layout.adoc#converters[`%<name>` pattern converters].
+
+Both lazy `+$${...}+` property expressions and pattern converters have access
to the value of the current `LogEvent` and can provide similar results.
+There is, however, an important difference between them:
+
+* Pattern converters can be garbage-free.
+See xref:manual/pattern-layout.adoc#garbage-free[Garbage-free pattern
converters] for more details.
+* Lazy lookups are **not** garbage-free and always create temporary `String`
objects.
+
+[#collection]
+== Collection
+
+Log4j Core provides many lookups out-of-the-box:
+
+* A large group of lookups supports evaluation in a global context.
Review Comment:
Shall we convert these two bullets to definitions? Suggestions:
* Lookups operating on the global context
* Lookups operating on the log event context
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
