diff --git a/examples/embedded/src/test/resources/realm.properties b/examples/embedded/src/test/resources/realm.properties index 9d88b852b7f..556117fcdbc 100644 --- a/examples/embedded/src/test/resources/realm.properties +++ b/examples/embedded/src/test/resources/realm.properties @@ -5,7 +5,7 @@ # : [, ...] # # 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 diff --git a/jetty-documentation/src/main/asciidoc/development/maven/jetty-jspc-maven-plugin.adoc b/jetty-documentation/src/main/asciidoc/development/maven/jetty-jspc-maven-plugin.adoc index b5d6601e687..51f4b9c3075 100644 --- a/jetty-documentation/src/main/asciidoc/development/maven/jetty-jspc-maven-plugin.adoc +++ b/jetty-documentation/src/main/asciidoc/development/maven/jetty-jspc-maven-plugin.adoc @@ -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}"] ---- - org.eclipse.jetty jetty-jspc-maven-plugin @@ -42,85 +41,82 @@ Here's the basic setup required to put the jspc plugin into your build: - - ---- 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 . +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 ``. useProvidedScope:: - Default value: false - + - If true, jars of dependencies marked with provided will - be placed on the compilation classpath. +Default value: false ++ +If true, jars of dependencies marked with provided 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}"] ---- - org.apache.maven.plugins maven-war-plugin @@ -128,8 +124,6 @@ Taking all the default settings, here's how to configure the war plugin to use t ${project.basedir}/target/web.xml - - ---- [[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}"] ---- - prod @@ -165,18 +158,13 @@ For example, the following profile will only be invoked if the flag `-Dprod` is - - ---- -So, the following invocation would cause your code to be compiled, the jsps to be compiled, the and 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 and 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}"] ---- - maven-war-plugin @@ -223,17 +210,14 @@ Here's an example configuration of the war plugin that separate those phases int - - ---- -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}"] ---- - org.eclipse.jetty jetty-jspc-maven-plugin @@ -252,6 +236,4 @@ Using the default settings, the web.xml merged with the jsp servlet definitions - - ---- diff --git a/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-helloworld.adoc b/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-helloworld.adoc index 3066c373a56..85ae2a8a8a6 100644 --- a/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-helloworld.adoc +++ b/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-helloworld.adoc @@ -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}"] ---- - 4.0.0 @@ -108,7 +115,7 @@ Use an editor to create the file `pom.xml` with the following contents: - 9.0.2.v20130417 + 9.3.9.v20160517 @@ -134,7 +141,7 @@ Use an editor to create the file `pom.xml` with the following contents: - + ---- [[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}"] ---- - 4.0.0 @@ -284,7 +292,7 @@ Use an editor to create the file `pom.xml` with the following contents, noting p - + ---- [[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]. diff --git a/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-plugin.adoc b/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-plugin.adoc index 7417d306879..c0db940dcea 100644 --- a/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-plugin.adoc +++ b/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-plugin.adoc @@ -18,18 +18,18 @@ === Configuring the Jetty Maven Plugin The Jetty Maven plugin is useful for rapid development and testing. -You can add it to any webapp project that is structured according to the usual Maven defaults. +You can add it to any webapp project that is structured according to the Maven defaults. The plugin can then periodically scan your 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. ____ [IMPORTANT] -You should use Maven 3.3+ and Java 1.8 for this plugin. +You should use Maven 3.3+ for this plugin. ____ 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 api and maven itself it not a production deployment tool. -We recommend either the traditional distribution deployment approach or using embedded Jetty. +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 distribution deployment approach or using link:#advanced-embedding[embedded Jetty.] [[get-up-and-running]] ==== Quick Start: Get Up and Running @@ -38,14 +38,11 @@ First, add `jetty-maven-plugin` to your `pom.xml` definition: [source, xml, subs="{sub-order}"] ---- - org.eclipse.jetty jetty-maven-plugin {VERSION} - - ---- Then, from the same directory as your root `pom.xml`, type: @@ -57,23 +54,25 @@ mvn jetty:run This starts Jetty and serves up your project on http://localhost:8080/. -Jetty continues to run until you stop it. While it runs, it periodically scans for changes to your project files, so if you save changes and recompile your class files, Jetty redeploys your webapp, and you can instantly test the changes you just made. +Jetty will continue to run until you stop it. +While it runs it periodically scans for changes to your project files +If you save changes and recompile your class files, Jetty redeploys your webapp, and you can instantly test the changes that were just made. You can terminate the plugin with a `ctrl-c` in the terminal window where it is running. ____ [NOTE] -The classpath of the running Jetty and its deployed webapp are managed by Maven, and may not be exactly what you expect. -For example: webapp's dependant jars might be referenced via the local repository, not the `WEB-INF/lib` directory. +The classpath of the running Jetty instance and its deployed webapp are managed by Maven, and may not be exactly what you expect. +For example: a webapp's dependent jars might be referenced via the local repository, not the `WEB-INF/lib` directory. ____ [[running-and-deploying]] ==== Supported Goals The Jetty Maven plugin has a number of distinct Maven goals. -Arguably the most useful is the `run` goal that we saw in the Quick Start section which runs Jetty on your unassembled webapp. +Arguably the most useful is the `run` goal which runs Jetty on an unassembled webapp. There are other goals which help you accomplish different tasks. -For example, you might need to run your webapp in a forked instance of Jetty, rather than within the process running Maven; or you may need finer grained control over the maven lifecycle stage in which you wish to deploy your webapp. +For example, you might need to run your webapp in a forked instance of Jetty rather than within the process running Maven; or you may need finer grained control over the maven lifecycle stage in which you wish to deploy your webapp. There are different goals to accomplish these tasks, as well as several others. To see a list of all goals supported by the Jetty Maven plugin, do: @@ -87,7 +86,7 @@ To see the detailed list of parameters that can be configured for a particular g [source, screen, subs="{sub-order}"] .... -mvn jetty:help -Ddetail=true -Dgoal= goal-name +mvn jetty:help -Ddetail=true -Dgoal= .... [[configuring-jetty-container]] @@ -97,109 +96,109 @@ These configuration elements set up the Jetty environment in which your webapp e They are common to most goals: httpConnector:: - Optional. If not specified, Jetty will create a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[ServerConnector] instance listening on port 8080. - You can change this default port number by using the system property `jetty.http.port` on the command line, for example, `mvn -Djetty.http.port=9999 jetty:run`. - Alternatively, you can use this configuration element to set up the information for the ServerConnector. - The following are the valid configuration sub-elements: +Optional. +If not specified, Jetty will create a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[ServerConnector] instance listening on port 8080. +You can change this default port number by using the system property `jetty.http.port` on the command line, for example, `mvn -Djetty.http.port=9999 jetty:run`. +Alternatively, you can use this configuration element to set up the information for the ServerConnector. +The following are the valid configuration sub-elements: + - port;; - The port number for the connector to listen on. - By default it is 8080. - host;; - The particular interface for the connector to listen on. - By default, all interfaces. - name;; - The name of the connector, which is useful for link:#serving-webapp-from-particular-port[configuring contexts to respond only on particular connectors]. - idleTimeout;; - Maximum idle time for a connection. - soLinger;; - The socket linger time. +port;; +The port number for the connector to listen on. +By default it is 8080. +host;; +The particular interface for the connector to listen on. +By default, all interfaces. +name;; +The name of the connector, which is useful for link:#serving-webapp-from-particular-port[configuring contexts to respond only on particular connectors]. +idleTimeout;; +Maximum idle time for a connection. +soLinger;; +The socket linger time. + You could instead configure the connectors in a standard link:#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 link:#maven-config-https[https connector] directly in the pom.xml: you need to link:#maven-config-https[use jetty xml config files to do it]. jettyXml:: - Optional. - 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. +Optional. +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. scanIntervalSeconds:: - The pause in seconds between sweeps of the webapp to check for changes and automatically hot redeploy if any are detected. - *By default this is 0, which disables hot deployment scanning.* - A number greater than 0 enables it. +The pause in seconds between sweeps of the webapp to check for changes and automatically hot redeploy if any are detected. +*By default this is 0, which disables hot deployment scanning.* +A number greater than 0 enables it. reload:: - Default value is "automatic", used in conjunction with a non-zero *_`scanIntervalSeconds`_* causes automatic hot redeploy when changes are detected. - Set to "manual" instead to trigger scanning by typing a linefeed in the console running the plugin. - This might be useful when you are doing a series of changes that you want to ignore until you're done. - In that use, use the ` reload` parameter. +Default value is "automatic", used in conjunction with a non-zero *_`scanIntervalSeconds`_* causes automatic hot redeploy when changes are detected. +Set to "manual" instead to trigger scanning by typing a linefeed in the console running the plugin. +This might be useful when you are doing a series of changes that you want to ignore until you're done. +In that use, use the `reload` parameter. dumpOnStart:: - Optional. - Default value is false. - If true, then jetty will dump out the server structure on start. +Optional. +Default value is false. +If true, then jetty will dump out the server structure on start. loginServices:: - Optional. - A list of `org.eclipse.jetty.security.LoginService` implementations. Note that there is no default realm. - If you use a realm in your `web.xml` you can specify a corresponding realm here. - You could instead configure the login services in a jetty xml file and add its location to the `jettyXml` parameter. +Optional. +A list of `org.eclipse.jetty.security.LoginService` implementations. Note that there is no default realm. +If you use a realm in your `web.xml` you can specify a corresponding realm here. +You could instead configure the login services in a jetty xml file and add its location to the `jettyXml` parameter. requestLog:: - Optional. - 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: +Optional. +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: + * 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 the `webApp` element. + -`See Configuring Request Logs for more information.` +See link:#configuring-jetty-request-logs[Configuring Request Logs] for more information. server:: - Optional since jetty-9.3.1. - This would configure an instance of the link:{SRCDIR}/jetty-server/src/main/java/org/eclipse/jetty/server/Server.java[`org.eclipse.jetty.server.Server`] for the plugin to use, however it is usually NOT necessary to configure this, as the plugin will automatically configure one for you. - In particular, if you use the jettyXml element, then you generally DON'T want to define this element, as you are probably using the jettyXml file to configure up a Server with a special constructor argument, such as a custom threadpool. - If you define both a server element AND use a jettyXml element which points to a config file that - has a line like "" then the the xml configuration will override what you configure for the server in the pom. +Optional as of Jetty 9.3.1. +This would configure an instance of the link:{SRCDIR}/jetty-server/src/main/java/org/eclipse/jetty/server/Server.java[`org.eclipse.jetty.server.Server`] for the plugin to use, however it is usually NOT necessary to configure this, as the plugin will automatically configure one for you. +In particular, if you use the jettyXml element, then you generally DON'T want to define this element, as you are probably using the jettyXml file to configure up a Server with a special constructor argument, such as a custom threadpool. +If you define both a server element AND use a jetty xml element which points to a config file that has a line like `` then the the xml configuration will override what you configure for the server in the `pom.xml`. stopPort:: - Optional. - Port to listen on for stop commands. - Useful to use in conjunction with the link:#jetty-stop-goal[stop] or link:#jetty-run-forked-goal[run-forked] goals. +Optional. +Port to listen on for stop commands. +Useful to use in conjunction with the link:#jetty-stop-goal[stop] or link:#jetty-run-forked-goal[run-forked] goals. stopKey:: - Optional. - Used in conjunction with stopPort for stopping jetty. - Useful when used in conjunction with the stop or run-forked goals. +Optional. +Used in conjunction with stopPort for stopping jetty. +Useful when used in conjunction with the stop or run-forked goals. systemProperties:: - Optional. - Allows you to configure System properties for the execution of the plugin. - For more information, see link:#sys_props[Setting System Properties]. +Optional. +Allows you to configure System properties for the execution of the plugin. +For more information, see link:#sys_props[Setting System Properties]. systemPropertiesFile:: - Optional. - A file containing System properties to set for the execution of the plugin. - By default, settings that you make here *do not* override any system properties already set on the command line, by the JVM, or in the POM via `systemProperties`. - Read link:#sys_props[Setting System Properties] for how to force overrides. +Optional. +A file containing System properties to set for the execution of the plugin. +By default, settings that you make here *do not* override any system properties already set on the command line, by the JVM, or in the POM via `systemProperties`. +Read link:#sys_props[Setting System Properties] for how to force overrides. skip:: - Default is false. - If true, the execution of the plugin exits. - Same as setting the SystemProperty `-Djetty.skip` on the command line. - This is most useful when configuring Jetty for execution during integration testing and you want to skip the tests. +Default is false. +If true, the execution of the plugin exits. +Same as setting the SystemProperty `-Djetty.skip` on the command line. +This is most useful when configuring Jetty for execution during integration testing and you want to skip the tests. useProvidedScope:: - Default value is `false`. - If true, the dependencies with `provided` are placed onto the __container classpath__. - Be aware that this is NOT the webapp classpath, as "provided" indicates that these dependencies would normally be expected to be provided by the container. - You should very rarely ever need to use this. - Instead, you should copy the provided dependencies as explicit dependencies of the `plugin` instead. +Default value is `false`. +If true, the dependencies with `provided` are placed onto the __container classpath__. +Be aware that this is NOT the webapp classpath, as "provided" indicates that these dependencies would normally be expected to be provided by the container. +You should very rarely ever need to use this. +Instead, you should copy the provided dependencies as explicit dependencies of the `plugin` instead. excludedGoals:: - Optional. - A list of jetty plugin goal names that will cause the plugin to print an informative message and exit. - Useful if you want to prevent users from executing goals that you know cannot work with your project. +Optional. +A list of Jetty plugin goal names that will cause the plugin to print an informative message and exit. +Useful if you want to prevent users from executing goals that you know cannot work with your project. [[maven-config-https]] ===== Configuring a Https Connector -In order to configure a https connector, you need to use jetty xml configuration files. +In order to configure an HTTPS connector, you need to use jetty xml configuration files. This example uses files copied directly from the jetty distribution etc/ directory, although you can of course make up your own xml file or files. We will use the following files: jetty.xml:: - Sets up various characteristics of the link:{SRCDIR}/jetty-server/src/main/java/org/eclipse/jetty/server/Server.java[`org.eclipse.jetty.server.Server`] instance for the plugin to use. - Importantly, it sets up the link:{SRCDIR}/jetty-server/src/main/java/org/eclipse/jetty/server/HttpConfiguration.java[`org.eclipse.jetty.server.HttpConfiguration`] element that we can refer to in subsequent xml files that configure the connectors. - Here's the relevant section: +Sets up various characteristics of the link:{SRCDIR}/jetty-server/src/main/java/org/eclipse/jetty/server/Server.java[`org.eclipse.jetty.server.Server`] instance for the plugin to use. +Importantly, it sets up the link:{SRCDIR}/jetty-server/src/main/java/org/eclipse/jetty/server/HttpConfiguration.java[`org.eclipse.jetty.server.HttpConfiguration`] element that we can refer to in subsequent xml files that configure the connectors. +Here's the relevant section: + [source, xml, subs="{sub-order}"] ---- @@ -221,16 +220,15 @@ jetty.xml:: ---- jetty-ssl.xml:: - Set up ssl which will be used by the https connector. - Here's the `jetty-ssl.xml` file from the jetty-distribution: +Set up ssl which will be used by the https connector. +Here's the `jetty-ssl.xml` file from the jetty-distribution: + [source, xml, subs="{sub-order}"] ---- include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-ssl.xml[] ---- jetty-https.xml:: - Set up the https connector using the HttpConfiguration from - `jetty.xml` and the ssl configuration from` jetty-ssl.xml`: +Set up the https connector using the HttpConfiguration from `jetty.xml` and the ssl configuration from `jetty-ssl.xml`: + [source, xml, subs="{sub-order}"] ---- @@ -256,7 +254,7 @@ ____ Just like with an installed distribution of Jetty, the ordering of the xml files is significant. ____ -You can also use jetty xml files to configure a http connector for the plugin to use. +You can also use Jetty xml files to configure a http connector for the plugin to use. Here we use the same `jetty-http.xml` file from the Jetty distribution: [source, xml, subs="{sub-order}"] @@ -287,45 +285,45 @@ These configuration parameters apply to your webapp. They are common to almost all goals. webApp:: - This is an instance of link:{JDURL}/org/eclipse/jetty/maven/plugin/JettyWebAppContext.html[org.eclipse.jetty.maven.plugin.JettyWebAppContext], which is an extension to the class link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.hml[`org.eclipse.jetty.webapp.WebAppContext`]. - You can use any of the setter methods on this object to configure your webapp. - Here are a few of the most useful ones: +This is an instance of link:{JDURL}/org/eclipse/jetty/maven/plugin/JettyWebAppContext.html[org.eclipse.jetty.maven.plugin.JettyWebAppContext], which is an extension to the class link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.hml[`org.eclipse.jetty.webapp.WebAppContext`]. +You can use any of the setter methods on this object to configure your webapp. +Here are a few of the most useful ones: + - contextPath;; - The context path for your webapp. By default, this is set to `/`. - If using a custom value for this parameter, you probably want to include the leading `/`, example `/mycontext`. - descriptor;; - The path to the `web.xml` file for your webapp. - defaultsDescriptor;; - 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`. - overrideDescriptor;; - The path to a `web.xml` file that Jetty applies after reading your `web.xml`. - You can use this to replace or add configuration. - tempDirectory;; - The path to a dir that Jetty can use to expand or copy jars and jsp compiles when your webapp is running. - The default is `${project.build.outputDirectory}/tmp`. - baseResource;; - he path from which Jetty serves static resources. - Defaults to ` src/main/webapp`. - resourceBases;; - Use instead of `baseResource` if you have multiple dirs from which you want to serve static content. - This is an array of dir names. - baseAppFirst;; - Defaults to "true". - Controls whether any overlaid wars are added before or after the original base resource(s) of the webapp. - See the section on link:#using-overlaid-wars[overlaid wars] for more information. - containerIncludeJarPattern;; - Defaults to ".*/javax.servlet-[^/]*\.jar$|.*/servlet-api-[^/]*\.jar$|.*javax.servlet.jsp.jstl-[^/]*\.jar|.*taglibs-standard-impl-.*\.jar". - This is a pattern that is applied to the names of the jars on the container's classpath (ie the classpath of the plugin, not that of the webapp) that should be scanned for fragments, tlds, annotations etc. - This is analogous to the context attribute link:#container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented link:#container-include-jar-pattern[here]. - You can define extra patterns of jars that will be included in the scan. - webInfIncludeJarPattern;; - Defaults to matching _all_ of the dependency jars for the webapp (ie the equivalent of WEB-INF/lib). - You can make this pattern more restrictive to only match certain jars by using this setter. - This is analogous to the context attribute link:#web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented link:#web-inf-include-jar-pattern[here]. +contextPath;; +The context path for your webapp. By default, this is set to `/`. +If using a custom value for this parameter, you probably want to include the leading `/`, example `/mycontext`. +descriptor;; +The path to the `web.xml` file for your webapp. +defaultsDescriptor;; +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`. +overrideDescriptor;; +The path to a `web.xml` file that Jetty applies after reading your `web.xml`. +You can use this to replace or add configuration. +tempDirectory;; +The path to a dir that Jetty can use to expand or copy jars and jsp compiles when your webapp is running. +The default is `${project.build.outputDirectory}/tmp`. +baseResource;; +The path from which Jetty serves static resources. +Defaults to `src/main/webapp`. +resourceBases;; +Use instead of `baseResource` if you have multiple directories from which you want to serve static content. +This is an array of directory names. +baseAppFirst;; +Defaults to "true". +Controls whether any overlaid wars are added before or after the original base resource(s) of the webapp. +See the section on link:#using-overlaid-wars[overlaid wars] for more information. +containerIncludeJarPattern;; +Defaults to `.*/javax.servlet-[^/]*\.jar$|.*/servlet-api-[^/]*\.jar$|.*javax.servlet.jsp.jstl-[^/]*\.jar|.*taglibs-standard-impl-.*\.jar`. +This is a pattern that is applied to the names of the jars on the container's classpath (ie the classpath of the plugin, not that of the webapp) that should be scanned for fragments, tlds, annotations etc. +This is analogous to the context attribute link:#container-include-jar-pattern[org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern] that is documented link:#container-include-jar-pattern[here]. +You can define extra patterns of jars that will be included in the scan. +webInfIncludeJarPattern;; +Defaults to matching _all_ of the dependency jars for the webapp (ie the equivalent of WEB-INF/lib). +You can make this pattern more restrictive to only match certain jars by using this setter. +This is analogous to the context attribute link:#web-inf-include-jar-pattern[org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern] that is documented link:#web-inf-include-jar-pattern[here]. contextXml:: - The path to a context xml file that is applied to your webapp AFTER the `webApp` element. +The path to a context xml file that is applied to your webapp AFTER the `webApp` element. [[jetty-run-goal]] ==== jetty:run @@ -339,17 +337,17 @@ For example, by default it looks for: * classes in `${project.build.outputDirectory}` * `web.xml` in `${project.basedir}/src/main/webapp/WEB-INF/` -The plugin automatically ensures the classes are rebuilt 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. +The plugin automatically ensures the classes are rebuilt 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. You do not need to assemble the webapp into a WAR, saving time during the development cycle. 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. -Here is a small 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="{sub-order}"] ---- - org.eclipse.jetty jetty-maven-plugin @@ -361,58 +359,55 @@ Here is a small example, which turns on scanning for changes every ten seconds, - - ---- [[configuring-additional-parameters]] ===== Configuration -In addition to the *`webApp`* element that is common to most goals, the `jetty:run` goal supports: +In addition to the `webApp` element that is common to most goals, the `jetty:run` goal supports: classesDirectory:: - Location of your compiled classes for the webapp. - You should rarely need to set this parameter. - Instead, you should set `build outputDirectory` in your `pom.xml`. +Location of your compiled classes for the webapp. +You should rarely need to set this parameter. +Instead, you should set `build outputDirectory` in your `pom.xml`. testClassesDirectory:: - Location of the compiled test classes for your webapp. By default this is `${project.build.testOutputDirectory}`. +Location of the compiled test classes for your webapp. By default this is `${project.build.testOutputDirectory}`. useTestScope:: - If true, the classes from `testClassesDirectory` and dependencies of scope "test" are placed first on the classpath. - By default this is false. +If true, the classes from `testClassesDirectory` and dependencies of scope "test" are placed first on the classpath. +By default this is false. webAppSourceDirectory:: - By default, this is set to `${project.basedir}/src/main/webapp`. - If your static sources are in a different location, set this parameter accordingly. +By default, this is set to `${project.basedir}/src/main/webapp`. +If your static sources are in a different location, set this parameter accordingly. jettyEnvXml:: - Optional. - Location of a `jetty-env.xml` file, which allows you to make JNDI bindings that satisfy `env-entry`, `resource-env-ref`, and `resource-ref` linkages in the `web.xml` that are scoped only to the webapp and not shared with other webapps that you might be deploying at the same time (for example, by using a ` jettyConfig` file). +Optional. +Location of a `jetty-env.xml` file, which allows you to make JNDI bindings that satisfy `env-entry`, `resource-env-ref`, and `resource-ref` linkages in the `web.xml` that are scoped only to the webapp and not shared with other webapps that you might be deploying at the same time (for example, by using a ` jettyConfig` file). scanTargets:: - Optional. - A list of files and directories to periodically scan in addition to those the plugin automatically scans. +Optional. +A list of files and directories to periodically scan in addition to those the plugin automatically scans. scanTargetPatterns:: - Optional. - If you have a long list of extra files you want scanned, it is more convenient to use pattern matching expressions to specify them instead of enumerating them with the `scanTargetsList` of `scanTargetPatterns`, each consisting of a directory, and including and/or excluding parameters to specify the file matching patterns. +Optional. +If you have a long list of extra files you want scanned, it is more convenient to use pattern matching expressions to specify them instead of enumerating them with the `scanTargetsList` of `scanTargetPatterns`, each consisting of a directory, and including and/or excluding parameters to specify the file matching patterns. scanClassesPattern:: - Since 9.3.0. - Optional. - Include and exclude patterns that can be applied to the classesDirectory for the purposes of scanning, it does *not* affect the classpath. - If a file or directory is excluded by the patterns then a change in that file (or subtree in the case of a directory) is ignored and will not cause the webapp to redeploy. - Patterns are specified as a relative path using a glob-like syntax as described in the http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-[javadoc] for http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-[FileSystem.getPathMatcher]. +Since 9.3.0. +Optional. +Include and exclude patterns that can be applied to the classesDirectory for the purposes of scanning, it does *not* affect the classpath. +If a file or directory is excluded by the patterns then a change in that file (or subtree in the case of a directory) is ignored and will not cause the webapp to redeploy. +Patterns are specified as a relative path using a glob-like syntax as described in the http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-[javadoc] for http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-[FileSystem.getPathMatcher]. scanTestClassesPattern:: - Since 9.3.0. - Optional. - Include and exclude patterns that can be applied to the testClassesDirectory for the purposes of scanning, it does *not* affect the classpath. - If a file or directory is excluded by the patterns then a change in that file (or subtree in the case of a directory) is ignored and will not cause the webapp to redeploy. - Patterns are specified as a relative path using a glob-like syntax as described in the http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-[javadoc] for http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-[FileSystem.getPathMatcher]. +Since 9.3.0. +Optional. +Include and exclude patterns that can be applied to the testClassesDirectory for the purposes of scanning, it does *not* affect the classpath. +If a file or directory is excluded by the patterns then a change in that file (or subtree in the case of a directory) is ignored and will not cause the webapp to redeploy. +Patterns are specified as a relative path using a glob-like syntax as described in the http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-[javadoc] for http://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-[FileSystem.getPathMatcher]. Here's an example: [source, xml, subs="{sub-order}"] ---- - -... +... -... +... org.eclipse.jetty jetty-maven-plugin @@ -451,32 +446,29 @@ Here's an example: - - ---- -If, for whatever reason, you cannot run on an unassembled webapp, the goals `run-war` and ` run-exploded` work on unassembled webapps. +If, for whatever reason, you cannot run on an unassembled webapp, the goals `run-war` and `run-exploded` work on unassembled webapps. [[running-assembled-webapp-as-war]] ==== jetty:run-war This goal first packages your webapp as a WAR file and then deploys it to Jetty. -If you set a non-zero ` scanInterval`, Jetty watches your `pom.xml` and the WAR file; if either changes, it redeploys the war. +If you set a non-zero `scanInterval`, Jetty watches your `pom.xml` and the WAR file; if either changes, it redeploys the war. [[configuring-war]] ===== Configuration war:: - The location of the built WAR file. This defaults to `${project.build.directory}/${project.build.finalName}.war`. - If this is not sufficient, set it to your custom location. +The location of the built WAR file. This defaults to `${project.build.directory}/${project.build.finalName}.war`. +If this is not sufficient, set it to your custom location. Here's how to set it: [source, xml, subs="{sub-order}"] ---- - -... +... ... @@ -489,31 +481,29 @@ Here's how to set it: - - ---- [[running-assembled-webapp-as-expanded-war]] ==== jetty:run-exploded The run-exploded goal first assembles your webapp into an exploded WAR file and then deploys it to Jetty. -If you set a non-zero `scanInterval`, Jetty watches your `pom.xml, WEB-INF/lib, WEB-INF/` classes and `WEB-INF/web.xml` for changes and redeploys when necessary. +If you set a non-zero `scanInterval`, Jetty watches your `pom.xml,`WEB-INF/lib`, `WEB-INF/` and `WEB-INF/web.xml` for changes and redeploys when necessary. [[configuring-exploded-war]] ===== Configuration war:: - The location of the exploded WAR. This defaults to `${project.build.directory}/${project.build.finalName}`, but you can override the default by setting this parameter. +The location of the exploded WAR. +This defaults to `${project.build.directory}/${project.build.finalName}`, but you can override the default by setting this parameter. Here's how to set it: [source, xml, subs="{sub-order}"] ---- - - -... + +... -... +... org.eclipse.jetty maven-jetty-plugin @@ -524,8 +514,6 @@ Here's how to set it: - - ---- [[deploy-war-running-pre-assembled-war]] @@ -537,11 +525,11 @@ Unlike `run-war`, the phase in which this plugin executes is not bound to the "p ===== Configuration war:: - The location of the WAR file. This defaults to `${project.build.directory}/${project.build.finalName}`, but you can override the default by setting this parameter. +The location of the WAR file. This defaults to `${project.build.directory}/${project.build.finalName}`, but you can override the default by setting this parameter. daemon:: - If true, this plugin will start jetty but let the build continue. - This is useful if you want to start jetty as an execution binding in a particular phase and then stop it in another. - Alternatively, you can set this parameter to false, in which case jetty will block and you will need to use a ctrl-c to stop it. +If true, this plugin will start Jetty but let the build continue. +This is useful if you want to start jetty as an execution binding in a particular phase and then stop it in another. +Alternatively, you can set this parameter to false, in which case Jetty will block and you will need to use a ctrl-c to stop it. Here's the configuration: @@ -549,9 +537,9 @@ Here's the configuration: ---- -... +... -... +... org.eclipse.jetty jetty-maven-plugin @@ -580,8 +568,8 @@ Here's the configuration: - - + + ---- [[jetty-run-forked-goal]] @@ -595,39 +583,39 @@ This goal supports the same configuration parameters as the `jetty:run` goal wit The available configuration parameters - in addition to those for the `jetty:run` goal - are: jvmArgs:: - Optional. - A string representing arbitrary arguments to pass to the forked JVM. +Optional. +A string representing arbitrary arguments to pass to the forked JVM. waitForChild:: - Default is `true`. - This causes the parent process to wait for the forked process to exit. - In this case you can use `ctrl-c` to terminate both processes. - It is more useful to set it to `false`, in which case the parent process terminates whilst leaving the child process running. - You use the `jetty:stop` goal to stop the child process. +Default is `true`. +This causes the parent process to wait for the forked process to exit. +In this case you can use `ctrl-c` to terminate both processes. +It is more useful to set it to `false`, in which case the parent process terminates whilst leaving the child process running. +You use the `jetty:stop` goal to stop the child process. maxStartupLines:: - Default is `50`. - This is maximum number of lines the parent process reads from the child process to receive an indication that the child has started. - If the child process produces an excessive amount of output on stdout you may need to increase this number. +Default is `50`. +This is maximum number of lines the parent process reads from the child process to receive an indication that the child has started. +If the child process produces an excessive amount of output on stdout you may need to increase this number. Some of the container configuration parameters are *NOT* available with this goal: scanIntervalSeconds:: - Not supported. - The forked jetty will not monitor and redeploy the webapp. +Not supported. +The forked jetty will not monitor and redeploy the webapp. reload:: - Not supported. - The forked jetty will not redeploy the webapp. +Not supported. +The forked jetty will not redeploy the webapp. httpConnector:: - Not supported. - To define custom connectors use a jetty xml file instead. +Not supported. +To define custom connectors use a jetty xml file instead. loginServices:: - Not supported. - To define LoginServices use a jetty xml or context xml file instead. +Not supported. +To define LoginServices use a jetty xml or context xml file instead. requestLog:: - Not supported. - To define a RequestLog setup, use a jetty xml or context xml file instead. +Not supported. +To define a RequestLog setup, use a jetty xml or context xml file instead. systemProperties:: - Not supported. - Use the `jvmArgs` parameter to pass system properties to the forked process. +Not supported. +Use the `jvmArgs` parameter to pass system properties to the forked process. To deploy your unassembled web app to Jetty running in a new JVM: @@ -639,11 +627,11 @@ mvn jetty:run-forked Jetty continues to execute until you either: * Press `ctrl-c` in the terminal window to stop the plugin, which also stops the forked JVM (only if you started with `waitForChild=true`) -* Use jetty:stop to stop the forked JVM, which also stops the plugin. +* Use `jetty:stop` to stop the forked JVM, which also stops the plugin. ____ [NOTE] -If you want to set a custom port for the jetty connector you need to specify it in a `jetty xml` file rather than setting the connector and port tags. +If you want to set a custom port for the Jetty connector you need to specify it in a `jetty xml` file rather than setting the connector and port tags. You can specify the location of the `jetty.xml` using the `jettyXml` parameter. ____ @@ -651,7 +639,7 @@ ____ ==== jetty:start This goal is for use with an execution binding in your `pom.xml`. -It is similar to the `jetty:run` goal, however it 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 is similar to the `jetty:run` goal, however it 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 most useful when you want to control the start and stop of Jetty via execution bindings in your `pom.xml`. For example, you can configure the plugin to start your webapp at the beginning of your unit tests and stop at the end. @@ -660,7 +648,6 @@ You use the `pre-integration-test` and `post-integration-test` Maven build phase [source, xml, subs="{sub-order}"] ---- - org.eclipse.jetty jetty-maven-plugin @@ -690,24 +677,22 @@ You use the `pre-integration-test` and `post-integration-test` Maven build phase - - ---- [[jetty-stop-goal]] ==== jetty:stop -The stop goal stops a running instance of jetty. +The stop goal stops a running instance of Jetty. 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. stopPort:: - A port number for jetty to listen on to receive a stop command to cause it to shutdown. +A port number for Jetty to listen on to receive a stop command to cause it to shutdown. stopKey:: - A string value sent to the `stopPort` to validate the stop command. +A string value sent to the `stopPort` to validate the stop command. stopWait:: - The maximum time in seconds that the plugin will wait for confirmation that jetty has stopped. - If false or not specified, the plugin does not wait for confirmation but exits after issuing the stop command. +The maximum time in seconds that the plugin will wait for confirmation that Jetty has stopped. +If false or not specified, the plugin does not wait for confirmation but exits after issuing the stop command. Here's a configuration example: @@ -724,8 +709,8 @@ Here's a configuration example: 10 - - + + ---- Then, while Jetty is running (in another window), type: @@ -736,22 +721,22 @@ mvn jetty:stop .... The `stopPort` must be free on the machine you are running on. -If this is not the case, you get an "Address already in use" error message after the "Started ServerConnector ..." message. +If this is not the case, you will get an "Address already in use" error message after the "Started ServerConnector ..." message. ==== jetty:effective-web-xml -This goal calculates a synthetic web.xml (the "effective web.xml") according to the rules of the Servlet Specification taking into account all sources of discoverable configuration of web components in your application: descriptors (webdefault.xml, web.xml, web-fragment.xmls, web-override.xml) and discovered annotations (@WebServlet, @WebFilter, @WebListener). -The effective web.xml from these combined sources is generated and displayed as maven log output. +This goal calculates a synthetic `web.xml` (the "effective web.xml") according to the rules of the Servlet Specification taking into account all sources of discoverable configuration of web components in your application: descriptors (`webdefault.xml`, `web.xml`, `web-fragment.xml`s, `web-override.xml`) and discovered annotations (`@WebServlet`, `@WebFilter`, `@WebListener`). +The effective `web.xml` from these combined sources is generated and displayed as maven log output. 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 link:#quickstart-webapp[Quickstart] feature to quickly start your webapp (note that Quickstart is not appropriate for the mvn jetty goals). The following configuration parameters allow you to save the file: deleteOnExit:: - By default this is `true`. - If set to `false`, the effective web.xml is generated into a file called `effective-web.xml` in the build `target` directory. +By default this is `true`. +If set to `false`, the effective web.xml is generated into a file called `effective-web.xml` in the build `target` directory. effectiveWebXml:: - The full path name of a file into which you would like the effective web xml generated. +The full path name of a file into which you would like the effective web xml generated. Note that no programmatic declarations of servlets, filters and listeners will be taken into account. @@ -764,14 +749,13 @@ It can do so based on the settings of the http://maven.apache.org/plugins/maven- ===== With maven-war-plugin The maven-war-plugin has a rich set of capabilities for merging resources. -The jetty:run and jetty:run-forked goals are able to interpret most of them and apply them during execution of your unassembled webapp. +The `jetty:run` and `jetty:run-forked` 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. Suppose your webapp depends on the following wars: [source, xml, subs="{sub-order}"] ---- - com.acme X @@ -782,29 +766,24 @@ Suppose your webapp depends on the following wars: Y war - - ---- -`Containing:` +Containing: [source,text] ---- +WebAppX: -WebAppX: + /foo.jsp + /bar.jsp + /WEB-INF/web.xml - /foo.jsp - /bar.jsp - /WEB-INF/web.xml - -WebAppY: +WebAppY: /bar.jsp /baz.jsp /WEB-INF/web.xml /WEB-INF/special.xml - - ---- They are configured for the http://maven.apache.org/plugins/maven-war-plugin/overlays.html[maven-war-plugin]: @@ -870,31 +849,31 @@ Suppose the webapps contain: [source,text] ---- -WebAppX: +WebAppX: - /foo.jsp - /bar.jsp - /WEB-INF/web.xml + /foo.jsp + /bar.jsp + /WEB-INF/web.xml -WebAppY: +WebAppY: - /bar.jsp + /bar.jsp /baz.jsp - /WEB-INF/web.xml + /WEB-INF/web.xml /WEB-INF/special.xml - + ---- Then our webapp has available these additional resources: [source,text] ---- -/foo.jsp (X) -/bar.jsp (X) -/baz.jsp (Y) +/foo.jsp (X) +/bar.jsp (X) +/baz.jsp (Y) /WEB-INF/web.xml (X) /WEB-INF/special.xml (Y) - + ---- [[configuring-security-settings]] @@ -922,15 +901,17 @@ Here's an example of setting up the HashLoginService for a webapp: - + ---- [[using-multiple-webapp-root-directories]] ==== Using Multiple Webapp Root Directories -If you have external resources that you want to incorporate in the execution of a webapp, but which are not assembled into WARs, you can't use the overlaid wars method described above, but you can tell Jetty the directories in which these external resources are located. +If you have external resources that you want to incorporate in the execution of a webapp, but which are not assembled into war files, you can't use the overlaid wars method described above, but you can tell Jetty the directories in which these external resources are located. At runtime, when Jetty receives a request for a resource, it searches all the locations to retrieve the resource. -It's a lot like the overlaid war situation, but without the war. Here's a configuration example: +It's a lot like the overlaid war situation, but without the war. + +Here is a configuration example: [source, xml, subs="{sub-order}"] ---- @@ -941,8 +922,7 @@ It's a lot like the overlaid war situation, but without the war. Here's a config src/main/webapp,/home/johndoe/path/to/my/other/source,/yet/another/folder - - + ---- [[running-more-than-one-webapp]] @@ -976,17 +956,16 @@ Putting the configuration in webapp A's `pom.xml`: - ---- ____ [IMPORTANT] -If the ContextHandler you are deploying is a webapp, it is *essential* that you use an `org.eclipse.jetty.maven.plugin.JettyWebAppContext` instance rather than a standard `org.eclipse.jetty.webapp.WebAppContext` instance. +If the `ContextHandler` you are deploying is a webapp, it is *essential* that you use an `org.eclipse.jetty.maven.plugin.JettyWebAppContext` instance rather than a standard `org.eclipse.jetty.webapp.WebAppContext` instance. Only the former will allow the webapp to function correctly in the maven environment. ____ Alternatively, add a `jetty.xml` file to webapp A. -Copy the `jetty.xml` file from the jetty distribution, and then add WebAppContexts for the other 2 webapps: +Copy the `jetty.xml` file from the Jetty distribution, and then add WebAppContexts for the other 2 webapps: [source, xml, subs="{sub-order}"] ---- @@ -999,7 +978,7 @@ Copy the `jetty.xml` file from the jetty distribution, and then add WebAppContex - + /C @@ -1007,8 +986,7 @@ Copy the `jetty.xml` file from the jetty distribution, and then add WebAppContex - - + ---- Then configure the location of this `jetty.xml` file into webapp A's jetty plugin: @@ -1026,8 +1004,8 @@ Then configure the location of this `jetty.xml` file into webapp A's jetty plugi src/main/etc/jetty.xml - - + + ---- For either of these solutions, the other webapps must already have been built, and they are not automatically monitored for changes. @@ -1036,15 +1014,14 @@ You can refer either to the packed WAR file of the pre-built webapps or to their [[setting-system-properties]] ==== Setting System Properties -You can specify property name/value pairs that Jetty sets as System properties for the execution of the plugin. This feature is useful to tidy up the command line and save a lot of typing. +You can specify property name/value pairs that Jetty sets as System properties for the execution of the plugin. +This feature is useful to tidy up the command line and save a lot of typing. -However, *sometimes it is not possible to use this feature to set System properties* - sometimes the software component using the System property is already initialized by the time that maven runs (in which case you will need to provide the System property on the command line), or by the -time that jetty runs. -In the latter case, you can use the http://mojo.codehaus.org/properties-maven-plugin/[maven properties plugin] to define the system properties instead. Here's an example that configures the logback logging system as the jetty logger: +However, *sometimes it is not possible to use this feature to set System properties* - sometimes the software component using the System property is already initialized by the time that maven runs (in which case you will need to provide the System property on the command line), or by the time that Jetty runs. +In the latter case, you can use the link:http://www.mojohaus.org/[maven properties plugin] to define the system properties instead. Here's an example that configures the logback logging system as the Jetty logger: [source, xml, subs="{sub-order}"] ---- - org.codehaus.mojo properties-maven-plugin @@ -1065,11 +1042,12 @@ In the latter case, you can use the http://mojo.codehaus.org/properties-maven-pl - - ---- -Note that if a System property is already set (for example, from the command line or by the JVM itself), then by default these configured properties DO NOT override them (see below for use of the parameter). +____ +[NOTE] +If a System property is already set (for example, from the command line or by the JVM itself), then by default these configured properties *DO NOT* override them (see below for use of the parameter). +____ [[specifying-properties-in-pom]] ===== Specifying System Properties in the POM @@ -1078,10 +1056,10 @@ Here's an example of how to specify System properties in the POM: [source, xml, subs="{sub-order}"] ---- - + org.eclipse.jetty jetty-maven-plugin - + fooprop @@ -1091,16 +1069,16 @@ Here's an example of how to specify System properties in the POM: /test - + - + ---- -To change the default behaviour so that these system properties override those on the command line, use the <`force>` parameter: +To change the default behavior so that these system properties override those on the command line, use the `` parameter: [source, xml, subs="{sub-order}"] ---- - + org.eclipse.jetty jetty-maven-plugin @@ -1116,21 +1094,19 @@ To change the default behaviour so that these system properties override those o - ---- [[specifying-properties-in-file]] ===== Specifying System Properties in a File You can also specify your System properties in a file. -System properties you specify in this way DO NOT override System properties that set on the command line, by the JVM, or directly in the POM via` systemProperties`. +System properties you specify in this way *do not* override System properties that set on the command line, by the JVM, or directly in the POM via `systemProperties`. Suppose we have a file called `mysys.props` which contains the following: [source,text] ---- fooprop=222 - ---- This can be configured on the plugin like so: @@ -1147,8 +1123,6 @@ This can be configured on the plugin like so: - ---- You can instead specify the file by setting the System property `jetty.systemPropertiesFile` on the command line. - diff --git a/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-scanning.adoc b/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-scanning.adoc index 02a0f0ea06a..b7d75ca0d1e 100644 --- a/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-scanning.adoc +++ b/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-scanning.adoc @@ -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, , , , or /WEB-INF/web.xml, or /WEB-INF/jetty-web.xml, /WEB-INF/jetty-web.xml, , , 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, |link:#running-assembled-webapp-as-expanded-war[jetty:run-exploded]