From f0826c17ffe8df0756f4d0874b7027ba6cb44ff4 Mon Sep 17 00:00:00 2001 From: Robert Rodewald Date: Wed, 4 Aug 2021 11:15:13 +0200 Subject: [PATCH 1/4] Minimal fixes to documentation of Context and Host - Documented default value of unpackWARs attribute - Tagged all boolean values als code - Punctuation --- webapps/docs/config/context.xml | 16 ++++++++-------- webapps/docs/config/host.xml | 16 ++++++++-------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/webapps/docs/config/context.xml b/webapps/docs/config/context.xml index af1cb84436d4..6ecf5b995b78 100644 --- a/webapps/docs/config/context.xml +++ b/webapps/docs/config/context.xml @@ -263,14 +263,14 @@ -

Set to true if Tomcat should automatically parse +

Set to true 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 false causes Tomcat to behave in a way that is not technically spec-compliant. - The default is false

+ The default is false.

 @@ -480,7 +480,7 @@

Even when statically defining a Context in server.xml, this attribute must not be set unless either the docBase is not located under the Host's appBase or both - deployOnStartup and autoDeploy are false. If + deployOnStartup and autoDeploy are false. If this rule is not followed, double deployment is likely to result.

 @@ -594,7 +594,7 @@ -

Set to false if Tomcat should not read any additional request +

Set to false if Tomcat should not read any additional request body data for aborted uploads and instead abort the client connection. This setting is used in the following situations:

@@ -757,7 +757,7 @@ -

If true, Tomcat will prevent any file locking. +

If true, 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,7 +768,7 @@ see Bugzilla 37668.

-

Please note that setting this flag to true in applications that are +

Please note that setting this flag to true in applications that are outside the appBase for the Host (the webapps directory by default) will cause the application to be deleted on Tomcat shutdown. You probably don't want to do this, so think twice @@ -858,7 +858,7 @@ createSubContext(), destroySubContext() or close() will trigger a javax.naming.OperationNotSupportedException 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 + disabled by setting this attribute to false in which case any calls to modify the JNDI context will return without making any changes and methods that return values will return null. If not specified, the specification compliant default of true will @@ -1264,7 +1264,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 singleton attribute is - false.

+ false.

For javax.sql.DataSource and javax.sql.XADataSource resources that implement AutoCloseable such as Apache Commons DBCP 2 and the default diff --git a/webapps/docs/config/host.xml b/webapps/docs/config/host.xml index 3e981a6e49fe..7742d0347174 100644 --- a/webapps/docs/config/host.xml +++ b/webapps/docs/config/host.xml @@ -110,21 +110,21 @@ -

If set to true, Tomcat will attempt to create the directories defined +

If set to true, Tomcat will attempt to create the directories defined by the attributes appBase and xmlBase during the startup phase. The default value is true. If set to - true, and directory creation fails, an error message will be printed out + true, and directory creation fails, an error message will be printed out but will not halt the startup sequence.

This flag value indicates if Tomcat should check periodically for new - or updated web applications while Tomcat is running. If true, Tomcat + or updated web applications while Tomcat is running. If true, Tomcat periodically checks the appBase and xmlBase 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 + to true. See Automatic Application Deployment for more information.

 @@ -170,7 +170,7 @@

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 + to true. See Automatic Application Deployment for more information.

 @@ -233,8 +233,8 @@

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 autoDeploy is true. If not - specified the default value of false will be used.

+ This flag only applies if autoDeploy is true. If not + specified the default value of false will be used.

 @@ -302,7 +302,7 @@ placed in the appBase directory as web application archive (WAR) files to be unpacked into a corresponding disk directory structure, false to run such web applications directly - from a WAR file. See + from a WAR file. The flag's value defaults to true. See Automatic Application Deployment for more information.

