Skip to content

Commit cd69a98

Browse files
ppkarwaszppkarwasz
committed
Add property expansion example
1 parent 5f8a7dc commit cd69a98

12 files changed

+315
-5
lines changed

‎src/site/antora/modules/ROOT/examples/manual/configuration/loggers.properties

+20-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
#
2+
# Licensed to the Apache Software Foundation (ASF) under one or more
3+
# contributor license agreements. See the NOTICE file distributed with
4+
# this work for additional information regarding copyright ownership.
5+
# The ASF licenses this file to you under the Apache License, Version 2.0
6+
# (the "License"); you may not use this file except in compliance with
7+
# the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
#
17+
##
18+
# tag::loggers[]
119
rootLogger.level = INFO # <1>
220
rootLogger.appenderRef.0.ref = APPENDER1
321

@@ -11,4 +29,5 @@ logger.1.appenderRef.0.ref = APPENDER3
1129

1230
logger.2.name = org.example.level # <4>
1331
logger.2.level = DEBUG
14-
logger.2.appenderRef.0.ref = APPENDER4
32+
logger.2.appenderRef.0.ref = APPENDER4
33+
# end::loggers[]

‎src/site/antora/modules/ROOT/examples/manual/configuration/loggers.xml

+18-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,20 @@
1-
<?xml version="1.0" encoding="UTF-8" ?>
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
~ Licensed to the Apache Software Foundation (ASF) under one or more
4+
~ contributor license agreements. See the NOTICE file distributed with
5+
~ this work for additional information regarding copyright ownership.
6+
~ The ASF licenses this file to you under the Apache License, Version 2.0
7+
~ (the "License"); you may not use this file except in compliance with
8+
~ the License. You may obtain a copy of the License at
9+
~
10+
~ http://www.apache.org/licenses/LICENSE-2.0
11+
~
12+
~ Unless required by applicable law or agreed to in writing, software
13+
~ distributed under the License is distributed on an "AS IS" BASIS,
14+
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
~ See the License for the specific language governing permissions and
16+
~ limitations under the License.
17+
-->
218
<Configuration xmlns="https://logging.apache.org/xml/ns"
319
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
420
xsi:schemaLocation="
@@ -21,4 +37,4 @@
2137
</Logger>
2238
</Loggers>
2339
<!-- end::loggers[] -->
24-
</Configuration>
40+
</Configuration>

‎src/site/antora/modules/ROOT/examples/manual/configuration/loggers.yaml

+17-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,19 @@
1+
#
2+
# Licensed to the Apache Software Foundation (ASF) under one or more
3+
# contributor license agreements. See the NOTICE file distributed with
4+
# this work for additional information regarding copyright ownership.
5+
# The ASF licenses this file to you under the Apache License, Version 2.0
6+
# (the "License"); you may not use this file except in compliance with
7+
# the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
#
117
Configuration:
218
# tag::loggers[]
319
Loggers:
@@ -18,4 +34,4 @@ Configuration:
1834
level: "DEBUG"
1935
AppenderRef:
2036
ref: "APPENDER4"
21-
# end::loggers[]
37+
# end::loggers[]

‎src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.json

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"Properties": {
3+
"Property": [
4+
{
5+
"name": "FOO",
6+
"value": "foo"
7+
},
8+
{
9+
"name": "BAR",
10+
"value": "bar"
11+
}
12+
]
13+
}
14+
}

‎src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.properties

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#
2+
# Licensed to the Apache Software Foundation (ASF) under one or more
3+
# contributor license agreements. See the NOTICE file distributed with
4+
# this work for additional information regarding copyright ownership.
5+
# The ASF licenses this file to you under the Apache License, Version 2.0
6+
# (the "License"); you may not use this file except in compliance with
7+
# the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
#
17+
property.FOO = foo
18+
property.BAR = bar

‎src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.xml

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
~ Licensed to the Apache Software Foundation (ASF) under one or more
4+
~ contributor license agreements. See the NOTICE file distributed with
5+
~ this work for additional information regarding copyright ownership.
6+
~ The ASF licenses this file to you under the Apache License, Version 2.0
7+
~ (the "License"); you may not use this file except in compliance with
8+
~ the License. You may obtain a copy of the License at
9+
~
10+
~ http://www.apache.org/licenses/LICENSE-2.0
11+
~
12+
~ Unless required by applicable law or agreed to in writing, software
13+
~ distributed under the License is distributed on an "AS IS" BASIS,
14+
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
~ See the License for the specific language governing permissions and
16+
~ limitations under the License.
17+
-->
18+
<Properties>
19+
<Property name="FOO" value="foo"/>
20+
<Property name="BAR" value="bar"/>
21+
</Properties>

‎src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.yaml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
#
2+
# Licensed to the Apache Software Foundation (ASF) under one or more
3+
# contributor license agreements. See the NOTICE file distributed with
4+
# this work for additional information regarding copyright ownership.
5+
# The ASF licenses this file to you under the Apache License, Version 2.0
6+
# (the "License"); you may not use this file except in compliance with
7+
# the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
#
17+
Properties:
18+
Property:
19+
- name: "FOO"
20+
value: "foo"
21+
- name: "BAR"
22+
value: "bar"

‎src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.json

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"Properties": {
3+
"Property": [
4+
{
5+
"name": "logging.file",
6+
"value": "${logging.path}/app.log"
7+
},
8+
{
9+
"name": "logging.dir",
10+
"value": "${env:APP_BASE}/logs"
11+
},
12+
{
13+
"name": "APP_BASE",
14+
"value": "."
15+
}
16+
]
17+
}
18+
}

