Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Issue #10925 More updates to jetty maven plugin documentation.

This commit is contained in:
Jan Bartel 2023-11-29 18:53:58 +11:00
parent df42cb276d
commit f6eac3ebbc
3 changed files with 131 additions and 174 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-jspc-maven-plugin.adoc
View File

@ -14,18 +14,18 @@
[[jetty-jspc-maven-plugin]] [[jetty-jspc-maven-plugin]]
=== Jetty Jspc Maven Plugin === Jetty Jspc Maven Plugin
This plugin will help you pre-compile your JSP and works in conjunction with the Maven war plugin to put them inside an assembled war. This plugin will pre-compile your JSP and works in conjunction with the Maven war plugin to put them inside an assembled war.
[[jspc-config]] [[jspc-config]]
==== Configuration ==== Configuration
Here's the basic setup required to put the jspc plugin into your build: Here's the basic setup required to put the JSPC plugin into your build:
[source,xml,subs="verbatim,attributes"] [source,xml,subs="verbatim,attributes"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-jspc-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-jspc-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
<executions> <executions>
<execution> <execution>
@ -101,13 +101,13 @@ Default value: true
+ +
Determines if the manifest of JAR files found on the classpath should be scanned. Determines if the manifest of JAR files found on the classpath should be scanned.
sourceVersion:: sourceVersion::
Introduced in Jetty 9.3.6.
Java version of jsp source files. Java version of jsp source files.
Defaults to 1.7. The default value depends on the version of the `jetty-{ee-current}-jspc-maven-plugin`.
targetVersion:: targetVersion::
Introduced in Jetty 9.3.6.
Java version of class files generated from jsps. Java version of class files generated from jsps.
Defaults to 1.7. The default value depends on the version of the `jetty-{ee-current}-jspc-maven-plugin`.
tldJarNamePatterns:: tldJarNamePatterns::
Default value: `+.*taglibs[^/]*\.jar|.*jstl[^/]*\.jar$+` Default value: `+.*taglibs[^/]*\.jar|.*jstl[^/]*\.jar$+`
+ +
@ -118,7 +118,6 @@ Default value: the `org.apache.jasper.JspC` instance being configured.
+ +
The JspC class actually performs the pre-compilation. The JspC class actually performs the pre-compilation.
All setters on the JspC class are available. All setters on the JspC class are available.
You can download the javadoc https://repo1.maven.org/maven2/org/glassfish/web/jakarta.servlet.jsp/2.3.2/jakarta.servlet.jsp-2.3.2-javadoc.jar[here].
Taking all the default settings, here's how to configure the war plugin to use the generated `web.xml` that includes all of the jsp servlet declarations: Taking all the default settings, here's how to configure the war plugin to use the generated `web.xml` that includes all of the jsp servlet declarations:
@ -151,8 +150,8 @@ For example, the following profile will only be invoked if the flag `-Dprod` is
<build> <build>
<plugins> <plugins>
<plugin> <plugin>
<groupId>org.eclipse.jetty</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-jspc-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-jspc-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
<!-- put your configuration in here --> <!-- put your configuration in here -->
</plugin> </plugin>
@ -177,13 +176,12 @@ $ mvn -Dprod package
==== Precompiling Jsps with Overlaid Wars ==== Precompiling Jsps with Overlaid Wars
Precompiling jsps with an overlaid war requires a bit more configuration. Precompiling jsps with an overlaid war requires a bit more configuration.
This is because you need to separate the steps of unpacking the overlaid war and then repacking the final target war so the jetty-jspc-maven-plugin has the opportunity to access the overlaid resources. This is because you need to separate the steps of unpacking the overlaid war and then repacking the final target war so the `jetty-{ee-current}-jspc-maven-plugin` has the opportunity to access the overlaid resources.
In the example we'll show, we will use an overlaid war. In the following example the overlaid war will provide the `web.xml` file but the jsps will be in `src/main/webapp` (i.e. part of the project that uses the overlay).
The overlaid war will provide the `web.xml` file but the jsps will be in `src/main/webapp` (i.e. part of the project that uses the overlay). The overlaid war file will be unpacked, the jsps compiled and their servlet definitions merged into the extracted `web.xml`, and everything packed into a war.
We will unpack the overlaid war file, compile the jsps and merge their servlet definitions into the extracted `web.xml`, then pack everything into a war.
Here's an example configuration of the war plugin that separate those phases into an unpack phase, and then a packing phase: An example configuration of the war plugin that separates those phases into an unpack phase, and then a packing phase:
[source,xml] [source,xml]
---- ----
@ -199,8 +197,8 @@ Here's an example configuration of the war plugin that separate those phases int
<overlays> <overlays>
<overlay /> <overlay />
<overlay> <overlay>
<groupId>org.eclipse.jetty.demos</groupId> <groupId>org.eclipse.jetty.{ee-current}.demos</groupId>
<artifactId>demo-jetty-webapp</artifactId> <artifactId>jetty-{ee-current}-demo-jetty-webapp</artifactId>
</overlay> </overlay>
</overlays> </overlays>
</configuration> </configuration>
@ -218,15 +216,15 @@ Here's an example configuration of the war plugin that separate those phases int
</plugin> </plugin>
---- ----
Now you also need to configure the `jetty-jspc-maven-plugin` so that it can use the web.xml that was extracted by the war unpacking and merge in the generated definitions of the servlets. Now you also need to configure the `jetty-{ee-current}-jspc-maven-plugin` so that it can use the web.xml that was extracted by the war unpacking and merge in the generated definitions of the servlets.
This is in `target/foo/WEB-INF/web.xml`. This is in `target/foo/WEB-INF/web.xml`.
Using the default settings, the `web.xml` merged with the jsp servlet definitions will be put into `target/web.xml`. Using the default settings, the `web.xml` merged with the jsp servlet definitions will be put into `target/web.xml`.
[source,xml,subs="verbatim,attributes"] [source,xml,subs="verbatim,attributes"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-jspc-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-jspc-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
<executions> <executions>
<execution> <execution>

53
documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-maven-helloworld.adoc
View File

@ -27,8 +27,6 @@ Using Maven for Jetty implementations is a popular choice, but users encouraged
Other popular tools include Ant and Gradle. Other popular tools include Ant and Gradle.
==== ====
First we'll have a look at a very simple HelloWorld java application that embeds Jetty, then a simple webapp which makes use of the xref:jetty-maven-plugin[jetty-maven-plugin] to speed up the development cycle.
[[configuring-embedded-jetty-with-maven]] [[configuring-embedded-jetty-with-maven]]
==== Using Embedded Jetty with Maven ==== Using Embedded Jetty with Maven
@ -146,40 +144,13 @@ You can now compile and execute the HelloWorld class by using these commands:
> mvn clean compile exec:java > mvn clean compile exec:java
---- ----
You can point your browser to `+http://localhost:8080+` to see the _Hello World_ page. Point your browser to `+http://localhost:8080+` to see the _Hello World_ page.
You can observe what Maven is doing for you behind the scenes by using the `mvn dependency:tree` command, which reveals the transitive dependency resolved and downloaded as:
----
> mvn dependency:tree
[INFO] Scanning for projects...
...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Jetty HelloWorld 0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- maven-dependency-plugin:2.8:tree (default-cli) @ hello-world ---
...
[INFO] org.example:hello-world:jar:0.1-SNAPSHOT
[INFO] \- org.eclipse.jetty:jetty-server:jar:9.3.9.v20160517:compile
[INFO] +- jakarta.servlet:jakarta.servlet-api:jar:3.1.0:compile
[INFO] +- org.eclipse.jetty:jetty-http:jar:9.3.9.v20160517:compile
[INFO] | \- org.eclipse.jetty:jetty-util:jar:9.3.9.v20160517:compile
[INFO] \- org.eclipse.jetty:jetty-io:jar:9.3.9.v20160517:compile
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.145 s
[INFO] Finished at: 2016-08-01T13:46:42-04:00
[INFO] Final Memory: 15M/209M
[INFO] ------------------------------------------------------------------------
----
[[developing-standard-webapp-with-jetty-and-maven]] [[developing-standard-webapp-with-jetty-and-maven]]
==== Developing a Standard WebApp with Jetty and Maven ==== Developing a Standard WebApp with Jetty and Maven
The previous section demonstrated how to use Maven with an application that embeds Jetty. The previous section demonstrated how to use Maven with an application that embeds Jetty.
Now we will examine instead how to develop a standard webapp with Maven and Jetty. We can instead develop a standard webapp using Maven and Jetty.
First create the Maven structure (you can use the maven webapp archetype instead if you prefer): First create the Maven structure (you can use the maven webapp archetype instead if you prefer):
---- ----
@ -216,17 +187,17 @@ public class HelloServlet extends HttpServlet
} }
---- ----
You need to declare this servlet in the deployment descriptor, so create the file `src/main/webapp/WEB-INF/web.xml` and add the following contents: This servlet must be declared in the web deployment descriptor, so create the file `src/main/webapp/WEB-INF/web.xml` and add the following contents:
[source,xml] [source,xml]
---- ----
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<web-app <web-app
xmlns="http://xmlns.jcp.org/xml/ns/javaee" xmlns="https://jakarta.ee/xml/ns/jakartaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd" xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
metadata-complete="false" metadata-complete="false"
version="3.1"> version="6.0">
<servlet> <servlet>
<servlet-name>Hello</servlet-name> <servlet-name>Hello</servlet-name>
@ -244,7 +215,7 @@ You need to declare this servlet in the deployment descriptor, so create the fil
===== Creating the POM Descriptor ===== Creating the POM Descriptor
The `pom.xml` file declares the project name and its dependencies. The `pom.xml` file declares the project name and its dependencies.
Use an editor to create the file `pom.xml` with the following contents in the `JettyMavenHelloWarApp` directory, noting particularly the declaration of the xref:jetty-maven-plugin[jetty-maven-plugin]: Use an editor to create the file `pom.xml` with the following contents in the `JettyMavenHelloWarApp` directory, noting particularly the declaration of the xref:jetty-maven-plugin[jetty-maven-plugin] for the Jakarta {ee-current-caps} environment:
[source,xml,subs="verbatim,attributes"] [source,xml,subs="verbatim,attributes"]
---- ----
@ -267,7 +238,7 @@ Use an editor to create the file `pom.xml` with the following contents in the `J
<dependency> <dependency>
<groupId>jakarta.servlet</groupId> <groupId>jakarta.servlet</groupId>
<artifactId>jakarta.servlet-api</artifactId> <artifactId>jakarta.servlet-api</artifactId>
<version>3.1.0</version> <version>6.0.0</version>
<scope>provided</scope> <scope>provided</scope>
</dependency> </dependency>
</dependencies> </dependencies>
@ -275,8 +246,8 @@ Use an editor to create the file `pom.xml` with the following contents in the `J
<build> <build>
<plugins> <plugins>
<plugin> <plugin>
<groupId>org.eclipse.jetty</groupId> <groupId>org.eclipse.jetty.ee10</groupId>
<artifactId>jetty-maven-plugin</artifactId> <artifactId>jetty-ee10-maven-plugin</artifactId>
<version>${jettyVersion}</version> <version>${jettyVersion}</version>
</plugin> </plugin>
</plugins> </plugins>
@ -288,7 +259,7 @@ Use an editor to create the file `pom.xml` with the following contents in the `J
[[building-and-running-web-application]] [[building-and-running-web-application]]
===== Building and Running the Web Application ===== Building and Running the Web Application
Now you can both build and run the web application without needing to assemble it into a war by using the xref:jetty-maven-plugin[jetty-maven-plugin] via the command: The web application can now be built and run without first needing to assemble it into a war by using the xref:jetty-maven-plugin[jetty-maven-plugin] via the command:
---- ----
> mvn jetty:run > mvn jetty:run
@ -302,7 +273,7 @@ The full reference is at xref:jetty-maven-plugin[Configuring the Jetty Maven Plu
[[building-war-file]] [[building-war-file]]
===== Building a WAR file ===== Building a WAR file
You can create a Web Application Archive (WAR) file from the project with the command: A Web Application Archive (WAR) file can be produced from the project with the command:
---- ----
> mvn package > mvn package

212
documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-maven-plugin.adoc
View File

@ -15,18 +15,10 @@
=== Using the Jetty Maven Plugin === Using the Jetty Maven Plugin
The Jetty Maven plugin is useful for rapid development and testing. The Jetty Maven plugin is useful for rapid development and testing.
It can optionally periodically scan your project for changes and automatically redeploy the webapp if any are found. It can optionally periodically scan a project for changes and automatically redeploy the webapp if any are found.
This makes the development cycle more productive by eliminating the build and deploy steps: you use your IDE to make changes to the project, and the running web container automatically picks them up, allowing you to test them straight away. This makes the development cycle more productive by eliminating the build and deploy steps: use an IDE to make changes to the project, and the running web container automatically picks them up, allowing them to be tested straight away.
The plugin has been substantially re-architected in jetty-10 to: There are only 4 goals to run a webapp in Jetty:
* have less goals
* make deployment modes (embedded, forked or to a jetty distribution) apply uniformly across all goals
* simplify configuration options
* make the purpose and operation of each goal clearer
* rearchitect with composition rather than inheritance to make future extensions easier
There are now only 4 goals to run a webapp in jetty:
* xref:jetty-run-goal[jetty:run] * xref:jetty-run-goal[jetty:run]
* xref:jetty-run-war-goal[jetty:run-war] * xref:jetty-run-war-goal[jetty:run-war]
@ -38,51 +30,51 @@ Plus two utility goals:
* xref:jetty-stop-goal[jetty:stop] * xref:jetty-stop-goal[jetty:stop]
* xref:jetty-effective-web-xml-goal[jetty:effective-web-xml] * xref:jetty-effective-web-xml-goal[jetty:effective-web-xml]
`jetty:run` and `jetty:start` are alike in that they both run an unassembled webapp in jetty,however `jetty:run` is designed to be used at the command line, whereas `jetty:start` is specifically designed to be bound to execution phases in the build lifecycle. `jetty:run` and `jetty:start` are alike in that they both run an _unassembled_ webapp in Jetty,however `jetty:run` is designed to be used at the command line, whereas `jetty:start` is specifically designed to be bound to execution phases in the build lifecycle.
`jetty:run` will pause maven while jetty is running, echoing all output to the console, and then stop maven when jetty exits. `jetty:run` will pause Maven while jetty is running, echoing all output to the console, and then stop Maven when jetty exits.
`jetty:start` will not pause maven, will write all its output to a file, and will not stop maven when jetty exits. `jetty:start` will not pause Maven, will write all its output to a file, and will not stop Maven when jetty exits.
`jetty:run-war` and `jetty:start-war` are similar in that they both run an _assembled_ war file in jetty. `jetty:run-war` and `jetty:start-war` are similar in that they both run an _assembled_ war file in Jetty.
However, `jetty:run-war` is designed to be run at the command line, whereas `jetty:start-war` is specifically designed to be bound to execution phases in the build lifecycle. However, `jetty:run-war` is designed to be run at the command line, whereas `jetty:start-war` is specifically designed to be bound to execution phases in the build lifecycle.
`jetty:run-war` will pause maven while jetty is running, echoing all output to the console, and then stop maven when jetty exits. `jetty:run-war` will pause Maven while Jetty is running, echoing all output to the console, and then stop Maven when Jetty exits.
`jetty:start-war` will not not pause maven, will write all its output to a file, and will not stop maven when jetty exits. `jetty:start-war` will not pause Maven, will write all its output to a file, and will not stop Maven when Jetty exits.
[IMPORTANT] [IMPORTANT]
==== ====
While the Jetty Maven Plugin can be very useful for development we do not recommend its use in a _production capacity_. While the Jetty Maven Plugin can be very useful for development we do not recommend its use in a _production capacity_.
In order for the plugin to work it needs to leverage many internal Maven apis and Maven itself it not a production deployment tool. In order for the plugin to work it needs to leverage many internal Maven APIs and Maven itself it not a production deployment tool.
We recommend either the traditional link:{DISTGUIDE}[distribution] deployment approach or using xref:advanced-embedding[embedded Jetty]. We recommend either the traditional link:{DISTGUIDE}[distribution] deployment approach or using xref:advanced-embedding[embedded Jetty].
==== ====
[[get-up-and-running]] [[get-up-and-running]]
==== Get Up and Running ==== Get Up and Running
Since Jetty 12, Jetty Maven plugin is repackaged for corresponding Jakarta EE version with an `eeX` classifier in the groupId and artifactId. The `eeX` can be `ee8`,`ee9` or `ee10`, which stands for Jakarta EE 8, 9 and 10 respectively. Since Jetty 12, Jetty Maven plugin is repackaged for the corresponding Jakarta EE version with an `eeX` classifier in the groupId and artifactId.
First, add `jetty-ee10-maven-plugin` to your `pom.xml` definition. Here's an example of how to do that for EE10: First, add `jetty-{ee-all}-maven-plugin` to your `pom.xml` definition. Here's an example of how to do that for Jakarta {ee-current-caps}:
[source,xml,subs="verbatim,attributes"] [source,xml,subs="verbatim,attributes"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty.ee10</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
</plugin> </plugin>
---- ----
Then, from the same directory as your root `pom.xml`, type: Then, from the same directory as the project's root `pom.xml`, type:
---- ----
mvn jetty:run mvn jetty:run
---- ----
This starts Jetty and serves up your project on `+http://localhost:8080/+`. This starts Jetty and serves up the project on `+http://localhost:8080/+`.
Jetty will continue to run until you stop it. Jetty will continue to run until you stop it.
By default, it will not automatically restart your webapp. By default, it will not automatically restart your webapp.
Set a non-zero `<scan>` value to have jetty scan your webapp for changes and automatically redeploy, or set `<scan>` to `0` to cause manual redeployment by hitting the kbd:[Enter] key. Set a non-zero `<scan>` value to have Jetty scan your webapp for changes and automatically redeploy, or set `<scan>` to `0` to cause manual redeployment by hitting the kbd:[Enter] key.
You can terminate the plugin with a kbd:[Ctrl+c] in the terminal window where it is running. Terminate the plugin with a kbd:[Ctrl+c] in the terminal window where it is running.
[NOTE] [NOTE]
==== ====
@ -93,17 +85,17 @@ For example: a webapp's dependent jars might be referenced via the local reposit
[[supported-goals]] [[supported-goals]]
==== Supported Goals ==== Supported Goals
The goals prefixed with `"run"` are designed to be used at the _command line_. The goals prefixed with `"run-"` are designed to be used at the _command line_.
They first run a maven build on your project to ensure at least the classes are all built. They first run a Maven build on your project to ensure at least the classes are all built.
They then start jetty and pause the maven build process until jetty is manually terminated, at which time the build will also be terminated. They then start Jetty and pause the Maven build process until Jetty is manually terminated, at which time the build will also be terminated.
Jetty can scan various files in your project for changes and redeploy the webapp as necessary, or you can choose to manually trigger a redeploy if you prefer. Jetty can scan various files in your project for changes and redeploy the webapp as necessary, or you can choose to manually trigger a redeploy if you prefer.
All output from jetty is echoed to the console. All output from Jetty is echoed to the console.
The goals prefixed with `"start"` are designed to be used with _build lifecycle bindings in the pom_, and _not_ at the command line. The goals prefixed with `"start-"` are designed to be used with _build lifecycle bindings in the pom_, and _not_ at the command line.
No part of your project will be rebuilt by invoking these goals - you should ensure that your bind the execution to a build phase where all necessary parts of your project have been built. No part of your project will be rebuilt by invoking these goals - you should ensure that your bind the execution to a build phase where all necessary parts of your project have been built.
Maven will start and terminate jetty at the appropriate points in the build lifecycle, continuing with the build. Maven will start and terminate Jetty at the appropriate points in the build lifecycle, continuing with the build.
Jetty will _not_ scan any files in your project for changes, and your webapp will _not_ be redeployed either automatically or manually. Jetty will _not_ scan any files in your project for changes, and your webapp will _not_ be redeployed either automatically or manually.
Output from jetty is directed to a file in the `target` directory. Output from Jetty is directed to a file in the `target` directory.
To see a list of all goals supported by the Jetty Maven plugin, do: To see a list of all goals supported by the Jetty Maven plugin, do:
@ -119,14 +111,14 @@ mvn jetty:help -Ddetail=true -Dgoal=<goalName>
[[deployment-modes]] [[deployment-modes]]
==== Deployment Modes ==== Deployment Modes
All of the `"run"` and `"start"` goals can deploy your webapp either into the running maven process, or forked into a new child process, or forked into a jetty distribution on disk. All of the `"run-"` and `"start-"` goals can deploy your webapp either into the running maven process, or forked into a new child process, or forked into a Jetty distribution on disk.
This is controlled by setting the `deployMode` configuration parameter in the pom, but can also be set by defining the maven property 'jetty.deployMode'. This is controlled by setting the `deployMode` configuration parameter in the pom, but can also be set by defining the Maven property 'jetty.deployMode'.
===== Embedded ===== Embedded
`deployMode` of `EMBED`. `deployMode` of `EMBED`.
This is the "classic" jetty maven plugin deployment mode, running in-process with maven. This is the "classic" Jetty Maven plugin deployment mode, running in-process with Maven.
This is the _default_ mode. This is the _default_ mode.
These extra configuration parameters are available: These extra configuration parameters are available:
@ -149,8 +141,8 @@ name:::
The name of the connector, which is useful for xref:serving-webapp-from-particular-port[configuring contexts to respond only on particular connectors]. The name of the connector, which is useful for xref:serving-webapp-from-particular-port[configuring contexts to respond only on particular connectors].
idleTimeout::: idleTimeout:::
Maximum idle time for a connection. Maximum idle time for a connection.
You could instead configure the connectors in a standard xref:jetty-xml-config[jetty xml config file] and put its location into the `jettyXml` parameter. You could instead configure the connectors in a standard xref:jetty-xml-config[Jetty xml config file] and put its location into the `jettyXml` parameter.
Note that since Jetty 9.0 it is no longer possible to configure a xref:maven-config-https[https connector] directly in the pom.xml: you need to xref:maven-config-https[use jetty xml config files to do it]. Note that since Jetty 9.0 it is no longer possible to configure a xref:maven-config-https[https connector] directly in the pom.xml: you need to xref:maven-config-https[use Jetty xml config files to do it].
loginServices:: loginServices::
Optional. Optional.
A list of `org.eclipse.jetty.security.LoginService` implementations. Note that there is no default realm. A list of `org.eclipse.jetty.security.LoginService` implementations. Note that there is no default realm.
@ -160,10 +152,9 @@ See xref:configuring-security-settings[Configuring Security].
requestLog:: requestLog::
Optional. Optional.
An implementation of the `org.eclipse.jetty.server.RequestLog` request log interface. An implementation of the `org.eclipse.jetty.server.RequestLog` request log interface.
An implementation that respects the NCSA format is available as `org.eclipse.jetty.server.NCSARequestLog`. There are three other ways to configure the `RequestLog`:
There are three other ways to configure the RequestLog:
+ +
* In a jetty xml config file, as specified in the `jettyXml` parameter. * In a Jetty xml config file, as specified in the `jettyXml` parameter.
* In a context xml config file, as specified in the `contextXml` parameter. * In a context xml config file, as specified in the `contextXml` parameter.
* In the `webApp` element. * In the `webApp` element.
+ +
@ -207,29 +198,29 @@ See xref:container-classpath[Container Classpath vs WebApp Classpath].
===== In a jetty distribution ===== In a jetty distribution
`deployMode` of `EXTERNAL`. `deployMode` of `EXTERNAL`.
This is similar to the old "jetty:run-distro" goal - your webapp is deployed into a dynamically downloaded, unpacked and configured jetty distribution. This is similar to the old "jetty:run-distro" goal - your webapp is deployed into a dynamically downloaded, unpacked and configured Jetty distribution.
A separate process is forked to run it. A separate process is forked to run it.
These extra configuration parameters are available: These extra configuration parameters are available:
jettyBase:: jettyBase::
Optional. Optional.
The location of an existing jetty base directory to use to deploy the webapp. The location of an existing Jetty base directory to use to deploy the webapp.
The existing base will be copied to the `target/` directory before the webapp is deployed. The existing base will be copied to the `target/` directory before the webapp is deployed.
If there is no existing jetty base, a fresh one will be made in `target/jetty-base`. If there is no existing jetty base, a fresh one will be made in `target/jetty-base`.
jettyHome:: jettyHome::
Optional. Optional.
The location of an existing unpacked jetty distribution. The location of an existing unpacked Jetty distribution.
If one does not exist, a fresh jetty distribution will be downloaded from maven and installed to the `target` directory. If one does not exist, a fresh Jetty distribution will be downloaded from Maven and installed to the `target` directory.
jettyOptions:: jettyOptions::
Optional. Optional.
A space separated string representing extra arguments to the synthesized jetty command line. A space separated string representing extra arguments to the synthesized Jetty command line.
Values for these arguments can be found in the section titled "Options" in the output of `java -jar $jetty.home/start.jar --help`. Values for these arguments can be found in the section titled "Options" in the output of `java -jar $jetty.home/start.jar --help`.
jvmArgs:: jvmArgs::
Optional. Optional.
A space separated string representing arguments that should be passed to the jvm of the child process running the distro. A space separated string representing arguments that should be passed to the jvm of the child process running the distro.
modules:: modules::
Optional. Optional.
An array of names of additional jetty modules that the jetty child process will activate. An array of names of additional Jetty modules that the Jetty child process will activate.
Use this to change the xref:container-classpath[container classpath] instead of `useProvidedScope`. Use this to change the xref:container-classpath[container classpath] instead of `useProvidedScope`.
These modules are enabled by default: `server,http,webapp,deploy`. These modules are enabled by default: `server,http,webapp,deploy`.
@ -243,11 +234,11 @@ deployMode::
One of `EMBED`, `FORK` or `EXTERNAL`. One of `EMBED`, `FORK` or `EXTERNAL`.
Default `EMBED`. Default `EMBED`.
Can also be configured by setting the Maven property `jetty.deployMode`. Can also be configured by setting the Maven property `jetty.deployMode`.
This parameter determines whether the webapp will run in jetty in-process with Maven, forked into a new process, or deployed into a jetty distribution. This parameter determines whether the webapp will run in Jetty in-process with Maven, forked into a new process, or deployed into a Jetty distribution.
See xref:deployment-modes[Deployment Modes]. See xref:deployment-modes[Deployment Modes].
jettyXmls:: jettyXmls::
Optional. Optional.
A comma separated list of locations of jetty xml files to apply in addition to any plugin configuration parameters. A comma separated list of locations of Jetty xml files to apply in addition to any plugin configuration parameters.
You might use it if you have other webapps, handlers, specific types of connectors etc., to deploy, or if you have other Jetty objects that you cannot configure from the plugin. You might use it if you have other webapps, handlers, specific types of connectors etc., to deploy, or if you have other Jetty objects that you cannot configure from the plugin.
skip:: skip::
Default is false. Default is false.
@ -281,16 +272,16 @@ Allows you to configure standard jetty properties.
[[container-classpath]] [[container-classpath]]
==== Container Classpath vs WebApp Classpath ==== Container Classpath vs WebApp Classpath
The Servlet Specification makes a strong distinction between the classpath for a webapp, and the classpath of the container. The Servlet Specification makes a strong distinction between the classpath for a _webapp_, and the classpath of the _container_.
When running in maven, the plugin's classpath is equivalent to the container classpath. When running in Maven, the plugin's classpath is equivalent to the _container_ classpath.
It will make a classpath for the webapp to be deployed comprised of &lt;dependencies&gt; specified in the pom. It will make a classpath for the _webapp_ to be deployed comprised of &lt;dependencies&gt; specified in the pom.
If your production environment places specific jars onto the container's classpath, the equivalent way to do this with maven is to define these as &lt;dependencies&gt; for the _plugin_ itself, not the _project_. See http://maven.apache.org/pom.html#Plugins[configuring maven plugins]. If your production environment places specific jars onto the container's classpath, the equivalent way to do this with Maven is to define these as &lt;dependencies&gt; for the _plugin_ itself, not the _project_. See http://maven.apache.org/pom.html#Plugins[configuring maven plugins].
This is suitable if you are using either `EMBED` or `FORK` mode. This is suitable if you are using either `EMBED` or `FORK` mode.
If you are using `EXTERNAL` mode, then you should configure the `modules` parameter with the names of the jetty modules that place these jars onto the container classpath. If you are using `EXTERNAL` mode, then you should configure the `modules` parameter with the names of the Jetty modules that place these jars onto the container classpath.
Note that in `EMBED` or `FORK` mode, you could also influence the container classpath by setting the `useProvidedScope` parameter to `true`: this will place any dependencies with &lt;scope&gt;provided&lt;scope&gt; onto the plugin's classpath. Note that in `EMBED` or `FORK` mode, you could also influence the container classpath by setting the `useProvidedScope` parameter to `true`: this will place any dependencies with &lt;scope&gt;provided&lt;scope&gt; onto the plugin's classpath.
Use this very cautiously: as the plugin already automatically places most jetty jars onto the classpath, you could wind up with duplicate jars. Use this very cautiously: as the plugin already automatically places most Jetty jars onto the classpath, you could wind up with duplicate jars.
[[jetty-run-goal]] [[jetty-run-goal]]
@ -298,35 +289,34 @@ Use this very cautiously: as the plugin already automatically places most jetty
The `run` goal deploys a webapp that is _not_ first built into a WAR. The `run` goal deploys a webapp that is _not_ first built into a WAR.
A virtual webapp is constructed from the project's sources and its dependencies. A virtual webapp is constructed from the project's sources and its dependencies.
It looks for the constituent parts of a webapp in the maven default project locations, although you can override these in the plugin configuration. It looks for the constituent parts of a webapp in the Maven default project locations, although you can override these in the plugin configuration.
For example, by default it looks for: For example, by default it looks for:
* resources in `${project.basedir}/src/main/webapp` * resources in `${project.basedir}/src/main/webapp`
* classes in `${project.build.outputDirectory}` * classes in `${project.build.outputDirectory}`
* `web.xml` in `${project.basedir}/src/main/webapp/WEB-INF/` * `web.xml` in `${project.basedir}/src/main/webapp/WEB-INF/`
The plugin first runs a maven parallel build to ensure that the classes are built and up-to-date before deployment. The plugin first runs a Maven parallel build to ensure that the classes are built and up-to-date before deployment.
If you change the source of a class and your IDE automatically compiles it in the background, the plugin picks up the changed class (note you need to configure a non-zero `scan` interval for automatic redeployment). If you change the source of a class and your IDE automatically compiles it in the background, the plugin picks up the changed class (note you need to configure a non-zero `scan` interval for automatic redeployment).
If the plugin is invoked in a multi-module build, any dependencies that are also in the maven reactor are used from their compiled classes. If the plugin is invoked in a multi-module build, any dependencies that are also in the Maven reactor are used from their compiled classes.
Prior to jetty-9.4.7 any dependencies needed to be built first.
Once invoked, you can configure the plugin to run continuously, scanning for changes in the project and automatically performing a hot redeploy when necessary. Once invoked, you can configure the plugin to run continuously, scanning for changes in the project and automatically performing a hot redeploy when necessary.
Any changes you make are immediately reflected in the running instance of Jetty, letting you quickly jump from coding to testing, rather than going through the cycle of: code, compile, reassemble, redeploy, test. Any changes you make are immediately reflected in the running instance of Jetty, letting you quickly jump from coding to testing, rather than going through the cycle of: code, compile, reassemble, redeploy, test.
The maven build will be paused until jetty exits, at which time maven will also exit. The Maven build will be paused until Jetty exits, at which time Maven will also exit.
Stopping jetty is accomplished by typing `cntrl-c` at the command line. Stopping Jetty is accomplished by typing `cntrl-c` at the command line.
Output from jetty will be logged to the console. Output from Jetty will be logged to the console.
Here is an example, which turns on scanning for changes every ten seconds, and sets the webapp context path to `/test`: Here is an example, which turns on scanning for changes every ten seconds, and sets the webapp context path to `/test`:
[source,xml,subs="verbatim,attributes"] [source,xml,subs="verbatim,attributes"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty.ee10</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
<configuration> <configuration>
<scan>10</scan> <scan>10</scan>
@ -340,7 +330,7 @@ Here is an example, which turns on scanning for changes every ten seconds, and s
===== Configuration ===== Configuration
webApp:: webApp::
This is an instance of link:{javadoc-url}/org/eclipse/jetty/maven/plugin/MavenWebAppContext.html[org.eclipse.jetty.maven.plugin.MavenWebAppContext], which is an extension to the class link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.hml[`org.eclipse.jetty.ee9.webapp.WebAppContext`]. This is an instance of link:{javadoc-url}/org/eclipse/jetty/{ee-current}}/maven/plugin/MavenWebAppContext.html[org.eclipse.jetty.{ee-current}.maven.plugin.MavenWebAppContext], which is an extension to the class link:{javadoc-url}/org/eclipse/jetty/{ee-current}/webapp/WebAppContext.hml[`org.eclipse.jetty.{ee-current}.webapp.WebAppContext`].
You can use any of the setter methods on this object to configure your webapp. You can use any of the setter methods on this object to configure your webapp.
Here are a few of the most useful ones: Here are a few of the most useful ones:
+ +
@ -352,7 +342,7 @@ The path to the `web.xml` file for your webapp.
By default, the plugin will look in `src/main/webapp/WEB-INF/web.xml`. By default, the plugin will look in `src/main/webapp/WEB-INF/web.xml`.
defaultsDescriptor;; defaultsDescriptor;;
The path to a `webdefault.xml` file that will be applied to your webapp before the `web.xml`. The path to a `webdefault.xml` file that will be applied to your webapp before the `web.xml`.
If you don't supply one, Jetty uses a default file baked into the `jetty-webapp.jar`. If you don't supply one, Jetty uses a default file baked into the `jetty-{ee-current}-webapp.jar`.
overrideDescriptor;; overrideDescriptor;;
The path to a `web.xml` file that Jetty applies after reading your `web.xml`. The path to a `web.xml` file that Jetty applies after reading your `web.xml`.
You can use this to replace or add configuration. You can use this to replace or add configuration.
@ -423,8 +413,8 @@ Here is an example of a pom configuration for the plugin with the `run` goal:
<plugins> <plugins>
... ...
<plugin> <plugin>
<groupId>org.eclipse.jetty.ee10</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
<configuration> <configuration>
<webApp> <webApp>
@ -466,13 +456,13 @@ If, for whatever reason, you cannot run on an unassembled webapp, the goal `run-
When invoked at the command line this goal first executes a maven build of your project to the package phase. When invoked at the command line this goal first executes a maven build of your project to the package phase.
By default it then deploys the resultant war to jetty, but you can use this goal instead to deploy _any_ war file by simply setting the `&lt;webApp&gt;&lt;war&gt;` configuration parameter to its location. By default it then deploys the resultant war to Jetty, but you can use this goal instead to deploy _any_ war file by simply setting the `&lt;webApp&gt;&lt;war&gt;` configuration parameter to its location.
If you set a non-zero `scan`, Jetty watches your `pom.xml` and the WAR file; if either changes, it redeploys the war. If you set a non-zero `scan`, Jetty watches your `pom.xml` and the WAR file; if either changes, it redeploys the war.
The maven build is held up until jetty exits, which is achieved by typing `cntrl-c` at the command line. The maven build is held up until Jetty exits, which is achieved by typing `cntrl-c` at the command line.
All jetty output is directed to the console. All Jetty output is directed to the console.
===== Configuration ===== Configuration
@ -487,7 +477,7 @@ The context path for your webapp. By default, this is set to `/`.
If using a custom value for this parameter, you should include the leading `/`, example `/mycontext`. If using a custom value for this parameter, you should include the leading `/`, example `/mycontext`.
defaultsDescriptor::: defaultsDescriptor:::
The path to a `webdefault.xml` file that will be applied to your webapp before the `web.xml`. The path to a `webdefault.xml` file that will be applied to your webapp before the `web.xml`.
If you don't supply one, Jetty uses a default file baked into the `jetty-webapp.jar`. If you don't supply one, Jetty uses a default file baked into the `jetty-{ee-current}-webapp.jar`.
overrideDescriptor::: overrideDescriptor:::
The path to a `web.xml` file that Jetty applies after reading your `web.xml`. The path to a `web.xml` file that Jetty applies after reading your `web.xml`.
You can use this to replace or add configuration. You can use this to replace or add configuration.
@ -521,21 +511,20 @@ See xref:deployment-modes[Deployment Modes] for other configuration parameters a
This is similar to the `jetty:run` goal, however it is _not_ designed to be run from the command line and does _not_ first execute the build up until the `test-compile` phase to ensure that all necessary classes and files of the webapp have been generated. This is similar to the `jetty:run` goal, however it is _not_ designed to be run from the command line and does _not_ first execute the build up until the `test-compile` phase to ensure that all necessary classes and files of the webapp have been generated.
It will _not_ scan your project for changes and restart your webapp. It will _not_ scan your project for changes and restart your webapp.
It does _not_ pause maven until jetty is stopped. It does _not_ pause maven until Jetty is stopped.
Instead, it is designed to be used with build phase bindings in your pom. Instead, it is designed to be used with build phase bindings in your pom.
For example to you can have maven start your webapp at the beginning of your tests and stop at the end. For example to you can have Maven start your webapp at the beginning of your tests and stop at the end.
If the plugin is invoked as part of a multi-module build, any dependencies that are also in the maven reactor are used from their compiled classes. If the plugin is invoked as part of a multi-module build, any dependencies that are also in the maven reactor are used from their compiled classes.
Prior to jetty-9.4.7 any dependencies needed to be built first.
Here's an example of using the `pre-integration-test` and `post-integration-test` Maven build phases to trigger the execution and termination of Jetty: Here's an example of using the `pre-integration-test` and `post-integration-test` Maven build phases to trigger the execution and termination of Jetty:
[source,xml,subs="verbatim,attributes"] [source,xml,subs="verbatim,attributes"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty.ee10</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
<configuration> <configuration>
<stopKey>foo</stopKey> <stopKey>foo</stopKey>
@ -567,7 +556,7 @@ This goal will generate output from jetty into the `target/jetty-start.out` file
These configuration parameters are available: These configuration parameters are available:
webApp:: webApp::
This is an instance of link:{javadoc-url}/org/eclipse/jetty/maven/plugin/MavenWebAppContext.html[org.eclipse.jetty.maven.plugin.MavenWebAppContext], which is an extension to the class link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.hml[`org.eclipse.jetty.ee9.webapp.WebAppContext`]. This is an instance of link:{javadoc-url}/org/eclipse/jetty/{ee-current}/maven/plugin/MavenWebAppContext.html[org.eclipse.jetty.{ee-current}.maven.plugin.MavenWebAppContext], which is an extension to the class link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.hml[`org.eclipse.jetty.ee9.webapp.WebAppContext`].
You can use any of the setter methods on this object to configure your webapp. You can use any of the setter methods on this object to configure your webapp.
Here are a few of the most useful ones: Here are a few of the most useful ones:
+ +
@ -579,7 +568,7 @@ The path to the `web.xml` file for your webapp.
The default is `src/main/webapp/WEB-INF/web.xml`. The default is `src/main/webapp/WEB-INF/web.xml`.
defaultsDescriptor;; defaultsDescriptor;;
The path to a `webdefault.xml` file that will be applied to your webapp before the `web.xml`. The path to a `webdefault.xml` file that will be applied to your webapp before the `web.xml`.
If you don't supply one, Jetty uses a default file baked into the `jetty-webapp.jar`. If you don't supply one, Jetty uses a default file baked into the `jetty-{ee-current}-webapp.jar`.
overrideDescriptor;; overrideDescriptor;;
The path to a `web.xml` file that Jetty applies after reading your `web.xml`. The path to a `web.xml` file that Jetty applies after reading your `web.xml`.
You can use this to replace or add configuration. You can use this to replace or add configuration.
@ -644,13 +633,12 @@ This is the time in milliseconds between checks on the startup of the forked jet
Similarly to the `jetty:start` goal, `jetty:start-war` is designed to be bound to build lifecycle phases in your pom. Similarly to the `jetty:start` goal, `jetty:start-war` is designed to be bound to build lifecycle phases in your pom.
It will _not_ scan your project for changes and restart your webapp. It will _not_ scan your project for changes and restart your webapp.
It does _not_ pause maven until jetty is stopped. It does _not_ pause maven until Jetty is stopped.
By default, if your pom is for a webapp project, it will deploy the war file for the project to jetty. By default, if your pom is for a webapp project, it will deploy the war file for the project to jetty.
However, like the `jetty:run-war` project, you can nominate any war file to deploy by defining its location in the `&lt;webApp&gt;&lt;war&gt;` parameter. However, like the `jetty:run-war` project, you can nominate any war file to deploy by defining its location in the `&lt;webApp&gt;&lt;war&gt;` parameter.
If the plugin is invoked as part of a multi-module build, any dependencies that are also in the maven reactor are used from their compiled classes. If the plugin is invoked as part of a multi-module build, any dependencies that are also in the Maven reactor are used from their compiled classes.
Prior to jetty-9.4.7 any dependencies needed to be built first.
This goal will generate output from jetty into the `target/jetty-start-war.out` file. This goal will generate output from jetty into the `target/jetty-start-war.out` file.
@ -667,7 +655,7 @@ The context path for your webapp. By default, this is set to `/`.
If using a custom value for this parameter, you should include the leading `/`, example `/mycontext`. If using a custom value for this parameter, you should include the leading `/`, example `/mycontext`.
defaultsDescriptor::: defaultsDescriptor:::
The path to a `webdefault.xml` file that will be applied to your webapp before the `web.xml`. The path to a `webdefault.xml` file that will be applied to your webapp before the `web.xml`.
If you don't supply one, Jetty uses a default file baked into the `jetty-webapp.jar`. If you don't supply one, Jetty uses a default file baked into the `jetty-{ee-current}-webapp.jar`.
overrideDescriptor::: overrideDescriptor:::
The path to a `web.xml` file that Jetty applies after reading your `web.xml`. The path to a `web.xml` file that Jetty applies after reading your `web.xml`.
You can use this to replace or add configuration. You can use this to replace or add configuration.
@ -698,10 +686,10 @@ These additional configuration parameters are available when running in FORK or
maxChildStartChecks:: maxChildStartChecks::
Default is `10`. Default is `10`.
This is maximum number of times the parent process checks to see if the forked jetty process has started correctly This is maximum number of times the parent process checks to see if the forked Jetty process has started correctly
maxChildStartCheckMs:: maxChildStartCheckMs::
Default is `200`. Default is `200`.
This is the time in milliseconds between checks on the startup of the forked jetty process. This is the time in milliseconds between checks on the startup of the forked Jetty process.
[[jetty-stop-goal]] [[jetty-stop-goal]]
@ -709,7 +697,7 @@ This is the time in milliseconds between checks on the startup of the forked jet
The stop goal stops a FORK or EXTERNAL mode running instance of Jetty. The stop goal stops a FORK or EXTERNAL mode running instance of Jetty.
To use it, you need to configure the plugin with a special port number and key. To use it, you need to configure the plugin with a special port number and key.
That same port number and key will also be used by the other goals that start jetty. That same port number and key will also be used by the other goals that start Jetty.
===== Configuration ===== Configuration
@ -726,8 +714,8 @@ Here's a configuration example:
[source,xml,subs="verbatim,attributes"] [source,xml,subs="verbatim,attributes"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty.ee10</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
<configuration> <configuration>
<stopPort>9966</stopPort> <stopPort>9966</stopPort>
@ -755,7 +743,7 @@ No programmatic declarations of servlets, filters and listeners can be taken int
You can calculate the effective web.xml for any pre-built war file by setting the `&lt;webApp&gt;&lt;war&gt;` parameter, or you can calculate it for the unassembled webapp by setting all of the usual `&lt;webApp&gt;` parameters as for `jetty:run`. You can calculate the effective web.xml for any pre-built war file by setting the `&lt;webApp&gt;&lt;war&gt;` parameter, or you can calculate it for the unassembled webapp by setting all of the usual `&lt;webApp&gt;` parameters as for `jetty:run`.
Other useful information about your webapp that is produced as part of the analysis is also stored as context parameters in the effective-web.xml. Other useful information about your webapp that is produced as part of the analysis is also stored as context parameters in the effective-web.xml.
The effective-web.xml can be used in conjunction with the xref:quickstart-webapp[Quickstart] feature to quickly start your webapp (note that Quickstart is not appropriate for the mvn jetty goals). The effective-web.xml can be used in conjunction with the xref:quickstart-webapp[Quickstart] feature to quickly start your webapp (note that Quickstart is not appropriate for the mvn Jetty goals).
The effective web.xml from these combined sources is generated into a file, which by default is `target/effective-web.xml`, but can be changed by setting the `effectiveWebXml` configuration parameter. The effective web.xml from these combined sources is generated into a file, which by default is `target/effective-web.xml`, but can be changed by setting the `effectiveWebXml` configuration parameter.
@ -773,7 +761,7 @@ The context path for your webapp. By default, this is set to `/`.
If using a custom value for this parameter, you should include the leading `/`, example `/mycontext`. If using a custom value for this parameter, you should include the leading `/`, example `/mycontext`.
defaultsDescriptor::: defaultsDescriptor:::
The path to a `webdefault.xml` file that will be applied to your webapp before the `web.xml`. The path to a `webdefault.xml` file that will be applied to your webapp before the `web.xml`.
If you don't supply one, Jetty uses a default file baked into the `jetty-webapp.jar`. If you don't supply one, Jetty uses a default file baked into the `jetty-{ee-current}-webapp.jar`.
overrideDescriptor::: overrideDescriptor:::
The path to a `web.xml` file that Jetty applies after reading your `web.xml`. The path to a `web.xml` file that Jetty applies after reading your `web.xml`.
You can use this to replace or add configuration. You can use this to replace or add configuration.
@ -811,7 +799,7 @@ originAttribute::
The name of the attribute that will contain the origin. The name of the attribute that will contain the origin.
By default it is `origin`. By default it is `origin`.
generateOrigin:: generateOrigin::
False by default. If true, will force the generation of the originAttribute onto each element. False by default. If true, will force the generation of the `originAttribute` onto each element.
[[using-overlaid-wars]] [[using-overlaid-wars]]
@ -822,7 +810,7 @@ It can do so based on the settings of the http://maven.apache.org/plugins/maven-
===== With maven-war-plugin ===== With maven-war-plugin
The maven-war-plugin has a rich set of capabilities for merging resources. The `maven-war-plugin` has a rich set of capabilities for merging resources.
The `jetty:run` and `jetty:start` goals are able to interpret most of them and apply them during execution of your unassembled webapp. The `jetty:run` and `jetty:start` goals are able to interpret most of them and apply them during execution of your unassembled webapp.
This is probably best seen by looking at a concrete example. This is probably best seen by looking at a concrete example.
@ -891,8 +879,8 @@ They are configured for the http://maven.apache.org/plugins/maven-war-plugin/ove
---- ----
Then executing jetty:run would yield the following ordering of resources: `com.acme.X.war : com.acme.Y.war: ${project.basedir}/src/main/webapp`. Then executing jetty:run would yield the following ordering of resources: `com.acme.X.war : com.acme.Y.war: ${project.basedir}/src/main/webapp`.
Note that the current project's resources are placed last in the ordering due to the empty <overlay/> element in the maven-war-plugin. Note that the current project's resources are placed last in the ordering due to the empty <overlay/> element in the `maven-war-plugin`.
You can either use that, or specify the `<baseAppFirst>false</baseAppFirst>` parameter to the jetty-ee10-maven-plugin. You can either use that, or specify the `<baseAppFirst>false</baseAppFirst>` parameter to the `jetty-{ee-current}-maven-plugin`.
Moreover, due to the `exclusions` specified above, a request for the resource ` bar.jsp` would only be satisfied from `com.acme.Y.war.` Moreover, due to the `exclusions` specified above, a request for the resource ` bar.jsp` would only be satisfied from `com.acme.Y.war.`
Similarly as `baz.jsp` is excluded, a request for it would result in a 404 error. Similarly as `baz.jsp` is excluded, a request for it would result in a 404 error.
@ -950,13 +938,13 @@ Then our webapp has available these additional resources:
==== Configuring Security Settings ==== Configuring Security Settings
You can configure LoginServices in the plugin. You can configure LoginServices in the plugin.
Here's an example of setting up the HashLoginService for a webapp: Here's an example of setting up the `HashLoginService` for a webapp:
[source,xml,subs="verbatim,attributes"] [source,xml,subs="verbatim,attributes"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty.ee10</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
<configuration> <configuration>
<scan>10</scan> <scan>10</scan>
@ -1009,8 +997,8 @@ Putting the configuration in webapp A's `pom.xml`:
[source,xml,subs="verbatim,attributes"] [source,xml,subs="verbatim,attributes"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty.ee10</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
<configuration> <configuration>
<scan>10</scan> <scan>10</scan>
@ -1018,11 +1006,11 @@ Putting the configuration in webapp A's `pom.xml`:
<contextPath>/test</contextPath> <contextPath>/test</contextPath>
</webApp> </webApp>
<contextHandlers> <contextHandlers>
<contextHandler implementation="org.eclipse.jetty.ee10.maven.plugin.MavenWebAppContext"> <contextHandler implementation="org.eclipse.jetty.{ee-current}.maven.plugin.MavenWebAppContext">
<war>${project.basedir}../../B.war</war> <war>${project.basedir}../../B.war</war>
<contextPath>/B</contextPath> <contextPath>/B</contextPath>
</contextHandler> </contextHandler>
<contextHandler implementation="org.eclipse.jetty.ee10.maven.plugin.MavenWebAppContext"> <contextHandler implementation="org.eclipse.jetty.{ee-current}.maven.plugin.MavenWebAppContext">
<war>${project.basedir}../../C.war</war> <war>${project.basedir}../../C.war</war>
<contextPath>/C</contextPath> <contextPath>/C</contextPath>
</contextHandler> </contextHandler>
@ -1033,8 +1021,8 @@ Putting the configuration in webapp A's `pom.xml`:
[IMPORTANT] [IMPORTANT]
==== ====
If the `ContextHandler` you are deploying is a webapp, it is *essential* that you use an `org.eclipse.jetty.ee10.maven.plugin.MavenWebAppContext` instance rather than a standard `org.eclipse.jetty.ee10.webapp.WebAppContext` instance. If the `ContextHandler` you are deploying is a webapp, it is *essential* that you use an `org.eclipse.jetty.{ee-current}.maven.plugin.MavenWebAppContext` instance rather than a standard `org.eclipse.jetty.{ee-current}.webapp.WebAppContext` instance.
Only the former will allow the webapp to function correctly in the maven environment. Only the former will allow the webapp to function correctly in the Maven environment.
==== ====
Alternatively, add a `jetty.xml` file to webapp A. Alternatively, add a `jetty.xml` file to webapp A.
@ -1045,7 +1033,7 @@ Copy the `jetty.xml` file from the Jetty distribution, and then add WebAppContex
<Ref refid="Contexts"> <Ref refid="Contexts">
<Call name="addHandler"> <Call name="addHandler">
<Arg> <Arg>
<New class="org.eclipse.jetty.ee10.maven.plugin.MavenWebAppContext"> <New class="org.eclipse.jetty.{ee-current}.maven.plugin.MavenWebAppContext">
<Set name="contextPath">/B</Set> <Set name="contextPath">/B</Set>
<Set name="war">../../B.war</Set> <Set name="war">../../B.war</Set>
</New> </New>
@ -1053,7 +1041,7 @@ Copy the `jetty.xml` file from the Jetty distribution, and then add WebAppContex
</Call> </Call>
<Call> <Call>
<Arg> <Arg>
<New class="org.eclipse.jetty.ee10.maven.plugin.MavenWebAppContext"> <New class="org.eclipse.jetty.{ee-current}.maven.plugin.MavenWebAppContext">
<Set name="contextPath">/C</Set> <Set name="contextPath">/C</Set>
<Set name="war">../../C.war</Set> <Set name="war">../../C.war</Set>
</New> </New>
@ -1062,13 +1050,13 @@ Copy the `jetty.xml` file from the Jetty distribution, and then add WebAppContex
</Ref> </Ref>
---- ----
Then configure the location of this `jetty.xml` file into webapp A's jetty plugin: Then configure the location of this `jetty.xml` file into webapp A's Jetty plugin:
[source,xml,subs="verbatim,attributes"] [source,xml,subs="verbatim,attributes"]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty.ee10</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-maven-plugin</artifactId>
<version>{version}</version> <version>{version}</version>
<configuration> <configuration>
<scan>10</scan> <scan>10</scan>
@ -1129,8 +1117,8 @@ Here's an example of how to specify System properties in the POM:
[source,xml] [source,xml]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty.ee10</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-maven-plugin</artifactId>
<configuration> <configuration>
<systemProperties> <systemProperties>
<fooprop>222</fooprop> <fooprop>222</fooprop>
@ -1159,8 +1147,8 @@ This can be configured on the plugin like so:
[source,xml] [source,xml]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty.ee10</groupId> <groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId> <artifactId>jetty-{ee-current}-maven-plugin</artifactId>
<configuration> <configuration>
<systemPropertiesFile>${project.basedir}/mysys.props</systemPropertiesFile> <systemPropertiesFile>${project.basedir}/mysys.props</systemPropertiesFile>
<webApp> <webApp>