Note: If Tomcat expands the WAR file then it will add a file From b2f7f8bfce5d45b3ae739c21c292c607ba7ca23d Mon Sep 17 00:00:00 2001 From: Robert Rodewald Date: Wed, 4 Aug 2021 11:40:50 +0200 Subject: [PATCH 2/4] Consistent tagging of appBase as code --- webapps/docs/config/context.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/webapps/docs/config/context.xml b/webapps/docs/config/context.xml index 6ecf5b995b78..721b8e3a4644 100644 --- a/webapps/docs/config/context.xml +++ b/webapps/docs/config/context.xml @@ -183,7 +183,7 @@

@@ -769,11 +769,11 @@ Bugzilla 37668.

Please note that setting this flag to true in applications that are - outside the appBase for the Host (the webapps directory + outside the appBase for the Host (the webapps directory by default) will cause the application to be deleted 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.

+ appBase for its Host.

From c88622ad38e2977db1bba9dff70de9c040e40d10 Mon Sep 17 00:00:00 2001 From: Robert Rodewald Date: Wed, 4 Aug 2021 12:44:57 +0200 Subject: [PATCH 3/4] Rewording of default values. --- webapps/docs/config/context.xml | 2 +- webapps/docs/config/host.xml | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/webapps/docs/config/context.xml b/webapps/docs/config/context.xml index 721b8e3a4644..4c4acea5e9db 100644 --- a/webapps/docs/config/context.xml +++ b/webapps/docs/config/context.xml @@ -844,7 +844,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 false. Note if + is more recent. The default is false. Note if the deployXML attribute of the owning Host is false or if the copyXML attribute of the owning diff --git a/webapps/docs/config/host.xml b/webapps/docs/config/host.xml index 7742d0347174..87eda496e208 100644 --- a/webapps/docs/config/host.xml +++ b/webapps/docs/config/host.xml @@ -123,8 +123,8 @@ periodically checks the appBase and xmlBase 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 + will trigger a reload of the web application. The default + is true. See Automatic Application Deployment for more information.

 @@ -169,8 +169,8 @@

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 true. See Automatic Application Deployment for more information.

 @@ -258,8 +258,8 @@ 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 false. Note if deployXML + embedded inside the application is more recent. The default + is false. Note if deployXML is false, this attribute will have no effect.

@@ -276,7 +276,7 @@ descriptor is present in xmlBase 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 true unless a + ignored. The default is true unless a security manager is enabled when the default is false. When running under a security manager this may be enabled on a per web application basis by granting the @@ -302,7 +302,7 @@ placed in the appBase directory as web application archive (WAR) files to be unpacked into a corresponding disk directory structure, false to run such web applications directly - from a WAR file. The flag's value defaults to true. See + from a WAR file. The default is true. See Automatic Application Deployment for more information.

Note: If Tomcat expands the WAR file then it will add a file From b880718b348831cf2540a8ed62278e3980fc0937 Mon Sep 17 00:00:00 2001 From: Robert Rodewald Date: Wed, 4 Aug 2021 14:23:55 +0200 Subject: [PATCH 4/4] Consistently tagged docBase attribute as code --- webapps/docs/config/context.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/webapps/docs/config/context.xml b/webapps/docs/config/context.xml index 4c4acea5e9db..7f602aed7c00 100644 --- a/webapps/docs/config/context.xml +++ b/webapps/docs/config/context.xml @@ -184,7 +184,7 @@

  • Disable autoDeploy and deployOnStartup and define all Contexts in server.xml
  • 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.
    • + a context.xml file with a docBase attribute to define it. @@ -393,7 +393,7 @@

    The value of this field must not be set unless the Context element is defined in server.xml or the docBase is not located under the Host's appBase.

    -

    If a symbolic link is used for docBase then changes to the +

    If a symbolic link is used for docBase 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.

    @@ -475,10 +475,10 @@ will process all requests not assigned to other Contexts.

    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 docBase.

    Even when statically defining a Context in server.xml, this attribute - must not be set unless either the docBase is not located under the + must not be set unless either the docBase is not located under the Host's appBase or both deployOnStartup and autoDeploy are false. If this rule is not followed, double deployment is likely to result.