This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 7.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/7.0.x by this push:
new 0350885 Fix https://bz.apache.org/bugzilla/show_bug.cgi?id=64008
0350885 is described below
commit 0350885f9f800f9fb17223a50b9f7e92ba228d7a
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Tue Dec 17 20:45:55 2019 +0000
Fix https://bz.apache.org/bugzilla/show_bug.cgi?id=64008
Improve Javadocs for addWebapp. Also back-port BZ 62755.
---
java/org/apache/catalina/startup/Tomcat.java | 137 ++++++++++++++++++++-------
webapps/docs/changelog.xml | 11 +++
2 files changed, 113 insertions(+), 35 deletions(-)
diff --git a/java/org/apache/catalina/startup/Tomcat.java
b/java/org/apache/catalina/startup/Tomcat.java
index ea2db1c..9a5a8d6 100644
--- a/java/org/apache/catalina/startup/Tomcat.java
+++ b/java/org/apache/catalina/startup/Tomcat.java
@@ -110,12 +110,17 @@ import org.apache.tomcat.util.res.StringManager;
* this class.
*
* <p>
- * This class provides a set of convenience methods for configuring webapp
- * contexts, all overloads of the method <code>addWebapp</code>. These methods
- * create a webapp context, configure it, and then add it to a {@link Host}.
- * They do not use a global default web.xml; rather, they add a lifecycle
- * listener that adds the standard DefaultServlet, JSP processing, and welcome
- * files.
+ * This class provides a set of convenience methods for configuring web
+ * application contexts; all overloads of the method <code>addWebapp()</code>.
+ * These methods are equivalent to adding a web application to the Host's
+ * appBase (normally the webapps directory). These methods create a Context,
+ * configure it with the equivalent of the defaults provided by
+ * <code>conf/web.xml</code> (see {@link #initWebappDefaults(String)} for
+ * details) and add the Context to a Host. These methods do not use a global
+ * default web.xml; rather, they add a {@link LifecycleListener} to configure
+ * the defaults. Any WEB-INF/web.xml and META-INF/context.xml packaged with the
+ * application will be processed normally. Normal web fragment and
+ * {@link javax.servlet.ServletContainerInitializer} processing will be
applied.
*
* <p>
* In complex cases, you may prefer to use the ordinary Tomcat API to create
@@ -187,6 +192,8 @@ public class Tomcat {
private final Map<String, Principal> userPrincipals =
new HashMap<String, Principal>();
+ private boolean addDefaultWebXmlToWebapp = true;
+
public Tomcat() {
ExceptionUtils.preload();
}
@@ -229,17 +236,22 @@ public class Tomcat {
hostname = s;
}
+
/**
- * This is equivalent to adding a web application to Tomcat's webapps
- * directory. The equivalent of the default web.xml will be applied to the
- * web application and any WEB-INF/web.xml and META-INF/context.xml
packaged
- * with the application will be processed normally. Normal web fragment and
- * {@link javax.servlet.ServletContainerInitializer} processing will be
- * applied.
+ * This is equivalent to adding a web application to a Host's appBase
+ * (usually Tomcat's webapps directory). By default, the equivalent of the
+ * default web.xml will be applied to the web application (see
+ * {@link #initWebappDefaults(String)}). This may be prevented by calling
+ * {@link #setAddDefaultWebXmlToWebapp(boolean)} with {@code false}. Any
+ * <code>WEB-INF/web.xml</code> and <code>META-INF/context.xml</code>
+ * packaged with the application will always be processed and normal web
+ * fragment and {@link javax.servlet.ServletContainerInitializer}
processing
+ * will always be applied.
*
* @param contextPath The context mapping to use, "" for root context.
- * @param docBase Base directory for the context, for static files.
- * Must exist, relative to the server home
+ * @param docBase Base directory for the context, for static files.
Must
+ * exist, relative to the server home
+ *
* @return the deployed context
*/
public Context addWebapp(String contextPath, String docBase) {
@@ -505,7 +517,7 @@ public class Tomcat {
}
// ------- Extra customization -------
- // You can tune individual tomcat objects, using internal APIs
+ // You can tune individual Tomcat objects, using internal APIs
/**
* Get the default http connector. You can set more
@@ -663,19 +675,30 @@ public class Tomcat {
return ctx;
}
+
/**
- * @param host The host in which the context will be deployed
+ * This is equivalent to adding a web application to a Host's appBase
+ * (usually Tomcat's webapps directory). By default, the equivalent of the
+ * default web.xml will be applied to the web application (see
+ * {@link #initWebappDefaults(String)}). This may be prevented by calling
+ * {@link #setAddDefaultWebXmlToWebapp(boolean)} with {@code false}. Any
+ * <code>WEB-INF/web.xml</code> and <code>META-INF/context.xml</code>
+ * packaged with the application will always be processed and normal web
+ * fragment and {@link javax.servlet.ServletContainerInitializer}
processing
+ * will always be applied.
+ *
+ * @param host The host in which the context will be deployed
* @param contextPath The context mapping to use, "" for root context.
- * @param docBase Base directory for the context, for static files.
- * Must exist, relative to the server home
+ * @param docBase Base directory for the context, for static files.
Must
+ * exist, relative to the server home
+ *
* @return the deployed context
- * @see #addWebapp(String, String)
*/
public Context addWebapp(Host host, String contextPath, String docBase) {
LifecycleListener listener = null;
try {
Class<?> clazz = Class.forName(getHost().getConfigClass());
- listener = (LifecycleListener) clazz.newInstance();
+ listener = (LifecycleListener)
clazz.getConstructor().newInstance();
} catch (Exception e) {
// Wrap in IAE since we can't easily change the method signature to
// to throw the specific checked exceptions
@@ -685,6 +708,7 @@ public class Tomcat {
return addWebapp(host, contextPath, docBase, listener);
}
+
/**
* @param host The host in which the context will be deployed
* @param contextPath The context mapping to use, "" for root context.
@@ -694,7 +718,6 @@ public class Tomcat {
* @return the deployed context
* @see #addWebapp(String, String)
*
- *
* @deprecated Use {@link #addWebapp(Host, String, String)}
*/
@Deprecated
@@ -703,13 +726,25 @@ public class Tomcat {
}
/**
- * @param host The host in which the context will be deployed
+ * This is equivalent to adding a web application to a Host's appBase
+ * (usually Tomcat's webapps directory). By default, the equivalent of the
+ * default web.xml will be applied to the web application (see
+ * {@link #initWebappDefaults(String)}). This may be prevented by calling
+ * {@link #setAddDefaultWebXmlToWebapp(boolean)} with {@code false}. Any
+ * <code>WEB-INF/web.xml</code> and <code>META-INF/context.xml</code>
+ * packaged with the application will always be processed and normal web
+ * fragment and {@link javax.servlet.ServletContainerInitializer}
processing
+ * will always be applied.
+ *
+ * @param host The host in which the context will be deployed
* @param contextPath The context mapping to use, "" for root context.
- * @param docBase Base directory for the context, for static files.
- * Must exist, relative to the server home
- * @param config Custom context configurator helper
+ * @param docBase Base directory for the context, for static files.
Must
+ * exist, relative to the server home
+ * @param config Custom context configuration helper. Any
configuration
+ * will be in addition to equivalent of the default
+ * web.xml configuration described above.
+ *
* @return the deployed context
- * @see #addWebapp(String, String)
*/
public Context addWebapp(Host host, String contextPath, String docBase,
LifecycleListener config) {
@@ -719,12 +754,16 @@ public class Tomcat {
Context ctx = createContext(host, contextPath);
ctx.setPath(contextPath);
ctx.setDocBase(docBase);
- ctx.addLifecycleListener(getDefaultWebXmlListener());
+
+ if (addDefaultWebXmlToWebapp) {
+ ctx.addLifecycleListener(getDefaultWebXmlListener());
+ }
+
ctx.setConfigFile(getWebappConfigFile(docBase, contextPath));
ctx.addLifecycleListener(config);
- if (config instanceof ContextConfig) {
+ if (addDefaultWebXmlToWebapp && (config instanceof ContextConfig)) {
// prevent it from looking ( if it finds one - it'll have dup
error )
((ContextConfig) config).setDefaultWebXml(noDefaultWebXmlPath());
}
@@ -885,6 +924,24 @@ public class Tomcat {
}
+ /**
+ * By default, when calling addWebapp() to create a Context, the settings
from
+ * from the default web.xml are added to the context. Calling this method
with
+ * a <code>false</code> value prior to calling addWebapp() allows to opt
out of
+ * the default settings. In that event you will need to add the
configurations
+ * yourself, either programmatically or by using web.xml deployment
descriptors.
+ * @param addDefaultWebXmlToWebapp <code>false</code> will prevent the
class from
+ * automatically adding the default
settings when
+ * calling addWebapp().
+ * <code>true</code> will add the default
settings
+ * and is the default behavior.
+ * @see #addWebapp(Host, String, String, LifecycleListener)
+ */
+ public void setAddDefaultWebXmlToWebapp(boolean addDefaultWebXmlToWebapp){
+ this.addDefaultWebXmlToWebapp = addDefaultWebXmlToWebapp;
+ }
+
+
/*
* Uses essentially the same logic as {@link ContainerBase#logName()}.
*/
@@ -1009,22 +1066,32 @@ public class Tomcat {
}
}
+
/**
- * Provide default configuration for a context. This is the programmatic
- * equivalent of the default web.xml.
- *
- * TODO: in normal Tomcat, if default-web.xml is not found, use this
- * method
+ * Provide default configuration for a context. This is broadly the
+ * programmatic equivalent of the default web.xml and provides the
following
+ * features:
+ * <ul>
+ * <li>Default servlet mapped to "/"</li>
+ * <li>JSP servlet mapped to "*.jsp" and ""*.jspx"</li>
+ * <li>Session timeout of 30 minutes</li>
+ * <li>MIME mappings (subset of those in conf/web.xml)</li>
+ * <li>Welcome files</li>
+ * </ul>
+ * TODO: Align the MIME mappings with conf/web.xml - possibly via a common
+ * file.
*
- * @param contextPath The context to set the defaults for
+ * @param contextPath The path of the context to set the defaults for
*/
public void initWebappDefaults(String contextPath) {
Container ctx = getHost().findChild(contextPath);
initWebappDefaults((Context) ctx);
}
+
/**
- * Static version of {@link #initWebappDefaults(String)}
+ * Static version of {@link #initWebappDefaults(String)}.
+ *
* @param ctx The context to set the defaults for
*/
public static void initWebappDefaults(Context ctx) {
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index 03cead9..6a0d3fd 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -66,6 +66,17 @@
Avoid useless environment restore when not using GSSCredential
in JNDIRealm. (remm)
</fix>
+ <add>
+ <bug>62755</bug>: Add ability to opt out of adding the default web.xml
+ config when embedding Tomcat and adding a context via
+ <code>addWebapp()</code>. Call
+ <code>setAddDefaultWebXmlToWebapp(false)</code> to prevent the
automatic
+ config. (isapir/markt)
+ </add>
+ <fix>
+ <bug>64008</bug>: Clarify/expand the Javadoc for the
+ <code>Tomcat#addWebapp()</code> and related methods. (markt)
+ </fix>
</changelog>
</subsection>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
