You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2021/08/17 12:07:38 UTC

[tomcat] branch 10.0.x updated: Improvements to documentation

This is an automated email from the ASF dual-hosted git repository.

markt pushed a commit to branch 10.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git


The following commit(s) were added to refs/heads/10.0.x by this push:
     new 7bf0c97  Improvements to documentation
7bf0c97 is described below

commit 7bf0c97392efc89d9b39ef6d3ae0ae34ec1564a5
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Tue Aug 17 13:05:47 2021 +0100

    Improvements to documentation
    
    - Documented default for unpackWARs
    - Tagged all boolean values as code
    - Punctuation
    
    PR provided by Robert Rodewald
---
 webapps/docs/changelog.xml      |  4 +++
 webapps/docs/config/context.xml | 59 ++++++++++++++++++++++-------------------
 webapps/docs/config/host.xml    | 48 +++++++++++++++++----------------
 3 files changed, 60 insertions(+), 51 deletions(-)

diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index 9162ebb..9d7a890 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -145,6 +145,10 @@
         Remove unnecessary Context settings from the examples web application.
         (markt)
       </fix>
+      <fix>
+        Document default value for <code>unpackWARs</code> and related clean-up.
+        Pull request <pr>439</pr> provided by Robert Rodewald. (markt)
+      </fix>
     </changelog>
   </subsection>
 </section>
diff --git a/webapps/docs/config/context.xml b/webapps/docs/config/context.xml
index 0f210df..c7d8b46 100644
--- a/webapps/docs/config/context.xml
+++ b/webapps/docs/config/context.xml
@@ -183,8 +183,9 @@
   <ul>
   <li>Disable autoDeploy and deployOnStartup and define all
   <strong>Context</strong>s in server.xml</li>
-  <li>Locate the WAR and/or directory outside of the Host&apos;s appBase and use
-      a context.xml file with a docBase attribute to define it.</li>
+  <li>Locate the WAR and/or directory outside of the Host&apos;s
+      <code>appBase</code> and use a context.xml file with a
+      <code>docBase</code> attribute to define it.</li>
   </ul>
   </subsection>
 
@@ -263,14 +264,14 @@
     <attributes>
 
       <attribute name="allowCasualMultipartParsing" required="false">
-        <p>Set to true if Tomcat should automatically parse
+        <p>Set to <code>true</code> if Tomcat should automatically parse
         multipart/form-data request bodies when HttpServletRequest.getPart*
         or HttpServletRequest.getParameter* is called, even when the
         target servlet isn't marked with the @MultipartConfig annotation
         (See Servlet Specification 3.0, Section 3.2 for details).
         Note that any setting other than <code>false</code> causes Tomcat
         to behave in a way that is not technically spec-compliant.
-        The default is <code>false</code></p>
+        The default is <code>false</code>.</p>
       </attribute>
 
       <attribute name="allowMultipleLeadingForwardSlashInPath" required="false">
@@ -393,8 +394,8 @@
         <p>The value of this field must not be set unless the Context element is
         defined in server.xml or the <code>docBase</code> is not located under
         the <a href="host.html">Host</a>&apos;s <code>appBase</code>.</p>
-        <p>If a symbolic link is used for docBase then changes to the
-        symbolic link will only be effective after a Tomcat restart or
+        <p>If a symbolic link is used for <code>docBase</code> then changes to
+        the symbolic link will only be effective after a Tomcat restart or
         by undeploying and redeploying the context. A context reload is not
         sufficient.</p>
       </attribute>
@@ -475,13 +476,15 @@
         will process all requests not assigned to other Contexts.</p>
         <p>This attribute must only be used when statically defining a Context
         in server.xml. In all other circumstances, the path will be inferred
-        from the filenames used for either the .xml context file or the docBase.
+        from the filenames used for either the .xml context file or the
+        <code>docBase</code>.
         </p>
         <p>Even when statically defining a Context in server.xml, this attribute
-        must not be set unless either the docBase is not located under the
-        <a href="host.html">Host</a>&apos;s <code>appBase</code> or both
-        <code>deployOnStartup</code> and <code>autoDeploy</code> are false. If
-        this rule is not followed, double deployment is likely to result.</p>
+        must not be set unless either the <code>docBase</code> is not located
+        under the <a href="host.html">Host</a>&apos;s <code>appBase</code> or
+        both <code>deployOnStartup</code> and <code>autoDeploy</code> are
+        <code>false</code>. If this rule is not followed, double deployment is
+        likely to result.</p>
       </attribute>
 
       <attribute name="preemptiveAuthentication" required="false">
