Skip to content

Commit 7be7d0e

Browse files
joakimesbordet
joakime
and
sbordet
authored
Create start.d/*.ini for [ini-template] modules (#12593)
* Create start.d/*.ini for [ini-template] * Will always create ini file if the module is enabled directly or via transitive dependency AND it has a [ini-template] section. * Fixing BaseBuilder logic * Updated documentation to reflect the fact that now `*.ini` files are created for transitive dependencies. Signed-off-by: Simone Bordet <[email protected]> --------- Signed-off-by: Simone Bordet <[email protected]> Co-authored-by: Simone Bordet <[email protected]>
1 parent 4050f02 commit 7be7d0e

File tree

8 files changed

+174
-103
lines changed

8 files changed

+174
-103
lines changed

‎documentation/jetty/modules/operations-guide/pages/begin/index.adoc‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -155,18 +155,22 @@ Before you <<deploy,deploy your first web application>>, take a moment to see wh
155155
$JETTY_BASE
156156
├── resources
157157
│ └── jetty-logging.properties <1>
158-
└── start.d <2>
159-
└── http.ini <3>
158+
└── start.d <2>
159+
├── bytebufferpool.ini
160+
├── http-config.ini
161+
├── http.ini <3>
162+
├── scheduler.ini
163+
├── server.ini
164+
└── threadpool.ini
160165
----
161166

162167
<1> The `resources/jetty-logging.properties` file configures the server's logging level; this file was auto-generated when the `jetty-logging` module was activated as a transitive dependency of the `http` module.
163-
<2> The `start.d/` directory contains the `+*.ini+` configuration files for any modules you have explicitly activated.
168+
<2> The `start.d/` directory contains the `+*.ini+` configuration files for any modules you have enabled, either explicitly or transitively.
164169
<3> The `start.d/http.ini` file is the `http` module configuration file, where you can specify values for the xref:modules/standard.adoc#http[`http` module properties].
165170

166171
[NOTE]
167172
====
168-
By default, Jetty does *not* generate `+*.ini+` configuration files in `start.d/` for modules activated as transitive dependencies.
169-
To manually configure such modules, you should activate them directly via Jetty's `--add-modules` flag.
173+
Jetty generates `+*.ini+` configuration files in `start.d/` also for modules enabled as transitive dependencies that have an xref:modules/index.adoc#directive-ini-template[`+[ini-template]+` directive].
170174
====
171175

172176
In the `http.ini` file you can find the following (among other contents):

‎documentation/jetty/modules/operations-guide/pages/modules/index.adoc‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ xref:modules/custom.adoc[Custom Jetty modules] should be put under `$JETTY_BASE/
3636
A Jetty module has a unique name.
3737
The module name is by default derived from the file name, so module file `acme.mod` identifies a module named `acme`.
3838

39-
However, a module file may specify a <<directive-provides,+[provides>>+] directive for a _virtual_ module, so that many modules may provide a different implementation for the same feature.
39+
However, a module file may specify a <<directive-provides,+[provides]+>> directive for a _virtual_ module, so that many modules may provide a different implementation for the same feature.
4040

4141
For example, among the standard modules provided by Jetty, the `server` module depends on the `logging` module, but there is no correspondent `logging.mod` file.
4242

@@ -195,7 +195,7 @@ Enabling the `http` module also enables, transitively, the `server` module, sinc
195195
The `[depends]` directive establishes a https://en.wikipedia.org/wiki/Partially_ordered_set[_partial order_] relationship among modules so that enabled modules can be sorted and organized in a graph.
196196
Circular dependencies are not allowed.
197197

198-
The order of the enabled modules is used to determine the processing of the configuration, for example the order of processing of the <<directive-files,+[files>>+] section, the order of processing of XML files defined in the <<directive-xml,+[xml>>+] section, etc.
198+
The order of the enabled modules is used to determine the processing of the configuration, for example the order of processing of the <<directive-files,+[files]+>> section, the order of processing of XML files defined in the <<directive-xml,+[xml]+>> section, etc.
199199

200200
[[directive-after]]
201201
=== [after]
@@ -213,8 +213,8 @@ In this way, you are guaranteed that the `https` module is processed after the `
213213

214214
This directive indicates that this module is ordered before the listed module names, if they are enabled.
215215

216-
For example, module `test-keystore` is `[before]` module `ssl`.
217-
Enabling the `test-keystore` module _does not_ enable the `ssl` module.
216+
For example, module `test-keystore` is `[before]` module `ssl-context`.
217+
Enabling the `test-keystore` module _does not_ enable the `ssl-context` module.
218218

219219
This directive is used to create a prerequisite module without the need to modify the `depends` directive of an existing module.
220220

@@ -385,7 +385,7 @@ See also the xref:start/start-jpms.adoc[JPMS section] for additional examples ab
385385
[[directive-ini-template]]
386386
=== [ini-template]
387387

388-
A list of properties to be copied in the `+*.ini+` file generated when xref:start/index.adoc#configure-enable[the module is enabled].
388+
A list of properties to be copied in the `+*.ini+` file generated when xref:start/index.adoc#configure-enable[the module is enabled], either explicitly or transitively.
389389

390390
The list of properties is derived from the <<components,module XML file(s)>> that declare them.
391391

‎documentation/jetty/modules/operations-guide/pages/protocols/index.adoc‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -710,8 +710,6 @@ For example, it is the <<https,`https` module>> that configures the wrapped prot
710710
Similarly, it is the <<http2,`http2` module>> that configures the wrapped protocol to be HTTP/2.
711711
If you enable _both_ the `https` and the `http2` module, you will have a single secure connector that will be able to interpret both HTTP/1.1 and HTTP/2.
712712

713-
TIP: Recall from the xref:modules/index.adoc[section about modules], that only modules that are explicitly enabled get their module configuration file (`+*.ini+`) saved in `$JETTY_BASE/start.d/`, and you want `$JETTY_BASE/start.d/ssl.ini` to be present so that you can configure the connector properties, the KeyStore properties and the TLS properties.
714-
715713
[[ssl-customize]]
716714
=== Customizing KeyStore and SSL/TLS Configuration
717715

‎documentation/jetty/modules/operations-guide/pages/start/index.adoc‎

Lines changed: 13 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -49,31 +49,36 @@ Within the Jetty start mechanism, the source of configurations is layered in thi
4949
You can enable Jetty modules persistently across restarts with the `--add-modules` command:
5050

5151
----
52-
$ java -jar $JETTY_HOME/start.jar --add-modules=server,http
52+
$ java -jar $JETTY_HOME/start.jar --add-modules=https,http2
5353
----
5454

5555
The Jetty start mechanism will look for the specified modules following the order specified above.
5656
In the common case (without a `--add-config-dir` directory), it will look in `$JETTY_BASE/modules/` first and then in `$JETTY_HOME/modules/`.
5757

58-
Since the `server` and `http` modules are standard Jetty modules, they are present in `$JETTY_HOME/modules/` and loaded from there.
58+
Since the `https` and `http2` modules are standard Jetty modules, they are present in `$JETTY_HOME/modules/` and loaded from there.
5959

6060
When you enable a Jetty module, the Jetty start mechanism:
6161

6262
* Creates the correspondent `+$JETTY_BASE/start.d/*.ini+` module configuration file.
6363
The content of these `+*.ini+` files is copied from the `[ini-template]` section of the correspondent `+*.mod+` file.
6464
* Executes the directives specified in `[files]` section (if present) of the `+*.mod+` file.
6565
This may simply create a file or a directory, or download files from the Internet.
66-
This step is performed transitively for all module dependencies.
6766

68-
For example, enabling the `server` and `http` modules results in the `$JETTY_BASE` directory to have the following structure:
67+
Both steps are performed transitively for all module dependencies.
68+
69+
For example, enabling the `http` module results in the `$JETTY_BASE` directory to have the following structure:
6970

7071
----
7172
$JETTY_BASE
7273
├── resources
7374
│ └── jetty-logging.properties
7475
└── start.d
76+
├── bytebufferpool.ini
77+
├── http-config.ini
7578
├── http.ini
76-
└── server.ini
79+
├── scheduler.ini
80+
├── server.ini
81+
└── threadpool.ini
7782
----
7883

7984
The `$JETTY_BASE/resources/jetty-logging.properties` is created by the `[files]` directives of the `logging-jetty` module, which is a transitive dependency of the `server` module.
@@ -92,26 +97,6 @@ Deleting the correspondent `+$JETTY_BASE/start.d/*.ini+` file also disables the
9297

9398
You can now edit the `+$JETTY_BASE/start.d/*.ini+` configuration files, typically by uncommenting properties to change their default value.
9499

95-
The `+$JETTY_BASE/start.d/*.ini+` configuration file may be missing, if the correspondent module is a transitive dependency.
96-
You can easily generate the configuration file by explicitly enabling the module, for example to generate the `$JETTY_BASE/start.d/logging-jetty.ini` configuration file you would issue the following command (the module order does not matter):
97-
98-
----
99-
$ java -jar $JETTY_HOME/start.jar --add-modules=server,http,logging-jetty
100-
----
101-
102-
The `$JETTY_BASE` directory structure is now:
103-
104-
[source,subs=+quotes]
105-
----
106-
$JETTY_BASE
107-
├── resources
108-
│ └── jetty-logging.properties
109-
└── start.d
110-
├── http.ini
111-
├── ##logging-jetty.ini##
112-
└── server.ini
113-
----
114-
115100
You want to edit the `+$JETTY_BASE/start.d/*.ini+` configuration files so that the configuration is applied every time Jetty is started (or re-started).
116101

117102
For example, `$JETTY_BASE/start.d/http.ini` contains the following property, commented out:
@@ -135,16 +120,16 @@ When Jetty is started (or re-started) this configuration is applied and Jetty wi
135120

136121
You can also enable a module transiently, only for the current execution of the `java -jar $JETTY_HOME/start.jar` command.
137122

138-
If you have an empty `$JETTY_BASE`, the following command enables the `server` and `http` modules, but does not create any `+$JETTY_BASE/start.d/*.ini+` files.
123+
If you have an empty `$JETTY_BASE`, the following command enables the `http` module, but does not create any `+$JETTY_BASE/start.d/*.ini+` files.
139124

140125
----
141-
$ java -jar $JETTY_HOME/start.jar --module=server,http
126+
$ java -jar $JETTY_HOME/start.jar --module=http
142127
----
143128

144129
Since there are no `+$JETTY_BASE/start.d/*.ini+` files, you can only customize the properties via the command line, for example:
145130

146131
----
147-
$ java -jar $JETTY_HOME/start.jar --module=server,http jetty.http.port=9876
132+
$ java -jar $JETTY_HOME/start.jar --module=http jetty.http.port=9876
148133
----
149134

150135
Enabling modules on the command line is useful to verify that the modules work as expected, or to try different configurations.

‎jetty-core/jetty-start/src/main/java/org/eclipse/jetty/start/BaseBuilder.java‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -290,8 +290,11 @@ public boolean accept(Path entry)
290290
}
291291
else
292292
{
293-
// if (explicitly added and ini file modified)
294-
if (startArgs.getStartModules().contains(module.getName()))
293+
// Figure out which modules need *.ini files created.
294+
// Modules declared in --add-modules are explicitlyAdded
295+
boolean explicitlyAdded = startArgs.getStartModules().contains(module.getName());
296+
// Modules that are transitive and have an ini-template
297+
if (explicitlyAdded || (module.isTransitive() && module.hasIniTemplate()))
295298
{
296299
ini = builder.get().addModule(module, startArgs.getJettyEnvironment().getProperties());
297300
if (ini != null)
@@ -317,16 +320,7 @@ public boolean accept(Path entry)
317320
}
318321
else if (module.isTransitive())
319322
{
320-
if (module.hasIniTemplate())
321-
{
322-
StartLog.info("%-15s transitively enabled, ini template available with --add-modules=%s",
323-
module.getName(),
324-
module.getName());
325-
}
326-
else
327-
{
328-
StartLog.info("%-15s transitively enabled", module.getName());
329-
}
323+
StartLog.info("%-15s transitively enabled", module.getName());
330324
}
331325
else
332326
{

‎jetty-core/jetty-start/src/main/java/org/eclipse/jetty/start/Modules.java‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -240,8 +240,6 @@ public void listEnabled(PrintStream out)
240240
index = "";
241241
name = "";
242242
}
243-
if (module.isTransitive() && module.hasIniTemplate())
244-
out.printf(" ".repeat(31) + "ini template available with --add-modules=%s%n", module.getName());
245243
}
246244
}
247245

‎jetty-core/jetty-start/src/test/java/org/eclipse/jetty/start/usecases/AbstractUseCase.java‎

Lines changed: 47 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@
2020
import java.nio.file.Files;
2121
import java.nio.file.Path;
2222
import java.util.ArrayList;
23-
import java.util.Arrays;
2423
import java.util.Collection;
2524
import java.util.List;
2625
import java.util.Objects;
@@ -102,53 +101,53 @@ protected void setupStandardHomeDir() throws IOException
102101
Path modules = homeDir.resolve("modules");
103102
FS.ensureDirExists(modules);
104103

105-
Files.write(modules.resolve("base.mod"),
106-
Arrays.asList(
107-
"[optional]",
108-
"optional",
109-
"[lib]",
110-
"lib/base.jar",
111-
"[xml]",
112-
"etc/base.xml"),
113-
StandardCharsets.UTF_8);
114-
Files.write(modules.resolve("extra.mod"),
115-
Arrays.asList(
116-
"[depend]",
117-
"main",
118-
"[lib]",
119-
"lib/extra/*.jar",
120-
"[xml]",
121-
"etc/extra.xml",
122-
"[ini]",
123-
"extra.prop=value0"),
124-
StandardCharsets.UTF_8);
125-
Files.write(modules.resolve("main.mod"),
126-
Arrays.asList(
127-
"[depend]",
128-
"base",
129-
"[optional]",
130-
"optional",
131-
"[lib]",
132-
"lib/main.jar",
133-
"lib/other.jar",
134-
"[xml]",
135-
"etc/main.xml",
136-
"[files]",
137-
"maindir/",
138-
"[ini]",
139-
"main.prop=value0",
140-
"[ini-template]",
141-
"main.prop=valueT"),
142-
StandardCharsets.UTF_8);
143-
Files.write(modules.resolve("optional.mod"),
144-
Arrays.asList(
145-
"[lib]",
146-
"lib/optional.jar",
147-
"[xml]",
148-
"etc/optional.xml",
149-
"[ini]",
150-
"optional.prop=value0"),
151-
StandardCharsets.UTF_8);
104+
Files.writeString(modules.resolve("base.mod"),
105+
"""
106+
[optional]
107+
optional
108+
[lib]
109+
lib/base.jar
110+
[xml]
111+
etc/base.xml
112+
""", StandardCharsets.UTF_8);
113+
Files.writeString(modules.resolve("extra.mod"),
114+
"""
115+
[depend]
116+
main
117+
[lib]
118+
lib/extra/*.jar
119+
[xml]
120+
etc/extra.xml
121+
[ini]
122+
extra.prop=value0
123+
""", StandardCharsets.UTF_8);
124+
Files.writeString(modules.resolve("main.mod"),
125+
"""
126+
[depend]
127+
base
128+
[optional]
129+
optional
130+
[lib]
131+
lib/main.jar
132+
lib/other.jar
133+
[xml]
134+
etc/main.xml
135+
[files]
136+
maindir/
137+
[ini]
138+
main.prop=value0
139+
[ini-template]
140+
# main.prop=valueT
141+
""", StandardCharsets.UTF_8);
142+
Files.writeString(modules.resolve("optional.mod"),
143+
"""
144+
[lib]
145+
lib/optional.jar
146+
[xml]
147+
etc/optional.xml
148+
[ini]
149+
optional.prop=value0
150+
""", StandardCharsets.UTF_8);
152151
}
153152

154153
public static class ExecResults

0 commit comments

Comments
 (0)