ASF Bugzilla – Attachment 30772 Details for
Bug 55383
Improve markup and design of Tomcat's HTML pages
Home
|
New
|
Browse
|
Search
|
[?]
|
Reports
|
Help
|
New Account
|
Log In
Remember
[x]
|
Forgot Password
Login:
[x]
[patch]
First part of updated documentation XMLs
DocsUpdate-Part1.patch (text/plain), 175.01 KB, created by
Konstantin Preißer
on 2013-08-28 00:42:57 UTC
(
hide
)
Description:
First part of updated documentation XMLs
Filename:
MIME Type:
Creator:
Konstantin Preißer
Created:
2013-08-28 00:42:57 UTC
Size:
175.01 KB
patch
obsolete
>Index: modules/jdbc-pool/doc/jdbc-pool.xml >=================================================================== >--- modules/jdbc-pool/doc/jdbc-pool.xml (revision 1518039) >+++ modules/jdbc-pool/doc/jdbc-pool.xml (working copy) >@@ -41,7 +41,7 @@ > > <p>So why do we need a new connection pool?</p> > >- <p>Here are a few of the reasons: >+ <p>Here are a few of the reasons:</p> > <ol> > <li>commons-dbcp is single threaded, in order to be thread safe commons-dbcp locks the entire pool, even during query validation.</li> > <li>commons-dbcp is slow - as the number of logical CPUs grow, the performance suffers, the above point shows that there is not support for high concurrency >@@ -59,9 +59,8 @@ > <li>Starvation proof. If a pool is empty, and threads are waiting for a connection, when a connection is returned, > the pool will awake the correct thread waiting. Most pools will simply starve.</li> > </ol> >- </p> > >- <p>Features added over other connection pool implementations >+ <p>Features added over other connection pool implementations</p> > <ol> > <li>Support for highly concurrent environments and multi core/cpu systems.</li> > <li>Dynamic implementation of interface, will support <code>java.sql</code> and <code>javax.sql</code> interfaces for >@@ -96,7 +95,6 @@ > This is achieved using the <code>dataSource</code> and <code>dataSourceJNDI</code> attributes.</li> > <li>XA connection support</li> > </ol> >- </p> > > > </section> >@@ -173,7 +171,7 @@ > </attribute> > > <attribute name="defaultTransactionIsolation" required="false"> >- <p>(String) The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc ) >+ <p>(String) The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc )</p> > <ul> > <li><code>NONE</code></li> > <li><code>READ_COMMITTED</code></li> >@@ -181,8 +179,7 @@ > <li><code>REPEATABLE_READ</code></li> > <li><code>SERIALIZABLE</code></li> > </ul> >- If not set, the method will not be called and it defaults to the JDBC driver. >- </p> >+ <p>If not set, the method will not be called and it defaults to the JDBC driver.</p> > </attribute> > > <attribute name="defaultCatalog" required="false"> >@@ -673,8 +670,7 @@ > <p>Other examples of Tomcat configuration for JDBC usage can be found <a href="http://tomcat.apache.org/tomcat-6.0-doc/jndi-datasource-examples-howto.html">in the Tomcat documentation</a>. </p> > <subsection name="Plain Ol' Java"> > <p>Here is a simple example of how to create and use a data source.</p> >-<source> >- import java.sql.Connection; >+<source><![CDATA[ import java.sql.Connection; > import java.sql.ResultSet; > import java.sql.Statement; > >@@ -705,8 +701,8 @@ > p.setLogAbandoned(true); > p.setRemoveAbandoned(true); > p.setJdbcInterceptors( >- "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;"+ >- "org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"); >+ "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;"+ >+ "org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"); > DataSource datasource = new DataSource(); > datasource.setPoolProperties(p); > >@@ -727,38 +723,35 @@ > } > } > >- } >-</source> >+ }]]></source> > </subsection> > <subsection name="As a Resource"> > <p>And here is an example on how to configure a resource for JNDI lookups</p> >-<source> >-<Resource name="jdbc/TestDB" >- auth="Container" >- type="javax.sql.DataSource" >- factory="org.apache.tomcat.jdbc.pool.DataSourceFactory" >- testWhileIdle="true" >- testOnBorrow="true" >- testOnReturn="false" >- validationQuery="SELECT 1" >- validationInterval="30000" >- timeBetweenEvictionRunsMillis="30000" >- maxActive="100" >- minIdle="10" >- maxWait="10000" >- initialSize="10" >- removeAbandonedTimeout="60" >- removeAbandoned="true" >- logAbandoned="true" >- minEvictableIdleTimeMillis="30000" >- jmxEnabled="true" >- jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState; >- org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer" >- username="root" >- password="password" >- driverClassName="com.mysql.jdbc.Driver" >- url="jdbc:mysql://localhost:3306/mysql"/> >-</source> >+<source><![CDATA[<Resource name="jdbc/TestDB" >+ auth="Container" >+ type="javax.sql.DataSource" >+ factory="org.apache.tomcat.jdbc.pool.DataSourceFactory" >+ testWhileIdle="true" >+ testOnBorrow="true" >+ testOnReturn="false" >+ validationQuery="SELECT 1" >+ validationInterval="30000" >+ timeBetweenEvictionRunsMillis="30000" >+ maxActive="100" >+ minIdle="10" >+ maxWait="10000" >+ initialSize="10" >+ removeAbandonedTimeout="60" >+ removeAbandoned="true" >+ logAbandoned="true" >+ minEvictableIdleTimeMillis="30000" >+ jmxEnabled="true" >+ jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState; >+ org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer" >+ username="root" >+ password="password" >+ driverClassName="com.mysql.jdbc.Driver" >+ url="jdbc:mysql://localhost:3306/mysql"/>]]></source> > > </subsection> > <subsection name="Asynchronous Connection Retrieval"> >@@ -765,15 +758,15 @@ > <p> The Tomcat JDBC connection pool supports asynchronous connection retrieval without adding additional threads to the > pool library. It does this by adding a method to the data source called <code>Future<Connection> getConnectionAsync()</code>. > In order to use the async retrieval, two conditions must be met: >+ </p> > <ol> > <li>You must configure the <code>fairQueue</code> property to be <code>true</code>.</li> > <li>You will have to cast the data source to <code>org.apache.tomcat.jdbc.pool.DataSource</code></li> > </ol> > An example of using the async feature is show below. >-<source> >- Connection con = null; >+<source><![CDATA[ Connection con = null; > try { >- Future<Connection> future = datasource.getConnectionAsync(); >+ Future<Connection> future = datasource.getConnectionAsync(); > while (!future.isDone()) { > System.out.println("Connection is not yet available. Do some background work"); > try { >@@ -784,9 +777,8 @@ > } > con = future.get(); //should return instantly > Statement st = con.createStatement(); >- ResultSet rs = st.executeQuery("select * from user"); >-</source> >- </p> >+ ResultSet rs = st.executeQuery("select * from user");]]></source> >+ > </subsection> > <subsection name="Interceptors"> > <p>Interceptors are a powerful way to enable, disable or modify functionality on a specific connection or its sub components. >@@ -796,43 +788,41 @@ > the pool itself will not reset them.</p> > <p>An interceptor has to extend the <code>org.apache.tomcat.jdbc.pool.JdbcInterceptor</code> class. This class is fairly simple, > You will need to have a no arg constructor</p> >-<source> >- public JdbcInterceptor() { >- } >-</source> >+<source><![CDATA[ public JdbcInterceptor() { >+ }]]></source> > <p> > When a connection is borrowed from the pool, the interceptor can initialize or in some other way react to the event by implementing the >-<source> >- public abstract void reset(ConnectionPool parent, PooledConnection con); >-</source> >+ </p> >+<source><![CDATA[ public abstract void reset(ConnectionPool parent, PooledConnection con);]]></source> >+ <p> > method. This method gets called with two parameters, a reference to the connection pool itself <code>ConnectionPool parent</code> > and a reference to the underlying connection <code>PooledConnection con</code>. > </p> > <p> > When a method on the <code>java.sql.Connection</code> object is invoked, it will cause the >-<source> >- public Object invoke(Object proxy, Method method, Object[] args) throws Throwable >-</source> >+ </p> >+<source><![CDATA[ public Object invoke(Object proxy, Method method, Object[] args) throws Throwable]]></source> >+ <p> > method to get invoked. The <code>Method method</code> is the actual method invoked, and <code>Object[] args</code> are the arguments. > To look at a very simple example, where we demonstrate how to make the invokation to <code>java.sql.Connection.close()</code> a noop > if the connection has been closed >-<source> >- if (CLOSE_VAL==method.getName()) { >+ </p> >+<source><![CDATA[ if (CLOSE_VAL==method.getName()) { > if (isClosed()) return null; //noop for already closed. > } >- return super.invoke(proxy,method,args); >-</source> >+ return super.invoke(proxy,method,args);]]></source> >+ <p> > There is an observation being made. It is the comparison of the method name. One way to do this would be to do > <code>"close".equals(method.getName())</code>. > Above we see a direct reference comparison between the method name and <code>static final String</code> reference. > According to the JVM spec, method names and static final String end up in a shared constant pool, so the reference comparison should work. > One could of course do this as well: >-<source> >- if (compare(CLOSE_VAL,method)) { >+ </p> >+<source><![CDATA[ if (compare(CLOSE_VAL,method)) { > if (isClosed()) return null; //noop for already closed. > } >- return super.invoke(proxy,method,args); >-</source> >+ return super.invoke(proxy,method,args);]]></source> >+ <p> > The <code>compare(String,Method)</code> will use the <code>useEquals</code> flag on an interceptor and do either reference comparison or > a string value comparison when the <code>useEquals=true</code> flag is set. > </p> >@@ -839,37 +829,35 @@ > <p>Pool start/stop<br/> > When the connection pool is started or closed, you can be notifed. You will only be notified once per interceptor class > even though it is an instance method. and you will be notified using an interceptor currently not attached to a pool. >-<source> >- public void poolStarted(ConnectionPool pool) { >+ </p> >+<source><![CDATA[ public void poolStarted(ConnectionPool pool) { > } > > public void poolClosed(ConnectionPool pool) { >- } >-</source> >+ }]]></source> >+ <p> > When overriding these methods, don't forget to call super if you are extending a class other than <code>JdbcInterceptor</code> > </p> > <p>Configuring interceptors<br/> > Interceptors are configured using the <code>jdbcInterceptors</code> property or the <code>setJdbcInterceptors</code> method. > An interceptor can have properties, and would be configured like this >-<source> >- String jdbcInterceptors= >- "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState(useEquals=true,fast=yes)" >-</source> > </p> >+<source><![CDATA[ String jdbcInterceptors= >+ "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState(useEquals=true,fast=yes)"]]></source> >+ > <p>Interceptor properties<br/> > Since interceptors can have properties, you need to be able to read the values of these properties within your > interceptor. Taking an example like the one above, you can override the <code>setProperties</code> method. >-<source> >- public void setProperties(Map<String, InterceptorProperty> properties) { >+ </p> >+<source><![CDATA[ public void setProperties(Map<String, InterceptorProperty> properties) { > super.setProperties(properties); >- final String myprop = "myprop"; >+ final String myprop = "myprop"; > InterceptorProperty p1 = properties.get(myprop); > if (p1!=null) { > setMyprop(Long.parseLong(p1.getValue())); > } >- } >-</source> >- </p> >+ }]]></source> >+ > </subsection> > <subsection name="Getting the actual JDBC connection"> > <p>Connection pools create wrappers around the actual connection in order to properly pool them. >@@ -876,11 +864,10 @@ > We also create interceptors in these wrappers to be able to perform certain functions. > If there is a need to retrieve the actual connection, one can do so using the <code>javax.sql.PooledConnection</code> > interface. >-<source> >- Connection con = datasource.getConnection(); >- Connection actual = ((javax.sql.PooledConnection)con).getConnection(); >-</source> > </p> >+<source><![CDATA[ Connection con = datasource.getConnection(); >+ Connection actual = ((javax.sql.PooledConnection)con).getConnection();]]></source> >+ > </subsection> > > </section> >@@ -890,25 +877,22 @@ > <p>Other examples of Tomcat configuration for JDBC usage can be found <a href="http://tomcat.apache.org/tomcat-6.0-doc/jndi-datasource-examples-howto.html">in the Tomcat documentation</a>. </p> > <subsection name="Building from source"> > <p>Building is pretty simple. The pool has a dependency on <code>tomcat-juli.jar</code> and in case you want the <code>SlowQueryReportJmx</code></p> >-<source> >- javac -classpath tomcat-juli.jar \ >+<source><![CDATA[ javac -classpath tomcat-juli.jar \ > -d . \ > org/apache/tomcat/jdbc/pool/*.java \ > org/apache/tomcat/jdbc/pool/interceptor/*.java \ >- org/apache/tomcat/jdbc/pool/jmx/*.java >-</source> >+ org/apache/tomcat/jdbc/pool/jmx/*.java]]></source> > <p> > A build file can be found in the Tomcat <a href="http://svn.apache.org/viewvc/tomcat/trunk/modules/jdbc-pool/">source repository</a>. > </p> > <p> > As a convenience, a build file is also included where a simple build command will generate all files needed. >-<source> >- ant download (downloads dependencies) >+ </p> >+<source> ant download (downloads dependencies) > ant build (compiles and generates .jar files) > ant dist (creates a release package) >- ant test (runs tests, expects a test database to be setup) >-</source> >- </p> >+ ant test (runs tests, expects a test database to be setup)</source> >+ > <p> > The system is structured for a Maven build, but does generate release artifacts. Just the library itself. > </p> >Index: webapps/docs/aio.xml >=================================================================== >--- webapps/docs/aio.xml (revision 1518039) >+++ webapps/docs/aio.xml (working copy) >@@ -161,12 +161,11 @@ > described above: > </p> > >- <source> >-public class ChatServlet >+ <source><![CDATA[public class ChatServlet > extends HttpServlet implements CometProcessor { > >- protected ArrayList<HttpServletResponse> connections = >- new ArrayList<HttpServletResponse>(); >+ protected ArrayList<HttpServletResponse> connections = >+ new ArrayList<HttpServletResponse>(); > protected MessageSender messageSender = null; > > public void init() throws ServletException { >@@ -197,8 +196,8 @@ > if (event.getEventType() == CometEvent.EventType.BEGIN) { > log("Begin for session: " + request.getSession(true).getId()); > PrintWriter writer = response.getWriter(); >- writer.println("<!doctype html public \"-//w3c//dtd html 4.0 transitional//en\">"); >- writer.println("<head><title>JSP Chat</title></head><body bgcolor=\"#FFFFFF\">"); >+ writer.println("<!DOCTYPE html>"); >+ writer.println("<head><title>JSP Chat</title></head><body>"); > writer.flush(); > synchronized(connections) { > connections.add(response); >@@ -215,7 +214,7 @@ > connections.remove(response); > } > PrintWriter writer = response.getWriter(); >- writer.println("</body></html>"); >+ writer.println("</body></html>"); > event.close(); > } else if (event.getEventType() == CometEvent.EventType.READ) { > InputStream is = request.getInputStream(); >@@ -222,10 +221,10 @@ > byte[] buf = new byte[512]; > do { > int n = is.read(buf); //can throw an IOException >- if (n > 0) { >+ if (n > 0) { > log("Read " + n + " bytes: " + new String(buf, 0, n) > + " for session: " + request.getSession(true).getId()); >- } else if (n < 0) { >+ } else if (n < 0) { > error(event, request, response); > return; > } >@@ -236,7 +235,7 @@ > public class MessageSender implements Runnable { > > protected boolean running = true; >- protected ArrayList<String> messages = new ArrayList<String>(); >+ protected ArrayList<String> messages = new ArrayList<String>(); > > public MessageSender() { > } >@@ -276,11 +275,11 @@ > messages.clear(); > } > // Send any pending message on all the open connections >- for (int i = 0; i < connections.size(); i++) { >+ for (int i = 0; i < connections.size(); i++) { > try { > PrintWriter writer = connections.get(i).getWriter(); >- for (int j = 0; j < pendingMessages.length; j++) { >- writer.println(pendingMessages[j] + "<br>"); >+ for (int j = 0; j < pendingMessages.length; j++) { >+ writer.println(pendingMessages[j] + "<br>"); > } > writer.flush(); > } catch (IOException e) { >@@ -295,16 +294,17 @@ > > } > >-} >- </source> >+}]]></source> > > </subsection> > <subsection name="Comet timeouts"> > <p>If you are using the NIO connector, you can set individual timeouts for your different comet connections. >- To set a timeout, simply set a request attribute like the following code shows: >- <source>CometEvent event.... event.setTimeout(30*1000);</source> or >- <source>event.getHttpServletRequest().setAttribute("org.apache.tomcat.comet.timeout", new Integer(30 * 1000));</source> >- This sets the timeout to 30 seconds. >+ To set a timeout, simply set a request attribute like the following code shows:</p> >+ <source>CometEvent event.... event.setTimeout(30*1000);</source> >+ <p>or</p> >+ <source>event.getHttpServletRequest().setAttribute("org.apache.tomcat.comet.timeout", new Integer(30 * 1000));</source> >+ <p> >+ This sets the timeout to 30 seconds. > Important note: in order to set this timeout, it has to be done on the <code>BEGIN</code> event. > The default value is <code>soTimeout</code> > </p> >Index: webapps/docs/apr.xml >=================================================================== >--- webapps/docs/apr.xml (revision 1518039) >+++ webapps/docs/apr.xml (working copy) >@@ -57,12 +57,12 @@ > > <p> > APR support requires three main native components to be installed: >- <ul> >- <li>APR library</li> >- <li>JNI wrappers for APR used by Tomcat (libtcnative)</li> >- <li>OpenSSL libraries</li> >- </ul> > </p> >+ <ul> >+ <li>APR library</li> >+ <li>JNI wrappers for APR used by Tomcat (libtcnative)</li> >+ <li>OpenSSL libraries</li> >+ </ul> > > <subsection name="Windows"> > >@@ -87,13 +87,13 @@ > > <p> > Requirements: >- <ul> >- <li>APR 1.2+ development headers (libapr1-dev package)</li> >- <li>OpenSSL 0.9.7+ development headers (libssl-dev package)</li> >- <li>JNI headers from Java compatible JDK 1.4+</li> >- <li>GNU development environment (gcc, make)</li> >- </ul> > </p> >+ <ul> >+ <li>APR 1.2+ development headers (libapr1-dev package)</li> >+ <li>OpenSSL 0.9.7+ development headers (libssl-dev package)</li> >+ <li>JNI headers from Java compatible JDK 1.4+</li> >+ <li>GNU development environment (gcc, make)</li> >+ </ul> > > <p> > The wrapper library sources are located in the Tomcat binary bundle, in the >@@ -100,8 +100,8 @@ > <code>bin/tomcat-native.tar.gz</code> archive. > Once the build environment is installed and the source archive is extracted, the wrapper library > can be compiled using (from the folder containing the configure script): >- <source>./configure && make && make install</source> > </p> >+ <source>./configure && make && make install</source> > > </subsection> > >@@ -119,18 +119,19 @@ > > <p> > When APR is enabled, the following features are also enabled in Tomcat: >- <ul> >- <li>Secure session ID generation by default on all platforms (platforms other than Linux required >- random number generation using a configured entropy)</li> >- <li>OS level statistics on memory usage and CPU usage by the Tomcat process are displayed by >- the status servlet</li> >- </ul> > </p> >+ <ul> >+ <li>Secure session ID generation by default on all platforms (platforms other than Linux required >+ random number generation using a configured entropy)</li> >+ <li>OS level statistics on memory usage and CPU usage by the Tomcat process are displayed by >+ the status servlet</li> >+ </ul> > > </section> > > <section name="APR Lifecycle Listener Configuration"> > <subsection name="AprLifecycleListener"> >+ <attributes> > <attribute name="SSLEngine" required="false"> > <p> > Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no specific ENGINE. >@@ -137,14 +138,14 @@ > The default value is <b>on</b>. > This initializes the native SSL engine, then enable the use of this engine in the connector > using the <code>SSLEnabled</code> attribute. Example: >- <source> >-<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" /> >- </source> >- </p> >+ </p> >+ <source><![CDATA[<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />]]></source> >+ > <p>See the <a href="http://www.openssl.org">Official OpenSSL > website</a> for more details on SSL hardware engines and manufacturers. > </p> > </attribute> >+ </attributes> > </subsection> > </section> > >@@ -156,19 +157,18 @@ > connector configuration documentation.</p> > > <p>For HTTPS configuration, see the >- <a href="config/http.html#SSL%20Support">HTTPS</a> connector configuration >+ <a href="config/http.html#SSL_Support">HTTPS</a> connector configuration > documentation.</p> > >- <p>An example SSL Connector declaration is: >- <source> >- <Connector port="443" maxHttpHeaderSize="8192" >+ <p>An example SSL Connector declaration is:</p> >+ <source><![CDATA[<Connector port="443" maxHttpHeaderSize="8192" > maxThreads="150" > enableLookups="false" disableUploadTimeout="true" > acceptCount="100" scheme="https" secure="true" > SSLEnabled="true" > SSLCertificateFile="${catalina.base}/conf/localhost.crt" >- SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" /></source> >- </p> >+ SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" />]]></source> >+ > > </subsection> > >Index: webapps/docs/building.xml >=================================================================== >--- webapps/docs/building.xml (revision 1518039) >+++ webapps/docs/building.xml (working copy) >@@ -107,10 +107,10 @@ > > <p> > Use the following commands to build Tomcat: >-<br/> >-<code><br/> >+<br/><br/> >+<code> > cd ${tomcat.source}<br/> >- ant<br/> >+ ant > </code> > </p> > >@@ -133,21 +133,19 @@ > <p> > The build can be controlled by creating a <code>${tomcat.source}/build.properties</code> > file and adding the following content to it: >-<br/> >-<code><br/> >- # ----- Proxy setup -----<br/> >- # Uncomment if using a proxy server.<br/> >- #proxy.host=proxy.domain<br/> >- #proxy.port=8080<br/> >- #proxy.use=on<br/> >-<br/> >- # ----- Default Base Path for Dependent Packages -----<br/> >- # Replace this path with the directory path where<br/> >- # dependencies binaries should be downloaded.<br/> >- base.path=/home/me/some-place-to-download-to<br/> >-</code> > </p> >+<source># ----- Proxy setup ----- >+# Uncomment if using a proxy server. >+#proxy.host=proxy.domain >+#proxy.port=8080 >+#proxy.use=on > >+# ----- Default Base Path for Dependent Packages ----- >+# Replace this path with the directory path where >+# dependencies binaries should be downloaded. >+base.path=/home/me/some-place-to-download-to</source> >+ >+ > <p> > Once the build has completed successfully, a usable Tomcat installation will have been > produced in the <code>${tomcat.source}/output/build</code> directory, and can be started >@@ -204,14 +202,14 @@ > Variables</em> to add two new <em>Classpath Variables</em>: > </p> > >-<p> >-<table border="1"> >+ >+<table class="defaultTable"> > <tr><td>TOMCAT_LIBS_BASE</td><td>The same location as the <code>base.path</code> > setting in <code>build.properties</code>, where the binary dependencies have been downloaded</td></tr> > <tr><td>ANT_HOME</td><td>the base path of Ant 1.8.1 or later</td></tr> > </table> >-</p> > >+ > <p> > Use <em>File->Import</em> and choose <em>Existing Projects into Workspace</em>. > From there choose the root directory of the Tomcat source tree (<code>${tomcat.source}</code>) >@@ -232,8 +230,8 @@ > Tweaking a few formatting preferences will make it much easier to keep consistent with Tomcat > coding conventions (and have your contributions accepted): > </p> >-<p> >-<table border="1"> >+ >+<table class="defaultTable"> > <tr><td>Java -> Code Style -> Formatter -> Edit...</td> > <td>Tab policy: Spaces only<br/>Tab and Indentation size: 4</td></tr> > <tr><td>General -> Editors -> Text Editors</td> >@@ -241,8 +239,8 @@ > <tr><td>XML -> XML Files -> Editor</td><td>Indent using spaces<br/>Indentation size: 2</td></tr> > <tr><td>Ant -> Editor -> Formatter</td><td>Tab size: 2<br/>Use tab character instead of spaces: unchecked</td></tr> > </table> >-</p> > >+ > </section> > > <section name="Building with other IDEs"> >Index: webapps/docs/cgi-howto.xml >=================================================================== >--- webapps/docs/cgi-howto.xml (revision 1518039) >+++ webapps/docs/cgi-howto.xml (working copy) >@@ -72,7 +72,7 @@ > <section name="Configuration"> > > <p>There are several servlet init parameters which can be used to >-configure the behaviour of the CGI servlet. >+configure the behaviour of the CGI servlet.</p> > <ul> > <li><strong>cgiPathPrefix</strong> - The CGI search path will start at > the web application root directory + File.separator + this prefix. >@@ -96,8 +96,8 @@ > the reading of stderr to complete before terminating the CGI process. Default > is 2000.</li> > </ul> >-</p> > >+ > </section> > > </body> >Index: webapps/docs/class-loader-howto.xml >=================================================================== >--- webapps/docs/class-loader-howto.xml (revision 1518039) >+++ webapps/docs/class-loader-howto.xml (working copy) >@@ -56,15 +56,13 @@ > organized into the following parent-child relationships, where the parent > class loader is above the child class loader:</p> > >-<source> >- Bootstrap >+<source> Bootstrap > | > System > | > Common > / \ >- Webapp1 Webapp2 ... >-</source> >+ Webapp1 Webapp2 ...</source> > > <p>The characteristics of each of these class loaders, including the source > of classes and resources that they make visible, are discussed in detail in >Index: webapps/docs/cluster-howto.xml >=================================================================== >--- webapps/docs/cluster-howto.xml (revision 1518039) >+++ webapps/docs/cluster-howto.xml (working copy) >@@ -41,7 +41,10 @@ > > <section name="For the impatient"> > <p> >- Simply add <source><Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/></source> >+ Simply add >+ </p> >+ <source><Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/></source> >+ <p> > to your <code><Engine></code> or your <code><Host></code> element to enable clustering. > </p> > <p> >@@ -51,57 +54,60 @@ > Also when using the delta manager it will replicate to all nodes, even nodes that don't have the application deployed.<br/> > To get around this problem, you'll want to use the BackupManager. This manager only replicates the session data to one backup > node, and only to nodes that have the application deployed. Downside of the BackupManager: not quite as battle tested as the delta manager. >- <br/> >- Here are some of the important default values:<br/> >- 1. Multicast address is 228.0.0.4<br/> >- 2. Multicast port is 45564 (the port and the address together determine cluster membership.<br/> >- 3. The IP broadcasted is <code>java.net.InetAddress.getLocalHost().getHostAddress()</code> (make sure you don't broadcast 127.0.0.1, this is a common error)<br/> >- 4. The TCP port listening for replication messages is the first available server socket in range <code>4000-4100</code><br/> >- 5. Two listeners are configured <code>ClusterSessionListener</code><br/> >- 6. Two interceptors are configured <code>TcpFailureDetector</code> and <code>MessageDispatch15Interceptor</code><br/> >- The following is the default cluster configuration:<br/> >- <source> >- <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" >- channelSendOptions="8"> >+ </p> >+ <p> >+ Here are some of the important default values: >+ </p> >+ <ol> >+ <li>Multicast address is 228.0.0.4</li> >+ <li>Multicast port is 45564 (the port and the address together determine cluster membership.</li> >+ <li>The IP broadcasted is <code>java.net.InetAddress.getLocalHost().getHostAddress()</code> (make sure you don't broadcast 127.0.0.1, this is a common error)</li> >+ <li>The TCP port listening for replication messages is the first available server socket in range <code>4000-4100</code></li> >+ <li>Two listeners are configured <code>ClusterSessionListener</code></li> >+ <li>Two interceptors are configured <code>TcpFailureDetector</code> and <code>MessageDispatch15Interceptor</code></li> >+ </ol> >+ <p> >+ The following is the default cluster configuration: >+ </p> >+ <source><![CDATA[ <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" >+ channelSendOptions="8"> > >- <Manager className="org.apache.catalina.ha.session.DeltaManager" >- expireSessionsOnShutdown="false" >- notifyListenersOnReplication="true"/> >+ <Manager className="org.apache.catalina.ha.session.DeltaManager" >+ expireSessionsOnShutdown="false" >+ notifyListenersOnReplication="true"/> > >- <Channel className="org.apache.catalina.tribes.group.GroupChannel"> >- <Membership className="org.apache.catalina.tribes.membership.McastService" >- address="228.0.0.4" >- port="45564" >- frequency="500" >- dropTime="3000"/> >- <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" >- address="auto" >- port="4000" >- autoBind="100" >- selectorTimeout="5000" >- maxThreads="6"/> >+ <Channel className="org.apache.catalina.tribes.group.GroupChannel"> >+ <Membership className="org.apache.catalina.tribes.membership.McastService" >+ address="228.0.0.4" >+ port="45564" >+ frequency="500" >+ dropTime="3000"/> >+ <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" >+ address="auto" >+ port="4000" >+ autoBind="100" >+ selectorTimeout="5000" >+ maxThreads="6"/> > >- <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> >- <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> >- </Sender> >- <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> >- <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> >- </Channel> >+ <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> >+ <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> >+ </Sender> >+ <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> >+ <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> >+ </Channel> > >- <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" >- filter=""/> >- <Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/> >+ <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" >+ filter=""/> >+ <Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/> > >- <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" >- tempDir="/tmp/war-temp/" >- deployDir="/tmp/war-deploy/" >- watchDir="/tmp/war-listen/" >- watchEnabled="false"/> >+ <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" >+ tempDir="/tmp/war-temp/" >+ deployDir="/tmp/war-deploy/" >+ watchDir="/tmp/war-listen/" >+ watchEnabled="false"/> > >- <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> >- </Cluster> >- </source> >- </p> >+ <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> >+ </Cluster>]]></source> > <p>Will cover this section in more detail later in this document.</p> > </section> > >@@ -128,7 +134,7 @@ > side otherwise, a new session will be created.</p> > <p>Note: Clustering support currently requires the JDK version 1.5 or later.</p> > <p>The Cluster module uses the Tomcat JULI logging framework, so you can configure logging >- through the regular logging.properties file. To track messages, you can enable logging on the key:<code>org.apache.catalina.tribes.MESSAGES</code></p> >+ through the regular logging.properties file. To track messages, you can enable logging on the key: <code>org.apache.catalina.tribes.MESSAGES</code></p> > </section> > > >@@ -152,15 +158,13 @@ > A very simple setup would look like this: > </p> > >-<source> >- DNS Round Robin >+<source> DNS Round Robin > | > Load Balancer > / \ > Cluster1 Cluster2 > / \ / \ >- Tomcat1 Tomcat2 Tomcat3 Tomcat4 >-</source> >+ Tomcat1 Tomcat2 Tomcat3 Tomcat4</source> > > <p>What is important to mention here, is that session replication is only the beginning of clustering. > Another popular concept used to implement clusters is farming, i.e., you deploy your apps only to one >@@ -231,58 +235,54 @@ > </section> > > <section name="Configuration Example"> >- <source> >- <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" >- channelSendOptions="6"> >+ <source><![CDATA[ <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" >+ channelSendOptions="6"> > >- <Manager className="org.apache.catalina.ha.session.BackupManager" >- expireSessionsOnShutdown="false" >- notifyListenersOnReplication="true" >- mapSendOptions="6"/> >- <!-- >- <Manager className="org.apache.catalina.ha.session.DeltaManager" >- expireSessionsOnShutdown="false" >- notifyListenersOnReplication="true"/> >- --> >- <Channel className="org.apache.catalina.tribes.group.GroupChannel"> >- <Membership className="org.apache.catalina.tribes.membership.McastService" >- address="228.0.0.4" >- port="45564" >- frequency="500" >- dropTime="3000"/> >- <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" >- address="auto" >- port="5000" >- selectorTimeout="100" >- maxThreads="6"/> >+ <Manager className="org.apache.catalina.ha.session.BackupManager" >+ expireSessionsOnShutdown="false" >+ notifyListenersOnReplication="true" >+ mapSendOptions="6"/> >+ <!-- >+ <Manager className="org.apache.catalina.ha.session.DeltaManager" >+ expireSessionsOnShutdown="false" >+ notifyListenersOnReplication="true"/> >+ --> >+ <Channel className="org.apache.catalina.tribes.group.GroupChannel"> >+ <Membership className="org.apache.catalina.tribes.membership.McastService" >+ address="228.0.0.4" >+ port="45564" >+ frequency="500" >+ dropTime="3000"/> >+ <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" >+ address="auto" >+ port="5000" >+ selectorTimeout="100" >+ maxThreads="6"/> > >- <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> >- <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> >- </Sender> >- <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> >- <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> >- <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/> >- </Channel> >+ <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> >+ <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> >+ </Sender> >+ <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> >+ <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> >+ <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/> >+ </Channel> > >- <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" >- filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"/> >+ <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" >+ filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"/> > >- <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" >- tempDir="/tmp/war-temp/" >- deployDir="/tmp/war-deploy/" >- watchDir="/tmp/war-listen/" >- watchEnabled="false"/> >+ <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" >+ tempDir="/tmp/war-temp/" >+ deployDir="/tmp/war-deploy/" >+ watchDir="/tmp/war-listen/" >+ watchEnabled="false"/> > >- <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> >- </Cluster> >- </source> >+ <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> >+ </Cluster>]]></source> > <p> > Break it down!! > </p> >- <source> >- <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" >- channelSendOptions="6"> >- </source> >+ <source><![CDATA[ <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" >+ channelSendOptions="6">]]></source> > <p> > The main element, inside this element all cluster details can be configured. > The <code>channelSendOptions</code> is the flag that is attached to each message sent by the >@@ -293,17 +293,15 @@ > sends it itself directly through the channel. > <br/>For more info, Please visit the <a href="config/cluster.html">reference documentation</a> > </p> >- <source> >- <Manager className="org.apache.catalina.ha.session.BackupManager" >- expireSessionsOnShutdown="false" >- notifyListenersOnReplication="true" >- mapSendOptions="6"/> >- <!-- >- <Manager className="org.apache.catalina.ha.session.DeltaManager" >- expireSessionsOnShutdown="false" >- notifyListenersOnReplication="true"/> >- --> >- </source> >+ <source><![CDATA[ <Manager className="org.apache.catalina.ha.session.BackupManager" >+ expireSessionsOnShutdown="false" >+ notifyListenersOnReplication="true" >+ mapSendOptions="6"/> >+ <!-- >+ <Manager className="org.apache.catalina.ha.session.DeltaManager" >+ expireSessionsOnShutdown="false" >+ notifyListenersOnReplication="true"/> >+ -->]]></source> > <p> > This is a template for the manager configuration that will be used if no manager is defined in the <Context> > element. In Tomcat 5.x each webapp marked distributable had to use the same manager, this is no longer the case >@@ -313,21 +311,17 @@ > and create a manager instance cloning this configuration. > <br/>For more info, Please visit the <a href="config/cluster-manager.html">reference documentation</a> > </p> >- <source> >- <Channel className="org.apache.catalina.tribes.group.GroupChannel"> >- </source> >+ <source><![CDATA[ <Channel className="org.apache.catalina.tribes.group.GroupChannel">]]></source> > <p> > The channel element is <a href="tribes/introduction.html">Tribes</a>, the group communication framework > used inside Tomcat. This element encapsulates everything that has to do with communication and membership logic. > <br/>For more info, Please visit the <a href="config/cluster-channel.html">reference documentation</a> > </p> >- <source> >- <Membership className="org.apache.catalina.tribes.membership.McastService" >- address="228.0.0.4" >- port="45564" >- frequency="500" >- dropTime="3000"/> >- </source> >+ <source><![CDATA[ <Membership className="org.apache.catalina.tribes.membership.McastService" >+ address="228.0.0.4" >+ port="45564" >+ frequency="500" >+ dropTime="3000"/>]]></source> > <p> > Membership is done using multicasting. Please note that Tribes also supports static memberships using the > <code>StaticMembershipInterceptor</code> if you want to extend your membership to points beyond multicasting. >@@ -339,13 +333,11 @@ > <code>Receiver.address</code> attribute. > <br/>For more info, Please visit the <a href="config/cluster-membership.html">reference documentation</a> > </p> >- <source> >- <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" >- address="auto" >- port="5000" >- selectorTimeout="100" >- maxThreads="6"/> >- </source> >+ <source><![CDATA[ <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" >+ address="auto" >+ port="5000" >+ selectorTimeout="100" >+ maxThreads="6"/>]]></source> > <p> > In tribes the logic of sending and receiving data has been broken into two functional components. The Receiver, as the name suggests > is responsible for receiving messages. Since the Tribes stack is thread less, (a popular improvement now adopted by other frameworks as well), >@@ -353,12 +345,9 @@ > The address attribute is the host address that will be broadcasted by the membership component to the other nodes. > <br/>For more info, Please visit the <a href="config/cluster-receiver.html">reference documentation</a> > </p> >- <source> >- >- <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> >- <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> >- </Sender> >- </source> >+ <source><![CDATA[ <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> >+ <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> >+ </Sender>]]></source> > <p> > The sender component, as the name indicates is responsible for sending messages to other nodes. > The sender has a shell component, the <code>ReplicationTransmitter</code> but the real stuff done is done in the >@@ -369,12 +358,10 @@ > at the same time. > <br/>For more info, Please visit the <a href="config/cluster-sender.html">reference documentation</a> > </p> >- <source> >- <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> >- <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> >- <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/> >- </Channel> >- </source> >+ <source><![CDATA[ <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> >+ <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> >+ <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/> >+ </Channel>]]></source> > <p> > Tribes uses a stack to send messages through. Each element in the stack is called an interceptor, and works much like the valves do > in the Tomcat servlet container. >@@ -387,10 +374,8 @@ > channel stack. Think of it as a linked list, with the head being the first most interceptor and the tail the last. > <br/>For more info, Please visit the <a href="config/cluster-interceptor.html">reference documentation</a> > </p> >- <source> >- <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" >- filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"/> >- </source> >+ <source><![CDATA[ <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" >+ filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"/>]]></source> > <p> > The cluster uses valves to track requests to web applications, we've mentioned the ReplicationValve and the JvmRouteBinderValve above. > The <Cluster> element itself is not part of the pipeline in Tomcat, instead the cluster adds the valve to its parent container. >@@ -397,13 +382,11 @@ > If the <Cluster> elements is configured in the <Engine> element, the valves get added to the engine and so on. > <br/>For more info, Please visit the <a href="config/cluster-valve.html">reference documentation</a> > </p> >- <source> >- <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" >- tempDir="/tmp/war-temp/" >- deployDir="/tmp/war-deploy/" >- watchDir="/tmp/war-listen/" >- watchEnabled="false"/> >- </source> >+ <source><![CDATA[ <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" >+ tempDir="/tmp/war-temp/" >+ deployDir="/tmp/war-deploy/" >+ watchDir="/tmp/war-listen/" >+ watchEnabled="false"/>]]></source> > <p> > The default tomcat cluster supports farmed deployment, ie, the cluster can deploy and undeploy applications on the other nodes. > The state of this component is currently in flux but will be addressed soon. There was a change in the deployment algorithm >@@ -411,10 +394,8 @@ > webapps directory. > <br/>For more info, Please visit the <a href="config/cluster-deployer.html">reference documentation</a> > </p> >- <source> >- <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> >- </Cluster> >- </source> >+ <source><![CDATA[ <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> >+ </Cluster>]]></source> > <p> > Since the SimpleTcpCluster itself is a sender and receiver of the Channel object, components can register themselves as listeners to > the SimpleTcpCluster. The listener above <code>ClusterSessionListener</code> listens for DeltaManager replication messages >@@ -426,9 +407,8 @@ > > <section name="Cluster Architecture"> > >-<p><b>Component Levels:</b> >-<source> >- Server >+<p><b>Component Levels:</b></p> >+<source> Server > | > Service > | >@@ -473,10 +453,9 @@ > \ > -- FarmWarDeployer > >- > </source> >-</p> > >+ > </section> > <section name="How it Works"> > <p>To make it easy to understand how clustering works, We are gonna take you through a series of scenarios. >@@ -507,7 +486,7 @@ > Tomcat will create a <code>DeltaManager</code> for that context instead of a <code>StandardManager</code>. > The cluster class will start up a membership service (multicast) and a replication service (tcp unicast). > More on the architecture further down in this document. >- </p><p></p> >+ </p> > </li> > <li><b><code>TomcatB</code> starts up</b> > <p> >@@ -520,7 +499,7 @@ > entry. The session state gets transferred for each web application that has distributable in > its web.xml. Note: To use session replication efficiently, all your tomcat instances should be > configured the same. >- </p><p></p> >+ </p> > </li> > <li><B><code>TomcatA</code> receives a request, a session <code>S1</code> is created.</B> > <p> >@@ -534,7 +513,7 @@ > in the session without calling setAttribute or removeAttribute to be replicated. > a useDirtyFlag configuration parameter can be used to optimize the number of times > a session is replicated. >- </p><p></p> >+ </p> > > </li> > <li><b><code>TomcatA</code> crashes</b> >@@ -544,11 +523,11 @@ > be notified of any changes that occurs in TomcatB. > The load balancer will redirect the requests from TomcatA to TomcatB and all the sessions > are current. >- </p><p></p> >+ </p> > </li> > <li><b><code>TomcatB</code> receives a request for session <code>S1</code></b> > <p>Nothing exciting, TomcatB will process the request as any other request. >- </p><p></p> >+ </p> > </li> > <li><b><code>TomcatA</code> starts up</b> > <p>Upon start up, before TomcatA starts taking new request and making itself >@@ -556,18 +535,18 @@ > It will join the cluster, contact TomcatB for the current state of all the sessions. > And once it receives the session state, it finishes loading and opens its HTTP/mod_jk ports. > So no requests will make it to TomcatA until it has received the session state from TomcatB. >- </p><p></p> >+ </p> > </li> > <li><b><code>TomcatA</code> receives a request, invalidate is called on the session (<code>S1</code>)</b> > <p>The invalidate is call is intercepted, and the session is queued with invalidated sessions. > When the request is complete, instead of sending out the session that has changed, it sends out > an "expire" message to TomcatB and TomcatB will invalidate the session as well. >- </p><p></p> >+ </p> > > </li> > <li><b><code>TomcatB</code> receives a request, for a new session (<code>S2</code>)</b> > <p>Same scenario as in step 3) >- </p><p></p> >+ </p> > > > </li> >@@ -576,7 +555,7 @@ > and the session is queued with invalidated sessions. > At this point, the invalidet session will not be replicated across until > another request comes through the system and checks the invalid queue. >- </p><p></p> >+ </p> > </li> > </ol> > >@@ -613,24 +592,23 @@ > > <section name="Monitoring your Cluster with JMX"> > <p>Monitoring is a very important question when you use a cluster. Some of the cluster objects are JMX MBeans </p> >-<p>Add the following parameter to your startup script with Java 5: >-<source> >-set CATALINA_OPTS=\ >+<p>Add the following parameter to your startup script with Java 5:</p> >+<source>set CATALINA_OPTS=\ > -Dcom.sun.management.jmxremote \ > -Dcom.sun.management.jmxremote.port=%my.jmx.port% \ > -Dcom.sun.management.jmxremote.ssl=false \ >--Dcom.sun.management.jmxremote.authenticate=false >-</source> >+-Dcom.sun.management.jmxremote.authenticate=false</source> >+ >+<p> >+ List of Cluster Mbeans > </p> >-<p> >-List of Cluster Mbeans<br/> >-<table border="1" cellpadding="5"> >+<table class="defaultTable"> > > <tr> >- <th align="center" bgcolor="aqua">Name</th> >- <th align="center" bgcolor="aqua">Description</th> >- <th align="center" bgcolor="aqua">MBean ObjectName - Engine</th> >- <th align="center" bgcolor="aqua">MBean ObjectName - Host</th> >+ <th>Name</th> >+ <th>Description</th> >+ <th>MBean ObjectName - Engine</th> >+ <th>MBean ObjectName - Host</th> > </tr> > > <tr> >@@ -678,7 +656,6 @@ > </tr> > > </table> >-</p> > </section> > > <section name="FAQ"> >Index: webapps/docs/connectors.xml >=================================================================== >--- webapps/docs/connectors.xml (revision 1518039) >+++ webapps/docs/connectors.xml (working copy) >@@ -64,13 +64,12 @@ > proxied HTTP. AJP clustering is the most efficient from the Tomcat perspective. > It is otherwise functionally equivalent to HTTP clustering.</p> > >-<p>The native connectors supported with this Tomcat release are: >+<p>The native connectors supported with this Tomcat release are:</p> > <ul> > <li>JK 1.2.x with any of the supported servers</li> > <li>mod_proxy on Apache HTTP Server 2.x (included by default in Apache HTTP Server 2.2), > with AJP enabled</li> > </ul> >-</p> > > <p><b>Other native connectors supporting AJP may work, but are no longer supported.</b></p> > >Index: webapps/docs/default-servlet.xml >=================================================================== >--- webapps/docs/default-servlet.xml (revision 1518039) >+++ webapps/docs/default-servlet.xml (working copy) >@@ -34,59 +34,56 @@ > </section> > > <section anchor="what" name="What is the DefaultServlet"> >+<p> > The default servlet is the servlet which serves static resources as well > as serves the directory listings (if directory listings are enabled). >- >+</p> > </section> > > <section anchor="where" name="Where is it declared?"> >+<p> > It is declared globally in <i>$CATALINA_BASE/conf/web.xml</i>. > By default here is it's declaration: >-<source> >- <servlet> >- <servlet-name>default</servlet-name> >- <servlet-class> >+</p> >+<source><![CDATA[ <servlet> >+ <servlet-name>default</servlet-name> >+ <servlet-class> > org.apache.catalina.servlets.DefaultServlet >- </servlet-class> >- <init-param> >- <param-name>debug</param-name> >- <param-value>0</param-value> >- </init-param> >- <init-param> >- <param-name>listings</param-name> >- <param-value>false</param-value> >- </init-param> >- <load-on-startup>1</load-on-startup> >- </servlet> >+ </servlet-class> >+ <init-param> >+ <param-name>debug</param-name> >+ <param-value>0</param-value> >+ </init-param> >+ <init-param> >+ <param-name>listings</param-name> >+ <param-value>false</param-value> >+ </init-param> >+ <load-on-startup>1</load-on-startup> >+ </servlet> > > ... > >- <servlet-mapping> >- <servlet-name>default</servlet-name> >- <url-pattern>/</url-pattern> >- </servlet-mapping> >+ <servlet-mapping> >+ <servlet-name>default</servlet-name> >+ <url-pattern>/</url-pattern> >+ </servlet-mapping>]]></source> > >-</source> >- > So by default, the default servlet is loaded at webapp startup and > directory listings are disabled and debugging is turned off. > </section> > > <section anchor="change" name="What can I change?"> >-The DefaultServlet allows the following initParamters: >+<p> >+ The DefaultServlet allows the following initParamters: >+</p> > >-<table border="1"> >- <tr> >- <th valign='top'>debug</th> >- <td valign='top'> >+<properties> >+ <property name="debug"> > Debugging level. It is not very useful unless you are a tomcat > developer. As > of this writing, useful values are 0, 1, 11, 1000. [0] >- </td> >- </tr> >- <tr> >- <th valign='top'>listings</th> >- <td valign='top'> >+ </property> >+ <property name="listings"> > If no welcome file is present, can a directory listing be > shown? > value may be <b>true</b> or <b>false</b> [false] >@@ -96,19 +93,13 @@ > <b>WARNING:</b> Listings of directories containing many entries are > expensive. Multiple requests for large directory listings can consume > significant proportions of server resources. >- </td> >- </tr> >- <tr> >- <th valign='top'>readmeFile</th> >- <td valign='top'> >+ </property> >+ <property name="readmeFile"> > If a directory listing is presented, a readme file may also > be presented with the listing. This file is inserted as is > so it may contain HTML. >- </td> >- </tr> >- <tr> >- <th valign='top'>globalXsltFile</th> >- <td valign='top'> >+ </property> >+ <property name="globalXsltFile"> > If you wish to customize your directory listing, you > can use an XSL transformation. This value is an absolute > file name which be used for all directory listings. >@@ -115,11 +106,8 @@ > This can be overridden per context and/or per directory. See > <strong>contextXsltFile</strong> and <strong>localXsltFile</strong> > below. The format of the xml is shown below. >- </td> >- </tr> >- <tr> >- <th valign='top'>contextXsltFile</th> >- <td valign='top'> >+ </property> >+ <property name="contextXsltFile"> > You may also customize your directory listing by context by > configuring <code>contextXsltFile</code>. This should be a context > relative path (e.g.: <code>/path/to/context.xslt</code>). This >@@ -127,11 +115,8 @@ > file does not exist, then <code>globalXsltFile</code> will be used. If > <code>globalXsltFile</code> does not exist, then the default > directory listing will be shown. >- </td> >- </tr> >- <tr> >- <th valign='top'>localXsltFile</th> >- <td valign='top'> >+ </property> >+ <property name="localXsltFile"> > You may also customize your directory listing by directory by > configuring <code>localXsltFile</code>. This should be a relative > file name in the directory where the listing will take place. >@@ -142,53 +127,33 @@ > <code>globalXsltFile</code> will be used. If > <code>globalXsltFile</code> does not exist, then the default > directory listing will be shown. >- </td> >- </tr> >- <tr> >- <th valign='top'>input</th> >- <td valign='top'> >+ </property> >+ <property name="input"> > Input buffer size (in bytes) when reading > resources to be served. [2048] >- </td> >- </tr> >- <tr> >- <th valign='top'>output</th> >- <td valign='top'> >+ </property> >+ <property name="output"> > Output buffer size (in bytes) when writing > resources to be served. [2048] >- </td> >- </tr> >- <tr> >- <th valign='top'>readonly</th> >- <td valign='top'> >+ </property> >+ <property name="readonly"> > Is this context "read only", so HTTP commands like PUT and > DELETE are rejected? [true] >- </td> >- </tr> >- <tr> >- <th valign='top'>fileEncoding</th> >- <td valign='top'> >+ </property> >+ <property name="fileEncoding"> > File encoding to be used when reading static resources. > [platform default] >- </td> >- </tr> >- <tr> >- <th valign='top'>sendfileSize</th> >- <td valign='top'> >+ </property> >+ <property name="sendfileSize"> > If the connector used supports sendfile, this represents the minimal > file size in KB for which sendfile will be used. Use a negative value > to always disable sendfile. [48] >- </td> >- </tr> >- <tr> >- <th valign='top'>useAcceptRanges</th> >- <td valign='top'> >+ </property> >+ <property name="useAcceptRanges"> > If true, the Accept-Ranges header will be set when appropriate for the > response. [true] >- </td> >- </tr> >- >-</table> >+ </property> >+</properties> > </section> > > <section anchor="dir" name="How do I customize directory listings?"> >@@ -210,102 +175,101 @@ > > <p> > Format: >-<source> >- <listing> >- <entries> >- <entry type='file|dir' urlPath='aPath' size='###' date='gmt date'> >+</p> >+<source><![CDATA[ <listing> >+ <entries> >+ <entry type='file|dir' urlPath='aPath' size='###' date='gmt date'> > fileName1 >- </entry> >- <entry type='file|dir' urlPath='aPath' size='###' date='gmt date'> >+ </entry> >+ <entry type='file|dir' urlPath='aPath' size='###' date='gmt date'> > fileName2 >- </entry> >+ </entry> > ... >- </entries> >- <readme></readme> >- </listing> >-</source> >+ </entries> >+ <readme></readme> >+ </listing>]]></source> > <ul> > <li>size will be missing if <code>type='dir'</code></li> > <li>Readme is a CDATA entry</li> > </ul> >+ >+<p> >+ The following is a sample xsl file which mimics the default tomcat behavior: > </p> >-The following is a sample xsl file which mimics the default tomcat behavior: >-<source> >-<?xml version="1.0"?> >+<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> > >-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" >- version="1.0"> >+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" >+ version="3.0"> > >- <xsl:output method="xhtml" encoding="iso-8859-1" indent="no"/> >+ <xsl:output method="html" html-version="5.0" >+ encoding="UTF-8" indent="no" >+ doctype-system="about:legacy-compat"/> > >- <xsl:template match="listing"> >- <html> >- <head> >- <title> >+ <xsl:template match="listing"> >+ <html> >+ <head> >+ <title> > Sample Directory Listing For >- <xsl:value-of select="@directory"/> >- </title> >- <style> >- h1{color : white;background-color : #0086b2;} >- h3{color : white;background-color : #0086b2;} >- body{font-family : sans-serif,Arial,Tahoma; >+ <xsl:value-of select="@directory"/> >+ </title> >+ <style> >+ h1 {color : white;background-color : #0086b2;} >+ h3 {color : white;background-color : #0086b2;} >+ body {font-family : sans-serif,Arial,Tahoma; > color : black;background-color : white;} >- b{color : white;background-color : #0086b2;} >- a{color : black;} HR{color : #0086b2;} >- </style> >- </head> >- <body> >- <h1>Sample Directory Listing For >- <xsl:value-of select="@directory"/> >- </h1> >- <hr size="1" /> >- <table cellspacing="0" >- width="100%" >- cellpadding="5" >- align="center"> >- <tr> >- <th align="left">Filename</th> >- <th align="center">Size</th> >- <th align="right">Last Modified</th> >- </tr> >- <xsl:apply-templates select="entries"/> >- </table> >- <xsl:apply-templates select="readme"/> >- <hr size="1" /> >- <h3>Apache Tomcat/7.0</h3> >- </body> >- </html> >- </xsl:template> >+ b {color : white;background-color : #0086b2;} >+ a {color : black;} HR{color : #0086b2;} >+ table td { padding: 5px; } >+ </style> >+ </head> >+ <body> >+ <h1>Sample Directory Listing For >+ <xsl:value-of select="@directory"/> >+ </h1> >+ <hr style="height: 1px;" /> >+ <table style="width: 100%;"> >+ <tr> >+ <th style="text-align: left;">Filename</th> >+ <th style="text-align: center;">Size</th> >+ <th style="text-align: right;">Last Modified</th> >+ </tr> >+ <xsl:apply-templates select="entries"/> >+ </table> >+ <xsl:apply-templates select="readme"/> >+ <hr style="height: 1px;" /> >+ <h3>Apache Tomcat/8.0</h3> >+ </body> >+ </html> >+ </xsl:template> > > >- <xsl:template match="entries"> >- <xsl:apply-templates select="entry"/> >- </xsl:template> >+ <xsl:template match="entries"> >+ <xsl:apply-templates select="entry"/> >+ </xsl:template> > >- <xsl:template match="readme"> >- <hr size="1" /> >- <pre><xsl:apply-templates/></pre> >- </xsl:template> >+ <xsl:template match="readme"> >+ <hr style="height: 1px;" /> >+ <pre><xsl:apply-templates/></pre> >+ </xsl:template> > >- <xsl:template match="entry"> >- <tr> >- <td align="left"> >- <xsl:variable name="urlPath" select="@urlPath"/> >- <a href="{$urlPath}"> >- <tt><xsl:apply-templates/></tt> >- </a> >- </td> >- <td align="right"> >- <tt><xsl:value-of select="@size"/></tt> >- </td> >- <td align="right"> >- <tt><xsl:value-of select="@date"/></tt> >- </td> >- </tr> >- </xsl:template> >+ <xsl:template match="entry"> >+ <tr> >+ <td style="text-align: left;"> >+ <xsl:variable name="urlPath" select="@urlPath"/> >+ <a href="{$urlPath}"> >+ <pre><xsl:apply-templates/></pre> >+ </a> >+ </td> >+ <td style="text-align: right;"> >+ <pre><xsl:value-of select="@size"/></pre> >+ </td> >+ <td style="text-align: right;"> >+ <pre><xsl:value-of select="@date"/></pre> >+ </td> >+ </tr> >+ </xsl:template> > >-</xsl:stylesheet> >-</source> >+</xsl:stylesheet>]]></source> > > </section> > >Index: webapps/docs/deployer-howto.xml >=================================================================== >--- webapps/docs/deployer-howto.xml (revision 1518039) >+++ webapps/docs/deployer-howto.xml (working copy) >@@ -41,7 +41,8 @@ > </p> > <p> > Web application deployment may be accomplished in a number of ways >- within the Tomcat server.</p> >+ within the Tomcat server. >+ </p> > <ul> > <li>Statically; the web application is setup before Tomcat is started</li> > <li> >Index: webapps/docs/html-manager-howto.xml >=================================================================== >--- webapps/docs/html-manager-howto.xml (revision 1518039) >+++ webapps/docs/html-manager-howto.xml (working copy) >@@ -125,33 +125,29 @@ > users continuously encounter database exceptions.</p> > > <p>If this command succeeds, you will see a Message like this:</p> >-<source> >-OK - Started application at context path /examples >-</source> >+<source>OK - Started application at context path /examples</source> > > <p>Otherwise, the Message will start with <code>FAIL</code> and include an > error message. Possible causes for problems include:</p> > <ul> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to start the web application. > Check the Tomcat logs for the details.</p> >- </blockquote></li> >+ </li> > <li><em>Invalid context path was specified</em> >- <blockquote> > <p>The context path must start with a slash character, unless you are > referencing the ROOT web application -- in which case the context path > must be a zero-length string.</p> >- </blockquote></li> >+ </li> > <li><em>No context exists for path /foo</em> >- <blockquote> > <p>There is no deployed application on the context path > that you specified.</p> >- </blockquote></li> >+ </li> > <li><em>No context path was specified</em> >- <blockquote> >+ <p> > The <code>path</code> parameter is required. >- </blockquote></li> >+ </p> >+</li> > </ul> > > </subsection> >@@ -164,33 +160,29 @@ > "stopped" on a list applications command.</p> > > <p>If this command succeeds, you will see a Message like this:</p> >-<source> >-OK - Stopped application at context path /examples >-</source> >+<source>OK - Stopped application at context path /examples</source> > > <p>Otherwise, the Message will start with <code>FAIL</code> and include an > error message. Possible causes for problems include:</p> > <ul> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to stop the web application. > Check the Tomcat logs for the details.</p> >- </blockquote></li> >+ </li> > <li><em>Invalid context path was specified</em> >- <blockquote> > <p>The context path must start with a slash character, unless you are > referencing the ROOT web application -- in which case the context path > must be a zero-length string.</p> >- </blockquote></li> >+ </li> > <li><em>No context exists for path /foo</em> >- <blockquote> > <p>There is no deployed application on the context path > that you specified.</p> >- </blockquote></li> >+ </li> > <li><em>No context path was specified</em> >- <blockquote> >+ <p> > The <code>path</code> parameter is required. >- </blockquote></li> >+ </p> >+</li> > </ul> > > </subsection> >@@ -219,35 +211,30 @@ > error message. Possible causes for problems include:</p> > <ul> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to restart the web application. > Check the Tomcat logs for the details.</p> >- </blockquote></li> >+ </li> > <li><em>Invalid context path was specified</em> >- <blockquote> > <p>The context path must start with a slash character, unless you are > referencing the ROOT web application -- in which case the context path > must be a zero-length string.</p> >- </blockquote></li> >+ </li> > <li><em>No context exists for path /foo</em> >- <blockquote> > <p>There is no deployed application on the context path > that you specified.</p> >- </blockquote></li> >+ </li> > <li><em>No context path was specified</em> >- <blockquote> >- The <code>path</code> parameter is required. >- </blockquote></li> >+ <p>The <code>path</code> parameter is required.</p> >+ </li> > <li><em>Reload not supported on WAR deployed at path /foo</em> >- <blockquote> >- Currently, application reloading (to pick up changes to the classes or >+ <p>Currently, application reloading (to pick up changes to the classes or > <code>web.xml</code> file) is not supported when a web application is > installed directly from a WAR file, which happens when the host is > configured to not unpack WAR files. As it only works when the web > application is installed from an unpacked directory, if you are using > a WAR file, you should <code>undeploy</code> and then <code>deploy</code> >- the application again to pick up your changes. >- </blockquote></li> >+ the application again to pick up your changes.</p> >+ </li> > </ul> > > </subsection> >@@ -254,7 +241,7 @@ > > <subsection name="Undeploy"> > >-<p><strong><font color="red">WARNING</font> - This command will delete the >+<p><strong><span style="color: red;">WARNING</span> - This command will delete the > contents of the web application directory and/or ".war" file if it exists within > the <code>appBase</code> directory (typically "webapps") for this virtual host > </strong>. The web application temporary work directory is also deleted. If >@@ -268,33 +255,27 @@ > in the HTML manager.</p> > > <p>If this command succeeds, you will see a Message like this:</p> >-<source> >-OK - Undeployed application at context path /examples >-</source> >+<source>OK - Undeployed application at context path /examples</source> > > <p>Otherwise, the Message will start with <code>FAIL</code> and include an > error message. Possible causes for problems include:</p> > <ul> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to undeploy the web application. > Check the Tomcat logs for the details.</p> >- </blockquote></li> >+ </li> > <li><em>Invalid context path was specified</em> >- <blockquote> > <p>The context path must start with a slash character, unless you are > referencing the ROOT web application -- in which case the context path > must be a zero-length string.</p> >- </blockquote></li> >+ </li> > <li><em>No context exists for path /foo</em> >- <blockquote> > <p>There is no deployed application on the context path > that you specified.</p> >- </blockquote></li> >+ </li> > <li><em>No context path was specified</em> >- <blockquote> > The <code>path</code> parameter is required. >- </blockquote></li> >+ </li> > </ul> > > </subsection> >@@ -319,7 +300,7 @@ > > <p>There are a number of different ways the deploy command can be used.</p> > >-<h3>Deploy a Directory or WAR by URL</h3> >+<h5>Deploy a Directory or WAR by URL</h5> > > <p>Install a web application directory or ".war" file located on the Tomcat > server. If no <i>Context Path</i> is specified, the directory name or the >@@ -344,12 +325,10 @@ > context named <code>/bar</code>. Notice that there is no <code>path</code> > parameter so the context path defaults to the name of the web application > archive file without the ".war" extension.</p> >-<source> >-WAR or Directory URL: jar:file:/path/to/bar.war!/ >-</source> >+<source>WAR or Directory URL: jar:file:/path/to/bar.war!/</source> > > >-<h3>Deploy a Directory or War from the Host appBase</h3> >+<h5>Deploy a Directory or War from the Host appBase</h5> > > <p>Install a web application directory or ".war" file located in your Host > appBase directory. If no <i>Context Path</i> is specified the directory name >@@ -360,21 +339,17 @@ > deployed as the web application context named <code>/foo</code>. Notice > that there is no <code>path</code> parameter so the context path defaults > to the name of the web application directory.</p> >-<source> >-WAR or Directory URL: foo >-</source> >+<source>WAR or Directory URL: foo</source> > > > <p>In this example the ".war" file <code>bar.war</code> located in your > Host appBase directory on the Tomcat server is deployed as the web > application context named <code>/bartoo</code>.</p> >-<source> >-Context Path: /bartoo >-WAR or Directory URL: bar.war >-</source> >+<source>Context Path: /bartoo >+WAR or Directory URL: bar.war</source> > > >-<h3>Deploy using a Context configuration ".xml" file</h3> >+<h5>Deploy using a Context configuration ".xml" file</h5> > > <p>If the Host deployXML flag is set to true, you can install a web > application using a Context configuration ".xml" file and an optional >@@ -386,10 +361,8 @@ > web application Context just as if it were configured in your > Tomcat <code>server.xml</code> configuration file. Here is an > example for Tomcat running on Windows:</p> >-<source> >-<Context path="/foobar" docBase="C:\path\to\application\foobar"> >-</Context> >-</source> >+<source><![CDATA[<Context path="/foobar" docBase="C:\path\to\application\foobar"> >+</Context>]]></source> > > > <p>Use of the <i>WAR or Directory URL</i> is optional. When used >@@ -398,18 +371,14 @@ > > <p>Here is an example of installing an application using a Context > configuration ".xml" file for Tomcat running on Windows.</p> >-<source> >-XML Configuration file URL: file:C:/path/to/context.xml >-</source> >+<source>XML Configuration file URL: file:C:/path/to/context.xml</source> > > > <p>Here is an example of installing an application using a Context > configuration ".xml" file and a web application ".war" file located > on the server (Tomcat running on Unix).</p> >-<source> >-XML Configuration file URL: file:/path/to/context.xml >-WAR or Directory URL: jar:file:/path/to/bar.war!/ >-</source> >+<source>XML Configuration file URL: file:/path/to/context.xml >+WAR or Directory URL: jar:file:/path/to/bar.war!/</source> > > > </subsection> >@@ -430,26 +399,22 @@ > <p>Upload of a WAR file could fail for the following reasons:</p> > <ul> > <li><em>File uploaded must be a .war</em> >- <blockquote> > <p>The upload install will only accept files which have the filename > extension of ".war".</p> >- </blockquote></li> >+ </li> > <li><em>War file already exists on server</em> >- <blockquote> > <p>If a war file of the same name already exists in your Host's > appBase the upload will fail. Either undeploy the existing war file > from your Host's appBase or upload the new war file using a different > name.</p> >- </blockquote></li> >+ </li> > <li><em>File upload failed, no file</em> >- <blockquote> > <p>The file upload failed, no file was received by the server.</p> >- </blockquote></li> >+ </li> > <li><em>Install Upload Failed, Exception:</em> >- <blockquote> > <p>The war file upload or install failed with a Java Exception. > The exception message will be listed.</p> >- </blockquote></li> >+ </li> > </ul> > > </subsection> >@@ -477,62 +442,54 @@ > > <p>If deployment and startup is successful, you will receive a Message > like this:</p> >-<source> >-OK - Deployed application at context path /foo >-</source> >+<source>OK - Deployed application at context path /foo</source> > > <p>Otherwise, the Message will start with <code>FAIL</code> and include an > error message. Possible causes for problems include:</p> > <ul> > <li><em>Application already exists at path /foo</em> >- <blockquote> > <p>The context paths for all currently running web applications must be > unique. Therefore, you must either undeploy the existing web > application using this context path, or choose a different context path > for the new one.</p> >- </blockquote></li> >+ </li> > <li><em>Document base does not exist or is not a readable directory</em> >- <blockquote> > <p>The URL specified by the <i>WAR or Directory URL:</i> field must > identify a directory on this server that contains the "unpacked" version > of a web application, or the absolute URL of a web application archive > (WAR) file that contains this application. Correct the value entered for > the <i>WAR or Directory URL:</i> field.</p> >- </blockquote></li> >+ </li> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to start the new web application. > Check the Tomcat logs for the details, but likely explanations include > problems parsing your <code>/WEB-INF/web.xml</code> file, or missing > classes encountered when initializing application event listeners and > filters.</p> >- </blockquote></li> >+ </li> > <li><em>Invalid application URL was specified</em> >- <blockquote> > <p>The URL for the <i>WAR or Directory URL:</i> field that you specified > was not valid. Such URLs must start with <code>file:</code>, and URLs > for a WAR file must end in ".war".</p> >- </blockquote></li> >+ </li> > <li><em>Invalid context path was specified</em> >- <blockquote> > <p>The context path must start with a slash character, unless you are > referencing the ROOT web application -- in which case the context path > must be a "/" string.</p> >- </blockquote></li> >+ </li> > <li><em>Context path must match the directory or WAR file name:</em> >- <blockquote> >- If the application war or directory is deployed in your Host appBase >+ <p>If the application war or directory is deployed in your Host appBase > directory and either the Host is configured with autoDeploy=true the Context > path must match the directory name or war file name without the ".war" >- extension. >- </blockquote></li> >+ extension.</p> >+ </li> > <li><em>Only web applications in the Host web application directory can > be deployed</em> >- <blockquote> >+ <p> > If the Host deployXML flag is set to false this error will happen > if an attempt is made to install a web application directory or > ".war" file outside of the Host appBase directory. >- </blockquote></li> >+ </p></li> > </ul> > > </subsection> >Index: webapps/docs/jasper-howto.xml >=================================================================== >--- webapps/docs/jasper-howto.xml (revision 1518039) >+++ webapps/docs/jasper-howto.xml (working copy) >@@ -42,7 +42,7 @@ > > <p>Jasper 2 has been redesigned to significantly improve performance over > the original Jasper. In addition to general code improvements the following >-changes were made: >+changes were made:</p> > <ul> > <li><strong>JSP Custom Tag Pooling</strong> - The java objects instantiated > for JSP Custom Tags can now be pooled and reused. This significantly boosts >@@ -61,8 +61,8 @@ > compilation. This compiler loads source dependencies from the container > classloader. Ant and javac can still be used.</li> > </ul> >-</p> > >+ > <p>Jasper is implemented using the servlet class > <code>org.apache.jasper.servlet.JspServlet</code>.</p> > >@@ -71,13 +71,13 @@ > <section name="Configuration"> > > <p>By default Jasper is configured for use when doing web application >-development. See the section <a href="#Production Configuration"> >+development. See the section <a href="#Production_Configuration"> > Production Configuration</a> for information on configuring Jasper > for use on a production Tomcat server.</p> > > <p>The servlet which implements Jasper is configured using init parameters > in your global <code>$CATALINA_BASE/conf/web.xml</code>. >- >+</p> > <ul> > <li><strong>checkInterval</strong> - If development is false and checkInterval > is greater than zero, background compiles are enabled. checkInterval is the time >@@ -198,8 +198,8 @@ > header is added by generated servlet. <code>true</code> or <code>false</code>, > default <code>false</code>.</li> > </ul> >-</p> > >+ > <p>The Java compiler from Eclipse JDT in included as the default compiler. It is > an advanced Java compiler which will load all dependencies from the Tomcat class > loader, which will help tremendously when compiling on large installations with >@@ -222,12 +222,12 @@ > <code>java.lang.InternalError: name is too long to represent</code> exception > when compiling very large JSPs. If this is observed then it may be worked around > by using one of the following: >+</p> > <ul> > <li>reduce the size of the JSP</li> > <li>disable SMAP generation and JSR-045 support by setting > <code>suppressSmap</code> to <code>true</code>.</li> > </ul> >-</p> > > </section> > >@@ -239,7 +239,7 @@ > Jasper servlet becomes critical.</p> > > <p>When using Jasper 2 in a production Tomcat server you should consider making >-the following changes from the default configuration. >+the following changes from the default configuration.</p> > <ul> > <li><strong>development</strong> - To disable on access checks for JSP > pages compilation set this to <code>false</code>.</li> >@@ -251,7 +251,6 @@ > <li><strong>trimSpaces</strong> - To remove useless bytes from the response, > set this to <code>true</code>.</li> > </ul> >-</p> > > </section> > >@@ -264,74 +263,69 @@ > download) to precompile a webapp: > </p> > >-<p> >-<source> >-<project name="Webapp Precompilation" default="all" basedir="."> >+<source><![CDATA[<project name="Webapp Precompilation" default="all" basedir="."> > >- <import file="${tomcat.home}/bin/catalina-tasks.xml"/> >+ <import file="${tomcat.home}/bin/catalina-tasks.xml"/> > >- <target name="jspc"> >+ <target name="jspc"> > >- <jasper >+ <jasper > validateXml="false" > uriroot="${webapp.path}" > webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml" >- outputDir="${webapp.path}/WEB-INF/src" /> >+ outputDir="${webapp.path}/WEB-INF/src" /> > >- </target> >+ </target> > >- <target name="compile"> >+ <target name="compile"> > >- <mkdir dir="${webapp.path}/WEB-INF/classes"/> >- <mkdir dir="${webapp.path}/WEB-INF/lib"/> >+ <mkdir dir="${webapp.path}/WEB-INF/classes"/> >+ <mkdir dir="${webapp.path}/WEB-INF/lib"/> > >- <javac destdir="${webapp.path}/WEB-INF/classes" >+ <javac destdir="${webapp.path}/WEB-INF/classes" > optimize="off" > debug="on" failonerror="false" > srcdir="${webapp.path}/WEB-INF/src" >- excludes="**/*.smap"> >- <classpath> >- <pathelement location="${webapp.path}/WEB-INF/classes"/> >- <fileset dir="${webapp.path}/WEB-INF/lib"> >- <include name="*.jar"/> >- </fileset> >- <pathelement location="${tomcat.home}/lib"/> >- <fileset dir="${tomcat.home}/lib"> >- <include name="*.jar"/> >- </fileset> >- <fileset dir="${tomcat.home}/bin"> >- <include name="*.jar"/> >- </fileset> >- </classpath> >- <include name="**" /> >- <exclude name="tags/**" /> >- </javac> >+ excludes="**/*.smap"> >+ <classpath> >+ <pathelement location="${webapp.path}/WEB-INF/classes"/> >+ <fileset dir="${webapp.path}/WEB-INF/lib"> >+ <include name="*.jar"/> >+ </fileset> >+ <pathelement location="${tomcat.home}/lib"/> >+ <fileset dir="${tomcat.home}/lib"> >+ <include name="*.jar"/> >+ </fileset> >+ <fileset dir="${tomcat.home}/bin"> >+ <include name="*.jar"/> >+ </fileset> >+ </classpath> >+ <include name="**" /> >+ <exclude name="tags/**" /> >+ </javac> > >- </target> >+ </target> > >- <target name="all" depends="jspc,compile"> >- </target> >+ <target name="all" depends="jspc,compile"> >+ </target> > >- <target name="cleanup"> >- <delete> >- <fileset dir="${webapp.path}/WEB-INF/src"/> >- <fileset dir="${webapp.path}/WEB-INF/classes/org/apache/jsp"/> >- </delete> >- </target> >+ <target name="cleanup"> >+ <delete> >+ <fileset dir="${webapp.path}/WEB-INF/src"/> >+ <fileset dir="${webapp.path}/WEB-INF/classes/org/apache/jsp"/> >+ </delete> >+ </target> > >-</project> >-</source> >-</p> >+</project>]]></source> > > <p> > The following command line can be used to run the script > (replacing the tokens with the Tomcat base path and the path to the webapp >-which should be precompiled):<br/> >-<source> >-$ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH> >-</source> >+which should be precompiled): > </p> >+<source>$ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH></source> > >+ > <p> > Then, the declarations and mappings for the servlets which were generated > during the precompilation must be added to the web application deployment >@@ -366,7 +360,7 @@ > <code>${webapp.path}/WEB-INF/classes/org/apache/jsp</code>. > </p> > >-<p><strong>Hints:</strong> >+<p><strong>Hints:</strong></p> > <ul> > <li> When you switch to another Tomcat release, then regenerate and recompile > your jsp's with the new Tomcat version.</li> >@@ -377,7 +371,6 @@ > that changing from the defaults may affect performance, but it will vary > depending on the application.</li> > </ul> >-</p> > </section> > > <section name="Optimisation"> >Index: webapps/docs/jndi-datasource-examples-howto.xml >=================================================================== >--- webapps/docs/jndi-datasource-examples-howto.xml (revision 1518039) >+++ webapps/docs/jndi-datasource-examples-howto.xml (working copy) >@@ -196,7 +196,7 @@ > > <subsection name="MySQL DBCP Example"> > >-<h3>0. Introduction</h3> >+<h5>0. Introduction</h5> > <p>Versions of <a href="http://www.mysql.com/products/mysql/index.html">MySQL</a> and JDBC > drivers that have been reported to work: > </p> >@@ -208,7 +208,7 @@ > > <p>Before you proceed, don't forget to copy the JDBC Driver's jar into <code>$CATALINA_HOME/lib</code>.</p> > >-<h3>1. MySQL configuration</h3> >+<h5>1. MySQL configuration</h5> > <p> > Ensure that you follow these instructions as variations can cause problems. > </p> >@@ -217,16 +217,14 @@ > Your MySQL user <strong>must</strong> have a password assigned. The driver > will fail if you try to connect with an empty password. > </p> >-<source> >-mysql> GRANT ALL PRIVILEGES ON *.* TO javauser@localhost >- -> IDENTIFIED BY 'javadude' WITH GRANT OPTION; >-mysql> create database javatest; >-mysql> use javatest; >-mysql> create table testdata ( >- -> id int not null auto_increment primary key, >- -> foo varchar(25), >- -> bar int); >-</source> >+<source><![CDATA[mysql> GRANT ALL PRIVILEGES ON *.* TO javauser@localhost >+ -> IDENTIFIED BY 'javadude' WITH GRANT OPTION; >+mysql> create database javatest; >+mysql> use javatest; >+mysql> create table testdata ( >+ -> id int not null auto_increment primary key, >+ -> foo varchar(25), >+ -> bar int);]]></source> > <blockquote> > <strong>Note:</strong> the above user should be removed once testing is > complete! >@@ -234,8 +232,7 @@ > > <p>Next insert some test data into the testdata table. > </p> >-<source> >-mysql> insert into testdata values(null, 'hello', 12345); >+<source><![CDATA[mysql> insert into testdata values(null, 'hello', 12345); > Query OK, 1 row affected (0.00 sec) > > mysql> select * from testdata; >@@ -246,95 +243,87 @@ > +----+-------+-------+ > 1 row in set (0.00 sec) > >-mysql> >-</source> >+mysql>]]></source> > >-<h3>2. Context configuration</h3> >+<h5>2. Context configuration</h5> > <p>Configure the JNDI DataSource in Tomcat by adding a declaration for your > resource to your <a href="config/context.html">Context</a>.</p> > <p>For example:</p> >-<source> >-<Context> >+<source><![CDATA[<Context> > >- <!-- maxActive: Maximum number of database connections in pool. Make sure you >+ <!-- maxActive: Maximum number of database connections in pool. Make sure you > configure your mysqld max_connections large enough to handle > all of your db connections. Set to -1 for no limit. >- --> >+ --> > >- <!-- maxIdle: Maximum number of idle database connections to retain in pool. >+ <!-- maxIdle: Maximum number of idle database connections to retain in pool. > Set to -1 for no limit. See also the DBCP documentation on this > and the minEvictableIdleTimeMillis configuration parameter. >- --> >+ --> > >- <!-- maxWait: Maximum time to wait for a database connection to become available >+ <!-- maxWait: Maximum time to wait for a database connection to become available > in ms, in this example 10 seconds. An Exception is thrown if > this timeout is exceeded. Set to -1 to wait indefinitely. >- --> >+ --> > >- <!-- username and password: MySQL username and password for database connections --> >+ <!-- username and password: MySQL username and password for database connections --> > >- <!-- driverClassName: Class name for the old mm.mysql JDBC driver is >+ <!-- driverClassName: Class name for the old mm.mysql JDBC driver is > org.gjt.mm.mysql.Driver - we recommend using Connector/J though. > Class name for the official MySQL Connector/J driver is com.mysql.jdbc.Driver. >- --> >+ --> > >- <!-- url: The JDBC connection url for connecting to your MySQL database. >- --> >+ <!-- url: The JDBC connection url for connecting to your MySQL database. >+ --> > >- <Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource" >+ <Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource" > maxActive="100" maxIdle="30" maxWait="10000" > username="javauser" password="javadude" driverClassName="com.mysql.jdbc.Driver" >- url="jdbc:mysql://localhost:3306/javatest"/> >+ url="jdbc:mysql://localhost:3306/javatest"/> > >-</Context> >-</source> >+</Context>]]></source> > >-<h3>3. web.xml configuration</h3> >+<h5>3. web.xml configuration</h5> > > <p>Now create a <code>WEB-INF/web.xml</code> for this test application.</p> >-<source> >-<web-app xmlns="http://java.sun.com/xml/ns/j2ee" >+<source><![CDATA[<web-app xmlns="http://java.sun.com/xml/ns/j2ee" > xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" > xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee > http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" >- version="2.4"> >- <description>MySQL Test App</description> >- <resource-ref> >- <description>DB Connection</description> >- <res-ref-name>jdbc/TestDB</res-ref-name> >- <res-type>javax.sql.DataSource</res-type> >- <res-auth>Container</res-auth> >- </resource-ref> >-</web-app> >-</source> >+ version="2.4"> >+ <description>MySQL Test App</description> >+ <resource-ref> >+ <description>DB Connection</description> >+ <res-ref-name>jdbc/TestDB</res-ref-name> >+ <res-type>javax.sql.DataSource</res-type> >+ <res-auth>Container</res-auth> >+ </resource-ref> >+</web-app>]]></source> > >-<h3>4. Test code</h3> >-<p>Now create a simple <code>test.jsp</code> page for use later. >-<source> >-<%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %> >-<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> >+<h5>4. Test code</h5> >+<p>Now create a simple <code>test.jsp</code> page for use later.</p> >+<source><![CDATA[<%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %> >+<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> > >-<sql:query var="rs" dataSource="jdbc/TestDB"> >+<sql:query var="rs" dataSource="jdbc/TestDB"> > select id, foo, bar from testdata >-</sql:query> >+</sql:query> > >-<html> >- <head> >- <title>DB Test</title> >- </head> >- <body> >+<html> >+ <head> >+ <title>DB Test</title> >+ </head> >+ <body> > >- <h2>Results</h2> >+ <h2>Results</h2> > >-<c:forEach var="row" items="${rs.rows}"> >- Foo ${row.foo}<br/> >- Bar ${row.bar}<br/> >-</c:forEach> >+<c:forEach var="row" items="${rs.rows}"> >+ Foo ${row.foo}<br/> >+ Bar ${row.bar}<br/> >+</c:forEach> > >- </body> >-</html> >-</source> >-</p> >+ </body> >+</html>]]></source> > > <p>That JSP page makes use of <a href="http://java.sun.com/products/jsp/jstl">JSTL</a>'s > SQL and Core taglibs. You can get it from >@@ -355,7 +344,7 @@ > </subsection> > > <subsection name="Oracle 8i, 9i & 10g"> >-<h3>0. Introduction</h3> >+<h5>0. Introduction</h5> > > <p>Oracle requires minimal changes from the MySQL configuration except for the > usual gotchas :-)</p> >@@ -372,7 +361,7 @@ > for this driver class will be discontinued in the next major release. > </p> > >-<h3>1. Context configuration</h3> >+<h5>1. Context configuration</h5> > <p>In a similar manner to the mysql config above, you will need to define your > Datasource in your <a href="config/context.html">Context</a>. Here we define a > Datasource called myoracle using the thin driver to connect as user scott, >@@ -382,43 +371,37 @@ > > <p>Use of the OCI driver should simply involve a changing thin to oci in the URL string. > </p> >-<source> >-<Resource name="jdbc/myoracle" auth="Container" >+<source><![CDATA[<Resource name="jdbc/myoracle" auth="Container" > type="javax.sql.DataSource" driverClassName="oracle.jdbc.OracleDriver" > url="jdbc:oracle:thin:@127.0.0.1:1521:mysid" > username="scott" password="tiger" maxActive="20" maxIdle="10" >- maxWait="-1"/> >-</source> >+ maxWait="-1"/>]]></source> > >-<h3>2. web.xml configuration</h3> >+<h5>2. web.xml configuration</h5> > <p>You should ensure that you respect the element ordering defined by the DTD when you > create you applications web.xml file.</p> >-<source> >-<resource-ref> >- <description>Oracle Datasource example</description> >- <res-ref-name>jdbc/myoracle</res-ref-name> >- <res-type>javax.sql.DataSource</res-type> >- <res-auth>Container</res-auth> >-</resource-ref> >-</source> >-<h3>3. Code example</h3> >+<source><![CDATA[<resource-ref> >+ <description>Oracle Datasource example</description> >+ <res-ref-name>jdbc/myoracle</res-ref-name> >+ <res-type>javax.sql.DataSource</res-type> >+ <res-auth>Container</res-auth> >+</resource-ref>]]></source> >+<h5>3. Code example</h5> > <p>You can use the same example application as above (asuming you create the required DB > instance, tables etc.) replacing the Datasource code with something like</p> >-<source> >-Context initContext = new InitialContext(); >+<source><![CDATA[Context initContext = new InitialContext(); > Context envContext = (Context)initContext.lookup("java:/comp/env"); > DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle"); > Connection conn = ds.getConnection(); >-//etc. >-</source> >+//etc.]]></source> > </subsection> > > > <subsection name="PostgreSQL"> >-<h3>0. Introduction</h3> >+<h5>0. Introduction</h5> > <p>PostgreSQL is configured in a similar manner to Oracle.</p> > >-<h3>1. Required files </h3> >+<h5>1. Required files </h5> > <p> > Copy the Postgres JDBC jar to $CATALINA_HOME/lib. As with Oracle, the > jars need to be in this directory in order for DBCP's Classloader to find >@@ -425,7 +408,7 @@ > them. This has to be done regardless of which configuration step you take next. > </p> > >-<h3>2. Resource configuration</h3> >+<h5>2. Resource configuration</h5> > > <p> > You have two choices here: define a datasource that is shared across all Tomcat >@@ -432,7 +415,7 @@ > applications, or define a datasource specifically for one application. > </p> > >-<h4>2a. Shared resource configuration</h4> >+<h6>2a. Shared resource configuration</h6> > <p> > Use this option if you wish to define a datasource that is shared across > multiple Tomcat applications, or if you just prefer defining your datasource >@@ -441,13 +424,11 @@ > <p><i>This author has not had success here, although others have reported so. > Clarification would be appreciated here.</i></p> > >-<source> >-<Resource name="jdbc/postgres" auth="Container" >+<source><![CDATA[<Resource name="jdbc/postgres" auth="Container" > type="javax.sql.DataSource" driverClassName="org.postgresql.Driver" > url="jdbc:postgresql://127.0.0.1:5432/mydb" >- username="myuser" password="mypasswd" maxActive="20" maxIdle="10" maxWait="-1"/> >-</source> >-<h4>2b. Application-specific resource configuration</h4> >+ username="myuser" password="mypasswd" maxActive="20" maxIdle="10" maxWait="-1"/>]]></source> >+<h6>2b. Application-specific resource configuration</h6> > > <p> > Use this option if you wish to define a datasource specific to your application, >@@ -460,28 +441,24 @@ > The Context element should look something like the following. > </p> > >-<source> >-<Context> >+<source><![CDATA[<Context> > >-<Resource name="jdbc/postgres" auth="Container" >+<Resource name="jdbc/postgres" auth="Container" > type="javax.sql.DataSource" driverClassName="org.postgresql.Driver" > url="jdbc:postgresql://127.0.0.1:5432/mydb" > username="myuser" password="mypasswd" maxActive="20" maxIdle="10" >-maxWait="-1"/> >-</Context> >-</source> >+maxWait="-1"/> >+</Context>]]></source> > >-<h3>3. web.xml configuration</h3> >-<source> >-<resource-ref> >- <description>postgreSQL Datasource example</description> >- <res-ref-name>jdbc/postgres</res-ref-name> >- <res-type>javax.sql.DataSource</res-type> >- <res-auth>Container</res-auth> >-</resource-ref> >-</source> >+<h5>3. web.xml configuration</h5> >+<source><![CDATA[<resource-ref> >+ <description>postgreSQL Datasource example</description> >+ <res-ref-name>jdbc/postgres</res-ref-name> >+ <res-type>javax.sql.DataSource</res-type> >+ <res-auth>Container</res-auth> >+</resource-ref>]]></source> > >-<h4>4. Accessing the datasource</h4> >+<h5>4. Accessing the datasource</h5> > <p> > When accessing the datasource programmatically, remember to prepend > <code>java:/comp/env</code> to your JNDI lookup, as in the following snippet of >@@ -489,8 +466,7 @@ > you change it in the above resource definition file as well. > </p> > >-<source> >-InitialContext cxt = new InitialContext(); >+<source><![CDATA[InitialContext cxt = new InitialContext(); > if ( cxt == null ) { > throw new Exception("Uh oh -- no context!"); > } >@@ -499,8 +475,7 @@ > > if ( ds == null ) { > throw new Exception("Data source not found!"); >-} >-</source> >+}]]></source> > > </subsection> > </section> >@@ -539,12 +514,10 @@ > You should next create a simple test servlet or jsp that has these > <strong>critical lines</strong>: > </p> >-<source> >-DriverManager.registerDriver(new >+<source><![CDATA[DriverManager.registerDriver(new > oracle.jdbc.driver.OracleDriver()); > conn = >-DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password"); >-</source> >+DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password");]]></source> > <p> > where database is of the form <code>host:port:SID</code> Now if you try to access the URL of your > test servlet/jsp and what you get is a >@@ -552,6 +525,7 @@ > </p> > <p> > First, the <code>UnsatisfiedLinkError</code> indicates that you have >+</p> > <ul> > <li>a mismatch between your JDBC classes file and > your Oracle client version. The giveaway here is the message stating that a needed library file cannot be >@@ -563,7 +537,6 @@ > the classes12.zip file from the directory <code>$ORAHOME\jdbc\lib</code> will also work. > </li> > </ul> >-</p> > <p> > Next you may experience the error <code>ORA-06401 NETCMN: invalid driver designator</code> > </p> >@@ -640,8 +613,7 @@ > Here is an example of properly written code to use a database connection > obtained from a connection pool: > </p> >-<pre> >- Connection conn = null; >+<source><![CDATA[ Connection conn = null; > Statement stmt = null; // Or PreparedStatement if needed > ResultSet rs = null; > try { >@@ -672,8 +644,7 @@ > try { conn.close(); } catch (SQLException e) { ; } > conn = null; > } >- } >-</pre> >+ }]]></source> > > </subsection> > >Index: webapps/docs/jndi-resources-howto.xml >=================================================================== >--- webapps/docs/jndi-resources-howto.xml (revision 1518039) >+++ webapps/docs/jndi-resources-howto.xml (working copy) >@@ -108,18 +108,18 @@ > element:</p> > > <ul> >-<li><a href="config/context.html#Environment Entries"><Environment></a> - >+<li><a href="config/context.html#Environment_Entries"><Environment></a> - > Configure names and values for scalar environment entries that will be > exposed to the web application through the JNDI > <code>InitialContext</code> (equivalent to the inclusion of an > <code><env-entry></code> element in the web application > deployment descriptor).</li> >-<li><a href="config/context.html#Resource Definitions"><Resource></a> - >+<li><a href="config/context.html#Resource_Definitions"><Resource></a> - > Configure the name and data type of a resource made available to the > application (equivalent to the inclusion of a > <code><resource-ref></code> element in the web application > deployment descriptor).</li> >-<li><a href="config/context.html#Resource Links"><ResourceLink></a> - >+<li><a href="config/context.html#Resource_Links"><ResourceLink></a> - > Add a link to a resource defined in the global JNDI context. Use resource > links to give a web application access to a resource defined in > the <a href="config/globalresources.html"><GlobalNamingResources></a> >@@ -161,11 +161,11 @@ > <code><strong><GlobalNamingResources></strong></code></a> element of > <code>$CATALINA_BASE/conf/server.xml</code>. You may expose these resources to > web applications by using a >-<a href="config/context.html#Resource Links"><ResourceLink></a> to >+<a href="config/context.html#Resource_Links"><ResourceLink></a> to > include it in the per-web-application context.</p> > > <p>If a resource has been defined using a >-<a href="config/context.html#Resource Links"><ResourceLink></a>, it is not >+<a href="config/context.html#Resource_Links"><ResourceLink></a>, it is not > necessary for that resource to be defined in <code>/WEB-INF/web.xml</code>. > However, it is recommended to keep the entry in <code>/WEB-INF/web.xml</code> > to document the resource requirements for the web application.</p> >@@ -181,8 +181,7 @@ > access to a resource - in this case, to a JDBC <code>DataSource</code> - > would look something like this:</p> > >-<source> >-// Obtain our environment naming context >+<source><![CDATA[// Obtain our environment naming context > Context initCtx = new InitialContext(); > Context envCtx = (Context) initCtx.lookup("java:comp/env"); > >@@ -193,8 +192,7 @@ > // Allocate and use a connection from the pool > Connection conn = ds.getConnection(); > ... use this connection to access the database ... >-conn.close(); >-</source> >+conn.close();]]></source> > > </section> > >@@ -208,7 +206,7 @@ > subsection below details the configuration and usage of the standard resource > factories.</p> > >- <p>See <a href="#Adding Custom Resource Factories">Adding Custom >+ <p>See <a href="#Adding_Custom_Resource_Factories">Adding Custom > Resource Factories</a> for information about how to create, install, > configure, and use your own custom resource factory classes with > Tomcat.</p> >@@ -223,7 +221,7 @@ > > <subsection name="Generic JavaBean Resources"> > >- <h3>0. Introduction</h3> >+ <h5>0. Introduction</h5> > > <p>This resource factory can be used to create objects of <em>any</em> > Java class that conforms to standard JavaBeans naming conventions (i.e. >@@ -234,7 +232,7 @@ > > <p>The steps required to use this facility are described below.</p> > >- <h3>1. Create Your JavaBean Class</h3> >+ <h5>1. Create Your JavaBean Class</h5> > > <p>Create the JavaBean class which will be instantiated each time > that the resource factory is looked up. For this example, assume >@@ -241,8 +239,7 @@ > you create a class <code>com.mycompany.MyBean</code>, which looks > like this:</p> > >-<source> >-package com.mycompany; >+<source><![CDATA[package com.mycompany; > > public class MyBean { > >@@ -267,10 +264,9 @@ > } > > >-} >-</source> >+}]]></source> > >- <h3>2. Declare Your Resource Requirements</h3> >+ <h5>2. Declare Your Resource Requirements</h5> > > <p>Next, modify your web application deployment descriptor > (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which >@@ -277,19 +273,17 @@ > you will request new instances of this bean. The simplest approach is > to use a <code><resource-env-ref></code> element, like this:</p> > >-<source> >-<resource-env-ref> >- <description> >+<source><![CDATA[<resource-env-ref> >+ <description> > Object factory for MyBean instances. >- </description> >- <resource-env-ref-name> >+ </description> >+ <resource-env-ref-name> > bean/MyBeanFactory >- </resource-env-ref-name> >- <resource-env-ref-type> >+ </resource-env-ref-name> >+ <resource-env-ref-type> > com.mycompany.MyBean >- </resource-env-ref-type> >-</resource-env-ref> >-</source> >+ </resource-env-ref-type> >+</resource-env-ref>]]></source> > > <p><strong>WARNING</strong> - Be sure you respect the element ordering > that is required by the DTD for web application deployment descriptors! >@@ -297,36 +291,32 @@ > <a href="http://wiki.apache.org/tomcat/Specifications">Servlet > Specification</a> for details.</p> > >- <h3>3. Code Your Application's Use Of This Resource</h3> >+ <h5>3. Code Your Application's Use Of This Resource</h5> > > <p>A typical use of this resource environment reference might look > like this:</p> > >-<source> >-Context initCtx = new InitialContext(); >+<source><![CDATA[Context initCtx = new InitialContext(); > Context envCtx = (Context) initCtx.lookup("java:comp/env"); > MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory"); > > writer.println("foo = " + bean.getFoo() + ", bar = " + >- bean.getBar()); >-</source> >+ bean.getBar());]]></source> > >- <h3>4. Configure Tomcat's Resource Factory</h3> >+ <h5>4. Configure Tomcat's Resource Factory</h5> > > <p>To configure Tomcat's resource factory, add an element like this to the > <a href="config/context.html"><code><Context></code></a> element for > this web application.</p> > >-<source> >-<Context ...> >+<source><![CDATA[<Context ...> > ... >- <Resource name="bean/MyBeanFactory" auth="Container" >+ <Resource name="bean/MyBeanFactory" auth="Container" > type="com.mycompany.MyBean" > factory="org.apache.naming.factory.BeanFactory" >- bar="23"/> >+ bar="23"/> > ... >-</Context> >-</source> >+</Context>]]></source> > > <p>Note that the resource name (here, <code>bean/MyBeanFactory</code> > must match the value specified in the web application deployment >@@ -341,7 +331,7 @@ > > <subsection name="UserDatabase Resources"> > >- <h3>0. Introduction</h3> >+ <h5>0. Introduction</h5> > > <p>UserDatabase resources are typically configured as global resources for > use by a UserDatabase realm. Tomcat includes a UserDatabaseFactoory that >@@ -351,7 +341,7 @@ > <p>The steps required to set up a global UserDatabase resource are described > below.</p> > >- <h3>1. Create/edit the XML file</h3> >+ <h5>1. Create/edit the XML file</h5> > > <p>The XMl file is typically located at > <code>$CATALINA_BASE/conf/tomcat-users.xml</code> however, you are free to >@@ -359,32 +349,28 @@ > files are placed in <code>$CATALINA_BASE/conf</code>. A typical XML would > look like:</p> > >-<source> >-<?xml version='1.0' encoding='utf-8'?> >-<tomcat-users> >- <role rolename="tomcat"/> >- <role rolename="role1"/> >- <user username="tomcat" password="tomcat" roles="tomcat"/> >- <user username="both" password="tomcat" roles="tomcat,role1"/> >- <user username="role1" password="tomcat" roles="role1"/> >-</tomcat-users> >-</source> >+<source><![CDATA[<?xml version='1.0' encoding='utf-8'?> >+<tomcat-users> >+ <role rolename="tomcat"/> >+ <role rolename="role1"/> >+ <user username="tomcat" password="tomcat" roles="tomcat"/> >+ <user username="both" password="tomcat" roles="tomcat,role1"/> >+ <user username="role1" password="tomcat" roles="role1"/> >+</tomcat-users>]]></source> > >- <h3>2. Declare Your Resource</h3> >+ <h5>2. Declare Your Resource</h5> > > <p>Next, modify <code>$CATALINA_BASE/conf/server.xml</code> to create the > UserDatabase resource based on your XMl file. It should look something like > this:</p> > >-<source> >-<Resource name="UserDatabase" >+<source><![CDATA[<Resource name="UserDatabase" > auth="Container" > type="org.apache.catalina.UserDatabase" > description="User database that can be updated and saved" > factory="org.apache.catalina.users.MemoryUserDatabaseFactory" > pathname="conf/tomcat-users.xml" >- readonly="false" /> >-</source> >+ readonly="false" />]]></source> > > <p>The <code>pathname</code> attribute can be absolute or relative. If > relative, it is relative to <code>$CATALINA_BASE</code>.</p> >@@ -396,7 +382,7 @@ > is running as. Ensure that these are appropriate to maintain the security > of your installation.</p> > >- <h3>3. Configure the Realm</h3> >+ <h5>3. Configure the Realm</h5> > > <p>Configure a UserDatabase Realm to use this resource as described in the > <a href="config/realm.html">Realm configuration documentation</a>.</p> >@@ -406,7 +392,7 @@ > > <subsection name="JavaMail Sessions"> > >- <h3>0. Introduction</h3> >+ <h5>0. Introduction</h5> > > <p>In many web applications, sending electronic mail messages is a > required part of the system's functionality. The >@@ -424,7 +410,7 @@ > > <p>The steps required for this are outlined below.</p> > >- <h3>1. Declare Your Resource Requirements</h3> >+ <h5>1. Declare Your Resource Requirements</h5> > > <p>The first thing you should do is modify the web application deployment > descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under >@@ -433,25 +419,23 @@ > standard <code>java:comp/env</code> naming context that is the root of > all provided resource factories. A typical <code>web.xml</code> entry > might look like this:</p> >-<source> >-<resource-ref> >- <description> >+<source><![CDATA[<resource-ref> >+ <description> > Resource reference to a factory for javax.mail.Session > instances that may be used for sending electronic mail > messages, preconfigured to connect to the appropriate > SMTP server. >- </description> >- <res-ref-name> >+ </description> >+ <res-ref-name> > mail/Session >- </res-ref-name> >- <res-type> >+ </res-ref-name> >+ <res-type> > javax.mail.Session >- </res-type> >- <res-auth> >+ </res-type> >+ <res-auth> > Container >- </res-auth> >-</resource-ref> >-</source> >+ </res-auth> >+</resource-ref>]]></source> > > <p><strong>WARNING</strong> - Be sure you respect the element ordering > that is required by the DTD for web application deployment descriptors! >@@ -459,11 +443,10 @@ > <a href="http://wiki.apache.org/tomcat/Specifications">Servlet > Specification</a> for details.</p> > >- <h3>2. Code Your Application's Use Of This Resource</h3> >+ <h5>2. Code Your Application's Use Of This Resource</h5> > > <p>A typical use of this resource reference might look like this:</p> >-<source> >-Context initCtx = new InitialContext(); >+<source><![CDATA[Context initCtx = new InitialContext(); > Context envCtx = (Context) initCtx.lookup("java:comp/env"); > Session session = (Session) envCtx.lookup("mail/Session"); > >@@ -474,8 +457,7 @@ > message.setRecipients(Message.RecipientType.TO, to); > message.setSubject(request.getParameter("subject")); > message.setContent(request.getParameter("content"), "text/plain"); >-Transport.send(message); >-</source> >+Transport.send(message);]]></source> > > <p>Note that the application uses the same resource reference name > that was declared in the web application deployment descriptor. This >@@ -483,21 +465,19 @@ > <a href="config/context.html"><code><Context></code></a> element > for the web application as described below.</p> > >- <h3>3. Configure Tomcat's Resource Factory</h3> >+ <h5>3. Configure Tomcat's Resource Factory</h5> > > <p>To configure Tomcat's resource factory, add an elements like this to the > <a href="config/context.html"><code><Context></code></a> element for > this web application.</p> > >-<source> >-<Context ...> >+<source><![CDATA[<Context ...> > ... >- <Resource name="mail/Session" auth="Container" >+ <Resource name="mail/Session" auth="Container" > type="javax.mail.Session" >- mail.smtp.host="localhost"/> >+ mail.smtp.host="localhost"/> > ... >-</Context> >-</source> >+</Context>]]></source> > > <p>Note that the resource name (here, <code>mail/Session</code>) must > match the value specified in the web application deployment descriptor. >@@ -517,9 +497,9 @@ > then Tomcat's resource factory will configure and add a > <code>javax.mail.Authenticator</code> to the mail session.</p> > >- <h3>4. Install the JavaMail libraries</h3> >+ <h5>4. Install the JavaMail libraries</h5> > >- <p><a href="http://www.oracle.com/technetwork/java/index-138643.html"> >+ <p><a href="http://javamail.java.net/"> > Download the JavaMail API</a>.</p> > > <p>Unpackage the distribution and place mail.jar into $CATALINA_HOME/lib so >@@ -529,13 +509,13 @@ > it in the $CATALINA_HOME/lib location only. > </p> > >- <h3>5. Restart Tomcat</h3> >+ <h5>5. Restart Tomcat</h5> > > <p>For the additional JAR to be visible to Tomcat, it is necessary for the > Tomcat instance to be restarted.</p> > > >- <h3>Example Application</h3> >+ <h5>Example Application</h5> > > <p>The <code>/examples</code> application included with Tomcat contains > an example of utilizing this resource factory. It is accessed via the >@@ -555,7 +535,7 @@ > > <subsection name="JDBC Data Sources"> > >- <h3>0. Introduction</h3> >+ <h5>0. Introduction</h5> > > <p>Many web applications need to access a database via a JDBC driver, > to support the functionality required by that application. The Java EE >@@ -586,9 +566,9 @@ > project. However, it is possible to use any other connection pool > that implements <code>javax.sql.DataSource</code>, by writing your > own custom resource factory, as described >- <a href="#Adding Custom Resource Factories">below</a>.</p> >+ <a href="#Adding_Custom_Resource_Factories">below</a>.</p> > >- <h3>1. Install Your JDBC Driver</h3> >+ <h5>1. Install Your JDBC Driver</h5> > > <p>Use of the <em>JDBC Data Sources</em> JNDI Resource Factory requires > that you make an appropriate JDBC driver available to both Tomcat internal >@@ -597,7 +577,7 @@ > <code>$CATALINA_HOME/lib</code> directory, which makes the driver > available both to the resource factory and to your application.</p> > >- <h3>2. Declare Your Resource Requirements</h3> >+ <h5>2. Declare Your Resource Requirements</h5> > > <p>Next, modify the web application deployment descriptor > (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under >@@ -606,25 +586,23 @@ > standard <code>java:comp/env</code> naming context that is the root of > all provided resource factories. A typical <code>web.xml</code> entry > might look like this:</p> >-<source> >-<resource-ref> >- <description> >+<source><![CDATA[<resource-ref> >+ <description> > Resource reference to a factory for java.sql.Connection > instances that may be used for talking to a particular >- database that is configured in the <Context> >+ database that is configured in the <Context> > configurartion for the web application. >- </description> >- <res-ref-name> >+ </description> >+ <res-ref-name> > jdbc/EmployeeDB >- </res-ref-name> >- <res-type> >+ </res-ref-name> >+ <res-type> > javax.sql.DataSource >- </res-type> >- <res-auth> >+ </res-type> >+ <res-auth> > Container >- </res-auth> >-</resource-ref> >-</source> >+ </res-auth> >+</resource-ref>]]></source> > > <p><strong>WARNING</strong> - Be sure you respect the element ordering > that is required by the DTD for web application deployment descriptors! >@@ -632,11 +610,10 @@ > <a href="http://wiki.apache.org/tomcat/Specifications">Servlet > Specification</a> for details.</p> > >- <h3>3. Code Your Application's Use Of This Resource</h3> >+ <h5>3. Code Your Application's Use Of This Resource</h5> > > <p>A typical use of this resource reference might look like this:</p> >-<source> >-Context initCtx = new InitialContext(); >+<source><![CDATA[Context initCtx = new InitialContext(); > Context envCtx = (Context) initCtx.lookup("java:comp/env"); > DataSource ds = (DataSource) > envCtx.lookup("jdbc/EmployeeDB"); >@@ -643,8 +620,7 @@ > > Connection conn = ds.getConnection(); > ... use this connection to access the database ... >-conn.close(); >-</source> >+conn.close();]]></source> > > <p>Note that the application uses the same resource reference name that was > declared in the web application deployment descriptor. This is matched up >@@ -652,16 +628,15 @@ > <a href="config/context.html"><code><Context></code></a> element for > the web application as described below.</p> > >- <h3>4. Configure Tomcat's Resource Factory</h3> >+ <h5>4. Configure Tomcat's Resource Factory</h5> > > <p>To configure Tomcat's resource factory, add an element like this to the > <a href="config/context.html"><code><Context></code></a> element for > the web application.</p> > >-<source> >-<Context ...> >+<source><![CDATA[<Context ...> > ... >- <Resource name="jdbc/EmployeeDB" >+ <Resource name="jdbc/EmployeeDB" > auth="Container" > type="javax.sql.DataSource" > username="dbusername" >@@ -669,10 +644,9 @@ > driverClassName="org.hsql.jdbcDriver" > url="jdbc:HypersonicSQL:database" > maxActive="8" >- maxIdle="4"/> >+ maxIdle="4"/> > ... >-</Context> >-</source> >+</Context>]]></source> > > <p>Note that the resource name (here, <code>jdbc/EmployeeDB</code>) must > match the value specified in the web application deployment descriptor.</p> >@@ -807,10 +781,10 @@ > <a href="config/context.html"><code><Context></code></a> element for > the web application. In the example below, we will create a factory that only > knows how to create <code>com.mycompany.MyBean</code> beans from the >- <a href="#Generic JavaBean Resources">Generic JavaBean Resources</a> example >+ <a href="#Generic_JavaBean_Resources">Generic JavaBean Resources</a> example > above.</p> > >- <h3>1. Write A Resource Factory Class</h3> >+ <h4>1. Write A Resource Factory Class</h4> > > <p>You must write a class that implements the JNDI service provider > <code>javax.naming.spi.ObjectFactory</code> inteface. Every time your >@@ -839,8 +813,7 @@ > <p>To create a resource factory that knows how to produce <code>MyBean</code> > instances, you might create a class like this:</p> > >-<source> >-package com.mycompany; >+<source><![CDATA[package com.mycompany; > > import java.util.Enumeration; > import java.util.Hashtable; >@@ -883,8 +856,7 @@ > > } > >-} >-</source> >+}]]></source> > > <p>In this example, we are unconditionally creating a new instance of > the <code>com.mycompany.MyBean</code> class, and populating its properties >@@ -907,7 +879,7 @@ > files are visible to both Catalina internal resources and your web > application.</p> > >- <h3>2. Declare Your Resource Requirements</h3> >+ <h4>2. Declare Your Resource Requirements</h4> > > <p>Next, modify your web application deployment descriptor > (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which >@@ -914,19 +886,17 @@ > you will request new instances of this bean. The simplest approach is > to use a <code><resource-env-ref></code> element, like this:</p> > >-<source> >-<resource-env-ref> >- <description> >+<source><![CDATA[<resource-env-ref> >+ <description> > Object factory for MyBean instances. >- </description> >- <resource-env-ref-name> >+ </description> >+ <resource-env-ref-name> > bean/MyBeanFactory >- </resource-env-ref-name> >- <resource-env-ref-type> >+ </resource-env-ref-name> >+ <resource-env-ref-type> > com.mycompany.MyBean >- </resource-env-ref-type> >-<resource-env-ref> >-</source> >+ </resource-env-ref-type> >+<resource-env-ref>]]></source> > > <p><strong>WARNING</strong> - Be sure you respect the element ordering > that is required by the DTD for web application deployment descriptors! >@@ -934,36 +904,32 @@ > <a href="http://wiki.apache.org/tomcat/Specifications">Servlet > Specification</a> for details.</p> > >- <h3>3. Code Your Application's Use Of This Resource</h3> >+ <h4>3. Code Your Application's Use Of This Resource</h4> > > <p>A typical use of this resource environment reference might look > like this:</p> > >-<source> >-Context initCtx = new InitialContext(); >+<source><![CDATA[Context initCtx = new InitialContext(); > Context envCtx = (Context) initCtx.lookup("java:comp/env"); > MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory"); > > writer.println("foo = " + bean.getFoo() + ", bar = " + >- bean.getBar()); >-</source> >+ bean.getBar());]]></source> > >- <h3>4. Configure Tomcat's Resource Factory</h3> >+ <h4>4. Configure Tomcat's Resource Factory</h4> > > <p>To configure Tomcat's resource factory, add an elements like this to the > <a href="config/context.html"><code><Context></code></a> element for > this web application.</p> > >-<source> >-<Context ...> >+<source><![CDATA[<Context ...> > ... >- <Resource name="bean/MyBeanFactory" auth="Container" >+ <Resource name="bean/MyBeanFactory" auth="Container" > type="com.mycompany.MyBean" > factory="com.mycompany.MyBeanFactory" >- bar="23"/> >+ bar="23"/> > ... >-</Context> >-</source> >+</Context>]]></source> > > <p>Note that the resource name (here, <code>bean/MyBeanFactory</code> > must match the value specified in the web application deployment >Index: webapps/docs/logging.xml >=================================================================== >--- webapps/docs/logging.xml (revision 1518039) >+++ webapps/docs/logging.xml (working copy) >@@ -222,6 +222,7 @@ > JULI is enabled by default, and supports per classloader configuration, in > addition to the regular global java.util.logging configuration. This means > that logging can be configured at the following layers: >+ </p> > <ul> > <li>Globally. That is usually done in the > <code>${catalina.base}/conf/logging.properties</code> file. >@@ -234,7 +235,6 @@ > <code>WEB-INF/classes/logging.properties</code> > </li> > </ul> >- </p> > <p> > The default <code>logging.properties</code> in the JRE specifies a > <code>ConsoleHandler</code> that routes logging to System.err. >@@ -253,10 +253,8 @@ > so FINEST or ALL should be set. Please refer to <code>java.util.logging</code> > documentation in the JDK for the complete details: > </p> >+ <source>org.apache.catalina.level=FINEST</source> > <p> >- <source>org.apache.catalina.level=FINEST</source> >- </p> >- <p> > The configuration used by JULI is extremely similar to the one supported by > plain <code>java.util.logging</code>, but uses a few > extensions to allow better flexibility in assigning loggers. The main >@@ -295,8 +293,8 @@ > </p> > <p> > Example logging.properties file to be placed in $CATALINA_BASE/conf: >- <source> >-handlers = 1catalina.org.apache.juli.FileHandler, \ >+ </p> >+ <source><![CDATA[handlers = 1catalina.org.apache.juli.FileHandler, \ > 2localhost.org.apache.juli.FileHandler, \ > 3manager.org.apache.juli.FileHandler, \ > java.util.logging.ConsoleHandler >@@ -340,15 +338,13 @@ > > # For example, set the org.apache.catalina.util.LifecycleBase logger to log > # each component that extends LifecycleBase changing state: >-#org.apache.catalina.util.LifecycleBase.level = FINE >-</source> >- </p> >+#org.apache.catalina.util.LifecycleBase.level = FINE]]></source> > > <p> > Example logging.properties for the servlet-examples web application to be > placed in WEB-INF/classes inside the web application: >- <source> >-handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler >+ </p> >+ <source><![CDATA[handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler > > ############################################################ > # Handler specific properties. >@@ -360,10 +356,9 @@ > org.apache.juli.FileHandler.prefix = servlet-examples. > > java.util.logging.ConsoleHandler.level = FINE >-java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter >-</source> >- </p> >+java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter]]></source> > >+ > <subsection name="Documentation references"> > <p>See the following resources for additional information:</p> > <ul> >@@ -423,7 +418,7 @@ > <li>Create a file called <code>log4j.properties</code> with the > following content and save it into <code>$CATALINA_BASE/lib</code></li> > </ol> >- <source> >+ <source><![CDATA[ > log4j.rootLogger = INFO, CATALINA > > # Define all the appenders >@@ -470,8 +465,7 @@ > log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager] =\ > INFO, MANAGER > log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager] =\ >- INFO, HOST-MANAGER >-</source> >+ INFO, HOST-MANAGER]]></source> > <ol start="2"> > <li><a href="http://logging.apache.org/log4j">Download Log4J</a> > (v1.2 or later).</li> >@@ -546,11 +540,9 @@ > configuration files, so we recommend you use a properties file as > described until a future version of log4j allows this convention. > </p> >- <source> >-log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG<br /> >-log4j.logger.org.apache.catalina.core=DEBUG<br /> >-log4j.logger.org.apache.catalina.session=DEBUG<br /> >-</source> >+ <source><![CDATA[log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG >+log4j.logger.org.apache.catalina.core=DEBUG >+log4j.logger.org.apache.catalina.session=DEBUG]]></source> > > <p> > Be warned: a level of DEBUG will produce megabytes of logging and slow >Index: webapps/docs/manager-howto.xml >=================================================================== >--- webapps/docs/manager-howto.xml (revision 1518039) >+++ webapps/docs/manager-howto.xml (working copy) >@@ -70,13 +70,11 @@ > <code>manager.xml</code> context configuration file in the > <code>$CATALINA_BASE/conf/[enginename]/[hostname]</code> folder. Here is an > example:</p> >-<pre> >-<Context privileged="true" antiResourceLocking="false" >- docBase="${catalina.home}/webapps/manager"> >- <Valve className="org.apache.catalina.valves.RemoteAddrValve" >- allow="127\.0\.0\.1" /> >-</Context> >-</pre> >+<source><![CDATA[<Context privileged="true" antiResourceLocking="false" >+ docBase="${catalina.home}/webapps/manager"> >+ <Valve className="org.apache.catalina.valves.RemoteAddrValve" >+ allow="127\.0\.0\.1" /> >+</Context>]]></source> > > <p>If you have Tomcat configured to support multiple virtual hosts > (websites) you would need to configure a Manager for each.</p> >@@ -89,11 +87,11 @@ > <li>A minimal version using HTTP requests only which is suitable for use > by scripts setup by system administrators. Commands are given as part of the > request URI, and responses are in the form of simple text that can be easily >-parsed and processed. See <a href="#Supported Manager Commands"> >+parsed and processed. See <a href="#Supported_Manager_Commands"> > Supported Manager Commands</a> for more information.</li> > <li>A convenient set of task definitions for the <em>Ant</em> > (version 1.4 or later) build tool. See >-<a href="#Executing Manager Commands With Ant">Executing Manager Commands >+<a href="#Executing_Manager_Commands_With_Ant">Executing Manager Commands > With Ant</a> for more information.</li> > </ul> > >@@ -101,13 +99,13 @@ > > <section name="Configuring Manager Application Access"> > >- <blockquote> >+ > <p><em>The description below uses the variable name $CATALINA_BASE to refer the > base directory against which most relative paths are resolved. If you have > not configured Tomcat for multiple instances by setting a CATALINA_BASE > directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, > the directory into which you have installed Tomcat.</em></p> >- </blockquote> >+ > > <p>It would be quite unsafe to ship Tomcat with default settings that allowed > anyone on the Internet to execute the Manager application on your server. >@@ -175,9 +173,7 @@ > edited with any text editor. This file contains an XML > <code><user></code> for each individual user, which might > look something like this: >-<source> >-<user name="craigmcc" password="secret" roles="standard,manager-script" /> >-</source> >+<source><![CDATA[<user name="craigmcc" password="secret" roles="standard,manager-script" />]]></source> > which defines the username and password used by this individual to > log on, and the role names he or she is associated with. You can > add the <strong>manager-script</strong> role to the comma-delimited >@@ -207,12 +203,10 @@ > See <a href="config/valve.html#Remote_Address_Filter">valves documentation</a> > for details. Here is > an example of restricting access to the localhost by IP address:</p> >-<pre> >-<Context privileged="true"> >- <Valve className="org.apache.catalina.valves.RemoteAddrValve" >- allow="127\.0\.0\.1"/> >-</Context> >-</pre> >+<source><![CDATA[<Context privileged="true"> >+ <Valve className="org.apache.catalina.valves.RemoteAddrValve" >+ allow="127\.0\.0\.1"/> >+</Context>]]></source> > > </section> > >@@ -221,9 +215,7 @@ > > <p>All commands that the Manager application knows how to process are > specified in a single request URI like this:</p> >-<source> >-http://{host}:{port}/manager/text/{command}?{parameters} >-</source> >+<source>http://{host}:{port}/manager/text/{command}?{parameters}</source> > <p>where <code>{host}</code> and <code>{port}</code> represent the hostname > and port number on which Tomcat is running, <code>{command}</code> > represents the Manager command you wish to execute, and >@@ -282,9 +274,7 @@ > > <subsection name="Deploy A New Application Remotely"> > >-<source> >-http://localhost:8080/manager/text/deploy?path=/foo >-</source> >+<source>http://localhost:8080/manager/text/deploy?path=/foo</source> > > <p>Upload the web application archive (WAR) file that is specified as the > request data in this HTTP PUT request, install it into the <code>appBase</code> >@@ -311,15 +301,12 @@ > > <p>If installation and startup is successful, you will receive a response > like this:</p> >-<source> >-OK - Deployed application at context path /foo >-</source> >+<source>OK - Deployed application at context path /foo</source> > > <p>Otherwise, the response will start with <code>FAIL</code> and include an > error message. Possible causes for problems include:</p> > <ul> > <li><em>Application already exists at path /foo</em> >- <blockquote> > <p>The context paths for all currently running web applications must be > unique. Therefore, you must undeploy the existing web > application using this context path, or choose a different context path >@@ -327,15 +314,14 @@ > a parameter on the URL, with a value of <code>true</code> to avoid this > error. In that case, an undeploy will be performed on an existing > application before performing the deployment.</p> >- </blockquote></li> >+ </li> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to start the new web application. > Check the Tomcat logs for the details, but likely explanations include > problems parsing your <code>/WEB-INF/web.xml</code> file, or missing > classes encountered when initializing application event listeners and > filters.</p> >- </blockquote></li> >+ </li> > </ul> > > </subsection> >@@ -348,18 +334,16 @@ > > <p>There are a number of different ways the deploy command can be used.</p> > >-<h3>Deploy a previously deployed webapp</h3> >+<h5>Deploy a previously deployed webapp</h5> > > <p>This can be used to deploy a previously deployed web application, which > has been deployed using the <code>tag</code> attribute. Note that the work > directory for the Manager webapp will contain the previously deployed WARs; > removing it would make the deployment fail.</p> >-<source> >-http://localhost:8080/manager/text/deploy?path=/footoo&tag=footag >-</source> >+<source>http://localhost:8080/manager/text/deploy?path=/footoo&tag=footag</source> > > >-<h3>Deploy a Directory or WAR by URL</h3> >+<h5>Deploy a Directory or WAR by URL</h5> > > <p>Deploy a web application directory or ".war" file located on the Tomcat > server. If no <code>path</code> is specified, the directory name or the war file >@@ -373,9 +357,7 @@ > <p>In this example the web application located in the directory > <code>/path/to/foo</code> on the Tomcat server is deployed as the > web application context named <code>/footoo</code>.</p> >-<source> >-http://localhost:8080/manager/text/deploy?path=/footoo&war=file:/path/to/foo >-</source> >+<source>http://localhost:8080/manager/text/deploy?path=/footoo&war=file:/path/to/foo</source> > > > <p>In this example the ".war" file <code>/path/to/bar.war</code> on the >@@ -383,12 +365,10 @@ > <code>/bar</code>. Notice that there is no <code>path</code> parameter > so the context path defaults to the name of the web application archive > file without the ".war" extension.</p> >-<source> >-http://localhost:8080/manager/text/deploy?war=jar:file:/path/to/bar.war!/ >-</source> >+<source>http://localhost:8080/manager/text/deploy?war=jar:file:/path/to/bar.war!/</source> > > >-<h3>Deploy a Directory or War from the Host appBase</h3> >+<h5>Deploy a Directory or War from the Host appBase</h5> > > <p>Deploy a web application directory or ".war" file located in your Host > appBase directory. The directory name or the war file name without the ".war" >@@ -398,20 +378,16 @@ > <code>foo</code> in the Host appBase directory of the Tomcat server is > deployed as the web application context named <code>/foo</code>. Notice > that the context path used is the name of the web application directory.</p> >-<source> >-http://localhost:8080/manager/text/deploy?war=foo >-</source> >+<source>http://localhost:8080/manager/text/deploy?war=foo</source> > > > <p>In this example the ".war" file <code>bar.war</code> located in your > Host appBase directory on the Tomcat server is deployed as the web > application context named <code>/bar</code>.</p> >-<source> >-http://localhost:8080/manager/text/deploy?war=bar.war >-</source> >+<source>http://localhost:8080/manager/text/deploy?war=bar.war</source> > > >-<h3>Deploy using a Context configuration ".xml" file</h3> >+<h5>Deploy using a Context configuration ".xml" file</h5> > > <p>If the Host deployXML flag is set to true you can deploy a web > application using a Context configuration ".xml" file and an optional >@@ -423,10 +399,8 @@ > web application Context just as if it were configured in your > Tomcat <code>server.xml</code> configuration file. Here is an > example:</p> >-<source> >-<Context path="/foobar" docBase="/path/to/application/foobar"> >-</Context> >-</source> >+<source><![CDATA[<Context path="/foobar" docBase="/path/to/application/foobar"> >+</Context>]]></source> > > > <p>When the optional <code>war</code> parameter is set to the URL >@@ -435,21 +409,17 @@ > > <p>Here is an example of deploying an application using a Context > configuration ".xml" file.</p> >-<source> >-http://localhost:8080/manager/text/deploy?config=file:/path/context.xml >-</source> >+<source>http://localhost:8080/manager/text/deploy?config=file:/path/context.xml</source> > > > <p>Here is an example of deploying an application using a Context > configuration ".xml" file and a web application ".war" file located > on the server.</p> >-<source> >-http://localhost:8080/manager/text/deploy >- ?config=file:/path/context.xml&war=jar:file:/path/bar.war!/ >-</source> >+<source>http://localhost:8080/manager/text/deploy >+ ?config=file:/path/context.xml&war=jar:file:/path/bar.war!/</source> > > >-<h3>Deployment Notes</h3> >+<h5>Deployment Notes</h5> > > <p>If the Host is configured with unpackWARs=true and you deploy a war > file, the war will be unpacked into a directory in your Host appBase >@@ -467,19 +437,16 @@ > files located outside of their Host appBase.</p> > > >-<h3>Deploy Response</h3> >+<h5>Deploy Response</h5> > > <p>If installation and startup is successful, you will receive a response > like this:</p> >-<source> >-OK - Deployed application at context path /foo >-</source> >+<source>OK - Deployed application at context path /foo</source> > > <p>Otherwise, the response will start with <code>FAIL</code> and include an > error message. Possible causes for problems include:</p> > <ul> > <li><em>Application already exists at path /foo</em> >- <blockquote> > <p>The context paths for all currently running web applications must be > unique. Therefore, you must undeploy the existing web > application using this context path, or choose a different context path >@@ -487,48 +454,43 @@ > a parameter on the URL, with a value of <code>true</code> to avoid this > error. In that case, an undeploy will be performed on an existing > application before performing the deployment.</p> >- </blockquote></li> >+ </li> > <li><em>Document base does not exist or is not a readable directory</em> >- <blockquote> > <p>The URL specified by the <code>war</code> parameter must identify a > directory on this server that contains the "unpacked" version of a > web application, or the absolute URL of a web application archive (WAR) > file that contains this application. Correct the value specified by > the <code>war</code> parameter.</p> >- </blockquote></li> >+ </li> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to start the new web application. > Check the Tomcat logs for the details, but likely explanations include > problems parsing your <code>/WEB-INF/web.xml</code> file, or missing > classes encountered when initializing application event listeners and > filters.</p> >- </blockquote></li> >+ </li> > <li><em>Invalid application URL was specified</em> >- <blockquote> > <p>The URL for the directory or web application that you specified > was not valid. Such URLs must start with <code>file:</code>, and URLs > for a WAR file must end in ".war".</p> >- </blockquote></li> >+ </li> > <li><em>Invalid context path was specified</em> >- <blockquote> > <p>The context path must start with a slash character. To reference the > ROOT web application use "/".</p> >- </blockquote></li> >+ </li> > <li><em>Context path must match the directory or WAR file name:</em> >- <blockquote> >- If the application war or directory is installed in your Host appBase >+ <p>If the application war or directory is installed in your Host appBase > directory and either the Host is configured with autoDeploy=true the > Context path must match the directory name or war file name without >- the ".war" extension. >- </blockquote></li> >+ the ".war" extension.</p> >+ </li> > <li><em>Only web applications in the Host web application directory can > be installed</em> >- <blockquote> >+ <p> > If the Host deployXML flag is set to false this error will happen > if an attempt is made to deploy a web application directory or > ".war" file outside of the Host appBase directory. >- </blockquote></li> >+ </p></li> > </ul> > > </subsection> >@@ -535,29 +497,23 @@ > > <subsection name="List Currently Deployed Applications"> > >-<source> >-http://localhost:8080/manager/text/list >-</source> >+<source>http://localhost:8080/manager/text/list</source> > > <p>List the context paths, current status (<code>running</code> or > <code>stopped</code>), and number of active sessions for all currently > deployed web applications. A typical response immediately > after starting Tomcat might look like this:</p> >-<source> >-OK - Listed applications for virtual host localhost >+<source>OK - Listed applications for virtual host localhost > /webdav:running:0 > /examples:running:0 > /manager:running:0 >-/:running:0 >-</source> >+/:running:0</source> > > </subsection> > > <subsection name="Reload An Existing Application"> > >-<source> >-http://localhost:8080/manager/text/reload?path=/examples >-</source> >+<source>http://localhost:8080/manager/text/reload?path=/examples</source> > > <p>Signal an existing application to shut itself down and reload. This can > be useful when the web application context is not reloadable and you have >@@ -572,34 +528,29 @@ > </p> > > <p>If this command succeeds, you will see a response like this:</p> >-<source> >-OK - Reloaded application at context path /examples >-</source> >+<source>OK - Reloaded application at context path /examples</source> > > <p>Otherwise, the response will start with <code>FAIL</code> and include an > error message. Possible causes for problems include:</p> > <ul> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to restart the web application. > Check the Tomcat logs for the details.</p> >- </blockquote></li> >+ </li> > <li><em>Invalid context path was specified</em> >- <blockquote> > <p>The context path must start with a slash character. To reference the > ROOT web application use "/".</p> >- </blockquote></li> >+ </li> > <li><em>No context exists for path /foo</em> >- <blockquote> > <p>There is no deployed application on the context path > that you specified.</p> >- </blockquote></li> >+ </li> > <li><em>No context path was specified</em> >- <blockquote> >+ <p> > The <code>path</code> parameter is required. >- </blockquote></li> >+ </p></li> > <li><em>Reload not supported on WAR deployed at path /foo</em> >- <blockquote> >+ <p> > Currently, application reloading (to pick up changes to the classes or > <code>web.xml</code> file) is not supported when a web application is > deployed directly from a WAR file. It only works when the web application >@@ -607,7 +558,7 @@ > you should <code>undeploy</code> and then <code>deploy</code> or > <code>deploy</code> with the <code>update</code> parameter the > application again to pick up your changes. >- </blockquote></li> >+ </p></li> > </ul> > > </subsection> >@@ -614,9 +565,7 @@ > > <subsection name="List OS and JVM Properties"> > >-<source> >-http://localhost:8080/manager/text/serverinfo >-</source> >+<source>http://localhost:8080/manager/text/serverinfo</source> > > <p>Lists information about the Tomcat version, OS, and JVM properties.</p> > >@@ -624,10 +573,9 @@ > include an error message. Possible causes for problems include:</p> > <ul> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to enumerate the system properties. > Check the Tomcat logs for the details.</p> >- </blockquote></li> >+ </li> > </ul> > > </subsection> >@@ -634,9 +582,7 @@ > > <subsection name="List Available Global JNDI Resources"> > >-<source> >-http://localhost:8080/manager/text/resources[?type=xxxxx] >-</source> >+<source>http://localhost:8080/manager/text/resources[?type=xxxxx]</source> > > <p>List the global JNDI resources that are available for use in resource > links for context configuration files. If you specify the <code>type</code> >@@ -648,13 +594,9 @@ > > <p>Depending on whether the <code>type</code> request parameter is specified > or not, the first line of a normal response will be:</p> >-<pre> >- OK - Listed global resources of all types >-</pre> >+<source>OK - Listed global resources of all types</source> > <p>or</p> >-<pre> >- OK - Listed global resources of type xxxxx >-</pre> >+<source>OK - Listed global resources of type xxxxx</source> > <p>followed by one line for each resource. Each line is composed of fields > delimited by colon characters (":"), as follows:</p> > <ul> >@@ -669,15 +611,13 @@ > include an error message. Possible causes for problems include:</p> > <ul> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to enumerate the global JNDI > resources. Check the Tomcat logs for the details.</p> >- </blockquote></li> >+ </li> > <li><em>No global JNDI resources are available</em> >- <blockquote> > <p>The Tomcat server you are running has been configured without > global JNDI resources.</p> >- </blockquote></li> >+ </li> > </ul> > > >@@ -685,9 +625,7 @@ > > <subsection name="Session Statistics"> > >-<source> >-http://localhost:8080/manager/text/sessions?path=/examples >-</source> >+<source>http://localhost:8080/manager/text/sessions?path=/examples</source> > > <p>Display the default session timeout for a web application, and the > number of currently active sessions that fall within ten-minute ranges of >@@ -694,11 +632,9 @@ > their actual timeout times. For example, after restarting Tomcat and then > executing one of the JSP samples in the <code>/examples</code> web app, > you might get something like this:</p> >-<source> >-OK - Session information for application at context path /examples >+<source>OK - Session information for application at context path /examples > Default maximum session inactive interval 30 minutes >-30 - <40 minutes:1 sessions >-</source> >+30 - <40 minutes:1 sessions</source> > > </subsection> > >@@ -705,9 +641,7 @@ > > <subsection name="Start an Existing Application"> > >-<source> >-http://localhost:8080/manager/text/start?path=/examples >-</source> >+<source>http://localhost:8080/manager/text/start?path=/examples</source> > > <p>Signal a stopped application to restart, and make itself available again. > Stopping and starting is useful, for example, if the database required by >@@ -716,32 +650,27 @@ > users continuously encounter database exceptions.</p> > > <p>If this command succeeds, you will see a response like this:</p> >-<source> >-OK - Started application at context path /examples >-</source> >+<source>OK - Started application at context path /examples</source> > > <p>Otherwise, the response will start with <code>FAIL</code> and include an > error message. Possible causes for problems include:</p> > <ul> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to start the web application. > Check the Tomcat logs for the details.</p> >- </blockquote></li> >+ </li> > <li><em>Invalid context path was specified</em> >- <blockquote> > <p>The context path must start with a slash character. To reference the > ROOT web application use "/".</p> >- </blockquote></li> >+ </li> > <li><em>No context exists for path /foo</em> >- <blockquote> > <p>There is no deployed application on the context path > that you specified.</p> >- </blockquote></li> >+ </li> > <li><em>No context path was specified</em> >- <blockquote> >+ <p> > The <code>path</code> parameter is required. >- </blockquote></li> >+ </p></li> > </ul> > > </subsection> >@@ -748,9 +677,7 @@ > > <subsection name="Stop an Existing Application"> > >-<source> >-http://localhost:8080/manager/text/stop?path=/examples >-</source> >+<source>http://localhost:8080/manager/text/stop?path=/examples</source> > > <p>Signal an existing application to make itself unavailable, but leave it > deployed. Any request that comes in while an application is >@@ -758,32 +685,26 @@ > "stopped" on a list applications command.</p> > > <p>If this command succeeds, you will see a response like this:</p> >-<source> >-OK - Stopped application at context path /examples >-</source> >+<source>OK - Stopped application at context path /examples</source> > > <p>Otherwise, the response will start with <code>FAIL</code> and include an > error message. Possible causes for problems include:</p> > <ul> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to stop the web application. > Check the Tomcat logs for the details.</p> >- </blockquote></li> >+ </li> > <li><em>Invalid context path was specified</em> >- <blockquote> > <p>The context path must start with a slash character. To reference the > ROOT web application use "/".</p> >- </blockquote></li> >+ </li> > <li><em>No context exists for path /foo</em> >- <blockquote> > <p>There is no deployed application on the context path > that you specified.</p> >- </blockquote></li> >+ </li> > <li><em>No context path was specified</em> >- <blockquote> > The <code>path</code> parameter is required. >- </blockquote></li> >+ </li> > </ul> > > </subsection> >@@ -791,11 +712,9 @@ > > <subsection name="Undeploy an Existing Application"> > >-<source> >-http://localhost:8080/manager/text/undeploy?path=/examples >-</source> >+<source>http://localhost:8080/manager/text/undeploy?path=/examples</source> > >-<p><strong><font color="red">WARNING</font> - This command will delete any web >+<p><strong><span style="color: red;">WARNING</span> - This command will delete any web > application artifacts that exist within <code>appBase</code> directory > (typically "webapps") for this virtual host</strong>. > This will delete the the application .WAR, if present, >@@ -813,32 +732,26 @@ > <code>/deploy</code> command.</p> > > <p>If this command succeeds, you will see a response like this:</p> >-<source> >-OK - Undeployed application at context path /examples >-</source> >+<source>OK - Undeployed application at context path /examples</source> > > <p>Otherwise, the response will start with <code>FAIL</code> and include an > error message. Possible causes for problems include:</p> > <ul> > <li><em>Encountered exception</em> >- <blockquote> > <p>An exception was encountered trying to undeploy the web application. > Check the Tomcat logs for the details.</p> >- </blockquote></li> >+ </li> > <li><em>Invalid context path was specified</em> >- <blockquote> > <p>The context path must start with a slash character. To reference the > ROOT web application use "/".</p> >- </blockquote></li> >+ </li> > <li><em>No context exists for path /foo</em> >- <blockquote> > <p>There is no deployed application on the context path > that you specified.</p> >- </blockquote></li> >+ </li> > <li><em>No context path was specified</em> >- <blockquote> > The <code>path</code> parameter is required. >- </blockquote></li> >+ </li> > </ul> > > </subsection> >@@ -845,9 +758,7 @@ > > <subsection name="Finding memory leaks"> > >-<source> >-http://localhost:8080/manager/text/findleaks[?statusLine=[true|false]] >-</source> >+<source>http://localhost:8080/manager/text/findleaks[?statusLine=[true|false]]</source> > > <p><strong>The find leaks diagnostic triggers a full garbage collection. It > should be used with extreme caution on production systems.</strong></p> >@@ -866,9 +777,7 @@ > GC, you will need to check using tools like GC logging, JConsole or similar.</p> > > <p>If this command succeeds, you will see a response like this:</p> >-<source> >-/leaking-webapp >-</source> >+<source>/leaking-webapp</source> > > <p>If you wish to see a status line included in the response then include the > <code>statusLine</code> query parameter in the request with a value of >@@ -886,9 +795,7 @@ > > <subsection name="Connector SSL diagnostics"> > >-<source> >-http://localhost:8080/manager/text/sslConnectorCiphers >-</source> >+<source>http://localhost:8080/manager/text/sslConnectorCiphers</source> > > <p>The SSL Connector/Ciphers diagnostic lists the SSL ciphers that are currently > configured for each connector. For BIO and NIO, the names of the individual >@@ -895,8 +802,7 @@ > cipher suites are listed. For APR, the value of SSLCipherSuite is returned.</p> > > <p>The response will ook something like this:</p> >-<source> >-OK - Connector / SSL Cipher information >+<source>OK - Connector / SSL Cipher information > Connector[HTTP/1.1-8080] > SSL is not enabled for this connector > Connector[HTTP/1.1-8443] >@@ -904,8 +810,7 @@ > TLS_DHE_RSA_WITH_AES_128_CBC_SHA > TLS_ECDH_RSA_WITH_AES_128_CBC_SHA > TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA >- ... >-</source> >+ ...</source> > > </subsection> > >@@ -982,57 +887,53 @@ > <code><taskdef></code> element. Therefore, your <code>build.xml</code> > file might look something like this:</p> > >-<table border="1"> >-<tr><td><pre> >-<project name="My Application" default="compile" basedir="."> >+<source><![CDATA[<project name="My Application" default="compile" basedir="."> > >- <!-- Configure the directory into which the web application is built --> >- <property name="build" value="${basedir}/build"/> >+ <!-- Configure the directory into which the web application is built --> >+ <property name="build" value="${basedir}/build"/> > >- <!-- Configure the context path for this application --> >- <property name="path" value="/myapp"/> >+ <!-- Configure the context path for this application --> >+ <property name="path" value="/myapp"/> > >- <!-- Configure properties to access the Manager application --> >- <property name="url" value="http://localhost:8080/manager/text"/> >- <property name="username" value="myusername"/> >- <property name="password" value="mypassword"/> >+ <!-- Configure properties to access the Manager application --> >+ <property name="url" value="http://localhost:8080/manager/text"/> >+ <property name="username" value="myusername"/> >+ <property name="password" value="mypassword"/> > >- <!-- Configure the custom Ant tasks for the Manager application --> >- <taskdef name="deploy" classname="org.apache.catalina.ant.DeployTask"/> >- <taskdef name="list" classname="org.apache.catalina.ant.ListTask"/> >- <taskdef name="reload" classname="org.apache.catalina.ant.ReloadTask"/> >- <taskdef name="findleaks" classname="org.apache.catalina.ant.FindLeaksTask"/> >- <taskdef name="resources" classname="org.apache.catalina.ant.ResourcesTask"/> >- <taskdef name="start" classname="org.apache.catalina.ant.StartTask"/> >- <taskdef name="stop" classname="org.apache.catalina.ant.StopTask"/> >- <taskdef name="undeploy" classname="org.apache.catalina.ant.UndeployTask"/> >+ <!-- Configure the custom Ant tasks for the Manager application --> >+ <taskdef name="deploy" classname="org.apache.catalina.ant.DeployTask"/> >+ <taskdef name="list" classname="org.apache.catalina.ant.ListTask"/> >+ <taskdef name="reload" classname="org.apache.catalina.ant.ReloadTask"/> >+ <taskdef name="findleaks" classname="org.apache.catalina.ant.FindLeaksTask"/> >+ <taskdef name="resources" classname="org.apache.catalina.ant.ResourcesTask"/> >+ <taskdef name="start" classname="org.apache.catalina.ant.StartTask"/> >+ <taskdef name="stop" classname="org.apache.catalina.ant.StopTask"/> >+ <taskdef name="undeploy" classname="org.apache.catalina.ant.UndeployTask"/> > >- <!-- Executable Targets --> >- <target name="compile" description="Compile web application"> >- <!-- ... construct web application in ${build} subdirectory, and >- generated a ${path}.war ... --> >- </target> >+ <!-- Executable Targets --> >+ <target name="compile" description="Compile web application"> >+ <!-- ... construct web application in ${build} subdirectory, and >+ generated a ${path}.war ... --> >+ </target> > >- <target name="deploy" description="Install web application" >- depends="compile"> >- <deploy url="${url}" username="${username}" password="${password}" >- path="${path}" war="file:${build}${path}.war"/> >- </target> >+ <target name="deploy" description="Install web application" >+ depends="compile"> >+ <deploy url="${url}" username="${username}" password="${password}" >+ path="${path}" war="file:${build}${path}.war"/> >+ </target> > >- <target name="reload" description="Reload web application" >- depends="compile"> >- <reload url="${url}" username="${username}" password="${password}" >- path="${path}"/> >- </target> >+ <target name="reload" description="Reload web application" >+ depends="compile"> >+ <reload url="${url}" username="${username}" password="${password}" >+ path="${path}"/> >+ </target> > >- <target name="undeploy" description="Remove web application"> >- <undeploy url="${url}" username="${username}" password="${password}" >- path="${path}"/> >- </target> >+ <target name="undeploy" description="Remove web application"> >+ <undeploy url="${url}" username="${username}" password="${password}" >+ path="${path}"/> >+ </target> > >-</project> >-</pre></td></tr> >-</table> >+</project>]]></source> > > <p>Note: The definition of the resources task above will override the resources > datatype added in Ant 1.7. If you wish to use the resources datatype you will >@@ -1047,9 +948,7 @@ > consider it a security risk to include the real manager password in your > <code>build.xml</code> file's source code. To avoid this, omit the password > property, and specify it from the command line:</p> >-<pre> >- ant -Dpassword=secret deploy >-</pre> >+<source>ant -Dpassword=secret deploy</source> > > <subsection name="Tasks output capture"> > >@@ -1059,95 +958,91 @@ > <code><redirector></code> type attributes: > </p> > >-<table border="1" cellpadding="2" cellspacing="0"> >-<tbody> >+<table class="defaultTable"> > <tr> >-<td valign="top"><b>Attribute</b></td> >-<td valign="top"><b>Description</b></td> >-<td align="center" valign="top"><b>Required</b></td> >+<th>Attribute</th> >+<th>Description</th> >+<th style="text-align: center;">Required</th> > </tr> > <tr> >-<td valign="top">output</td> >-<td valign="top">Name of a file to which to write the output. If >+<td>output</td> >+<td>Name of a file to which to write the output. If > the error stream is not also redirected to a file or property, it will > appear in this output.</td> >-<td align="center" valign="top">No</td> >+<td style="text-align: center;">No</td> > </tr> > <tr> >-<td valign="top">error</td> >-<td valign="top">The file to which the standard error of the >+<td>error</td> >+<td>The file to which the standard error of the > command should be redirected.</td> >-<td align="center" valign="top">No</td> >+<td style="text-align: center;">No</td> > </tr> > <tr> >-<td valign="top">logError</td> >-<td valign="top">This attribute is used when you wish to see >+<td>logError</td> >+<td>This attribute is used when you wish to see > error output in Ant's log and you are redirecting output to a > file/property. The error output will not be included in the output > file/property. If you redirect error with the <i>error</i> or <i>errorProperty</i> > attributes, this will have no effect.</td> >-<td align="center" valign="top">No</td> >+<td style="text-align: center;">No</td> > </tr> > <tr> >-<td valign="top">append</td> >-<td valign="top">Whether output and error files should be >+<td>append</td> >+<td>Whether output and error files should be > appended to or overwritten. Defaults to <code>false</code>.</td> >-<td align="center" valign="top">No</td> >+<td style="text-align: center;">No</td> > </tr> > <tr> >-<td valign="top">createemptyfiles</td> >-<td valign="top">Whether output and error files should be created >+<td>createemptyfiles</td> >+<td>Whether output and error files should be created > even when empty. Defaults to <code>true</code>.</td> >-<td align="center" valign="top">No</td> >+<td style="text-align: center;">No</td> > </tr> > <tr> >-<td valign="top">outputproperty</td> >-<td valign="top">The name of a property in which the output of >+<td>outputproperty</td> >+<td>The name of a property in which the output of > the command should be stored. Unless the error stream is redirected to > a separate file or stream, this property will include the error output.</td> >-<td align="center" valign="top">No</td> >+<td style="text-align: center;">No</td> > </tr> > <tr> >-<td valign="top">errorproperty</td> >-<td valign="top">The name of a property in which the standard >+<td>errorproperty</td> >+<td>The name of a property in which the standard > error of the command should be stored.</td> >-<td align="center" valign="top">No</td> >+<td style="text-align: center;">No</td> > </tr> >-</tbody> > </table> > > <p>A couple of additional attributes can also be specified: > </p> >-<table border="1" cellpadding="2" cellspacing="0"> >-<tbody> >+<table class="defaultTable"> > <tr> >-<td valign="top"><b>Attribute</b></td> >-<td valign="top"><b>Description</b></td> >-<td align="center" valign="top"><b>Required</b></td> >+<th>Attribute</th> >+<th>Description</th> >+<th style="text-align: center;">Required</th> > </tr> > <tr> >-<td valign="top">alwaysLog</td> >-<td valign="top">This attribute is used when you wish to see the >+<td>alwaysLog</td> >+<td>This attribute is used when you wish to see the > output you are capturing, appearing also in the Ant's log. It must not be > used unless you are capturing task output. > Defaults to <code>false</code>. > <em>This attribute will be supported directly by <code><redirector></code> > in Ant 1.6.3</em></td> >-<td align="center" valign="top">No</td> >+<td style="text-align: center;">No</td> > </tr> > <tr> >-<td valign="top">failonerror</td> >-<td valign="top">This attribute is used when you wish to avoid that >+<td>failonerror</td> >+<td>This attribute is used when you wish to avoid that > any manager command processing error terminates the ant execution. Defaults to <code>true</code>. > It must be set to <code>false</code>, if you want to capture error output, > otherwise execution will terminate before anything can be captured. >-<br></br> >+<br/> > This attribute acts only on manager command execution, > any wrong or missing command attribute will still cause Ant execution termination. > </td> >-<td align="center" valign="top">No</td> >+<td style="text-align: center;">No</td> > </tr> >-</tbody> > </table> > > <p>They also support the embedded <code><redirector></code> element >@@ -1164,73 +1059,69 @@ > can be used: > </p> > >-<table border="1"> >-<tr><td><pre> >- <target name="manager.deploy" >+<source><![CDATA[ <target name="manager.deploy" > depends="context.status" >- if="context.notInstalled"> >- <deploy url="${mgr.url}" >+ if="context.notInstalled"> >+ <deploy url="${mgr.url}" > username="${mgr.username}" > password="${mgr.password}" > path="${mgr.context.path}" >- config="${mgr.context.descriptor}"/> >- </target> >+ config="${mgr.context.descriptor}"/> >+ </target> > >- <target name="manager.deploy.war" >+ <target name="manager.deploy.war" > depends="context.status" >- if="context.deployable"> >- <deploy url="${mgr.url}" >+ if="context.deployable"> >+ <deploy url="${mgr.url}" > username="${mgr.username}" > password="${mgr.password}" > update="${mgr.update}" > path="${mgr.context.path}" >- war="${mgr.war.file}"/> >- </target> >+ war="${mgr.war.file}"/> >+ </target> > >- <target name="context.status"> >- <property name="running" value="${mgr.context.path}:running"/> >- <property name="stopped" value="${mgr.context.path}:stopped"/> >+ <target name="context.status"> >+ <property name="running" value="${mgr.context.path}:running"/> >+ <property name="stopped" value="${mgr.context.path}:stopped"/> > >- <list url="${mgr.url}" >+ <list url="${mgr.url}" > outputproperty="ctx.status" > username="${mgr.username}" >- password="${mgr.password}"> >- </list> >+ password="${mgr.password}"> >+ </list> > >- <condition property="context.running"> >- <contains string="${ctx.status}" substring="${running}"/> >- </condition> >- <condition property="context.stopped"> >- <contains string="${ctx.status}" substring="${stopped}"/> >- </condition> >- <condition property="context.notInstalled"> >- <and> >- <isfalse value="${context.running}"/> >- <isfalse value="${context.stopped}"/> >- </and> >- </condition> >- <condition property="context.deployable"> >- <or> >- <istrue value="${context.notInstalled}"/> >- <and> >- <istrue value="${context.running}"/> >- <istrue value="${mgr.update}"/> >- </and> >- <and> >- <istrue value="${context.stopped}"/> >- <istrue value="${mgr.update}"/> >- </and> >- </or> >- </condition> >- <condition property="context.undeployable"> >- <or> >- <istrue value="${context.running}"/> >- <istrue value="${context.stopped}"/> >- </or> >- </condition> >- </target> >-</pre></td></tr> >-</table> >+ <condition property="context.running"> >+ <contains string="${ctx.status}" substring="${running}"/> >+ </condition> >+ <condition property="context.stopped"> >+ <contains string="${ctx.status}" substring="${stopped}"/> >+ </condition> >+ <condition property="context.notInstalled"> >+ <and> >+ <isfalse value="${context.running}"/> >+ <isfalse value="${context.stopped}"/> >+ </and> >+ </condition> >+ <condition property="context.deployable"> >+ <or> >+ <istrue value="${context.notInstalled}"/> >+ <and> >+ <istrue value="${context.running}"/> >+ <istrue value="${mgr.update}"/> >+ </and> >+ <and> >+ <istrue value="${context.stopped}"/> >+ <istrue value="${mgr.update}"/> >+ </and> >+ </or> >+ </condition> >+ <condition property="context.undeployable"> >+ <or> >+ <istrue value="${context.running}"/> >+ <istrue value="${context.stopped}"/> >+ </or> >+ </condition> >+ </target>]]></source> > > <p><strong>WARNING:</strong> even if it doesn't make many sense, and is always a bad idea, > calling a Catalina task more than once, >@@ -1265,12 +1156,10 @@ > </subsection> > > <subsection name="JMX Query command"> >- This takes the form: >-<source> >-http://webserver/manager/jmxproxy/?qry=STUFF >-</source> >- Where <code>STUFF</code> is the JMX query you wish to perform. For example, >- here are some queries you might wish to run: >+ <p>This takes the form:</p> >+<source>http://webserver/manager/jmxproxy/?qry=STUFF</source> >+ <p>Where <code>STUFF</code> is the JMX query you wish to perform. For example, >+ here are some queries you might wish to run:</p> > <ul> > <li> > <code>qry=*%3Atype%3DRequestProcessor%2C* --> >@@ -1288,96 +1177,85 @@ > which look for a specific MBean by the given name. > </li> > </ul> >+ <p> > You'll need to experiment with this to really understand its capabilites. > If you provide no <code>qry</code> parameter, then all of the MBeans will > be displayed. We really recommend looking at the tomcat source code and > understand the JMX spec to get a better understanding of all the queries > you may run. >+ </p> > </subsection> > > <subsection name="JMX Get command"> >+ <p> > The JXMProxyServlet also supports a "get" command that you can use to > fetch the value of a specific MBean's attribute. The general form of > the <code>get</code> command is: >+ </p> > >-<source> >-http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY >-</source> >+<source>http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY</source> > >- You must provide the following parameters: >+ <p>You must provide the following parameters:</p> > <ol> > <li><code>get</code>: The full bean name</li> > <li><code>att</code>: The attribute you wish to fetch</li> > <li><code>key</code>: (optional) The key into a CompositeData MBean attribute</li> > </ol> >- >+ <p> > If all goes well, then it will say OK, otherwise an error message will > be shown. For example, let's say we wish to fetch the current heap memory > data: >+ </p> > >-<source> >-http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage >-</source> >+<source>http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage</source> > >- Or, if you only want the "used" key: >+ <p>Or, if you only want the "used" key:</p> > >-<source> >-http://webserver/manager/jmxproxy/ >- ?get=java.lang:type=Memory&att=HeapMemoryUsage&key=used >-</source> >+<source>http://webserver/manager/jmxproxy/ >+ ?get=java.lang:type=Memory&att=HeapMemoryUsage&key=used</source> > </subsection> > > <subsection name="JMX Set command"> >+ <p> > Now that you can query an MBean, its time to muck with Tomcat's internals! > The general form of the set command is : >-<source> >-http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE >-</source> >- So you need to provide 3 request parameters: >+ </p> >+<source>http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE</source> >+ <p>So you need to provide 3 request parameters:</p> > <ol> > <li><code>set</code>: The full bean name</li> > <li><code>att</code>: The attribute you wish to alter</li> > <li><code>val</code>: The new value </li> > </ol> >+ <p> > If all goes ok, then it will say OK, otherwise an error message will be > shown. For example, lets say we wish to turn up debugging on the fly for the > <code>ErrorReportValve</code>. The following will set debugging to 10. >-<source> >-http://localhost:8080/manager/jmxproxy/ >+ </p> >+<source>http://localhost:8080/manager/jmxproxy/ > ?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost >- &att=debug&val=10 >-</source> >- and my result is (YMMV): >-<source> >-Result: ok >-</source> >+ &att=debug&val=10</source> >+ <p>and my result is (YMMV):</p> >+<source>Result: ok</source> > >- Here is what I see if I pass in a bad value. Here is the URL I used, >- I try set debugging equal to 'cow': >-<source> >-http://localhost:8080/manager/jmxproxy/ >+ <p>Here is what I see if I pass in a bad value. Here is the URL I used, >+ I try set debugging equal to 'cow':</p> >+<source>http://localhost:8080/manager/jmxproxy/ > ?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost >- &att=debug&val=cow >-</source> >- When I try that, my result is >-<source> >-Error: java.lang.NumberFormatException: For input string: "cow" >-</source> >+ &att=debug&val=cow</source> >+ <p>When I try that, my result is</p> >+<source>Error: java.lang.NumberFormatException: For input string: "cow"</source> > </subsection> > > <subsection name="JMX Invoke command"> > <p>The <code>invoke</code> command enables methods to be called on MBeans. The > general form of the command is:</p> >-<source> >-http://webserver/manager/jmxproxy/ >- ?invoke=BEANNAME&op=METHODNAME&ps=COMMASEPARATEDPARAMETERS >-</source> >+<source>http://webserver/manager/jmxproxy/ >+ ?invoke=BEANNAME&op=METHODNAME&ps=COMMASEPARATEDPARAMETERS</source> > <p>For example, to call the <code>findConnectors()</code> method of the > <strong>Service</strong> use:</p> >-<source> >-http://localhost:8080/manager/jmxproxy/ >- ?invoke=Catalina%3Atype%3DService&op=findConnectors&ps= >-</source> >+<source>http://localhost:8080/manager/jmxproxy/ >+ ?invoke=Catalina%3Atype%3DService&op=findConnectors&ps=</source> > </subsection> > </section> >
You cannot view the attachment while viewing its details because your browser does not support IFRAMEs.
View the attachment on a separate page
.
View Attachment As Diff
View Attachment As Raw
Actions:
View
|
Diff
Attachments on
bug 55383
:
30719
|
30735
|
30739
|
30740
|
30741
|
30760
| 30772 |
30778
|
30779
|
30786
|
30793
|
30797
|
30809
|
30812
|
30813
|
30814
|
30815
|
30818
|
30819
|
30824
|
30862
|
30863
|
30864