@@ -594,9 +597,9 @@
       </attribute>
 
       <attribute name="swallowAbortedUploads" required="false">
-        <p>Set to false if Tomcat should <b>not</b> read any additional request
-        body data for aborted uploads and instead abort the client connection.
-        This setting is used in the following situations:
+        <p>Set to <code>false</code> if Tomcat should <b>not</b> read any
+        additional request body data for aborted uploads and instead abort the
+        client connection. This setting is used in the following situations:
         </p>
         <ul>
         <li>the size of the request body is larger than the
@@ -757,7 +760,7 @@
       </attribute>
 
       <attribute name="antiResourceLocking" required="false">
-        <p>If true, Tomcat will prevent any file locking.
+        <p>If <code>true</code>, Tomcat will prevent any file locking.
         This will significantly impact startup time of applications,
         but allows full webapp hot deploy and undeploy on platforms
         or configurations where file locking can occur.
@@ -768,12 +771,12 @@
         see <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=37668">
         Bugzilla 37668</a>.</p>
 
-        <p>Please note that setting this flag to true in applications that are
-        outside the appBase for the Host (the <code>webapps</code> directory
-        by default) will cause the application to be <strong>deleted</strong> on
-        Tomcat shutdown.  You probably don't want to do this, so think twice
-        before setting antiResourceLocking=true on a webapp that's outside the
-        appBase for its Host.</p>
+        <p>Please note that setting this flag to <code>true</code> in
+        applications that are outside the <code>appBase</code> for the Host (the
+        <code>webapps</code> directory by default) will cause the application to
+        be <strong>deleted</strong> on Tomcat shutdown.  You probably don't want
+        to do this, so think twice before setting antiResourceLocking=true on a
+        webapp that's outside the <code>appBase</code> for its Host.</p>
       </attribute>
 
       <attribute name="clearReferencesHttpClientKeepAliveThread" required="false">
@@ -845,7 +848,7 @@
         is deployed. On subsequent starts, the copied context XML descriptor
         will be used in preference to any context XML descriptor embedded inside
         the application even if the descriptor embedded inside the application
-        is more recent. The flag's value defaults to <code>false</code>. Note if
+        is more recent. The default is <code>false</code>. Note if
         the <strong>deployXML</strong> attribute of the owning
         <a href="host.html">Host</a> is <code>false</code> or if the
         <strong>copyXML</strong> attribute of the owning
@@ -859,11 +862,11 @@
         createSubContext(), destroySubContext() or close() will trigger a
         <code>javax.naming.OperationNotSupportedException</code> as required by
         section EE.5.3.4 of the Jakarta EE specification. This exception can be
-        disabled by setting this attribute to false in which case any calls to
-        modify the JNDI context will return <b>without</b> making any changes
-        and methods that return values will return <code>null</code>. If not
-        specified, the specification compliant default of <code>true</code> will
-        be used.</p>
+        disabled by setting this attribute to <code>false</code> in which case
+        any calls to modify the JNDI context will return <b>without</b> making
+        any changes and methods that return values will return
+        <code>null</code>. If not specified, the specification compliant default
+        of <code>true</code> will be used.</p>
       </attribute>
 
       <attribute name="renewThreadsWhenStoppingContext" required="false">
@@ -1265,7 +1268,7 @@
         it is no longer required. This is intended to speed up clean-up of
         resources that would otherwise happen as part of garbage collection.
         This attribute is ignored if the <code>singleton</code> attribute is
-        false.</p>
+        <code>false</code>.</p>
         <p>For <code>javax.sql.DataSource</code> and
         <code>javax.sql.XADataSource</code> resources that implement
         <code>AutoCloseable</code> such as Apache Commons DBCP 2 and the default
diff --git a/webapps/docs/config/host.xml b/webapps/docs/config/host.xml
index 3e981a6..81f52e3 100644
--- a/webapps/docs/config/host.xml
+++ b/webapps/docs/config/host.xml
@@ -110,21 +110,22 @@
       </attribute>
 
       <attribute name="createDirs" required="false">
