ScanningAppProvider.setEnvironmentName() and Environments not documented

[byteit101]

Jetty version(s)
12

Jetty Environment
My question was answered by filing a ticket: <!-- Applicable for jetty-12 only, choose: core, ee8, ee9, ee10, ee11 --> This (ticket template) is the only place I've found documentation so far on what an environment is!

Java version/vendor
All

OS type/version
All

Description

java.lang.IllegalStateException: No environment configured
	at org.eclipse.jetty.deploy.providers.ScanningAppProvider.doStart(ScanningAppProvider.java:199)

This is a strange error that I encountered when migrating from 11 to 12. "environment" wasn't found on the migration guide, and setEnvironmentName has no javadoc. I had instantiated Shiro environments, but still this error persisted. I couldn't figure out how to create an environment until I went to file this ticket and it asked for the environment with a list of them. This may be obvious to people more enmeshed in the Jetty/EE world, but it's not obvious to casual users like myself. Document at least the javadoc on the method, and ideally more about what a Jetty environment actually is.

How to reproduce?
Look for the (missing) documentation.

[janbartel]

https://jetty.org/docs/jetty/12.1/operations-guide/deploy/index.html has some documentation on what environments are wrt deploying web applications, and specifically how they relate to configuring the deployer - see section https://jetty.org/docs/jetty/12.1/operations-guide/deploy/index.html#rules-environment.

That said, I take your point that it is not well documented in the migration guide.

[sbordet]

@byteit101 I'm not sure what the problem is.

If you are using Jetty as a standalone server, you should enable the ee10-deploy module, and that would take care of calling setEnvironmentName().

Changing Jetty 11's deploy.mod to Jetty 12's ee10-deploy.mod has been documented in the migration guide.

In order to get the error you report, you must have done something unusual, which you do not explain.

An embedded use of Jetty would typically not use a deployer.
If you do, it is an advanced use of Jetty, and you have to explain in precise details what you are doing.

[byteit101]

I am doing essentially this example: https://github.com/jetty/jetty-examples/blob/12.0.x/embedded/deploying/src/main/java/examples/WebAppsHotDeployExample.java#L63

The problem is that the javadoc for the method setEnvironmentName() and https://javadoc.jetty.org/jetty-12/org/eclipse/jetty/util/component/Environment.html don't say what the valid environments are, nor do they link to any explanation of environments in the user guide. Not having too much experience here, I at first assumed that "environment" meant an environment variable or such, and not a Jakarta API version.

[joakime]

I am doing essentially this example: https://github.com/jetty/jetty-examples/blob/12.0.x/embedded/deploying/src/main/java/examples/WebAppsHotDeployExample.java#L63

The problem is that the javadoc for the method setEnvironmentName() and https://javadoc.jetty.org/jetty-12/org/eclipse/jetty/util/component/Environment.html don't say what the valid environments are, nor do they link to any explanation of environments in the user guide. Not having too much experience here, I at first assumed that "environment" meant an environment variable or such, and not a Jakarta API version.

