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]>

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

@@ -155,18 +155,22 @@ Before you <<deploy,deploy your first web application>>, take a moment to see wh
 $JETTY_BASE
 ├── resources
 │   └── jetty-logging.properties <1>
-└── start.d <2>
-    └── http.ini <3>
+└── start.d                      <2>
+    ├── bytebufferpool.ini
+    ├── http-config.ini
+    ├── http.ini                 <3>
+    ├── scheduler.ini
+    ├── server.ini
+    └── threadpool.ini
 ----
 
 <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.
-<2> The `start.d/` directory contains the `+*.ini+` configuration files for any modules you have explicitly activated.
+<2> The `start.d/` directory contains the `+*.ini+` configuration files for any modules you have enabled, either explicitly or transitively.
 <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].
 
 [NOTE]
 ====
-By default, Jetty does *not* generate `+*.ini+` configuration files in `start.d/` for modules activated as transitive dependencies.
-To manually configure such modules, you should activate them directly via Jetty's `--add-modules` flag.
+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].
 ====
 
 In the `http.ini` file you can find the following (among other contents):

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

@@ -36,7 +36,7 @@ xref:modules/custom.adoc[Custom Jetty modules] should be put under `$JETTY_BASE/
 A Jetty module has a unique name.
 The module name is by default derived from the file name, so module file `acme.mod` identifies a module named `acme`.
 
-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.
+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.
 
 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.
 
@@ -195,7 +195,7 @@ Enabling the `http` module also enables, transitively, the `server` module, sinc
 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.
 Circular dependencies are not allowed.
 
-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.
+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.
 
 [[directive-after]]
 === [after]
@@ -213,8 +213,8 @@ In this way, you are guaranteed that the `https` module is processed after the `
 
 This directive indicates that this module is ordered before the listed module names, if they are enabled.
 
-For example, module `test-keystore` is `[before]` module `ssl`.
-Enabling the `test-keystore` module _does not_ enable the `ssl` module.
+For example, module `test-keystore` is `[before]` module `ssl-context`.
+Enabling the `test-keystore` module _does not_ enable the `ssl-context` module.
 
 This directive is used to create a prerequisite module without the need to modify the `depends` directive of an existing module.
 
@@ -385,7 +385,7 @@ See also the xref:start/start-jpms.adoc[JPMS section] for additional examples ab
 [[directive-ini-template]]
 === [ini-template]
 
-A list of properties to be copied in the `+*.ini+` file generated when xref:start/index.adoc#configure-enable[the module is enabled].
+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.
 
 The list of properties is derived from the <<components,module XML file(s)>> that declare them.
 

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

@@ -710,8 +710,6 @@ For example, it is the <<https,`https` module>> that configures the wrapped prot
 Similarly, it is the <<http2,`http2` module>> that configures the wrapped protocol to be HTTP/2.
 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.
 
-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.
-
 [[ssl-customize]]
 === Customizing KeyStore and SSL/TLS Configuration
 

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

@@ -49,31 +49,36 @@ Within the Jetty start mechanism, the source of configurations is layered in thi
 You can enable Jetty modules persistently across restarts with the `--add-modules` command:
 
 ----
-$ java -jar $JETTY_HOME/start.jar --add-modules=server,http
+$ java -jar $JETTY_HOME/start.jar --add-modules=https,http2
 ----
 
 The Jetty start mechanism will look for the specified modules following the order specified above.
 In the common case (without a `--add-config-dir` directory), it will look in `$JETTY_BASE/modules/` first and then in `$JETTY_HOME/modules/`.
 
-Since the `server` and `http` modules are standard Jetty modules, they are present in `$JETTY_HOME/modules/` and loaded from there.
+Since the `https` and `http2` modules are standard Jetty modules, they are present in `$JETTY_HOME/modules/` and loaded from there.
 
 When you enable a Jetty module, the Jetty start mechanism:
 
 * Creates the correspondent `+$JETTY_BASE/start.d/*.ini+` module configuration file.
 The content of these `+*.ini+` files is copied from the `[ini-template]` section of the correspondent `+*.mod+` file.
 * Executes the directives specified in `[files]` section (if present) of the `+*.mod+` file.
 This may simply create a file or a directory, or download files from the Internet.
-This step is performed transitively for all module dependencies.
 
-For example, enabling the `server` and `http` modules results in the `$JETTY_BASE` directory to have the following structure:
+Both steps are performed transitively for all module dependencies.
+
+For example, enabling the `http` module results in the `$JETTY_BASE` directory to have the following structure:
 
 ----
 $JETTY_BASE
 ├── resources
 │   └── jetty-logging.properties
 └── start.d
+    ├── bytebufferpool.ini
+    ├── http-config.ini
     ├── http.ini
-    └── server.ini
+    ├── scheduler.ini
+    ├── server.ini
+    └── threadpool.ini
 ----
 
 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
 
 You can now edit the `+$JETTY_BASE/start.d/*.ini+` configuration files, typically by uncommenting properties to change their default value.
 