-        <p>If set to true, Tomcat will attempt to create the directories defined
-        by the  attributes <code>appBase</code> and <code>xmlBase</code> during
-        the startup phase. The default value is <code>true</code>. If set to
-        true, and directory creation fails, an error message will be printed out
-        but will not halt the startup sequence.</p>
+        <p>If set to <code>true</code>, Tomcat will attempt to create the
+        directories defined by the  attributes <code>appBase</code> and
+        <code>xmlBase</code> during the startup phase. The default value is
+        <code>true</code>. If set to <code>true</code>, and directory creation
+        fails, an error message will be printed out but will not halt the
+        startup sequence.</p>
       </attribute>
 
       <attribute name="autoDeploy" required="false">
         <p>This flag value indicates if Tomcat should check periodically for new
-        or updated web applications while Tomcat is running. If true, Tomcat
-        periodically checks the <code>appBase</code> and <code>xmlBase</code>
-        directories and deploys any new web applications or context XML
-        descriptors found. Updated web applications or context XML descriptors
-        will trigger a reload of the web application. The flag's value defaults
-        to true.  See
+        or updated web applications while Tomcat is running. If
+        <code>true</code>, Tomcat periodically checks the <code>appBase</code>
+        and <code>xmlBase</code> directories and deploys any new web
+        applications or context XML descriptors found. Updated web applications
+        or context XML descriptors will trigger a reload of the web application.
+        The default is <code>true</code>. See
         <a href="#Automatic_Application_Deployment">Automatic Application
         Deployment</a> for more information.</p>
       </attribute>
@@ -169,8 +170,8 @@
 
       <attribute name="deployOnStartup" required="false">
         <p>This flag value indicates if web applications from this host should
-        be automatically deployed when Tomcat starts. The flag's value defaults
-        to true.  See
+        be automatically deployed when Tomcat starts. The default is
+        <code>true</code>.  See
         <a href="#Automatic_Application_Deployment">Automatic Application
         Deployment</a> for more information.</p>
       </attribute>
@@ -233,8 +234,9 @@
         <p>This flag determines if Tomcat, as part of the auto deployment
         process, will check for old, unused versions of web applications
         deployed using parallel deployment and, if any are found, remove them.
-        This flag only applies if <code>autoDeploy</code> is true. If not
-        specified the default value of false will be used.</p>
+        This flag only applies if <code>autoDeploy</code> is <code>true</code>.
+        If not specified the default value of <code>false</code> will be used.
+        </p>
       </attribute>
 
     </attributes>
@@ -258,9 +260,9 @@
         when the application is deployed. On subsequent starts, the copied
         context XML descriptor will be used in preference to any context XML
         descriptor embedded inside the application even if the descriptor
-        embedded inside the application is more recent. The flag's value
-        defaults to <code>false</code>.  Note if <strong>deployXML</strong>
-        is <code>false</code>, this attribute will have no effect.</p>
+        embedded inside the application is more recent. The default is
+        <code>false</code>.  Note if <strong>deployXML</strong> is
+        <code>false</code>, this attribute will have no effect.</p>
       </attribute>
 
       <attribute name="deployXML" required="false">
@@ -276,10 +278,10 @@
         descriptor is present in <strong>xmlBase</strong> then the context will
         fail to start in case the descriptor contains necessary configuration
         for secure deployment (such as a RemoteAddrValve) which should not be
-        ignored. The flag's value defaults to <code>true</code> unless a
-        security manager is enabled when the default is <code>false</code>.
-        When running under a security manager this may be enabled on a per web
-        application basis by granting the
+        ignored. The default is <code>true</code> unless a security manager is
+        enabled when the default is <code>false</code>. When running under a
+        security manager this may be enabled on a per web application basis by
+        granting the
         <code>org.apache.catalina.security.DeployXmlPermission</code> to the web
         application. The Manager and Host Manager applications are granted this
         permission by default so that they continue to work when running under a
@@ -302,7 +304,7 @@
         placed in the <code>appBase</code> directory as web application
         archive (WAR) files to be unpacked into a corresponding disk directory
         structure, <code>false</code> to run such web applications directly
-        from a WAR file. See
+        from a WAR file. The default is <code>true</code>. See
         <a href="#Automatic_Application_Deployment">Automatic Application
         Deployment</a> for more information.</p>
         <p>Note: If Tomcat expands the WAR file then it will add a file

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org