Since you are referencing 12.0.x examples, and the ScanningAppProvider (which doesn't exist in 12.1.x), here's the relevant doc.

See: https://jetty.org/docs/jetty/12/operations-guide/deploy/index.html#rules-environment

Environment name can be anything, it's not a hard-coded list.

Jetty 12 ships with implementations for ...

• core - the jetty-core environment, full server support, you can write a handler to answer web requests with it, it has no servlet support.
• ee8 - the Jakarta EE8 environment, eg: servlet 4.x support
• ee9 - the Jakarta EE9 environment, eg: servlet 5.x support
• ee10 - the Jakarta EE10 environment, eg: servlet 6.0.x support
• ee11 - the Jakarta EE11 environment, eg: servlet 6.1.x support (only in Jetty 12.1.x)
• static - an environment that only does static file serving (only in Jetty 12.1.x)

In Jetty 12 each environment also has a default implementation of ContextHandler that suits that environment.

In Jetty 12.0.x the ScanningAppProvider is environment specific, and you'll have a unique one per environment you want to run. (multiple environments at the same time in the same JVM is supported)

In Jetty 12.1.x, there's only one scanner, org.eclipse.jetty.deploy.DeploymentScanner, it can handle all environments that are configured in it.

See example: https://github.com/jetty/jetty-examples/blob/12.1.x/embedded/deploying/src/main/java/examples/WebAppsHotDeployExample.java

[byteit101]

Environment name can be anything, it's not a hard-coded list.

Indeed, but it's nice to know some of the options, vs none of the options

I see that https://javadoc.jetty.org/jetty-12.1/org/eclipse/jetty/deploy/DeploymentScanner.html#configureEnvironment(java.lang.String) does have at least some javadoc vs 12.0, but it would be nice to mention the options

Parameters:
    name - the name of the environment. (ex: core, static, ee8, ee9, ...)

[joakime]

Indeed, but it's nice to know some of the options, vs none of the options

I see that https://javadoc.jetty.org/jetty-12.1/org/eclipse/jetty/deploy/DeploymentScanner.html#configureEnvironment(java.lang.String) does have at least some javadoc vs 12.0, but it would be nice to mention the options

Parameters:
    name - the name of the environment. (ex: core, static, ee8, ee9, ...)

You have been asking about 12.0.x, that link is for 12.1.x, and has nothing to do with 12.0.x.

Anyway, that parameter can be anything you want.
It would be wise to configure things that you have implementations for (jars & classes), or have configuration for (defaults).

Example, you can configure for ee9, but if you don't have the classes present, that configuration is bogus.
The return from configureEnvironment is important too, that's how you configure things for that environment.

You might want to pay attention to org.eclipse.jetty.util.component.Environment.getAll() as the list of registered environments.

The Jetty Start mechanism initializes that list.
See: https://github.com/jetty/jetty.project/blob/jetty-12.1.1/jetty-core/jetty-xml/src/main/java/org/eclipse/jetty/xml/XmlConfiguration.java#L1971

[byteit101]

12.1 suffers the same thing as 12.0: there could be improved documentation. Here is my bad attempt to fix this issue:

12.1:

diff --git a/jetty-core/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/DeploymentScanner.java b/jetty-core/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/DeploymentScanner.java
index 35672ec6592..d12123b3ee0 100644
--- a/jetty-core/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/DeploymentScanner.java
+++ b/jetty-core/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/DeploymentScanner.java
@@ -273,7 +273,11 @@ public class DeploymentScanner extends ContainerLifeCycle implements Scanner.Bul
     /**
      * Configure the Environment specific Deploy settings.
      *
-     * @param name the name of the environment.
+     * @param name the name of the environment. This is usually one of "core", "static",
+     *             "ee8", "ee9" if using the associated jetty-provided modules.
+     * @see <a href="https://jetty.org/docs/jetty/12.1/operations-guide/deploy/index.html">The web Applicaiton Deployment page</a>
+     * for all available environments, as well as {@link Environment#getAll()}
+     *
      * @return the deployment configuration for the {@link Environment}.
      */
     public EnvironmentConfig configureEnvironment(String name)
diff --git a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/component/Environment.java b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/component/Environment.java
index fd5bd09fff4..79648655dcb 100644
--- a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/component/Environment.java
+++ b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/component/Environment.java
@@ -23,6 +23,9 @@ import org.slf4j.LoggerFactory;
 
 /**
  * A named runtime environment containing a {@link ClassLoader} and {@link Attributes}.
+ *
+ * The Jetty Project provides a number of environments, such as "static", "core", "ee8"
+ * "ee9", etc. See <a href="https://jetty.org/docs/jetty/12.1/operations-guide/deploy/index.html">The web Applicaiton Deployment page</a> for more information.
  */
 public interface Environment extends Attributes
 {

And 12.0:

diff --git a/jetty-core/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/providers/ScanningAppProvider.java b/jetty-core/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/providers/ScanningAppProvider.java
index 16ebe67723c..a7a50d5a360 100644
--- a/jetty-core/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/providers/ScanningAppProvider.java
+++ b/jetty-core/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/providers/ScanningAppProvider.java
@@ -99,6 +99,14 @@ public abstract class ScanningAppProvider extends ContainerLifeCycle implements
         return _environmentName;
     }
 
+    /**
+     * Set the deployment application name
+     *
+     * @param name the name of the environment. This is usually one of "core", "static",
+     *             "ee8", "ee9" if using the associated jetty-provided modules.
+     * @see <a href="https://jetty.org/docs/jetty/12.0/operations-guide/deploy/index.html">The web Applicaiton Deployment page</a>
+     * for all available environments, as well as {@link Environment#getAll()}
+     */
     public void setEnvironmentName(String environmentName)
     {
         _environmentName = environmentName;
diff --git a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/component/Environment.java b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/component/Environment.java
index f9825b01b7a..837127101d1 100644
--- a/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/component/Environment.java
+++ b/jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/component/Environment.java
@@ -24,6 +24,9 @@ import org.eclipse.jetty.util.TypeUtil;
 
 /**
  * A named runtime environment containing a {@link ClassLoader} and {@link Attributes}.
+ *
+ * The Jetty Project provides a number of environments, such as "static", "core", "ee8"
+ * "ee9", etc. See <a href="https://jetty.org/docs/jetty/12.0/operations-guide/deploy/index.html">The web Applicaiton Deployment page</a> for more information.
  */
 public interface Environment extends Attributes
 {

[joakime]

That suggested change is actually more confusing.

Those environments do not exist out of the box.
Keep that in mind.

The only thing that makes them exist, is if the following things occur.

1. Your code makes them exist by calling Environment class.
2. Your code has dependencies that fits that created environment.
3. Your code populates the Environment classloader with the jars / directories that suit that environment.

For jetty embedded, that means your code is creating those environments.

For jetty standalone, that's the role of jetty's $JETTY_HOME/start.jar, it is creating a command line that XmlConfiguration.main() uses to create those environments, and populate the classloader for that created environment.

Example: In the jetty-home modules, the static environment has a classloader of 1 entry (jetty-staticapp-<ver>.jar), and is just a configuration that points to org.eclipse.jetty.staticapp.StaticAppContext as the defaultContextHandlerClass. (and this is only because of the configuration in $JETTY_HOME/modules/static-deploy.mod and $JETTY_HOME/etc/jetty-static-deploy.xml)

If you want to use jetty-staticapp-<ver>.jar in your embedded jetty then you would ...

1. not have it be a dependency in your application (and not be present in your application classloader)
2. create a new ClassLoader pointing to your jetty-staticapp-<ver>.jar with the parent classloader being your application classloader (eg: using java.net.URLClassLoader, or OSGIClassLoader, or a JPMS tree, or a Spring Classloader, or a any of a dozen other common classloader setups).
3. use Environment.create("static", classloader) to establish the name "static" to that classloader. (this is the first time this name comes into existence, because you called that method)
4. use DeploymentScanner (in 12.1.x) as your deployment scanner.
5. use DeploymentScanner.configureEnvironment("static") to establish support for the name "static" in your deployer.
6. use $JETTY_BASE/webapps/<context>.<ext> to establish your context.
7. use $JETTY_BASE/webapps/<context>.properties with the setting environment=static to specify which environment name to deploy that context to.

Note that you can easily use "nonchanging" as a name in those steps too, and it will all work.
The name "static" only exists because you have specified that name.

This is what the $JETTY_HOME/start.jar and XmlConfiguration.main() is doing btw.

Again, if you are using Jetty 12.1.x and DeploymentScanner, then you are not using standalone jetty-home and it's configuration files (the mod files and xml files), which means you have no Environment names.

[joakime]

Another way to look at this.

Environment doesn't use deploy, nor is it even aware of deploy. (So documenting deployment names in the Environment apidoc is not relevant)

Deploy uses Environment, but via its name, and only if the context configuration has specified the name. (those names are not present in default core jetty, those names are what your configuration has specified)

In between is your server setup, the one that created each Environment: its name, the classloader, and the attributes for each.
That (startup) step is the only place these names come into existence.
Your deployer and context configurations then use these names.

It is not that hard to setup an entirely new springboot environment name that has it's own classloaders and attributes to support this new concept. This can be done in any existing Jetty 12 release, without a new release of Jetty being required for it to function.

BTW, we've already seen environment configurations with names like xwiki and jfaces that have been created to work with Jetty 12.

[byteit101]

You are both proving and missing my point: There is no javadoc that explains what you have said. The reason I filed this issue is that.. there is no javadoc that explains what you have said.

documenting deployment names in the Environment apidoc is not relevant

Why not? It's a perfect Tutorial on how to implement your own environment, as it tells users "here is how Jetty meant Environment to be implemented". Javadoc for Map<> shows that PrinterStateReasons is a known implementing class, even though Map<> itself doesn't use that. Specifying known Environments is a valid and useful documentation goal

Deploy uses Environment, but via its name, and only if the context configuration has specified the name

Great, it takes a name! Does the javadoc Reference specify where you can find out what names exist? No. In contrast, javadoc for Charset is such that if you Ctrl-F for "available", you will find the method, as well as a list of "Standard Charsets" at the top

In between is your server setup, the one that created each Environment: its name, the classloader, and the attributes for each.
That (startup) step is the only place these names come into existence.

Are you asserting that this documentation should be located in each user's glue code? I don't know how else to interpret this statement.
In the most charitiable interpretation, the example glue code should document that, or even better have Environment and Deploy point to jetty-examples in their javadoc.

It is not that hard to setup an entirely new springboot environment name that has it's own classloaders and attributes to support this new concept. This can be done in any existing Jetty 12 release, without a new release of Jetty being required for it to function.

Nice, where are the how-to guides to do this?

BTW, we've already seen environment configurations with names like xwiki and jfaces that have been created to work with Jetty 12.

Great, are there any pointers in jetty docs to this as example 3rd-party environments?

Those environments do not exist out of the box.
Keep that in mind.

Yes, you are technically correct, but it's not relevant to what I'm trying to point out here: There is missing documentation that could clarify this more. Let me explain.

The only thing that makes them exist, is if the following things occur.

1. Your code makes them exist by calling Environment class.

"my code" has no references to Environment

3. Your code populates the Environment classloader with the jars / directories that suit that environment.

"my code" has no references to classloaders

2. Your code has dependencies that fits that created environment.

"my code" only depends on Jetty. Yes, your pedantry eyebrow may be twitching, but as a casual user, "Jetty" is not a specific module, but the whole project. Explanations are handy for understanding the module structure, but avoiding documenting places (both sources and targets) where logical linking takes place between modules is very strange. A good example of cross-project linking can be seen with Pango, PangoCairo, Cairo, and HarfBuzz all referencing each other in documentation as they are often used together, despite being separate projects.

That suggested change is actually more confusing.

It is indeed a lie-to-children, but it's a useful and relevant part of the documentation. I presume someone with more experience than me can expand on it, hence why I pasted it in this issue vs creating a PR myself.

[gregw]

@byteit101 Can you turn your diff on the javadoc into a PR for 12.1 (we are not going to fix 12.0 documentation at this stage), and then that can be the basis for some constructive feedback and collaborate on making sure we do document these methods and behaviours.