Skip to content

Commit

Permalink
Merge pull request #10939 from jetty/jetty-12.0.x-10925-update-jetty-…
Browse files Browse the repository at this point in the history 
…maven-plugin-doc

Issue #10925 More updates to jetty maven plugin documentation.
  • Loading branch information
@joakime
joakime authored Nov 30, 2023
2 parents 9d00a7c + 03425a2 commit 80b1602
Show file tree
Hide file tree
Showing 3 changed files with 131 additions and 174 deletions.
40 changes: 19 additions & 21 deletions ...entation/src/main/asciidoc/programming-guide/maven/jetty-jspc-maven-plugin.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,18 +14,18 @@
[[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]]
==== 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 for the Jakarta EE {ee-current} environment:

[source,xml,subs="verbatim,attributes"]
----
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-jspc-maven-plugin</artifactId>
<groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-{ee-current}-jspc-maven-plugin</artifactId>
<version>{version}</version>
<executions>
<execution>
Expand Down Expand Up @@ -101,13 +101,13 @@ Default value: true
+
Determines if the manifest of JAR files found on the classpath should be scanned.
sourceVersion::
Introduced in Jetty 9.3.6.
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::
Introduced in Jetty 9.3.6.
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::
Default value: `+.*taglibs[^/]*\.jar|.*jstl[^/]*\.jar$+`
+
Expand All @@ -118,7 +118,6 @@ Default value: the `org.apache.jasper.JspC` instance being configured.
+
The JspC class actually performs the pre-compilation.
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:

Expand Down Expand Up @@ -151,8 +150,8 @@ For example, the following profile will only be invoked if the flag `-Dprod` is
<build>
<plugins>
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-jspc-maven-plugin</artifactId>
<groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-{ee-current}-jspc-maven-plugin</artifactId>
<version>{version}</version>
<!-- put your configuration in here -->
</plugin>
Expand All @@ -177,13 +176,12 @@ $ mvn -Dprod package
==== Precompiling Jsps with Overlaid Wars

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.
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).
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.
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 file will be unpacked, the jsps compiled and their servlet definitions merged into the extracted `web.xml`, and everything packed 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]
----
Expand All @@ -199,8 +197,8 @@ Here's an example configuration of the war plugin that separate those phases int
<overlays>
<overlay />
<overlay>
<groupId>org.eclipse.jetty.demos</groupId>
<artifactId>demo-jetty-webapp</artifactId>
<groupId>org.eclipse.jetty.{ee-current}.demos</groupId>
<artifactId>jetty-{ee-current}-demo-jetty-webapp</artifactId>
</overlay>
</overlays>
</configuration>
Expand All @@ -218,15 +216,15 @@ Here's an example configuration of the war plugin that separate those phases int
</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`.
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"]
----
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-jspc-maven-plugin</artifactId>
<groupId>org.eclipse.jetty.{ee-current}</groupId>
<artifactId>jetty-{ee-current}-jspc-maven-plugin</artifactId>
<version>{version}</version>
<executions>
<execution>
Expand Down
53 changes: 12 additions & 41 deletions ...mentation/src/main/asciidoc/programming-guide/maven/jetty-maven-helloworld.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,6 @@ Using Maven for Jetty implementations is a popular choice, but users encouraged
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]]
==== Using Embedded Jetty with Maven

Expand Down Expand Up @@ -146,40 +144,13 @@ You can now compile and execute the HelloWorld class by using these commands:
> mvn clean compile exec:java
----

You can 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] ------------------------------------------------------------------------
----
Point your browser to `+http://localhost:8080+` to see the _Hello World_ page.

[[developing-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.
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):

----
Expand Down Expand Up @@ -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]
----
<?xml version="1.0" encoding="UTF-8"?>
<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"
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"
version="3.1">
version="6.0">
<servlet>
<servlet-name>Hello</servlet-name>
Expand All @@ -244,7 +215,7 @@ You need to declare this servlet in the deployment descriptor, so create the fil
===== Creating the POM Descriptor

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"]
----
Expand All @@ -267,16 +238,16 @@ Use an editor to create the file `pom.xml` with the following contents in the `J
<dependency>
<groupId>jakarta.servlet</groupId>
<artifactId>jakarta.servlet-api</artifactId>
<version>3.1.0</version>
<version>6.0.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-maven-plugin</artifactId>
<groupId>org.eclipse.jetty.ee10</groupId>
<artifactId>jetty-ee10-maven-plugin</artifactId>
<version>${jettyVersion}</version>
</plugin>
</plugins>
Expand All @@ -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 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
Expand All @@ -302,7 +273,7 @@ The full reference is at xref:jetty-maven-plugin[Configuring the Jetty Maven Plu
[[building-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
Expand Down
Loading

0 comments on commit 80b1602

Please sign in to comment.