‎src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.properties

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
#
2+
# Licensed to the Apache Software Foundation (ASF) under one or more
3+
# contributor license agreements. See the NOTICE file distributed with
4+
# this work for additional information regarding copyright ownership.
5+
# The ASF licenses this file to you under the Apache License, Version 2.0
6+
# (the "License"); you may not use this file except in compliance with
7+
# the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
#
17+
property.logging.file = ${logging.dir}/app.log
18+
property.logging.dir = ${env:APP_BASE}/logs
19+
property.APP_BASE = .

‎src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.xml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
~ Licensed to the Apache Software Foundation (ASF) under one or more
4+
~ contributor license agreements. See the NOTICE file distributed with
5+
~ this work for additional information regarding copyright ownership.
6+
~ The ASF licenses this file to you under the Apache License, Version 2.0
7+
~ (the "License"); you may not use this file except in compliance with
8+
~ the License. You may obtain a copy of the License at
9+
~
10+
~ http://www.apache.org/licenses/LICENSE-2.0
11+
~
12+
~ Unless required by applicable law or agreed to in writing, software
13+
~ distributed under the License is distributed on an "AS IS" BASIS,
14+
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
~ See the License for the specific language governing permissions and
16+
~ limitations under the License.
17+
-->
18+
<Properties>
19+
<Property name="logging.file" value="${logging.dir}/app.log"/>
20+
<Property name="logging.dir" value="${env:APP_BASE}/logs"/>
21+
<Property name="APP_BASE" value="."/>
22+
</Properties>

‎src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.yaml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#
2+
# Licensed to the Apache Software Foundation (ASF) under one or more
3+
# contributor license agreements. See the NOTICE file distributed with
4+
# this work for additional information regarding copyright ownership.
5+
# The ASF licenses this file to you under the Apache License, Version 2.0
6+
# (the "License"); you may not use this file except in compliance with
7+
# the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
#
17+
Properties:
18+
Property:
19+
- name: "logging.file"
20+
value: "${logging.dir}/app.log"
21+
- name: "logging.dir"
22+
value: "${env:APP_BASE}/logs"
23+
- name: "APP_BASE"
24+
value: "."

‎src/site/antora/modules/ROOT/pages/manual/configuration.adoc

+102-1
Original file line numberDiff line numberDiff line change
@@ -489,7 +489,7 @@ Java properties::
489489
+
490490
[source,properties]
491491
----
492-
include::example$manual/configuration/loggers.properties[]
492+
include::example$manual/configuration/loggers.properties[tags=loggers]
493493
----
494494
====
495495
@@ -818,6 +818,107 @@ To prevent the expansion of one of the expressions above, the initial `$` must b
818818
The same rule applies to the `name` parameter: if it contains a `${` sequence, the sequence must be escaped as `$${`.
819819
====
820820
821+
.Property substitution example
822+
=====
823+
824+
If your configuration file contains the following definitions:
825+
[tabs]
826+
====
827+
XML::
828+
+
829+
[source,xml]
830+
----
831+
include::example$manual/configuration/properties-example.xml[lines=18..-1]
832+
----
833+
834+
JSON::
835+
+
836+
[source,json]
837+
----
838+
include::example$manual/configuration/properties-example.json[]
839+
----
840+
841+
YAML::
842+
+
843+
[source,yaml]
844+
----
845+
include::example$manual/configuration/properties-example.yaml[lines=17..-1]
846+
----
847+
848+
Java properties::
849+
+
850+
[source,properties]
851+
----
852+
include::example$manual/configuration/properties-example.properties[lines=17..-1]
853+
----
854+
====
855+
856+
and the OS environment variable `FOO` has a value of `environment`, Log4j will evaluate expression as follows
857+
858+
[cols="1m,1m"]
859+
|===
860+
| Expression | Value
861+
862+
| $\{FOO} | foo
863+
| $\{BAZ} | $\{BAZ}
864+
| ${BAR:-$\{FOO}} | bar
865+
| ${BAZ:-$\{FOO}} | foo
866+
| ${env:FOO} | environment
867+
| ${env:BAR} | bar
868+
| ${env:BAZ} | $\{BAZ}
869+
| ${env:BAR:-$\{FOO}} | bar
870+
| ${env:BAZ:-$\{FOO}} | foo
871+
|===
872+
=====
873+
874+
[CAUTION]
875+
=====
876+
For security reasons, if the **expansion** of a `${...}` expression contains other expressions, these will **not** be expanded.
877+
The only exception to this rule is the expansion of properties in the `Properties` container.
878+
879+
Properties defined in the `Properties` container can depend on each other.
880+
If your configuration contains, for example:
881+
882+
[tabs]
883+
====
884+
XML::
885+
+
886+
[source,xml]
887+
----
888+
include::example$manual/configuration/properties-recursion.xml[lines=18..-1]
889+
----
890+
891+
JSON::
892+
+
893+
[source,json]
894+
----
895+
include::example$manual/configuration/properties-recursion.json[]
896+
----
897+
898+
YAML::
899+
+
900+
[source,yaml]
901+
----
902+
include::example$manual/configuration/properties-recursion.yaml[lines=17..-1]
903+
----
904+
905+
Java properties::
906+
+
907+
[source,properties]
908+
----
909+
include::example$manual/configuration/properties-recursion.properties[lines=17..-1]
910+
----
911+
====
912+
913+
the `logging.dir` property will be expanded **before** the `logging.file` property and the expanded value will be substituted in `${logging.dir}/app.log`.
914+
Therefore, the value of the `logging.file` property will be:
915+
916+
* `./logs/app.log` if the environment variable `APP_BASE` is not defined,
917+
* `/var/lib/app/logs/app.log` if the environment variable `APP_BASE` has a value of `/var/lib/app`.
918+
919+
920+
=====
921+
821922
[id=lazy-property-substitution]
822923
==== Lazy property substitution
823924

0 commit comments

Comments
 (0)