From 7a5768a055527d3a55656bc5b320c93a42f5fe45 Mon Sep 17 00:00:00 2001 From: Jan Bartel Date: Tue, 29 Sep 2020 19:11:43 +0200 Subject: [PATCH 1/5] Update to quickstart docs WIP Signed-off-by: Jan Bartel --- .../operations-guide/quickstart/chapter.adoc | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc new file mode 100644 index 00000000000..10864996d84 --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc @@ -0,0 +1,65 @@ +// +// ======================================================================== +// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others. +// +// This program and the accompanying materials are made available under +// the terms of the Eclipse Public License 2.0 which is available at +// https://www.eclipse.org/legal/epl-2.0 +// +// This Source Code may also be made available under the following +// Secondary Licenses when the conditions for such availability set +// forth in the Eclipse Public License, v. 2.0 are satisfied: +// the Apache License v2.0 which is available at +// https://www.apache.org/licenses/LICENSE-2.0 +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// ======================================================================== +// + +[[og-quickstart]] +=== Quickstart + + +The auto discovery features of the Servlet Specification can make deployments slow and uncertain. +Auto discovery of web application configuration can be useful during the development as it allows new features and frameworks to be enabled simply by dropping in a jar file. +However, for deployment, the need to scan the contents of many jars can have a significant impact at startup time. + +The `quickstart` module allows a webapp to be pre-scanned, making startup predictable and faster. +During scanning all declarative configuration (ie from web.xml, web-fragment.xml and annotations) are encoded into an effective `web.xml`, called `WEB-INF/quickstart-web.xml`, which can be inspected to understand what will be deployed. +NOTE:: Programmatic configuration is _not_ encoded into the generated `quickstart-web.xml` file. + +With `quickstart`, webapps that took many seconds to scan and deploy can now be deployed in a few hundred milliseconds. + +==== Enabling Quickstart + +Enable the `quickstart` module for your jetty base: + +[source, screen, subs="{sub-order}"] +.... +$ cd $JETTY-BASE +$ java -jar $JETTY_HOME/start.jar --add-module=quickstart +.... + +The `$JETTY-BASE/start.d/quickstart.ini` file contains these configurable parameters: + +jetty.quickstart.mode:: + The values are: + + AUTO::: + Allows jetty to run either with or without a `quickstart-web.xml` file. + If jetty detects the file, then it will be used, otherwise the app is started normally. + GENERATE::: + In this mode, jetty will generate a `quickstart-web.xml` file and then terminate. + QUICKSTART::: + In this mode, if jetty does not detect a `quickstart-web.xml` file then jetty will not start. + +jetty.quickstart.origin:: +Use this parameter to set the name of the attribute in the `quickstart-web.xml` file that contains the origin of each element. + +jetty.quickstart.xml:: +Use this parameter to change the name of the generated file. +By default this is `quickstart-web.xml` in the webapp's `WEB-INF` directory. +The file named by this parameter will always be interpreted relative to `WEB-INF`. + + + From 7b1ec0a4fa9681bd8579dae2f6fe80f53d809de9 Mon Sep 17 00:00:00 2001 From: Jan Bartel Date: Wed, 7 Oct 2020 10:57:33 +0200 Subject: [PATCH 2/5] Update to quickstart doc. --- .../main/asciidoc/operations-guide/quickstart/chapter.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc index 10864996d84..7a5d76e0be0 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc @@ -55,11 +55,16 @@ jetty.quickstart.mode:: jetty.quickstart.origin:: Use this parameter to set the name of the attribute in the `quickstart-web.xml` file that contains the origin of each element. +Knowing the descriptor or annotation from which each element derives can be useful for debugging. +Note that the origin attribute does not conform to the web xml schema, so if you deploy with xml validation, you'll see errors. +It is probably best to do a few trial runs with the attribute set, then turn it off for final generation. jetty.quickstart.xml:: Use this parameter to change the name of the generated file. By default this is `quickstart-web.xml` in the webapp's `WEB-INF` directory. The file named by this parameter will always be interpreted relative to `WEB-INF`. - +In previous versions of Jetty, if a webapp was deployed as a war, the quickstart mechanism would automatically unpack it to a directory that was a sibling of the war file. +From jetty-10.0.0, you will need to either first unpack the war file, or use a context xml file (or code equivalent) that calls `WebAppContext.setExtractWAR(true)`. +If you allow Jetty to do the unpacking, it will use the usual mechanisms to find the location to which to unpack. From a42f768cf7088acaca41a90db356a121fee14481 Mon Sep 17 00:00:00 2001 From: Jan Bartel Date: Wed, 7 Oct 2020 10:57:55 +0200 Subject: [PATCH 3/5] No idea. --- .../src/it/test-jar-manifest/postbuild.groovy | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/jetty-runner/src/it/test-jar-manifest/postbuild.groovy b/jetty-runner/src/it/test-jar-manifest/postbuild.groovy index da1a6d99e3c..af66cf7472d 100644 --- a/jetty-runner/src/it/test-jar-manifest/postbuild.groovy +++ b/jetty-runner/src/it/test-jar-manifest/postbuild.groovy @@ -1,10 +1,10 @@ -import java.util.jar.* - -File artifact = new File( basedir, "target/jetty-runner.jar" ) -assert artifact.exists() - -JarFile jar = new JarFile( artifact ); - -Attributes manifest = jar.getManifest().getMainAttributes(); - -assert manifest.getValue( new Attributes.Name( "Main-Class" ) ).equals( "org.eclipse.jetty.runner.Runner" ) +import java.util.jar.* + +File artifact = new File( basedir, "target/jetty-runner.jar" ) +assert artifact.exists() + +JarFile jar = new JarFile( artifact ); + +Attributes manifest = jar.getManifest().getMainAttributes(); + +assert manifest.getValue( new Attributes.Name( "Main-Class" ) ).equals( "org.eclipse.jetty.runner.Runner" ) From 8db68334e3372a141c4cfcd3156fcc0d578bd1df Mon Sep 17 00:00:00 2001 From: Jan Bartel Date: Wed, 7 Oct 2020 13:18:11 +0200 Subject: [PATCH 4/5] Update quickstart doco --- .../src/main/asciidoc/operations-guide/index.adoc | 3 ++- .../src/main/asciidoc/operations-guide/introduction.adoc | 1 + .../main/asciidoc/operations-guide/quickstart/chapter.adoc | 6 +++--- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc index 33b1223c104..89d628590b6 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc @@ -31,5 +31,6 @@ include::deploy/chapter.adoc[] include::protocols/chapter.adoc[] include::keystore/chapter.adoc[] include::modules/chapter.adoc[] -include::sessions/chapter.adoc[] include::xml/chapter.adoc[] +include::sessions/chapter.adoc[] +include::quickstart/chapter.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc index 392b8f4e76f..de3fdcf0547 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc @@ -31,6 +31,7 @@ If you know Eclipse Jetty already, jump to a feature: * xref:og-sessions[HTTP Session Caching and Clustering] * xref:og-protocols-http2[HTTP/2 Support] +* xref:og-quickstart[Faster Web Application Deployment] TODO diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc index c96e1604cb6..d472aef40a8 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/quickstart/chapter.adoc @@ -17,12 +17,12 @@ // [[og-quickstart]] -=== Quickstart +=== Faster Web Application Deployment The auto discovery features of the Servlet Specification can make deployments slow and uncertain. Auto discovery of web application configuration can be useful during the development as it allows new features and frameworks to be enabled simply by dropping in a jar file. -However, for deployment, the need to scan the contents of many jars can have a significant impact at startup time. +However for production deployment, the need to scan the contents of many jars can have a significant impact at startup time. The `quickstart` module allows a webapp to be pre-scanned, making startup predictable and faster. During scanning all declarative configuration (ie from web.xml, web-fragment.xml and annotations) are encoded into an effective `web.xml`, called `WEB-INF/quickstart-web.xml`, which can be inspected to understand what will be deployed. @@ -30,7 +30,7 @@ NOTE:: Programmatic configuration is _not_ encoded into the generated `quickstar With `quickstart`, webapps that took many seconds to scan and deploy can now be deployed in a few hundred milliseconds. -==== Enabling Quickstart +==== Enabling Enable the `quickstart` module for your jetty base: From a374898884506eb244fdfb9556d69b033d532d2a Mon Sep 17 00:00:00 2001 From: Jan Bartel Date: Mon, 12 Oct 2020 10:31:56 +0200 Subject: [PATCH 5/5] Messed up in head. --- .../it/javax-annotation-api/postbuild.groovy | 42 ++++++++--------- .../postbuild.groovy | 42 ++++++++--------- .../postbuild.groovy | 6 +-- .../it/jetty-start-mojo-it/postbuild.groovy | 46 +++++++++---------- 4 files changed, 68 insertions(+), 68 deletions(-) diff --git a/jetty-maven-plugin/src/it/javax-annotation-api/postbuild.groovy b/jetty-maven-plugin/src/it/javax-annotation-api/postbuild.groovy index f3d4457eee4..a4f69f880f1 100644 --- a/jetty-maven-plugin/src/it/javax-annotation-api/postbuild.groovy +++ b/jetty-maven-plugin/src/it/javax-annotation-api/postbuild.groovy @@ -1,21 +1,21 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ -File buildLog = new File( basedir, 'build.log' ) -assert buildLog.text.contains( 'Started Server' ) -assert buildLog.text.contains( 'all good guys get a good Beer') +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +File buildLog = new File( basedir, 'build.log' ) +assert buildLog.text.contains( 'Started Server' ) +assert buildLog.text.contains( 'all good guys get a good Beer') diff --git a/jetty-maven-plugin/src/it/jetty-maven-plugin-provided-module-dep/postbuild.groovy b/jetty-maven-plugin/src/it/jetty-maven-plugin-provided-module-dep/postbuild.groovy index 1ec1341da06..bfadcee89c4 100644 --- a/jetty-maven-plugin/src/it/jetty-maven-plugin-provided-module-dep/postbuild.groovy +++ b/jetty-maven-plugin/src/it/jetty-maven-plugin-provided-module-dep/postbuild.groovy @@ -1,21 +1,21 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ -File buildLog = new File( basedir, 'build.log' ) -assert buildLog.text.contains( 'Started Server' ) -assert buildLog.text.contains( 'ClassNotFoundException') +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +File buildLog = new File( basedir, 'build.log' ) +assert buildLog.text.contains( 'Started Server' ) +assert buildLog.text.contains( 'ClassNotFoundException') diff --git a/jetty-maven-plugin/src/it/jetty-run-mojo-jar-scan-it/postbuild.groovy b/jetty-maven-plugin/src/it/jetty-run-mojo-jar-scan-it/postbuild.groovy index 75cfafa3fee..caf7a534eab 100644 --- a/jetty-maven-plugin/src/it/jetty-run-mojo-jar-scan-it/postbuild.groovy +++ b/jetty-maven-plugin/src/it/jetty-run-mojo-jar-scan-it/postbuild.groovy @@ -1,3 +1,3 @@ -File buildLog = new File( basedir, 'build.log' ) -assert buildLog.text.contains( 'Started Server' ) -assert buildLog.text.contains( 'STARTED[class jettyissue.NormalClass]') +File buildLog = new File( basedir, 'build.log' ) +assert buildLog.text.contains( 'Started Server' ) +assert buildLog.text.contains( 'STARTED[class jettyissue.NormalClass]') diff --git a/jetty-maven-plugin/src/it/jetty-start-mojo-it/postbuild.groovy b/jetty-maven-plugin/src/it/jetty-start-mojo-it/postbuild.groovy index 9bc3c598f11..660dcf76e67 100644 --- a/jetty-maven-plugin/src/it/jetty-start-mojo-it/postbuild.groovy +++ b/jetty-maven-plugin/src/it/jetty-start-mojo-it/postbuild.groovy @@ -1,23 +1,23 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ -File buildLog = new File( basedir, 'build.log' ) -assert buildLog.text.contains( 'Started Server' ) -assert buildLog.text.contains( 'Running org.eclipse.jetty.maven.plugin.it.IntegrationTestGetContent') -assert buildLog.text.contains( 'pingServlet ok') -assert buildLog.text.contains( 'helloServlet') +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +File buildLog = new File( basedir, 'build.log' ) +assert buildLog.text.contains( 'Started Server' ) +assert buildLog.text.contains( 'Running org.eclipse.jetty.maven.plugin.it.IntegrationTestGetContent') +assert buildLog.text.contains( 'pingServlet ok') +assert buildLog.text.contains( 'helloServlet')