Merge branch 'jetty-9.3.x' into jetty-9.4.x

This commit is contained in:
Jesse McConnell 2016-08-02 14:48:14 -05:00
commit 6108b9a234
5 changed files with 365 additions and 401 deletions

View File

@ -5,7 +5,7 @@
# <username>: <password>[,<rolename> ...]
#
# Passwords may be clear text, obfuscated or checksummed. The class
# org.eclipse.util.Password should be used to generate obfuscated
# org.eclipse.jetty.util.security.Password should be used to generate obfuscated
# passwords or password checksums
#
# If DIGEST Authentication is used, the password must be in a recoverable

View File

@ -17,7 +17,7 @@
[[jetty-jspc-maven-plugin]]
=== Jetty Jspc Maven Plugin
This plugin will help you pre-compile your jsps and works in conjunction with the maven war plugin to put them inside an assembled war.
This plugin will help you pre-compile your jsps and works in conjunction with the Maven war plugin to put them inside an assembled war.
[[jspc-config]]
==== Configuration
@ -26,7 +26,6 @@ Here's the basic setup required to put the jspc plugin into your build:
[source, xml, subs="{sub-order}"]
----
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-jspc-maven-plugin</artifactId>
@ -42,85 +41,82 @@ Here's the basic setup required to put the jspc plugin into your build:
</execution>
</executions>
</plugin>
----
The configurable parameters are as follows:
webXmlFragment::
Default value: $\{project.basedir}/target/webfrag.xml
+
File into which to generate the servlet declarations.
Will be merged with an existing web.xml.
Default value: `$\{project.basedir}/target/webfrag.xml`
+
File into which to generate the servlet declarations.
Will be merged with an existing `web.xml`.
webAppSourceDirectory::
Default value: $\{project.basedir}/src/main/webapp
+
Root of resources directory where jsps, tags etc are located.
Default value: `$\{project.basedir}/src/main/webapp`
+
Root of resources directory where jsps, tags etc are located.
webXml::
Default value: $\{project.basedir}/src/main/webapp/WEB-INF/web.xml
+
The web.xml file to use to merge with the generated fragments.
Default value: `$\{project.basedir}/src/main/webapp/WEB-INF/web.xml`
+
The web.xml file to use to merge with the generated fragments.
includes::
Default value: **\/*.jsp, **\/*.jspx
+
The comma separated list of patterns for file extensions to be processed.
Default value: `**\/*.jsp, **\/*.jspx`
+
The comma separated list of patterns for file extensions to be processed.
excludes::
Default value: **\/.svn\/**
+
The comma separated list of patterns for file extensions to be skipped.
Default value: `**\/.svn\/**`
+
The comma separated list of patterns for file extensions to be skipped.
classesDirectory::
Default value: $\{project.build.outputDirectory}
+
Location of classes for the webapp.
Default value: `$\{project.build.outputDirectory}`
+
Location of classes for the webapp.
generatedClasses::
Default value: $\{project.build.outputDirectory}
+
Location to put the generated classes for the jsps.
Default value: `$\{project.build.outputDirectory}`
+
Location to put the generated classes for the jsps.
insertionMarker::
Default value: _none_
+
A marker string in the src web.xml file which indicates where to merge in the generated web.xml fragment.
Note that the marker string will NOT be preserved during the insertion. Can be left blank, in which case the generated fragment is inserted just before the line containing </web-app>.
Default value: _none_
+
A marker string in the src `web.xml` file which indicates where to merge in the generated web.xml fragment.
Note that the marker string will NOT be preserved during the insertion.
Can be left blank, in which case the generated fragment is inserted just before the line containing `</web-app>`.
useProvidedScope::
Default value: false
+
If true, jars of dependencies marked with <scope>provided</scope> will
be placed on the compilation classpath.
Default value: false
+
If true, jars of dependencies marked with <scope>provided</scope> will be placed on the compilation classpath.
mergeFragment::
Default value: true
+
Whether or not to merge the generated fragment file with the source web.xml.
The merged file will go into the same directory as the webXmlFragment.
Default value: true
+
Whether or not to merge the generated fragment file with the source web.xml.
The merged file will go into the same directory as the webXmlFragment.
keepSources::
Default value: false
+
If true, the generated .java files are not deleted at the end of processing.
Default value: false
+
If true, the generated .java files are not deleted at the end of processing.
sourceVersion::
Since jetty-9.3.6.
Java version of jsp source files.
Defaults to 1.7.
Introduced in Jetty 9.3.6.
Java version of jsp source files.
Defaults to 1.7.
targetVersion::
Since jetty-9.3.6.
Java version of class files generated from jsps.
Defaults to 1.7.
Introduced in Jetty 9.3.6.
Java version of class files generated from jsps.
Defaults to 1.7.
tldJarNamePatterns::
Default value: .*taglibs[^/]*\.jar|.*jstl-impl[^/]*\.jar$
+
Patterns of jars on the 'system' (ie container) path that contain tlds.
Use | to separate each pattern.
Default value: `.*taglibs[^/]*\.jar|.*jstl-impl[^/]*\.jar$`
+
Patterns of jars on the 'system' (ie container) path that contain tlds.
Use | to separate each pattern.
jspc::
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 http://central.maven.org/maven2/org/glassfish/web/javax.servlet.jsp/2.3.2/javax.servlet.jsp-2.3.2-javadoc.jar[download] the javadoc from http://central.maven.org/maven2/org/glassfish/web/javax.servlet.jsp/2.3.2/javax.servlet.jsp-2.3.2-javadoc.jar[here].
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 http://central.maven.org/maven2/org/glassfish/web/javax.servlet.jsp/2.3.2/javax.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:
[source, xml, subs="{sub-order}"]
----
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
@ -128,8 +124,6 @@ Taking all the default settings, here's how to configure the war plugin to use t
<webXml>${project.basedir}/target/web.xml</webXml>
</configuration>
</plugin>
----
[[jspc-production-precompile]]
@ -141,7 +135,6 @@ For example, the following profile will only be invoked if the flag `-Dprod` is
[source, xml, subs="{sub-order}"]
----
<profiles>
<profile>
<id>prod</id>
@ -165,18 +158,13 @@ For example, the following profile will only be invoked if the flag `-Dprod` is
</build>
</profile>
</profiles>
----
So, the following invocation would cause your code to be compiled, the jsps to be compiled, the <servlet> and <servlet-mapping>s inserted in the web.xml and your webapp assembled into a war:
The following invocation would cause your code to be compiled, the jsps to be compiled, the <servlet> and <servlet-mapping>s inserted in the `web.xml` and your webapp assembled into a war:
[source, screen, subs="{sub-order}"]
....
$ mvn -Dprod package
....
[[jspc-overlay-precompile]]
@ -186,14 +174,13 @@ 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.
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 (ie 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 war up the lot.
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.
Here's an example configuration of the war plugin that separate those phases into an unpack phase, and then a packing phase:
[source, xml, subs="{sub-order}"]
----
<plugin>
<artifactId>maven-war-plugin</artifactId>
<executions>
@ -223,17 +210,14 @@ Here's an example configuration of the war plugin that separate those phases int
</execution>
</executions>
</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.
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.
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.
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="{sub-order}"]
----
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-jspc-maven-plugin</artifactId>
@ -252,6 +236,4 @@ Using the default settings, the web.xml merged with the jsp servlet definitions
</execution>
</executions>
</plugin>
----

View File

@ -23,6 +23,13 @@ Based on the concept of a project object model (POM), Maven can manage a project
It is an ideal tool to build a web application project, and such projects can use the link:#jetty-maven-plugin[jetty-maven-plugin] to easily run the web application and save time in development.
You can also use Maven to build, test and run a project which embeds Jetty.
____
[NOTE]
Use of Maven and the jetty-maven-plugin is *not* required.
Using Maven for Jetty implementations is a popular choice, but users encouraged to manage their projects in whatever way suits their needs.
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 link:#jetty-maven-plugin[jetty-maven-plugin] to speed up the development cycle.
[[configuring-embedded-jetty-with-maven]]
@ -30,7 +37,7 @@ First we'll have a look at a very simple HelloWorld java application that embeds
To understand the basic operations of building and running against Jetty, first review:
* link:#advanced-embedding[embedding with Jetty]
* link:#advanced-embedding[Embedding with Jetty]
* link:#jetty-helloworld[Jetty HelloWorld example]
Maven uses convention over configuration, so it is best to use the project structure Maven recommends.
@ -65,7 +72,7 @@ public class HelloWorld extends AbstractHandler
public void handle(String target,
Request baseRequest,
HttpServletRequest request,
HttpServletResponse response)
HttpServletResponse response)
throws IOException, ServletException
{
response.setContentType("text/html;charset=utf-8");
@ -78,23 +85,23 @@ public class HelloWorld extends AbstractHandler
{
Server server = new Server(8080);
server.setHandler(new HelloWorld());
server.start();
server.join();
}
}
}
----
[[creating-embedded-pom-descriptor]]
===== 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:
Use an editor to create the file `pom.xml` in the `JettyMavenHelloWorld` directory with the following contents:
[source, java, subs="{sub-order}"]
[source, xml, subs="{sub-order}"]
----
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
@ -108,7 +115,7 @@ Use an editor to create the file `pom.xml` with the following contents:
<!-- Adapt this to a version found on
http://central.maven.org/maven2/org/eclipse/jetty/jetty-maven-plugin/
-->
<jettyVersion>9.0.2.v20130417</jettyVersion>
<jettyVersion>9.3.9.v20160517</jettyVersion>
</properties>
<dependencies>
@ -134,7 +141,7 @@ Use an editor to create the file `pom.xml` with the following contents:
</plugin>
</plugins>
</build>
</project>
</project>
----
[[buildng-and-running-embedded-helloworld]]
@ -144,36 +151,37 @@ You can now compile and execute the HelloWorld class by using these commands:
[source, screen, subs="{sub-order}"]
....
> 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.
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:
[source, screen, subs="{sub-order}"]
....
> mvn dependency:tree
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'dependency'.
...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Jetty HelloWorld
[INFO] task-segment: [dependency:tree]
[INFO] Building Jetty HelloWorld 0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] [dependency:tree {execution: default-cli}]
[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.0.0:compile
[INFO] +- org.eclipse.jetty:javax.servlet:jar:3.0.0.v201112011016:compile
[INFO] +- org.eclipse.jetty:jetty-continuation:jar:9.0.0:compile
[INFO] \- org.eclipse.jetty:jetty-http:jar:9.0.0:compile
[INFO] \- org.eclipse.jetty:jetty-io:jar:9.0.0:compile
[INFO] \- org.eclipse.jetty:jetty-util:jar:9.0.0:compile
[INFO] \- org.eclipse.jetty:jetty-server:jar:9.3.9.v20160517:compile
[INFO] +- javax.servlet:javax.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 SUCCESSFUL
[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] ------------------------------------------------------------------------
[INFO] Total time: 4 seconds
[INFO] Finished at: Thu Jan 24 16:19:08 EST 2013
[INFO] Final Memory: 11M/68M
[INFO] ------------------------------------------------------------------------
....
[[developing-standard-webapp-with-jetty-and-maven]]
@ -218,12 +226,12 @@ public class HelloServlet extends HttpServlet
}
----
You need to declare this servlet in the deployment descriptor, so edit the file `src/main/webapp/WEB-INF/web.xml` and add the following contents:
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:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<web-app
<web-app
xmlns="http://xmlns.jcp.org/xml/ns/javaee"
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"
@ -246,12 +254,12 @@ You need to declare this servlet in the deployment descriptor, so edit the file
===== 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, noting particularly the declaration of the link:#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 link:#jetty-maven-plugin[jetty-maven-plugin]:
[source, java, subs="{sub-order}"]
[source, xml, subs="{sub-order}"]
----
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
@ -284,7 +292,7 @@ Use an editor to create the file `pom.xml` with the following contents, noting p
</plugins>
</build>
</project>
</project>
----
[[building-and-running-web-application]]
@ -309,7 +317,7 @@ You can create a Web Application Archive (WAR) file from the project with the co
[source, screen, subs="{sub-order}"]
....
> mvn package
> mvn package
....
The resulting war file is in the `target` directory and may be deployed on any standard servlet server, including link:#configuring-deployment[Jetty].

View File

@ -17,15 +17,15 @@
[[jetty-maven-scanning]]
=== Files Scanned by the Jetty Maven Plugin
If you set a non zero *scanInterval* link:#jetty-maven-plugin[configuration parameter], the jetty maven plugin will scan certain files every *scanInterval* seconds for changes, and redeploy the webapp if necessary.
If you set a non zero `scanInterval` link:#jetty-maven-plugin[configuration parameter], the `jetty-maven-plugin` will scan certain files every `scanInterval` seconds for changes, and redeploy the webapp if necessary.
The files that are scanned depend on the goal being executed.
[[scanner-matrix]]
==== Scanner Matrix
[width="100%",cols="<100%",options="header",]
[width="100%",cols="2",options="header"]
|=======================================================================
|Goal |Files
|Goal |Files
|link:#jetty-run-goal[jetty:run] |pom.xml, <dependencies>, <classesDirectory>, <testClassesDirectory>, <webXml> or <webAppSourceDirectory>/WEB-INF/web.xml, <jettyEnvXml> or <webAppSourceDirectory>/WEB-INF/jetty-web.xml, <webAppSourceDirectory>/WEB-INF/jetty-web.xml, <scanTargets>, <scanTargetPatterns>, any link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#setDefaultsDescriptor%28java.lang.String%29[defaultsDescriptor] for the webapp, any link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#setOverrideDescriptor%28java.lang.String%29[overrideDescriptor] for the webapp
|link:#running-assembled-webapp-as-war[jetty:run-war] |pom.xml, <war>
|link:#running-assembled-webapp-as-expanded-war[jetty:run-exploded]