-The `+$JETTY_BASE/start.d/*.ini+` configuration file may be missing, if the correspondent module is a transitive dependency.
-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):
-
-----
-$ java -jar $JETTY_HOME/start.jar --add-modules=server,http,logging-jetty
-----
-
-The `$JETTY_BASE` directory structure is now:
-
-[source,subs=+quotes]
-----
-$JETTY_BASE
-├── resources
-│   └── jetty-logging.properties
-└── start.d
-    ├── http.ini
-    ├── ##logging-jetty.ini##
-    └── server.ini
-----
-
 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).
 
 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
 
 You can also enable a module transiently, only for the current execution of the `java -jar $JETTY_HOME/start.jar` command.
 
-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.
+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.
 
 ----
-$ java -jar $JETTY_HOME/start.jar --module=server,http
+$ java -jar $JETTY_HOME/start.jar --module=http
 ----
 
 Since there are no `+$JETTY_BASE/start.d/*.ini+` files, you can only customize the properties via the command line, for example:
 
 ----
-$ java -jar $JETTY_HOME/start.jar --module=server,http jetty.http.port=9876
+$ java -jar $JETTY_HOME/start.jar --module=http jetty.http.port=9876
 ----
 
 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

@@ -290,8 +290,11 @@ public boolean accept(Path entry)
                     }
                     else
                     {
-                        // if (explicitly added and ini file modified)
-                        if (startArgs.getStartModules().contains(module.getName()))
+                        // Figure out which modules need *.ini files created.
+                        // Modules declared in --add-modules are explicitlyAdded
+                        boolean explicitlyAdded = startArgs.getStartModules().contains(module.getName());
+                        // Modules that are transitive and have an ini-template
+                        if (explicitlyAdded || (module.isTransitive() && module.hasIniTemplate()))
                         {
                             ini = builder.get().addModule(module, startArgs.getJettyEnvironment().getProperties());
                             if (ini != null)
@@ -317,16 +320,7 @@ public boolean accept(Path entry)
                 }
                 else if (module.isTransitive())
                 {
-                    if (module.hasIniTemplate())
-                    {
-                        StartLog.info("%-15s transitively enabled, ini template available with --add-modules=%s",
-                            module.getName(),
-                            module.getName());
-                    }
-                    else
-                    {
-                        StartLog.info("%-15s transitively enabled", module.getName());
-                    }
+                    StartLog.info("%-15s transitively enabled", module.getName());
                 }
                 else
                 {

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

@@ -240,8 +240,6 @@ public void listEnabled(PrintStream out)
                 index = "";
                 name = "";
             }
-            if (module.isTransitive() && module.hasIniTemplate())
-                out.printf(" ".repeat(31) + "ini template available with --add-modules=%s%n", module.getName());
         }
     }
 

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

@@ -20,7 +20,6 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
 import java.util.Objects;
@@ -102,53 +101,53 @@ protected void setupStandardHomeDir() throws IOException
         Path modules = homeDir.resolve("modules");
         FS.ensureDirExists(modules);
 
-        Files.write(modules.resolve("base.mod"),
-            Arrays.asList(
-                "[optional]",
-                "optional",
-                "[lib]",
-                "lib/base.jar",
-                "[xml]",
-                "etc/base.xml"),
-            StandardCharsets.UTF_8);
-        Files.write(modules.resolve("extra.mod"),
-            Arrays.asList(
-                "[depend]",
-                "main",
-                "[lib]",
-                "lib/extra/*.jar",
-                "[xml]",
-                "etc/extra.xml",
-                "[ini]",
-                "extra.prop=value0"),
-            StandardCharsets.UTF_8);
-        Files.write(modules.resolve("main.mod"),
-            Arrays.asList(
-                "[depend]",
-                "base",
-                "[optional]",
-                "optional",
-                "[lib]",
-                "lib/main.jar",
-                "lib/other.jar",
-                "[xml]",
-                "etc/main.xml",
-                "[files]",
-                "maindir/",
-                "[ini]",
-                "main.prop=value0",
-                "[ini-template]",
-                "main.prop=valueT"),
-            StandardCharsets.UTF_8);
-        Files.write(modules.resolve("optional.mod"),
-            Arrays.asList(
-                "[lib]",
-                "lib/optional.jar",
-                "[xml]",
-                "etc/optional.xml",
-                "[ini]",
-                "optional.prop=value0"),
-            StandardCharsets.UTF_8);
+        Files.writeString(modules.resolve("base.mod"),
+            """
+                [optional]
+                optional
+                [lib]
+                lib/base.jar
+                [xml]
+                etc/base.xml
+                """, StandardCharsets.UTF_8);
+        Files.writeString(modules.resolve("extra.mod"),
+            """
+                [depend]
+                main
+                [lib]
+                lib/extra/*.jar
+                [xml]
+                etc/extra.xml
+                [ini]
+                extra.prop=value0
+                """, StandardCharsets.UTF_8);
+        Files.writeString(modules.resolve("main.mod"),
+            """
+                [depend]
+                base
+                [optional]
+                optional
+                [lib]
+                lib/main.jar
+                lib/other.jar
+                [xml]
+                etc/main.xml
+                [files]
+                maindir/
+                [ini]
+                main.prop=value0
+                [ini-template]
+                # main.prop=valueT
+                """, StandardCharsets.UTF_8);
+        Files.writeString(modules.resolve("optional.mod"),
+            """
+                [lib]
+                lib/optional.jar
+                [xml]
+                etc/optional.xml
+                [ini]
+                optional.prop=value0
+                """, StandardCharsets.UTF_8);
     }
 
     public static class ExecResults