This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/main by this push:
new 38dbc21 Improvements to documentation
38dbc21 is described below
commit 38dbc21ce7d5cb2af9780526ba26b607648e7691
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 db6f18a..7e63112 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 af1cb84..cc07f5e 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'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'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>'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>'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>'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">
@@ -844,7 +847,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
@@ -858,11 +861,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">
@@ -1264,7 +1267,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-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
