Author: violetagg
Date: Sun Jun 11 19:04:14 2017
New Revision: 1798395
URL: http://svn.apache.org/viewvc?rev=1798395&view=rev
Log:
Fix https://bz.apache.org/bugzilla/show_bug.cgi?id=61173
Polish the javadoc for o.a.catalina.startup.Tomcat. Patch provided by
peterhansson_se.
Modified:
tomcat/trunk/java/org/apache/catalina/startup/Tomcat.java
tomcat/trunk/webapps/docs/changelog.xml
Modified: tomcat/trunk/java/org/apache/catalina/startup/Tomcat.java
URL:
http://svn.apache.org/viewvc/tomcat/trunk/java/org/apache/catalina/startup/Tomcat.java?rev=1798395&r1=1798394&r2=1798395&view=diff
==============================================================================
--- tomcat/trunk/java/org/apache/catalina/startup/Tomcat.java (original)
+++ tomcat/trunk/java/org/apache/catalina/startup/Tomcat.java Sun Jun 11
19:04:14 2017
@@ -75,28 +75,35 @@ import org.apache.tomcat.util.descriptor
/**
* Minimal tomcat starter for embedding/unit tests.
*
+ * <p>
* Tomcat supports multiple styles of configuration and
* startup - the most common and stable is server.xml-based,
* implemented in org.apache.catalina.startup.Bootstrap.
*
+ * <p>
* This class is for use in apps that embed tomcat.
- * Requirements:
*
- * - all tomcat classes and possibly servlets are in the classpath.
- * ( for example all is in one big jar, or in eclipse CP, or in any other
- * combination )
- *
- * - we need one temporary directory for work files
- *
- * - no config file is required. This class provides methods to
- * use if you have a webapp with a web.xml file, but it is
- * optional - you can use your own servlets.
+ * <p>
+ * Requirements:
+ * <ul>
+ * <li>all tomcat classes and possibly servlets are in the classpath.
+ * (for example all is in one big jar, or in eclipse CP, or in
+ * any other combination)</li>
+ *
+ * <li>we need one temporary directory for work files</li>
+ *
+ * <li>no config file is required. This class provides methods to
+ * use if you have a webapp with a web.xml file, but it is
+ * optional - you can use your own servlets.</li>
+ * </ul>
*
+ * <p>
* There are a variety of 'add' methods to configure servlets and webapps.
These
* methods, by default, create a simple in-memory security realm and apply it.
* If you need more complex security processing, you can define a subclass of
* 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}.
@@ -104,6 +111,7 @@ import org.apache.tomcat.util.descriptor
* listener that adds the standard DefaultServlet, JSP processing, and welcome
* files.
*
+ * <p>
* In complex cases, you may prefer to use the ordinary Tomcat API to create
* webapp contexts; for example, you might need to install a custom Loader
* before the call to {@link Host#addChild(Container)}. To replicate the basic
@@ -111,14 +119,17 @@ import org.apache.tomcat.util.descriptor
* methods of this class: {@link #noDefaultWebXmlPath()} and
* {@link #getDefaultWebXmlListener()}.
*
+ * <p>
* {@link #getDefaultWebXmlListener()} returns a {@link LifecycleListener} that
* adds the standard DefaultServlet, JSP processing, and welcome files. If you
* add this listener, you must prevent Tomcat from applying any standard global
* web.xml with ...
*
+ * <p>
* {@link #noDefaultWebXmlPath()} returns a dummy pathname to configure to
* prevent {@link ContextConfig} from trying to apply a global web.xml file.
*
+ * <p>
* This class provides a main() and few simple CLI arguments,
* see setters for doc. It can be used for simple tests and
* demo.
@@ -152,11 +163,15 @@ public class Tomcat {
* Tomcat needs a directory for temp files. This should be the
* first method called.
*
+ * <p>
* By default, if this method is not called, we use:
- * - system properties - catalina.base, catalina.home
- * - $PWD/tomcat.$PORT
+ * <ul>
+ * <li>system properties - catalina.base, catalina.home</li>
+ * <li>$PWD/tomcat.$PORT</li>
+ * </ul>
* (/tmp doesn't seem a good choice for security).
*
+ * <p>
* TODO: disable work dir if not needed ( no jsp, etc ).
*
* @param basedir The Tomcat base folder on which all others
@@ -214,24 +229,30 @@ public class Tomcat {
* programmatically, there will still be no scanning for
* {@link javax.servlet.annotation.HandlesTypes} matches.
*
+ * <p>
* API calls equivalent with web.xml:
*
- * context-param
+ * <pre>{@code
+ * // context-param
* ctx.addParameter("name", "value");
*
*
- * error-page
- * ErrorPage ep = new ErrorPage();
- * ep.setErrorCode(500);
- * ep.setLocation("/error.html");
- * ctx.addErrorPage(ep);
+ * // error-page
+ * ErrorPage ep = new ErrorPage();
+ * ep.setErrorCode(500);
+ * ep.setLocation("/error.html");
+ * ctx.addErrorPage(ep);
*
- * ctx.addMimeMapping("ext", "type");
+ * ctx.addMimeMapping("ext", "type");
+ * }</pre>
*
+ *
+ * <p>
* Note: If you reload the Context, all your configuration will be lost. If
* you need reload support, consider using a LifecycleListener to provide
* your configuration.
*
+ * <p>
* TODO: add the rest
*
* @param contextPath The context mapping to use, "" for root context.
@@ -246,14 +267,16 @@ public class Tomcat {
/**
* Equivalent to <servlet><servlet-name><servlet-class>.
*
+ * <p>
* In general it is better/faster to use the method that takes a
* Servlet as param - this one can be used if the servlet is not
* commonly used, and want to avoid loading all deps.
* ( for example: jsp servlet )
*
* You can customize the returned servlet, ex:
- *
+ * <pre>
* wrapper.addInitParameter("name", "value");
+ * </pre>
*
* @param contextPath Context to add Servlet to
* @param servletName Servlet name (used in mappings)
@@ -909,6 +932,7 @@ public class Tomcat {
/**
* Fix startup sequence - required if you don't use web.xml.
*
+ * <p>
* The start() method in context will set 'configured' to false - and
* expects a listener to set it back to true.
*/
Modified: tomcat/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/changelog.xml?rev=1798395&r1=1798394&r2=1798395&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/trunk/webapps/docs/changelog.xml Sun Jun 11 19:04:14 2017
@@ -95,6 +95,11 @@
and then granting that permission to the Manager and Host Manager.
(markt)
</fix>
+ <fix>
+ <bug>61173</bug>: Polish the javadoc for
+ <code>o.a.catalina.startup.Tomcat</code>. Patch provided by
+ peterhansson_se. (violetagg)
+ </fix>
</changelog>
</subsection>
<subsection name="Coyote">
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
