Issue #2844 Clean up webdefault and DefaultServlet documentation (#2851)

Signed-off-by: Jan Bartel <janb@webtide.com>
2018-08-28 09:53:06 +10:00 · 2018-08-28 09:53:06 +10:00 · 09be34e08b
parent 5b5f2fcf5f
commit 09be34e08b
4 changed files with 53 additions and 39 deletions
--- a/jetty-documentation/src/main/asciidoc/administration/extras/default-servlet.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/default-servlet.adoc
@ -40,18 +40,39 @@ See the `DefaultServlet` link:{JDURL}/org/eclipse/jetty/servlet/DefaultServlet.h
 Jetty supports the following `initParameters`:

 acceptRanges::
-If true, range requests and responses are supported.
+If `true`, range requests and responses are supported.
 dirAllowed::
-If true, directory listings are returned if no welcome file is found.
+If `true`, directory listings are returned if no welcome file is found.
 Otherwise 403 Forbidden displays.
 redirectWelcome::
-If true, welcome files are redirected rather that forwarded.
+If `true`, welcome files are redirected rather that forwarded.
+welcomeServlets::
+If `true`, attempt to dispatch to welcome files that are servlets, but only after no matching static
+resources could be found. If `false`, then a welcome file must exist on disk. If `exact`, then exact
+servlet matches are supported without an existing file. Default is `true`. This must be `false` if you want directory listings,
+but have index.jsp in your welcome file list.
+precompressed::
+If set to a comma separated list of encoding types (that may be listed in a requests Accept-Encoding header) to file
+extension mappings to look for and serve. For example:
+`br=.br,gzip=.gz,bzip2=.bz`.
+If set to a boolean `true`, then a default set of compressed formats
+will be used, otherwise no precompressed formats supported.
 gzip::
-If set to true, then static content is served as gzip content encoded if a matching resource is found ending with ".gz".
+Deprecated. Use `precompressed` instead. If set to `true`, then static content is served as gzip content encoded if a matching resource is found ending with ".gz".
 resourceBase::
 Set to replace the context resource base.
-aliases::
-If true, aliases of resources are allowed (that is, symbolic links and caps variations) and may bypass security constraints.
+resourceCache::
+If set, this is a context attribute name, which the servlet will use to look for a shared ResourceCache instance.
+relativeResourceBase::
+Set with a pathname relative to the base of the servlet context root. Useful for only serving static content out of only specific subdirectories.
+cacheControl::
+If set, all static content will have this value set as the cache-control header.
+pathInfoOnly::
+If `true`, only the path info will be applied to the resourceBase
+stylesheet::
+Set with the location of an optional stylesheet that will be used to decorate the directory listing html.
+etags::
+If `true`, weak etags will be generated and handled.
 maxCacheSize::
 Maximum total size of the cache or 0 for no cache.
 maxCachedFileSize::
@ -59,9 +80,11 @@ Maximum size of a file to cache.
 maxCachedFiles::
 Maximum number of files to cache.
 useFileMappedBuffer::
-If set to true, mapped file buffer serves static content.
-Setting this value to false means that a direct buffer is used instead of a mapped file buffer.
-By default, this is set to true.
+If set to `true`, mapped file buffer serves static content.
+Setting this value to `false` means that a direct buffer is used instead of a mapped file buffer.
+By default, this is set to `true`.
 otherGzipFileExtensions::
 A comma separated list of other file extensions that signify that a file is gzip compressed.
-If you don't explicitly set this, it defaults to ".svgz".
+If you don't explicitly set this, it defaults to `.svgz`.
+encodingHeaderCacheSize::
+Max entries in a cache of ACCEPT-ENCODING headers
--- a/jetty-servlet/src/main/java/org/eclipse/jetty/servlet/DefaultServlet.java
+++ b/jetty-servlet/src/main/java/org/eclipse/jetty/servlet/DefaultServlet.java
@ -123,7 +123,8 @@ import org.eclipse.jetty.util.resource.ResourceFactory;
 *  otherGzipFileExtensions
 *                    Other file extensions that signify that a file is already compressed. Eg ".svgz"
 *
- *
+ *  encodingHeaderCacheSize
+ *                    Max entries in a cache of ACCEPT-ENCODING headers.
 * </pre>
 *
 */
--- a/jetty-webapp/src/main/config/etc/webdefault.xml
+++ b/jetty-webapp/src/main/config/etc/webdefault.xml
@ -95,9 +95,10 @@
 *                    found ending with ".gz" (default false) 
 *                    (deprecated: use precompressed)
 *                    
- *  precompressed     If set to a comma separated list of file extensions, these
- *                    indicate compressed formats that are known to map to a mime-type
- *                    that may be listed in a requests Accept-Encoding header.
+ *  precompressed     If set to a comma separated list of encoding types (that may be
+ *                    listed in a requests Accept-Encoding header) to file
+ *                    extension mappings to look for and serve. For example:
+ *                    "br=.br,gzip=.gz,bzip2=.bz".
 *                    If set to a boolean True, then a default set of compressed formats
 *                    will be used, otherwise no precompressed formats.
 *
@ -115,9 +116,6 @@
 *
 *  stylesheet        Set with the location of an optional stylesheet that will be used
 *                    to decorate the directory listing html.
- *
- *  aliases           If True, aliases of resources are allowed (eg. symbolic
- *                    links and caps variations). May bypass security constraints.
 *                    
 *  etags             If True, weak etags will be generated and handled.
 *
@ -134,15 +132,17 @@
 *  cacheControl      If set, all static content will have this value set as the cache-control
 *                    header.
 *
+ * encodingHeaderCacheSize
+ *                    Max entries in a cache of ACCEPT-ENCODING headers.
+ *
+ * otherGzipFileExtensions  
+ *                    defaults to .svgz but a comma separated list of gzip equivalent file extensions can be supplied
+ *
 -->
 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  -->
  <servlet>
    <servlet-name>default</servlet-name>
    <servlet-class>org.eclipse.jetty.servlet.DefaultServlet</servlet-class>
-    <init-param>
-      <param-name>aliases</param-name>
-      <param-value>false</param-value>
-    </init-param>
    <init-param>
      <param-name>acceptRanges</param-name>
      <param-value>true</param-value>
@ -171,12 +171,6 @@
      <param-name>maxCachedFiles</param-name>
      <param-value>2048</param-value>
    </init-param>
-    <!--
-    <init-param>
-      <param-name>precompressed</param-name>
-      <param-value>gzip,br</param-value>
-    </init-param>
-    -->
    <init-param>
      <param-name>etags</param-name>
      <param-value>false</param-value>
@ -185,18 +179,6 @@
      <param-name>useFileMappedBuffer</param-name>
      <param-value>true</param-value>
    </init-param>
-    <!--
-    <init-param>
-      <param-name>resourceCache</param-name>
-      <param-value>resourceCache</param-value>
-    </init-param>
-    -->
-    <!--
-    <init-param>
-      <param-name>cacheControl</param-name>
-      <param-value>max-age=3600,public</param-value>
-    </init-param>
-    -->
    <load-on-startup>0</load-on-startup>
  </servlet>

--- a/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/webapps/test.d/override-web.xml
+++ b/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/webapps/test.d/override-web.xml
@ -15,6 +15,14 @@
    <param-value>a context value</param-value>
  </context-param>

+  <!-- Add or override servlet init parameter -->
+  <servlet>
+    <servlet-name>default</servlet-name>
+    <init-param>
+      <param-name>precompressed</param-name>
+      <param-value>true</param-value>
+    </init-param>
+  </servlet>

  <!-- Add or override servlet init parameter -->
  <servlet>