Attachment #30772 for bug #55383

View | Details | Raw Unified | Return to bug 55383
Collapse All | Expand All





  <p>So why do we need a new connection pool?</p>

  <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

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

          This is achieved using the <code>dataSource</code> and <code>dataSourceJNDI</code> attributes.</li>
      <li>XA connection support</li>
    </ol>
  </p>


</section>

    </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>
         <ul>
           <li><code>NONE</code></li>
           <li><code>READ_COMMITTED</code></li>

           <li><code>REPEATABLE_READ</code></li>
           <li><code>SERIALIZABLE</code></li>
         </ul>
         <p>If not set, the method will not be called and it defaults to the JDBC driver.</p>
      </p>
    </attribute>

    <attribute name="defaultCatalog" required="false">

  <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><![CDATA[  import java.sql.Connection;
  import java.sql.Connection;
  import java.sql.ResultSet;
  import java.sql.Statement;


          p.setLogAbandoned(true);
          p.setRemoveAbandoned(true);
          p.setJdbcInterceptors(
            "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;"+
            "org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer");
          DataSource datasource = new DataSource();
          datasource.setPoolProperties(p);


          }
      }

  }]]></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><![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>
          url=&quot;jdbc:mysql://localhost:3306/mysql&quot;/&gt;
</source>

  </subsection>
  <subsection name="Asynchronous Connection Retrieval">

    <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&lt;Connection&gt; 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><![CDATA[  Connection con = null;
  Connection con = null;
  try {
    Future<Connection> future = datasource.getConnectionAsync();
    while (!future.isDone()) {
      System.out.println("Connection is not yet available. Do some background work");
      try {

    }
    con = future.get(); //should return instantly
    Statement st = con.createStatement();
    ResultSet rs = st.executeQuery("select * from user");]]></source>

    </p>
  </subsection>
  <subsection name="Interceptors">
    <p>Interceptors are a powerful way to enable, disable or modify functionality on a specific connection or its sub components.

       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><![CDATA[  public JdbcInterceptor() {
  }]]></source>
  }
</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
    </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
    </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
    </p>
<source><![CDATA[  if (CLOSE_VAL==method.getName()) {
      if (isClosed()) return null; //noop for already closed.
  }
  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>&quot;close&quot;.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:
    </p>
<source><![CDATA[  if (compare(CLOSE_VAL,method)) {
      if (isClosed()) return null; //noop for already closed.
  }
  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>

    <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.
    </p>
<source><![CDATA[  public void poolStarted(ConnectionPool pool) {
  }

  public void poolClosed(ConnectionPool pool) {
  }]]></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=
    &quot;org.apache.tomcat.jdbc.pool.interceptor.ConnectionState(useEquals=true,fast=yes)&quot;
</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.
    </p>
<source><![CDATA[  public void setProperties(Map<String, InterceptorProperty> properties) {
     super.setProperties(properties);
     final String myprop = "myprop";
     InterceptorProperty p1 = properties.get(myprop);
     if (p1!=null) {
         setMyprop(Long.parseLong(p1.getValue()));
     }
  }]]></source>

    </p>
  </subsection>
  <subsection name="Getting the actual JDBC connection">
    <p>Connection pools create wrappers around the actual connection in order to properly pool them.

       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>

  <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><![CDATA[  javac -classpath tomcat-juli.jar \
  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>
</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.
    </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>
    <p>
      The system is structured for a Maven build, but does generate release artifacts. Just the library itself.
    </p>




    described above:
  </p>

  <source><![CDATA[public class ChatServlet
public class ChatServlet
    extends HttpServlet implements CometProcessor {

    protected ArrayList<HttpServletResponse> connections =
        new ArrayList<HttpServletResponse>();
    protected MessageSender messageSender = null;

    public void init() throws ServletException {

        if (event.getEventType() == CometEvent.EventType.BEGIN) {
            log("Begin for session: " + request.getSession(true).getId());
            PrintWriter writer = response.getWriter();
            writer.println("<!DOCTYPE html>");
            writer.println("<head><title>JSP Chat</title></head><body>");
            writer.flush();
            synchronized(connections) {
                connections.add(response);

                connections.remove(response);
            }
            PrintWriter writer = response.getWriter();
            writer.println("</body></html>");
            event.close();
        } else if (event.getEventType() == CometEvent.EventType.READ) {
            InputStream is = request.getInputStream();

            byte[] buf = new byte[512];
            do {
                int n = is.read(buf); //can throw an IOException
                if (n > 0) {
                    log("Read " + n + " bytes: " + new String(buf, 0, n)
                            + " for session: " + request.getSession(true).getId());
                } else if (n < 0) {
                    error(event, request, response);
                    return;
                }

    public class MessageSender implements Runnable {

        protected boolean running = true;
        protected ArrayList<String> messages = new ArrayList<String>();

        public MessageSender() {
        }

                        messages.clear();
                    }
                    // Send any pending message on all the open connections
                    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>");
                            }
                            writer.flush();
                        } catch (IOException e) {


    }

}]]></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:</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>





    <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">



    <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

      <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 &amp;&amp; make &amp;&amp; make install</source>
    </p>
    <source>./configure &amp;&amp; make &amp;&amp; make install</source>

    </subsection>



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

      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:
	</p>
      <source><![CDATA[<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />]]></source>
    
    </p>
    <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>


      connector configuration documentation.</p>

      <p>For HTTPS configuration, see the
      <a href="config/http.html#SSL_Support">HTTPS</a> connector configuration
      documentation.</p>

      <p>An example SSL Connector declaration is:</p>
      <source><![CDATA[<Connector port="443" maxHttpHeaderSize="8192"
      &lt;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>
      

    </subsection>






<p>
Use the following commands to build Tomcat:
<br/><br/>
<code>
    cd ${tomcat.source}<br/>
    ant
</code>
</p>


<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

Variables</em> to add two new <em>Classpath Variables</em>:
</p>


<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-&gt;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>)

Tweaking a few formatting preferences will make it much easier to keep consistent with Tomcat
coding conventions (and have your contributions accepted):
</p>

<table class="defaultTable">
  <tr><td>Java -&gt; Code Style -> Formatter -&gt; Edit...</td>
  <td>Tab policy: Spaces only<br/>Tab and Indentation size: 4</td></tr>
  <tr><td>General -&gt; Editors -> Text Editors</td>

  <tr><td>XML -&gt; XML Files -> Editor</td><td>Indent using spaces<br/>Indentation size: 2</td></tr>
  <tr><td>Ant -&gt; 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">




<section name="Configuration">

<p>There are several servlet init parameters which can be used to
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.

the reading of stderr to complete before terminating the CGI process. Default
is 2000.</li>
</ul>
</p>


</section>

</body>




organized into the following parent-child relationships, where the parent
class loader is above the child class loader:</p>

<source>      Bootstrap
      Bootstrap
          |
       System
          |
       Common
       /     \
  Webapp1   Webapp2 ...</source>
</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





<section name="For the impatient">
  <p>
    Simply add
  </p>
  <source>&lt;Cluster className=&quot;org.apache.catalina.ha.tcp.SimpleTcpCluster&quot;/&gt;</source>
  <p>
    to your <code>&lt;Engine&gt;</code> or your <code>&lt;Host&gt;</code> element to enable clustering.
  </p>
  <p>

    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.
  </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"/>

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

          <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"/>

          <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>
        </Cluster>]]></source>
    </source>
  </p>
  <p>Will cover this section in more detail later in this document.</p>
</section>


   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>
</section>



   A very simple setup would look like this:
   </p>

<source>        DNS Round Robin
        DNS Round Robin
               |
         Load Balancer
          /           \
      Cluster1      Cluster2
      /     \        /     \
  Tomcat1 Tomcat2  Tomcat3 Tomcat4</source>
</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

</section>

<section name="Configuration Example">
    <source><![CDATA[        <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
                 channelSendOptions="6">
                 channelSendOptions=&quot;6&quot;&gt;

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

          <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"/>

          <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>
        </Cluster>]]></source>
    </source>
    <p>
      Break it down!!
    </p>
    <source><![CDATA[        <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
                 channelSendOptions="6">]]></source>
                 channelSendOptions=&quot;6&quot;&gt;
    </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

      sends it itself directly through the channel.
      <br/>For more info, Please visit the <a href="config/cluster.html">reference documentation</a>
    </p>
    <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>
          --&gt;
    </source>
    <p>
        This is a template for the manager configuration that will be used if no manager is defined in the &lt;Context&gt;
        element. In Tomcat 5.x each webapp marked distributable had to use the same manager, this is no longer the case

        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><![CDATA[          <Channel className="org.apache.catalina.tribes.group.GroupChannel">]]></source>
          &lt;Channel className=&quot;org.apache.catalina.tribes.group.GroupChannel&quot;&gt;
    </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><![CDATA[            <Membership className="org.apache.catalina.tribes.membership.McastService"
                        address="228.0.0.4"
                        port="45564"
                        frequency="500"
                        dropTime="3000"/>]]></source>
                        dropTime=&quot;3000&quot;/&gt;
    </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.

        <code>Receiver.address</code> attribute.
        <br/>For more info, Please visit the <a href="config/cluster-membership.html">reference documentation</a>
    </p>
    <source><![CDATA[            <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
                      address="auto"
                      port="5000"
                      selectorTimeout="100"
                      maxThreads="6"/>]]></source>
                      maxThreads=&quot;6&quot;/&gt;
    </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),

        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><![CDATA[            <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
              <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/>
            </Sender>]]></source>
              &lt;Transport className=&quot;org.apache.catalina.tribes.transport.nio.PooledParallelSender&quot;/&gt;
            &lt;/Sender&gt;
    </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

        at the same time.
        <br/>For more info, Please visit the <a href="config/cluster-sender.html">reference documentation</a>
    </p>
    <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>
          &lt;/Channel&gt;
    </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.

        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><![CDATA[          <Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
                 filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"/>]]></source>
                 filter=&quot;.*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt&quot;/&gt;
    </source>
    <p>
        The cluster uses valves to track requests to web applications, we've mentioned the ReplicationValve and the JvmRouteBinderValve above.
        The &lt;Cluster&gt; element itself is not part of the pipeline in Tomcat, instead the cluster adds the valve to its parent container.

        If the &lt;Cluster&gt; elements is configured in the &lt;Engine&gt; 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><![CDATA[          <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
                    tempDir="/tmp/war-temp/"
                    deployDir="/tmp/war-deploy/"
                    watchDir="/tmp/war-listen/"
                    watchEnabled="false"/>]]></source>
                    watchEnabled=&quot;false&quot;/&gt;
    </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

        webapps directory.
        <br/>For more info, Please visit the <a href="config/cluster-deployer.html">reference documentation</a>
    </p>
    <source><![CDATA[          <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>
        </Cluster>]]></source>
        &lt;/Cluster&gt;
    </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


<section name="Cluster Architecture">

<p><b>Component Levels:</b></p>
<source>         Server
         Server
           |
         Service
           |

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

        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>
</li>
<li><b><code>TomcatB</code> starts up</b>
    <p>

        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>
</li>
<li><B><code>TomcatA</code> receives a request, a session <code>S1</code> is created.</B>
    <p>

        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>

</li>
<li><b><code>TomcatA</code> crashes</b>

        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>
</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>
</li>
<li><b><code>TomcatA</code> starts up</b>
    <p>Upon start up, before TomcatA starts taking new request and making itself

    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>
</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>

</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>


</li>

       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>
</li>
</ol>



<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:</p>
<source>set CATALINA_OPTS=\
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>

<p>
  List of Cluster Mbeans
</p>
<table class="defaultTable">
List of Cluster Mbeans<br/>
<table border="1" cellpadding="5">

  <tr>
    <th>Name</th>
    <th>Description</th>
    <th>MBean ObjectName - Engine</th>
    <th>MBean ObjectName - Host</th>
  </tr>

  <tr>

  </tr>

</table>
</p>
</section>

<section name="FAQ">




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





</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:
</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-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?">
<p>
  The DefaultServlet allows the following initParamters:
</p>

<properties>
  <property name="debug">
    <th valign='top'>debug</th>
    <td valign='top'>
        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]
  </property>
  <property name="listings">
  <tr>
    <th valign='top'>listings</th>
    <td valign='top'>
        If no welcome file is present, can a directory listing be
        shown?
        value may be <b>true</b> or <b>false</b> [false]

        <b>WARNING:</b> Listings of directories containing many entries are
        expensive. Multiple requests for large directory listings can consume
        significant proportions of server resources.
  </property>
  <property name="readmeFile">
  <tr>
    <th valign='top'>readmeFile</th>
    <td valign='top'>
        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.
  </property>
  <property name="globalXsltFile">
  <tr>
    <th valign='top'>globalXsltFile</th>
    <td valign='top'>
        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.

        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.
  </property>
  <property name="contextXsltFile">
  <tr>
    <th valign='top'>contextXsltFile</th>
    <td valign='top'>
        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

        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.
  </property>
  <property name="localXsltFile">
  <tr>
    <th valign='top'>localXsltFile</th>
    <td valign='top'>
        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.

        <code>globalXsltFile</code> will be used. If
        <code>globalXsltFile</code> does not exist, then the default
        directory listing will be shown.
  </property>
  <property name="input">
  <tr>
    <th valign='top'>input</th>
    <td valign='top'>
        Input buffer size (in bytes) when reading
        resources to be served.  [2048]
  </property>
  <property name="output">
  <tr>
    <th valign='top'>output</th>
    <td valign='top'>
        Output buffer size (in bytes) when writing
        resources to be served.  [2048]
  </property>
  <property name="readonly">
  <tr>
    <th valign='top'>readonly</th>
    <td valign='top'>
        Is this context "read only", so HTTP commands like PUT and
        DELETE are rejected?  [true]
  </property>
  <property name="fileEncoding">
  <tr>
    <th valign='top'>fileEncoding</th>
    <td valign='top'>
        File encoding to be used when reading static resources.
        [platform default]
  </property>
  <property name="sendfileSize">
  <tr>
    <th valign='top'>sendfileSize</th>
    <td valign='top'>
        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]
  </property>
  <property name="useAcceptRanges">
  <tr>
    <th valign='top'>useAcceptRanges</th>
    <td valign='top'>
        If true, the Accept-Ranges header will be set when appropriate for the
        response. [true]
  </property>
</properties>

</table>
</section>

<section anchor="dir" name="How do I customize directory listings?">


<p>
Format:
</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'>
        fileName2
      </entry>
      ...
     </entries>
     <readme></readme>
    </listing>]]></source>
</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>
<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<source>
&lt;?xml version="1.0"?&gt;

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  version="3.0">

  <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>
        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;
             color : black;background-color : white;}
        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>
   &lt;/html&gt;
  &lt;/xsl:template&gt;


  <xsl:template match="entries">
    <xsl:apply-templates select="entry"/>
  </xsl:template>

  <xsl:template match="readme">
    <hr style="height: 1px;" />
    <pre><xsl:apply-templates/></pre>
  </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>
</source>

</section>


Lines 41-47 Link Here

(-)webapps/docs/deployer-howto.xml (-1 / +2 lines)
41	</p>	41	</p>
42	<p>	42	<p>
43	Web application deployment may be accomplished in a number of ways	43	Web application deployment may be accomplished in a number of ways
44	within the Tomcat server.</p>	44	within the Tomcat server.
		45	</p>
45	<ul>	46	<ul>
46	<li>Statically; the web application is setup before Tomcat is started</li>	47	<li>Statically; the web application is setup before Tomcat is started</li>
47	<li>	48	<li>




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>
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>
    </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>
    </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>
    </li>
<li><em>No context path was specified</em>
    <p>
    The <code>path</code> parameter is required.
    </p>
</li>
</ul>

</subsection>

"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>
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>
    </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>
    </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>
    </li>
<li><em>No context path was specified</em>
    <p>
    The <code>path</code> parameter is required.
    </p>
</li>
</ul>

</subsection>

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>
    </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>
    </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>
    </li>
<li><em>No context path was specified</em>
    <p>The <code>path</code> parameter is required.</p>
    </li>
    </blockquote></li>
<li><em>Reload not supported on WAR deployed at path /foo</em>
    <p>Currently, application reloading (to pick up changes to the classes or
    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.</p>
    </li>
</ul>

</subsection>


<subsection name="Undeploy">

<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

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>
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>
    </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>
    </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>
    </li>
<li><em>No context path was specified</em>
    <blockquote>
    The <code>path</code> parameter is required.
    </li>
</ul>

</subsection>


<p>There are a number of different ways the deploy command can be used.</p>

<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

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>
WAR or Directory URL: jar:file:/path/to/bar.war!/
</source>


<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

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>
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>
WAR or Directory URL: bar.war
</source>


<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

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><![CDATA[<Context path="/foobar" docBase="C:\path\to\application\foobar">
</Context>]]></source>
&lt;/Context&gt;
</source>


<p>Use of the <i>WAR or Directory URL</i> is optional. When used


<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>
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>
WAR or Directory URL: jar:file:/path/to/bar.war!/
</source>


</subsection>

<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>
    </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>
    </li>
<li><em>File upload failed, no file</em>
    <blockquote>
    <p>The file upload failed, no file was received by the server.</p>
    </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>
    </li>
</ul>

</subsection>


<p>If deployment and startup is successful, you will receive a Message
like this:</p>
<source>OK - Deployed application at context path /foo</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>
    </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>
    </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>
    </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>
    </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>
    </li>
<li><em>Context path must match the directory or WAR file name:</em>
    <p>If the application war or directory is deployed in your Host appBase
    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.</p>
    </li>
<li><em>Only web applications in the Host web application directory can
     be deployed</em>
     <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.
     </p></li>
</ul>

</subsection>





<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:</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

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>


<section name="Configuration">

<p>By default Jasper is configured for use when doing web application
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

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

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


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.</p>
<ul>
<li><strong>development</strong> - To disable on access checks for JSP
pages compilation set this to <code>false</code>.</li>

<li><strong>trimSpaces</strong> - To remove useless bytes from the response,
set this to <code>true</code>.</li>
</ul>
</p>

</section>


download) to precompile a webapp:
</p>

<source><![CDATA[<project name="Webapp Precompilation" default="all" basedir=".">
<source>
&lt;project name="Webapp Precompilation" default="all" basedir="."&gt;

   <import file="${tomcat.home}/bin/catalina-tasks.xml"/>

   <target name="jspc">

    <jasper
             validateXml="false"
             uriroot="${webapp.path}"
             webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml"
             outputDir="${webapp.path}/WEB-INF/src" />

  </target>

  <target name="compile">

    <mkdir dir="${webapp.path}/WEB-INF/classes"/>
    <mkdir dir="${webapp.path}/WEB-INF/lib"/>

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

  </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>

</project>]]></source>
</source>
</p>

<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):
<source>
$ANT_HOME/bin/ant -Dtomcat.home=&lt;$TOMCAT_HOME&gt; -Dwebapp.path=&lt;$WEBAPP_PATH&gt;
</source>
</p>
<source>$ANT_HOME/bin/ant -Dtomcat.home=&lt;$TOMCAT_HOME&gt; -Dwebapp.path=&lt;$WEBAPP_PATH&gt;</source>


<p>
Then, the declarations and mappings for the servlets which were generated
during the precompilation must be added to the web application deployment

<code>${webapp.path}/WEB-INF/classes/org/apache/jsp</code>.
</p>

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

that changing from the defaults may affect performance, but it will vary
depending on the application.</li>
</ul>
</p>
</section>

<section name="Optimisation">





<subsection name="MySQL DBCP Example">

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


<p>Before you proceed, don't forget to copy the JDBC Driver's jar into <code>$CATALINA_HOME/lib</code>.</p>

<h5>1. MySQL configuration</h5>
<p>
Ensure that you follow these instructions as variations can cause problems.
</p>

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><![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>
    -&gt;   bar int);
</source>
<blockquote>
<strong>Note:</strong> the above user should be removed once testing is
complete!


<p>Next insert some test data into the testdata table.
</p>
<source><![CDATA[mysql> insert into testdata values(null, 'hello', 12345);
mysql&gt; insert into testdata values(null, 'hello', 12345);
Query OK, 1 row affected (0.00 sec)

mysql> select * from testdata;

+----+-------+-------+
1 row in set (0.00 sec)

mysql>]]></source>
</source>

<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><![CDATA[<Context>
&lt;Context&gt;

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

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

  <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"/>

</Context>]]></source>
</source>

<h5>3. web.xml configuration</h5>

<p>Now create a <code>WEB-INF/web.xml</code> for this test application.</p>
<source><![CDATA[<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
&lt;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>
</source>

<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" %>
&lt;%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %&gt;

<sql:query var="rs" dataSource="jdbc/TestDB">
select id, foo, bar from testdata
</sql:query>

<html>
  <head>
    <title>DB Test</title>
  </head>
  <body>

  <h2>Results</h2>

<c:forEach var="row" items="${rs.rows}">
    Foo ${row.foo}<br/>
    Bar ${row.bar}<br/>
</c:forEach>

  </body>
</html>]]></source>
</source>
</p>

<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

</subsection>

<subsection name="Oracle 8i, 9i &amp; 10g">
<h5>0.    Introduction</h5>

<p>Oracle requires minimal changes from the MySQL configuration except for the
usual gotchas :-)</p>

for this driver class will be discontinued in the next major release.
</p>

<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,


<p>Use of the OCI driver should simply involve a changing thin to oci in the URL string.
</p>
<source><![CDATA[<Resource name="jdbc/myoracle" auth="Container"
&lt;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>
</source>

<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><![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>
</source>
<h3>3.   Code example</h3>
<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><![CDATA[Context initContext = new InitialContext();
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>
</source>
</subsection>


<subsection name="PostgreSQL">
<h5>0.    Introduction</h5>
<p>PostgreSQL is configured in a similar manner to Oracle.</p>

<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

them. This has to be done regardless of which configuration step you take next.
</p>

<h5>2. Resource configuration</h5>

<p>
You have two choices here: define a datasource that is shared across all Tomcat

applications, or define a datasource specifically for one application.
</p>

<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

<p><i>This author has not had success here, although others have reported so.
Clarification would be appreciated here.</i></p>

<source><![CDATA[<Resource name="jdbc/postgres" auth="Container"
&lt;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>
<h6>2b. Application-specific resource configuration</h6>
<h4>2b. Application-specific resource configuration</h4>

<p>
Use this option if you wish to define a datasource specific to your application,

The Context element should look something like the following.
</p>

<source><![CDATA[<Context>
&lt;Context&gt;

<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>
</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>
&lt;/resource-ref&gt;
</source>

<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

you change it in the above resource definition file as well.
</p>

<source><![CDATA[InitialContext cxt = new InitialContext();
InitialContext cxt = new InitialContext();
if ( cxt == null ) {
   throw new Exception("Uh oh -- no context!");
}


if ( ds == null ) {
   throw new Exception("Data source not found!");
}]]></source>
</source>

</subsection>
</section>

You should next create a simple test servlet or jsp that has these
<strong>critical lines</strong>:
</p>
<source><![CDATA[DriverManager.registerDriver(new
DriverManager.registerDriver(new
oracle.jdbc.driver.OracleDriver());
conn =
DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password");]]></source>
</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

</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

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>

Here is an example of properly written code to use a database connection
obtained from a connection pool:
</p>
<source><![CDATA[  Connection conn = null;
  Connection conn = null;
  Statement stmt = null;  // Or PreparedStatement if needed
  ResultSet rs = null;
  try {

      try { conn.close(); } catch (SQLException e) { ; }
      conn = null;
    }
  }]]></source>
</pre>

</subsection>





element:</p>

<ul>
<li><a href="config/context.html#Environment_Entries">&lt;Environment&gt;</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>&lt;env-entry&gt;</code> element in the web application
    deployment descriptor).</li>
<li><a href="config/context.html#Resource_Definitions">&lt;Resource&gt;</a> -
    Configure the name and data type of a resource made available to the
    application (equivalent to the inclusion of a
    <code>&lt;resource-ref&gt;</code> element in the web application
    deployment descriptor).</li>
<li><a href="config/context.html#Resource_Links">&lt;ResourceLink&gt;</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">&lt;GlobalNamingResources&gt;</a>

<code><strong>&lt;GlobalNamingResources&gt;</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">&lt;ResourceLink&gt;</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">&lt;ResourceLink&gt;</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>

access to a resource - in this case, to a JDBC <code>DataSource</code> -
would look something like this:</p>

<source><![CDATA[// Obtain our environment naming context
// Obtain our environment naming context
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");


// Allocate and use a connection from the pool
Connection conn = ds.getConnection();
... use this connection to access the database ...
conn.close();]]></source>
</source>

</section>


  subsection below details the configuration and usage of the standard resource
  factories.</p>

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


  <subsection name="Generic JavaBean Resources">

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


    <p>The steps required to use this facility are described below.</p>

    <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

    you create a class <code>com.mycompany.MyBean</code>, which looks
    like this:</p>

<source><![CDATA[package com.mycompany;
package com.mycompany;

public class MyBean {


  }


}]]></source>
</source>

  <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

  you will request new instances of this bean.  The simplest approach is
  to use a <code>&lt;resource-env-ref&gt;</code> element, like this:</p>

<source><![CDATA[<resource-env-ref>
  <description>
  &lt;description&gt;
    Object factory for MyBean instances.
  </description>
  <resource-env-ref-name>
    bean/MyBeanFactory
  </resource-env-ref-name>
  <resource-env-ref-type>
    com.mycompany.MyBean
  </resource-env-ref-type>
</resource-env-ref>]]></source>
</source>

    <p><strong>WARNING</strong> - Be sure you respect the element ordering
    that is required by the DTD for web application deployment descriptors!

    <a href="http://wiki.apache.org/tomcat/Specifications">Servlet
    Specification</a> for details.</p>

  <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><![CDATA[Context initCtx = new InitialContext();
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>
</source>

    <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>&lt;Context&gt;</code></a> element for
    this web application.</p>

<source><![CDATA[<Context ...>
&lt;Context ...&gt;
  ...
  <Resource name="bean/MyBeanFactory" auth="Container"
            type="com.mycompany.MyBean"
            factory="org.apache.naming.factory.BeanFactory"
            bar="23"/>
  ...
</Context>]]></source>
</source>

    <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
    must match the value specified in the web application deployment


  <subsection name="UserDatabase Resources">

    <h5>0.  Introduction</h5>

    <p>UserDatabase resources are typically configured as global resources for
    use by a UserDatabase realm. Tomcat includes a UserDatabaseFactoory that

    <p>The steps required to set up a global UserDatabase resource are described
    below.</p>

    <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

    files are placed in <code>$CATALINA_BASE/conf</code>. A typical XML would
    look like:</p>

<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>
&lt;/tomcat-users&gt;
</source>

    <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><![CDATA[<Resource name="UserDatabase"
&lt;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>
</source>

    <p>The <code>pathname</code> attribute can be absolute or relative. If
    relative, it is relative to <code>$CATALINA_BASE</code>.</p>

    is running as. Ensure that these are appropriate to maintain the security
    of your installation.</p>

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


  <subsection name="JavaMail Sessions">

    <h5>0.  Introduction</h5>

    <p>In many web applications, sending electronic mail messages is a
    required part of the system's functionality.  The


    <p>The steps required for this are outlined below.</p>

    <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

    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><![CDATA[<resource-ref>
  <description>
  &lt;description&gt;
    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>
    mail/Session
  </res-ref-name>
  <res-type>
    javax.mail.Session
  </res-type>
  <res-auth>
    Container
  </res-auth>
</resource-ref>]]></source>
</source>

    <p><strong>WARNING</strong> - Be sure you respect the element ordering
    that is required by the DTD for web application deployment descriptors!

    <a href="http://wiki.apache.org/tomcat/Specifications">Servlet
    Specification</a> for details.</p>

    <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><![CDATA[Context initCtx = new InitialContext();
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
Session session = (Session) envCtx.lookup("mail/Session");


message.setRecipients(Message.RecipientType.TO, to);
message.setSubject(request.getParameter("subject"));
message.setContent(request.getParameter("content"), "text/plain");
Transport.send(message);]]></source>
</source>

    <p>Note that the application uses the same resource reference name
    that was declared in the web application deployment descriptor.  This

    <a href="config/context.html"><code>&lt;Context&gt;</code></a> element
    for the web application as described below.</p>

    <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>&lt;Context&gt;</code></a> element for
    this web application.</p>

<source><![CDATA[<Context ...>
&lt;Context ...&gt;
  ...
  <Resource name="mail/Session" auth="Container"
            type="javax.mail.Session"
            mail.smtp.host="localhost"/>
  ...
</Context>]]></source>
</source>

    <p>Note that the resource name (here, <code>mail/Session</code>) must
    match the value specified in the web application deployment descriptor.

    then Tomcat&apos;s resource factory will configure and add a
    <code>javax.mail.Authenticator</code> to the mail session.</p>

    <h5>4.  Install the JavaMail libraries</h5>

    <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

    it in the $CATALINA_HOME/lib location only.
    </p>

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


    <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


  <subsection name="JDBC Data Sources">

    <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

    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>

    <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

    <code>$CATALINA_HOME/lib</code> directory, which makes the driver
    available both to the resource factory and to your application.</p>

    <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

    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><![CDATA[<resource-ref>
  <description>
  &lt;description&gt;
    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>
    configurartion for the web application.
  </description>
  <res-ref-name>
    jdbc/EmployeeDB
  </res-ref-name>
  <res-type>
    javax.sql.DataSource
  </res-type>
  <res-auth>
    Container
  </res-auth>
</resource-ref>]]></source>
</source>

    <p><strong>WARNING</strong> - Be sure you respect the element ordering
    that is required by the DTD for web application deployment descriptors!

    <a href="http://wiki.apache.org/tomcat/Specifications">Servlet
    Specification</a> for details.</p>

    <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><![CDATA[Context initCtx = new InitialContext();
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
DataSource ds = (DataSource)
  envCtx.lookup("jdbc/EmployeeDB");


Connection conn = ds.getConnection();
... use this connection to access the database ...
conn.close();]]></source>
</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

    <a href="config/context.html"><code>&lt;Context&gt;</code></a> element for
    the web application as described below.</p>

    <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>&lt;Context&gt;</code></a> element for
    the web application.</p>

<source><![CDATA[<Context ...>
&lt;Context ...&gt;
  ...
  <Resource name="jdbc/EmployeeDB"
            auth="Container"
            type="javax.sql.DataSource"
            username="dbusername"

            driverClassName="org.hsql.jdbcDriver"
            url="jdbc:HypersonicSQL:database"
            maxActive="8"
            maxIdle="4"/>
  ...
</Context>]]></source>
</source>

    <p>Note that the resource name (here, <code>jdbc/EmployeeDB</code>) must
    match the value specified in the web application deployment descriptor.</p>

  <a href="config/context.html"><code>&lt;Context&gt;</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
  above.</p>

  <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

  <p>To create a resource factory that knows how to produce <code>MyBean</code>
  instances, you might create a class like this:</p>

<source><![CDATA[package com.mycompany;
package com.mycompany;

import java.util.Enumeration;
import java.util.Hashtable;


  }

}]]></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

  files are visible to both Catalina internal resources and your web
  application.</p>

  <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

  you will request new instances of this bean.  The simplest approach is
  to use a <code>&lt;resource-env-ref&gt;</code> element, like this:</p>

<source><![CDATA[<resource-env-ref>
  <description>
  &lt;description&gt;
    Object factory for MyBean instances.
  </description>
  <resource-env-ref-name>
    bean/MyBeanFactory
  </resource-env-ref-name>
  <resource-env-ref-type>
    com.mycompany.MyBean
  </resource-env-ref-type>
<resource-env-ref>]]></source>
</source>

    <p><strong>WARNING</strong> - Be sure you respect the element ordering
    that is required by the DTD for web application deployment descriptors!

    <a href="http://wiki.apache.org/tomcat/Specifications">Servlet
    Specification</a> for details.</p>

  <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><![CDATA[Context initCtx = new InitialContext();
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>
</source>

    <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>&lt;Context&gt;</code></a> element for
    this web application.</p>

<source><![CDATA[<Context ...>
&lt;Context ...&gt;
  ...
  <Resource name="bean/MyBeanFactory" auth="Container"
            type="com.mycompany.MyBean"
            factory="com.mycompany.MyBeanFactory"
            bar="23"/>
  ...
</Context>]]></source>
</source>

    <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
    must match the value specified in the web application deployment




    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.

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

    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

  </p>
  <p>
    Example logging.properties file to be placed in $CATALINA_BASE/conf:
  </p>
  <source><![CDATA[handlers = 1catalina.org.apache.juli.FileHandler, \
           2localhost.org.apache.juli.FileHandler, \
           3manager.org.apache.juli.FileHandler, \
           java.util.logging.ConsoleHandler


# 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>
</source>
    </p>

    <p>
      Example logging.properties for the servlet-examples web application to be
      placed in WEB-INF/classes inside the web application:
    </p>
    <source><![CDATA[handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler

############################################################
# Handler specific properties.

org.apache.juli.FileHandler.prefix = servlet-examples.

java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter]]></source>
</source>
    </p>


    <subsection name="Documentation references">
      <p>See the following resources for additional information:</p>
      <ul>

        <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><![CDATA[
log4j.rootLogger = INFO, CATALINA

# Define all the appenders

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>
</source>
    <ol start="2">
        <li><a href="http://logging.apache.org/log4j">Download Log4J</a>
        (v1.2 or later).</li>

      configuration files, so we recommend you use a properties file as
      described until a future version of log4j allows this convention.
    </p>
      <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>
log4j.logger.org.apache.catalina.session=DEBUG<br />
</source>

    <p>
      Be warned: a level of DEBUG will produce megabytes of logging and slow




<code>manager.xml</code> context configuration file in the
<code>$CATALINA_BASE/conf/[enginename]/[hostname]</code> folder. Here is an
example:</p>
<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>
&lt;/Context&gt;
</pre>

<p>If you have Tomcat configured to support multiple virtual hosts
(websites) you would need to configure a Manager for each.</p>

<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">
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
With Ant</a> for more information.</li>
</ul>



<section name="Configuring Manager Application Access">

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

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

    edited with any text editor.  This file contains an XML
    <code>&lt;user&gt;</code> for each individual user, which might
    look something like this:
<source><![CDATA[<user name="craigmcc" password="secret" roles="standard,manager-script" />]]></source>
&lt;user name="craigmcc" password="secret" roles="standard,manager-script" /&gt;
</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

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>
<source><![CDATA[<Context privileged="true">
         <Valve className="org.apache.catalina.valves.RemoteAddrValve"
                allow="127\.0\.0\.1"/>
</Context>]]></source>
&lt;/Context&gt;
</pre>

</section>



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


<subsection name="Deploy A New Application Remotely">

<source>http://localhost:8080/manager/text/deploy?path=/foo</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>


<p>If installation and startup is successful, you will receive a response
like this:</p>
<source>OK - Deployed application at context path /foo</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

    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>
    </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>
    </li>
</ul>

</subsection>


<p>There are a number of different ways the deploy command can be used.</p>

<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&amp;tag=footag</source>
http://localhost:8080/manager/text/deploy?path=/footoo&amp;tag=footag
</source>


<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

<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&amp;war=file:/path/to/foo</source>
http://localhost:8080/manager/text/deploy?path=/footoo&amp;war=file:/path/to/foo
</source>


<p>In this example the ".war" file <code>/path/to/bar.war</code> on the

<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>
http://localhost:8080/manager/text/deploy?war=jar:file:/path/to/bar.war!/
</source>


<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"

<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>
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>
http://localhost:8080/manager/text/deploy?war=bar.war
</source>


<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

web application Context just as if it were configured in your
Tomcat <code>server.xml</code> configuration file. Here is an
example:</p>
<source><![CDATA[<Context path="/foobar" docBase="/path/to/application/foobar">
</Context>]]></source>
&lt;/Context&gt;
</source>


<p>When the optional <code>war</code> parameter is set to the URL


<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>
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&amp;war=jar:file:/path/bar.war!/</source>
 ?config=file:/path/context.xml&amp;war=jar:file:/path/bar.war!/
</source>


<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

files located outside of their Host appBase.</p>


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

    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>
    </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>
    </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>
    </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>
    </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>
    </li>
<li><em>Context path must match the directory or WAR file name:</em>
    <p>If the application war or directory is installed in your Host appBase
    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.</p>
    </li>
<li><em>Only web applications in the Host web application directory can
     be installed</em>
     <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.
     </p></li>
</ul>

</subsection>


<subsection name="List Currently Deployed Applications">

<source>http://localhost:8080/manager/text/list</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
OK - Listed applications for virtual host localhost
/webdav:running:0
/examples:running:0
/manager:running:0
/:running:0</source>
</source>

</subsection>

<subsection name="Reload An Existing Application">

<source>http://localhost:8080/manager/text/reload?path=/examples</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

</p>

<p>If this command succeeds, you will see a response like this:</p>
<source>OK - Reloaded application at context path /examples</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>
    </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>
    </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>
    </li>
<li><em>No context path was specified</em>
    <p>
    The <code>path</code> parameter is required.
    </p></li>
<li><em>Reload not supported on WAR deployed at path /foo</em>
    <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

    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.
    </p></li>
</ul>

</subsection>


<subsection name="List OS and JVM Properties">

<source>http://localhost:8080/manager/text/serverinfo</source>
http://localhost:8080/manager/text/serverinfo
</source>

<p>Lists information about the Tomcat version, OS, and JVM properties.</p>


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>
    </li>
</ul>

</subsection>


<subsection name="List Available Global JNDI Resources">

<source>http://localhost:8080/manager/text/resources[?type=xxxxx]</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>


<p>Depending on whether the <code>type</code> request parameter is specified
or not, the first line of a normal response will be:</p>
<source>OK - Listed global resources of all types</source>
  OK - Listed global resources of all types
</pre>
<p>or</p>
<source>OK - Listed global resources of type xxxxx</source>
  OK - Listed global resources of type xxxxx
</pre>
<p>followed by one line for each resource.  Each line is composed of fields
delimited by colon characters (":"), as follows:</p>
<ul>

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>
    </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>
    </li>
</ul>




<subsection name="Session Statistics">

<source>http://localhost:8080/manager/text/sessions?path=/examples</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

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
OK - Session information for application at context path /examples
Default maximum session inactive interval 30 minutes
30 - &lt;40 minutes:1 sessions</source>
</source>

</subsection>



<subsection name="Start an Existing Application">

<source>http://localhost:8080/manager/text/start?path=/examples</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

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>
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>
    </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>
    </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>
    </li>
<li><em>No context path was specified</em>
    <p>
    The <code>path</code> parameter is required.
    </p></li>
</ul>

</subsection>


<subsection name="Stop an Existing Application">

<source>http://localhost:8080/manager/text/stop?path=/examples</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

"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>
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>
    </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>
    </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>
    </li>
<li><em>No context path was specified</em>
    <blockquote>
    The <code>path</code> parameter is required.
    </li>
</ul>

</subsection>


<subsection name="Undeploy an Existing Application">

<source>http://localhost:8080/manager/text/undeploy?path=/examples</source>
http://localhost:8080/manager/text/undeploy?path=/examples
</source>

<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,

<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>
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>
    </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>
    </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>
    </li>
<li><em>No context path was specified</em>
    <blockquote>
    The <code>path</code> parameter is required.
    </li>
</ul>

</subsection>


<subsection name="Finding memory leaks">

<source>http://localhost:8080/manager/text/findleaks[?statusLine=[true|false]]</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>

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>
/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


<subsection name="Connector SSL diagnostics">

<source>http://localhost:8080/manager/text/sslConnectorCiphers</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

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
OK - Connector / SSL Cipher information
Connector[HTTP/1.1-8080]
  SSL is not enabled for this connector
Connector[HTTP/1.1-8443]

  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>


<code>&lt;taskdef&gt;</code> element.  Therefore, your <code>build.xml</code>
file might look something like this:</p>

<source><![CDATA[<project name="My Application" default="compile" basedir=".">
<tr><td><pre>
&lt;project name="My Application" default="compile" basedir="."&gt;

  <!-- 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 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"/>

  <!-- 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="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>

</project>]]></source>
</pre></td></tr>
</table>

<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

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>
<source>ant -Dpassword=secret deploy</source>
  ant -Dpassword=secret deploy
</pre>

<subsection name="Tasks output capture">


<code>&lt;redirector&gt;</code> type attributes:
</p>

<table class="defaultTable">
<tbody>
<tr>
<th>Attribute</th>
<th>Description</th>
<th style="text-align: center;">Required</th>
</tr>
<tr>
<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 style="text-align: center;">No</td>
</tr>
<tr>
<td>error</td>
<td>The file to which the standard error of the
command should be redirected.</td>
<td style="text-align: center;">No</td>
</tr>
<tr>
<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 style="text-align: center;">No</td>
</tr>
<tr>
<td>append</td>
<td>Whether output and error files should be
appended to or overwritten. Defaults to <code>false</code>.</td>
<td style="text-align: center;">No</td>
</tr>
<tr>
<td>createemptyfiles</td>
<td>Whether output and error files should be created
even when empty. Defaults to <code>true</code>.</td>
<td style="text-align: center;">No</td>
</tr>
<tr>
<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 style="text-align: center;">No</td>
</tr>
<tr>
<td>errorproperty</td>
<td>The name of a property in which the standard
error of the command should be stored.</td>
<td style="text-align: center;">No</td>
</tr>
</tbody>
</table>

<p>A couple of additional attributes can also be specified:
</p>
<table class="defaultTable">
<tbody>
<tr>
<th>Attribute</th>
<th>Description</th>
<th style="text-align: center;">Required</th>
</tr>
<tr>
<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>&lt;redirector&gt;</code>
in Ant 1.6.3</em></td>
<td style="text-align: center;">No</td>
</tr>
<tr>
<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/>
This attribute acts only on manager command execution,
any wrong or missing command attribute will still cause Ant execution termination.
</td>
<td style="text-align: center;">No</td>
</tr>
</tbody>
</table>

<p>They also support the embedded <code>&lt;redirector&gt;</code> element

can be used:
</p>

<source><![CDATA[    <target name="manager.deploy"
<tr><td><pre>
    &lt;target name="manager.deploy"
        depends="context.status"
        if="context.notInstalled">
        <deploy url="${mgr.url}"
            username="${mgr.username}"
            password="${mgr.password}"
            path="${mgr.context.path}"
            config="${mgr.context.descriptor}"/>
    </target>

    <target name="manager.deploy.war"
        depends="context.status"
        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>

    <target name="context.status">
        <property name="running" value="${mgr.context.path}:running"/>
        <property name="stopped" value="${mgr.context.path}:stopped"/>

        <list url="${mgr.url}"
            outputproperty="ctx.status"
            username="${mgr.username}"
            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>]]></source>
</pre></td></tr>
</table>

<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,

  </subsection>

  <subsection name="JMX Query command">
    <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>
    Where <code>STUFF</code> is the JMX query you wish to perform. For example,
    here are some queries you might wish to run:
    <ul>
      <li>
        <code>qry=*%3Atype%3DRequestProcessor%2C* -->

            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&amp;att=MYATTRIBUTE&amp;key=MYKEY</source>
http://webserver/manager/jmxproxy/?get=BEANNAME&amp;att=MYATTRIBUTE&amp;key=MYKEY
</source>

    <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&amp;att=HeapMemoryUsage</source>
http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&amp;att=HeapMemoryUsage
</source>

    <p>Or, if you only want the "used" key:</p>

<source>http://webserver/manager/jmxproxy/
 ?get=java.lang:type=Memory&amp;att=HeapMemoryUsage&amp;key=used</source>
 ?get=java.lang:type=Memory&amp;att=HeapMemoryUsage&amp;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 :
    </p>
<source>http://webserver/manager/jmxproxy/?set=BEANNAME&amp;att=MYATTRIBUTE&amp;val=NEWVALUE</source>
    <p>So you need to provide 3 request parameters:</p>
    So you need to provide 3 request parameters:
    <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.
    </p>
<source>http://localhost:8080/manager/jmxproxy/
 ?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost
 &amp;att=debug&amp;val=10</source>
    <p>and my result is (YMMV):</p>
<source>Result: ok</source>
<source>
Result: ok
</source>

    <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/
http://localhost:8080/manager/jmxproxy/
 ?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost
 &amp;att=debug&amp;val=cow</source>
    <p>When I try that, my result is</p>
<source>Error: java.lang.NumberFormatException: For input string: "cow"</source>
<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&amp;op=METHODNAME&amp;ps=COMMASEPARATEDPARAMETERS</source>
 ?invoke=BEANNAME&amp;op=METHODNAME&amp;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&amp;op=findConnectors&amp;ps=</source>
 ?invoke=Catalina%3Atype%3DService&amp;op=findConnectors&amp;ps=
</source>
  </subsection>
</section>


Return to bug 55383

Lines 161-172 Link Here

(-)webapps/docs/aio.xml (-19 / +19 lines)
161	described above:	161	described above:
162	</p>	162	</p>
163		163
164	<source>	164	<source><![CDATA[public class ChatServlet
165	public class ChatServlet
166	extends HttpServlet implements CometProcessor {	165	extends HttpServlet implements CometProcessor {
167		166
168	protected ArrayList<HttpServletResponse> connections =	167	protected ArrayList<HttpServletResponse> connections =
169	new ArrayList<HttpServletResponse>();	168	new ArrayList<HttpServletResponse>();
170	protected MessageSender messageSender = null;	169	protected MessageSender messageSender = null;
171		170
172	public void init() throws ServletException {	171	public void init() throws ServletException {
Lines 197-204 Link Here
197	if (event.getEventType() == CometEvent.EventType.BEGIN) {	196	if (event.getEventType() == CometEvent.EventType.BEGIN) {
198	log("Begin for session: " + request.getSession(true).getId());	197	log("Begin for session: " + request.getSession(true).getId());
199	PrintWriter writer = response.getWriter();	198	PrintWriter writer = response.getWriter();
200	writer.println("<!doctype html public \"-//w3c//dtd html 4.0 transitional//en\">");	199	writer.println("<!DOCTYPE html>");
201	writer.println("<head><title>JSP Chat</title></head><body bgcolor=\"#FFFFFF\">");	200	writer.println("<head><title>JSP Chat</title></head><body>");
202	writer.flush();	201	writer.flush();
203	synchronized(connections) {	202	synchronized(connections) {
204	connections.add(response);	203	connections.add(response);
Lines 215-221 Link Here
215	connections.remove(response);	214	connections.remove(response);
216	}	215	}
217	PrintWriter writer = response.getWriter();	216	PrintWriter writer = response.getWriter();
218	writer.println("</body></html>");	217	writer.println("</body></html>");
219	event.close();	218	event.close();
220	} else if (event.getEventType() == CometEvent.EventType.READ) {	219	} else if (event.getEventType() == CometEvent.EventType.READ) {
221	InputStream is = request.getInputStream();	220	InputStream is = request.getInputStream();
Lines 222-231 Link Here
222	byte[] buf = new byte[512];	221	byte[] buf = new byte[512];
223	do {	222	do {
224	int n = is.read(buf); //can throw an IOException	223	int n = is.read(buf); //can throw an IOException
225	if (n > 0) {	224	if (n > 0) {
226	log("Read " + n + " bytes: " + new String(buf, 0, n)	225	log("Read " + n + " bytes: " + new String(buf, 0, n)
227	+ " for session: " + request.getSession(true).getId());	226	+ " for session: " + request.getSession(true).getId());
228	} else if (n < 0) {	227	} else if (n < 0) {
229	error(event, request, response);	228	error(event, request, response);
230	return;	229	return;
231	}	230	}
Lines 236-242 Link Here
236	public class MessageSender implements Runnable {	235	public class MessageSender implements Runnable {
237		236
238	protected boolean running = true;	237	protected boolean running = true;
239	protected ArrayList<String> messages = new ArrayList<String>();	238	protected ArrayList<String> messages = new ArrayList<String>();
240		239
241	public MessageSender() {	240	public MessageSender() {
242	}	241	}
Lines 276-286 Link Here
276	messages.clear();	275	messages.clear();
277	}	276	}
278	// Send any pending message on all the open connections	277	// Send any pending message on all the open connections
279	for (int i = 0; i < connections.size(); i++) {	278	for (int i = 0; i < connections.size(); i++) {
280	try {	279	try {
281	PrintWriter writer = connections.get(i).getWriter();	280	PrintWriter writer = connections.get(i).getWriter();
282	for (int j = 0; j < pendingMessages.length; j++) {	281	for (int j = 0; j < pendingMessages.length; j++) {
283	writer.println(pendingMessages[j] + "<br>");	282	writer.println(pendingMessages[j] + "<br>");
284	}	283	}
285	writer.flush();	284	writer.flush();
286	} catch (IOException e) {	285	} catch (IOException e) {
Lines 295-310 Link Here
295		294
296	}	295	}
297		296
298	}	297	}]]></source>
299	</source>
300		298
301	</subsection>	299	</subsection>
302	<subsection name="Comet timeouts">	300	<subsection name="Comet timeouts">
303	<p>If you are using the NIO connector, you can set individual timeouts for your different comet connections.	301	<p>If you are using the NIO connector, you can set individual timeouts for your different comet connections.
304	To set a timeout, simply set a request attribute like the following code shows:	302	To set a timeout, simply set a request attribute like the following code shows:</p>
305	<source>CometEvent event.... event.setTimeout(30*1000);</source> or	303	<source>CometEvent event.... event.setTimeout(30*1000);</source>
306	<source>event.getHttpServletRequest().setAttribute("org.apache.tomcat.comet.timeout", new Integer(30 * 1000));</source>	304	<p>or</p>
307	This sets the timeout to 30 seconds.	305	<source>event.getHttpServletRequest().setAttribute("org.apache.tomcat.comet.timeout", new Integer(30 * 1000));</source>
		306	<p>
		307	This sets the timeout to 30 seconds.
308	Important note: in order to set this timeout, it has to be done on the <code>BEGIN</code> event.	308	Important note: in order to set this timeout, it has to be done on the <code>BEGIN</code> event.
309	The default value is <code>soTimeout</code>	309	The default value is <code>soTimeout</code>
310	</p>	310	</p>

Lines 57-68 Link Here

(-)webapps/docs/apr.xml (-28 / +28 lines)
57		57
58	<p>	58	<p>
59	APR support requires three main native components to be installed:	59	APR support requires three main native components to be installed:
60	<ul>
61	<li>APR library</li>
62	<li>JNI wrappers for APR used by Tomcat (libtcnative)</li>
63	<li>OpenSSL libraries</li>
64	</ul>
65	</p>	60	</p>
		61	<ul>
		62	<li>APR library</li>
		63	<li>JNI wrappers for APR used by Tomcat (libtcnative)</li>
		64	<li>OpenSSL libraries</li>
		65	</ul>
66		66
67	<subsection name="Windows">	67	<subsection name="Windows">
68		68
Lines 87-99 Link Here
87		87
88	<p>	88	<p>
89	Requirements:	89	Requirements:
90	<ul>
91	<li>APR 1.2+ development headers (libapr1-dev package)</li>
92	<li>OpenSSL 0.9.7+ development headers (libssl-dev package)</li>
93	<li>JNI headers from Java compatible JDK 1.4+</li>
94	<li>GNU development environment (gcc, make)</li>
95	</ul>
96	</p>	90	</p>
		91	<ul>
		92	<li>APR 1.2+ development headers (libapr1-dev package)</li>
		93	<li>OpenSSL 0.9.7+ development headers (libssl-dev package)</li>
		94	<li>JNI headers from Java compatible JDK 1.4+</li>
		95	<li>GNU development environment (gcc, make)</li>
		96	</ul>
97		97
98	<p>	98	<p>
99	The wrapper library sources are located in the Tomcat binary bundle, in the	99	The wrapper library sources are located in the Tomcat binary bundle, in the
Lines 100-107 Link Here
100	<code>bin/tomcat-native.tar.gz</code> archive.	100	<code>bin/tomcat-native.tar.gz</code> archive.
101	Once the build environment is installed and the source archive is extracted, the wrapper library	101	Once the build environment is installed and the source archive is extracted, the wrapper library
102	can be compiled using (from the folder containing the configure script):	102	can be compiled using (from the folder containing the configure script):
103	<source>./configure && make && make install</source>
104	</p>	103	</p>
		104	<source>./configure && make && make install</source>
105		105
106	</subsection>	106	</subsection>
107		107
Lines 119-136 Link Here
119		119
120	<p>	120	<p>
121	When APR is enabled, the following features are also enabled in Tomcat:	121	When APR is enabled, the following features are also enabled in Tomcat:
122	<ul>
123	<li>Secure session ID generation by default on all platforms (platforms other than Linux required
124	random number generation using a configured entropy)</li>
125	<li>OS level statistics on memory usage and CPU usage by the Tomcat process are displayed by
126	the status servlet</li>
127	</ul>
128	</p>	122	</p>
		123	<ul>
		124	<li>Secure session ID generation by default on all platforms (platforms other than Linux required
		125	random number generation using a configured entropy)</li>
		126	<li>OS level statistics on memory usage and CPU usage by the Tomcat process are displayed by
		127	the status servlet</li>
		128	</ul>
129		129
130	</section>	130	</section>
131		131
132	<section name="APR Lifecycle Listener Configuration">	132	<section name="APR Lifecycle Listener Configuration">
133	<subsection name="AprLifecycleListener">	133	<subsection name="AprLifecycleListener">
		134	<attributes>
134	<attribute name="SSLEngine" required="false">	135	<attribute name="SSLEngine" required="false">
135	<p>	136	<p>
136	Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no specific ENGINE.	137	Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no specific ENGINE.
Lines 137-150 Link Here
137	The default value is <b>on</b>.	138	The default value is <b>on</b>.
138	This initializes the native SSL engine, then enable the use of this engine in the connector	139	This initializes the native SSL engine, then enable the use of this engine in the connector
139	using the <code>SSLEnabled</code> attribute. Example:	140	using the <code>SSLEnabled</code> attribute. Example:
140	<source>	141	</p>
141	<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />	142	<source><![CDATA[<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />]]></source>
142	</source>	143
143	</p>
144	<p>See the <a href="http://www.openssl.org">Official OpenSSL	144	<p>See the <a href="http://www.openssl.org">Official OpenSSL
145	website</a> for more details on SSL hardware engines and manufacturers.	145	website</a> for more details on SSL hardware engines and manufacturers.
146	</p>	146	</p>
147	</attribute>	147	</attribute>
		148	</attributes>
148	</subsection>	149	</subsection>
149	</section>	150	</section>
150		151
Lines 156-174 Link Here
156	connector configuration documentation.</p>	157	connector configuration documentation.</p>
157		158
158	<p>For HTTPS configuration, see the	159	<p>For HTTPS configuration, see the
159	<a href="config/http.html#SSL%20Support">HTTPS</a> connector configuration	160	<a href="config/http.html#SSL_Support">HTTPS</a> connector configuration
160	documentation.</p>	161	documentation.</p>
161		162
162	<p>An example SSL Connector declaration is:	163	<p>An example SSL Connector declaration is:</p>
163	<source>	164	<source><![CDATA[<Connector port="443" maxHttpHeaderSize="8192"
164	<Connector port="443" maxHttpHeaderSize="8192"
165	maxThreads="150"	165	maxThreads="150"
166	enableLookups="false" disableUploadTimeout="true"	166	enableLookups="false" disableUploadTimeout="true"
167	acceptCount="100" scheme="https" secure="true"	167	acceptCount="100" scheme="https" secure="true"
168	SSLEnabled="true"	168	SSLEnabled="true"
169	SSLCertificateFile="${catalina.base}/conf/localhost.crt"	169	SSLCertificateFile="${catalina.base}/conf/localhost.crt"
170	SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" /></source>	170	SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" />]]></source>
171	</p>	171
172		172
173	</subsection>	173	</subsection>
174		174

Lines 107-116 Link Here

(-)webapps/docs/building.xml (-22 / +20 lines)
107		107
108	<p>	108	<p>
109	Use the following commands to build Tomcat:	109	Use the following commands to build Tomcat:
110	<br/>	110	<br/><br/>
111	<code><br/>	111	<code>
112	cd ${tomcat.source}<br/>	112	cd ${tomcat.source}<br/>
113	ant<br/>	113	ant
114	</code>	114	</code>
115	</p>	115	</p>
116		116
Lines 133-153 Link Here
133	<p>	133	<p>
134	The build can be controlled by creating a <code>${tomcat.source}/build.properties</code>	134	The build can be controlled by creating a <code>${tomcat.source}/build.properties</code>
135	file and adding the following content to it:	135	file and adding the following content to it:
136	<br/>
137	<code><br/>
138	# ----- Proxy setup -----<br/>
139	# Uncomment if using a proxy server.<br/>
140	#proxy.host=proxy.domain<br/>
141	#proxy.port=8080<br/>
142	#proxy.use=on<br/>
143	<br/>
144	# ----- Default Base Path for Dependent Packages -----<br/>
145	# Replace this path with the directory path where<br/>
146	# dependencies binaries should be downloaded.<br/>
147	base.path=/home/me/some-place-to-download-to<br/>
148	</code>
149	</p>	136	</p>
		137	<source># ----- Proxy setup -----
		138	# Uncomment if using a proxy server.
		139	#proxy.host=proxy.domain
		140	#proxy.port=8080
		141	#proxy.use=on
150		142
		143	# ----- Default Base Path for Dependent Packages -----
		144	# Replace this path with the directory path where
		145	# dependencies binaries should be downloaded.
		146	base.path=/home/me/some-place-to-download-to</source>
		147
		148
151	<p>	149	<p>
152	Once the build has completed successfully, a usable Tomcat installation will have been	150	Once the build has completed successfully, a usable Tomcat installation will have been
153	produced in the <code>${tomcat.source}/output/build</code> directory, and can be started	151	produced in the <code>${tomcat.source}/output/build</code> directory, and can be started
Lines 204-217 Link Here
204	Variables</em> to add two new <em>Classpath Variables</em>:	202	Variables</em> to add two new <em>Classpath Variables</em>:
205	</p>	203	</p>
206		204
207	<p>	205
208	<table border="1">	206	<table class="defaultTable">
209	<tr><td>TOMCAT_LIBS_BASE</td><td>The same location as the <code>base.path</code>	207	<tr><td>TOMCAT_LIBS_BASE</td><td>The same location as the <code>base.path</code>
210	setting in <code>build.properties</code>, where the binary dependencies have been downloaded</td></tr>	208	setting in <code>build.properties</code>, where the binary dependencies have been downloaded</td></tr>
211	<tr><td>ANT_HOME</td><td>the base path of Ant 1.8.1 or later</td></tr>	209	<tr><td>ANT_HOME</td><td>the base path of Ant 1.8.1 or later</td></tr>
212	</table>	210	</table>
213	</p>
214		211
		212
215	<p>	213	<p>
216	Use <em>File->Import</em> and choose <em>Existing Projects into Workspace</em>.	214	Use <em>File->Import</em> and choose <em>Existing Projects into Workspace</em>.
217	From there choose the root directory of the Tomcat source tree (<code>${tomcat.source}</code>)	215	From there choose the root directory of the Tomcat source tree (<code>${tomcat.source}</code>)
Lines 232-239 Link Here
232	Tweaking a few formatting preferences will make it much easier to keep consistent with Tomcat	230	Tweaking a few formatting preferences will make it much easier to keep consistent with Tomcat
233	coding conventions (and have your contributions accepted):	231	coding conventions (and have your contributions accepted):
234	</p>	232	</p>
235	<p>	233
236	<table border="1">	234	<table class="defaultTable">
237	<tr><td>Java -> Code Style -> Formatter -> Edit...</td>	235	<tr><td>Java -> Code Style -> Formatter -> Edit...</td>
238	<td>Tab policy: Spaces only<br/>Tab and Indentation size: 4</td></tr>	236	<td>Tab policy: Spaces only<br/>Tab and Indentation size: 4</td></tr>
239	<tr><td>General -> Editors -> Text Editors</td>	237	<tr><td>General -> Editors -> Text Editors</td>
Lines 241-248 Link Here
241	<tr><td>XML -> XML Files -> Editor</td><td>Indent using spaces<br/>Indentation size: 2</td></tr>	239	<tr><td>XML -> XML Files -> Editor</td><td>Indent using spaces<br/>Indentation size: 2</td></tr>
242	<tr><td>Ant -> Editor -> Formatter</td><td>Tab size: 2<br/>Use tab character instead of spaces: unchecked</td></tr>	240	<tr><td>Ant -> Editor -> Formatter</td><td>Tab size: 2<br/>Use tab character instead of spaces: unchecked</td></tr>
243	</table>	241	</table>
244	</p>
245		242
		243
246	</section>	244	</section>
247		245
248	<section name="Building with other IDEs">	246	<section name="Building with other IDEs">

Lines 222-227 Link Here

(-)webapps/docs/logging.xml (-22 / +14 lines)
222	JULI is enabled by default, and supports per classloader configuration, in	222	JULI is enabled by default, and supports per classloader configuration, in
223	addition to the regular global java.util.logging configuration. This means	223	addition to the regular global java.util.logging configuration. This means
224	that logging can be configured at the following layers:	224	that logging can be configured at the following layers:
		225	</p>
225	<ul>	226	<ul>
226	<li>Globally. That is usually done in the	227	<li>Globally. That is usually done in the
227	<code>${catalina.base}/conf/logging.properties</code> file.	228	<code>${catalina.base}/conf/logging.properties</code> file.
Lines 234-240 Link Here
234	<code>WEB-INF/classes/logging.properties</code>	235	<code>WEB-INF/classes/logging.properties</code>
235	</li>	236	</li>
236	</ul>	237	</ul>
237	</p>
238	<p>	238	<p>
239	The default <code>logging.properties</code> in the JRE specifies a	239	The default <code>logging.properties</code> in the JRE specifies a
240	<code>ConsoleHandler</code> that routes logging to System.err.	240	<code>ConsoleHandler</code> that routes logging to System.err.
Lines 253-262 Link Here
253	so FINEST or ALL should be set. Please refer to <code>java.util.logging</code>	253	so FINEST or ALL should be set. Please refer to <code>java.util.logging</code>
254	documentation in the JDK for the complete details:	254	documentation in the JDK for the complete details:
255	</p>	255	</p>
		256	<source>org.apache.catalina.level=FINEST</source>
256	<p>	257	<p>
257	<source>org.apache.catalina.level=FINEST</source>
258	</p>
259	<p>
260	The configuration used by JULI is extremely similar to the one supported by	258	The configuration used by JULI is extremely similar to the one supported by
261	plain <code>java.util.logging</code>, but uses a few	259	plain <code>java.util.logging</code>, but uses a few
262	extensions to allow better flexibility in assigning loggers. The main	260	extensions to allow better flexibility in assigning loggers. The main
Lines 295-302 Link Here
295	</p>	293	</p>
296	<p>	294	<p>
297	Example logging.properties file to be placed in $CATALINA_BASE/conf:	295	Example logging.properties file to be placed in $CATALINA_BASE/conf:
298	<source>	296	</p>
299	handlers = 1catalina.org.apache.juli.FileHandler, \	297	<source><![CDATA[handlers = 1catalina.org.apache.juli.FileHandler, \
300	2localhost.org.apache.juli.FileHandler, \	298	2localhost.org.apache.juli.FileHandler, \
301	3manager.org.apache.juli.FileHandler, \	299	3manager.org.apache.juli.FileHandler, \
302	java.util.logging.ConsoleHandler	300	java.util.logging.ConsoleHandler
Lines 340-354 Link Here
340		338
341	# For example, set the org.apache.catalina.util.LifecycleBase logger to log	339	# For example, set the org.apache.catalina.util.LifecycleBase logger to log
342	# each component that extends LifecycleBase changing state:	340	# each component that extends LifecycleBase changing state:
343	#org.apache.catalina.util.LifecycleBase.level = FINE	341	#org.apache.catalina.util.LifecycleBase.level = FINE]]></source>
344	</source>
345	</p>
346		342
347	<p>	343	<p>
348	Example logging.properties for the servlet-examples web application to be	344	Example logging.properties for the servlet-examples web application to be
349	placed in WEB-INF/classes inside the web application:	345	placed in WEB-INF/classes inside the web application:
350	<source>	346	</p>
351	handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler	347	<source><![CDATA[handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
352		348
353	############################################################	349	############################################################
354	# Handler specific properties.	350	# Handler specific properties.
Lines 360-369 Link Here
360	org.apache.juli.FileHandler.prefix = servlet-examples.	356	org.apache.juli.FileHandler.prefix = servlet-examples.
361		357
362	java.util.logging.ConsoleHandler.level = FINE	358	java.util.logging.ConsoleHandler.level = FINE
363	java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter	359	java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter]]></source>
364	</source>
365	</p>
366		360
		361
367	<subsection name="Documentation references">	362	<subsection name="Documentation references">
368	<p>See the following resources for additional information:</p>	363	<p>See the following resources for additional information:</p>
369	<ul>	364	<ul>
Lines 423-429 Link Here
423	<li>Create a file called <code>log4j.properties</code> with the	418	<li>Create a file called <code>log4j.properties</code> with the
424	following content and save it into <code>$CATALINA_BASE/lib</code></li>	419	following content and save it into <code>$CATALINA_BASE/lib</code></li>
425	</ol>	420	</ol>
426	<source>	421	<source><![CDATA[
427	log4j.rootLogger = INFO, CATALINA	422	log4j.rootLogger = INFO, CATALINA
428		423
429	# Define all the appenders	424	# Define all the appenders
Lines 470-477 Link Here
470	log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager] =\	465	log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager] =\
471	INFO, MANAGER	466	INFO, MANAGER
472	log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager] =\	467	log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager] =\
473	INFO, HOST-MANAGER	468	INFO, HOST-MANAGER]]></source>
474	</source>
475	<ol start="2">	469	<ol start="2">
476	<li><a href="http://logging.apache.org/log4j">Download Log4J</a>	470	<li><a href="http://logging.apache.org/log4j">Download Log4J</a>
477	(v1.2 or later).</li>	471	(v1.2 or later).</li>
Lines 546-556 Link Here
546	configuration files, so we recommend you use a properties file as	540	configuration files, so we recommend you use a properties file as
547	described until a future version of log4j allows this convention.	541	described until a future version of log4j allows this convention.
548	</p>	542	</p>
549	<source>	543	<source><![CDATA[log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG
550	log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG<br />	544	log4j.logger.org.apache.catalina.core=DEBUG
551	log4j.logger.org.apache.catalina.core=DEBUG<br />	545	log4j.logger.org.apache.catalina.session=DEBUG]]></source>
552	log4j.logger.org.apache.catalina.session=DEBUG<br />
553	</source>
554		546
555	<p>	547	<p>
556	Be warned: a level of DEBUG will produce megabytes of logging and slow	548	Be warned: a level of DEBUG will produce megabytes of logging and slow

Lines 72-78 Link Here

(-)webapps/docs/cgi-howto.xml (-2 / +2 lines)
72	<section name="Configuration">	72	<section name="Configuration">
73		73
74	<p>There are several servlet init parameters which can be used to	74	<p>There are several servlet init parameters which can be used to
75	configure the behaviour of the CGI servlet.	75	configure the behaviour of the CGI servlet.</p>
76	<ul>	76	<ul>
77	<li><strong>cgiPathPrefix</strong> - The CGI search path will start at	77	<li><strong>cgiPathPrefix</strong> - The CGI search path will start at
78	the web application root directory + File.separator + this prefix.	78	the web application root directory + File.separator + this prefix.
Lines 96-103 Link Here
96	the reading of stderr to complete before terminating the CGI process. Default	96	the reading of stderr to complete before terminating the CGI process. Default
97	is 2000.</li>	97	is 2000.</li>
98	</ul>	98	</ul>
99	</p>
100		99
		100
101	</section>	101	</section>
102		102
103	</body>	103	</body>

Lines 56-70 Link Here

(-)webapps/docs/class-loader-howto.xml (-4 / +2 lines)
56	organized into the following parent-child relationships, where the parent	56	organized into the following parent-child relationships, where the parent
57	class loader is above the child class loader:</p>	57	class loader is above the child class loader:</p>
58		58
59	<source>	59	<source> Bootstrap
60	Bootstrap
61	\|	60	\|
62	System	61	System
63	\|	62	\|
64	Common	63	Common
65	/ \	64	/ \
66	Webapp1 Webapp2 ...	65	Webapp1 Webapp2 ...</source>
67	</source>
68		66
69	<p>The characteristics of each of these class loaders, including the source	67	<p>The characteristics of each of these class loaders, including the source
70	of classes and resources that they make visible, are discussed in detail in	68	of classes and resources that they make visible, are discussed in detail in

Lines 64-76 Link Here

(-)webapps/docs/connectors.xml (-2 / +1 lines)
64	proxied HTTP. AJP clustering is the most efficient from the Tomcat perspective.	64	proxied HTTP. AJP clustering is the most efficient from the Tomcat perspective.
65	It is otherwise functionally equivalent to HTTP clustering.</p>	65	It is otherwise functionally equivalent to HTTP clustering.</p>
66		66
67	<p>The native connectors supported with this Tomcat release are:	67	<p>The native connectors supported with this Tomcat release are:</p>
68	<ul>	68	<ul>
69	<li>JK 1.2.x with any of the supported servers</li>	69	<li>JK 1.2.x with any of the supported servers</li>
70	<li>mod_proxy on Apache HTTP Server 2.x (included by default in Apache HTTP Server 2.2),	70	<li>mod_proxy on Apache HTTP Server 2.x (included by default in Apache HTTP Server 2.2),
71	with AJP enabled</li>	71	with AJP enabled</li>
72	</ul>	72	</ul>
73	</p>
74		73
75	<p><b>Other native connectors supporting AJP may work, but are no longer supported.</b></p>	74	<p><b>Other native connectors supporting AJP may work, but are no longer supported.</b></p>
76		75

Lines 34-92 Link Here

(-)webapps/docs/default-servlet.xml (-164 / +128 lines)
34	</section>	34	</section>
35		35
36	<section anchor="what" name="What is the DefaultServlet">	36	<section anchor="what" name="What is the DefaultServlet">
		37	<p>
37	The default servlet is the servlet which serves static resources as well	38	The default servlet is the servlet which serves static resources as well
38	as serves the directory listings (if directory listings are enabled).	39	as serves the directory listings (if directory listings are enabled).
39		40	</p>
40	</section>	41	</section>
41		42
42	<section anchor="where" name="Where is it declared?">	43	<section anchor="where" name="Where is it declared?">
		44	<p>
43	It is declared globally in <i>$CATALINA_BASE/conf/web.xml</i>.	45	It is declared globally in <i>$CATALINA_BASE/conf/web.xml</i>.
44	By default here is it's declaration:	46	By default here is it's declaration:
45	<source>	47	</p>
46	<servlet>	48	<source><![CDATA[ <servlet>
47	<servlet-name>default</servlet-name>	49	<servlet-name>default</servlet-name>
48	<servlet-class>	50	<servlet-class>
49	org.apache.catalina.servlets.DefaultServlet	51	org.apache.catalina.servlets.DefaultServlet
50	</servlet-class>	52	</servlet-class>
51	<init-param>	53	<init-param>
52	<param-name>debug</param-name>	54	<param-name>debug</param-name>
53	<param-value>0</param-value>	55	<param-value>0</param-value>
54	</init-param>	56	</init-param>
55	<init-param>	57	<init-param>
56	<param-name>listings</param-name>	58	<param-name>listings</param-name>
57	<param-value>false</param-value>	59	<param-value>false</param-value>
58	</init-param>	60	</init-param>
59	<load-on-startup>1</load-on-startup>	61	<load-on-startup>1</load-on-startup>
60	</servlet>	62	</servlet>
61		63
62	...	64	...
63		65
64	<servlet-mapping>	66	<servlet-mapping>
65	<servlet-name>default</servlet-name>	67	<servlet-name>default</servlet-name>
66	<url-pattern>/</url-pattern>	68	<url-pattern>/</url-pattern>
67	</servlet-mapping>	69	</servlet-mapping>]]></source>
68		70
69	</source>
70
71	So by default, the default servlet is loaded at webapp startup and	71	So by default, the default servlet is loaded at webapp startup and
72	directory listings are disabled and debugging is turned off.	72	directory listings are disabled and debugging is turned off.
73	</section>	73	</section>
74		74
75	<section anchor="change" name="What can I change?">	75	<section anchor="change" name="What can I change?">
76	The DefaultServlet allows the following initParamters:	76	<p>
		77	The DefaultServlet allows the following initParamters:
		78	</p>
77		79
78	<table border="1">	80	<properties>
79	<tr>	81	<property name="debug">
80	<th valign='top'>debug</th>
81	<td valign='top'>
82	Debugging level. It is not very useful unless you are a tomcat	82	Debugging level. It is not very useful unless you are a tomcat
83	developer. As	83	developer. As
84	of this writing, useful values are 0, 1, 11, 1000. [0]	84	of this writing, useful values are 0, 1, 11, 1000. [0]
85	</td>	85	</property>
86	</tr>	86	<property name="listings">
87	<tr>
88	<th valign='top'>listings</th>
89	<td valign='top'>
90	If no welcome file is present, can a directory listing be	87	If no welcome file is present, can a directory listing be
91	shown?	88	shown?
92	value may be <b>true</b> or <b>false</b> [false]	89	value may be <b>true</b> or <b>false</b> [false]
Lines 96-114 Link Here
96	<b>WARNING:</b> Listings of directories containing many entries are	93	<b>WARNING:</b> Listings of directories containing many entries are
97	expensive. Multiple requests for large directory listings can consume	94	expensive. Multiple requests for large directory listings can consume
98	significant proportions of server resources.	95	significant proportions of server resources.
99	</td>	96	</property>
100	</tr>	97	<property name="readmeFile">
101	<tr>
102	<th valign='top'>readmeFile</th>
103	<td valign='top'>
104	If a directory listing is presented, a readme file may also	98	If a directory listing is presented, a readme file may also
105	be presented with the listing. This file is inserted as is	99	be presented with the listing. This file is inserted as is
106	so it may contain HTML.	100	so it may contain HTML.
107	</td>	101	</property>
108	</tr>	102	<property name="globalXsltFile">
109	<tr>
110	<th valign='top'>globalXsltFile</th>
111	<td valign='top'>
112	If you wish to customize your directory listing, you	103	If you wish to customize your directory listing, you
113	can use an XSL transformation. This value is an absolute	104	can use an XSL transformation. This value is an absolute
114	file name which be used for all directory listings.	105	file name which be used for all directory listings.
Lines 115-125 Link Here
115	This can be overridden per context and/or per directory. See	106	This can be overridden per context and/or per directory. See
116	<strong>contextXsltFile</strong> and <strong>localXsltFile</strong>	107	<strong>contextXsltFile</strong> and <strong>localXsltFile</strong>
117	below. The format of the xml is shown below.	108	below. The format of the xml is shown below.
118	</td>	109	</property>
119	</tr>	110	<property name="contextXsltFile">
120	<tr>
121	<th valign='top'>contextXsltFile</th>
122	<td valign='top'>
123	You may also customize your directory listing by context by	111	You may also customize your directory listing by context by
124	configuring <code>contextXsltFile</code>. This should be a context	112	configuring <code>contextXsltFile</code>. This should be a context
125	relative path (e.g.: <code>/path/to/context.xslt</code>). This	113	relative path (e.g.: <code>/path/to/context.xslt</code>). This
Lines 127-137 Link Here
127	file does not exist, then <code>globalXsltFile</code> will be used. If	115	file does not exist, then <code>globalXsltFile</code> will be used. If
128	<code>globalXsltFile</code> does not exist, then the default	116	<code>globalXsltFile</code> does not exist, then the default
129	directory listing will be shown.	117	directory listing will be shown.
130	</td>	118	</property>
131	</tr>	119	<property name="localXsltFile">
132	<tr>
133	<th valign='top'>localXsltFile</th>
134	<td valign='top'>
135	You may also customize your directory listing by directory by	120	You may also customize your directory listing by directory by
136	configuring <code>localXsltFile</code>. This should be a relative	121	configuring <code>localXsltFile</code>. This should be a relative
137	file name in the directory where the listing will take place.	122	file name in the directory where the listing will take place.
Lines 142-194 Link Here
142	<code>globalXsltFile</code> will be used. If	127	<code>globalXsltFile</code> will be used. If
143	<code>globalXsltFile</code> does not exist, then the default	128	<code>globalXsltFile</code> does not exist, then the default
144	directory listing will be shown.	129	directory listing will be shown.
145	</td>	130	</property>
146	</tr>	131	<property name="input">
147	<tr>
148	<th valign='top'>input</th>
149	<td valign='top'>
150	Input buffer size (in bytes) when reading	132	Input buffer size (in bytes) when reading
151	resources to be served. [2048]	133	resources to be served. [2048]
152	</td>	134	</property>
153	</tr>	135	<property name="output">
154	<tr>
155	<th valign='top'>output</th>
156	<td valign='top'>
157	Output buffer size (in bytes) when writing	136	Output buffer size (in bytes) when writing
158	resources to be served. [2048]	137	resources to be served. [2048]
159	</td>	138	</property>
160	</tr>	139	<property name="readonly">
161	<tr>
162	<th valign='top'>readonly</th>
163	<td valign='top'>
164	Is this context "read only", so HTTP commands like PUT and	140	Is this context "read only", so HTTP commands like PUT and
165	DELETE are rejected? [true]	141	DELETE are rejected? [true]
166	</td>	142	</property>
167	</tr>	143	<property name="fileEncoding">
168	<tr>
169	<th valign='top'>fileEncoding</th>
170	<td valign='top'>
171	File encoding to be used when reading static resources.	144	File encoding to be used when reading static resources.
172	[platform default]	145	[platform default]
173	</td>	146	</property>
174	</tr>	147	<property name="sendfileSize">
175	<tr>
176	<th valign='top'>sendfileSize</th>
177	<td valign='top'>
178	If the connector used supports sendfile, this represents the minimal	148	If the connector used supports sendfile, this represents the minimal
179	file size in KB for which sendfile will be used. Use a negative value	149	file size in KB for which sendfile will be used. Use a negative value
180	to always disable sendfile. [48]	150	to always disable sendfile. [48]
181	</td>	151	</property>
182	</tr>	152	<property name="useAcceptRanges">
183	<tr>
184	<th valign='top'>useAcceptRanges</th>
185	<td valign='top'>
186	If true, the Accept-Ranges header will be set when appropriate for the	153	If true, the Accept-Ranges header will be set when appropriate for the
187	response. [true]	154	response. [true]
188	</td>	155	</property>
189	</tr>	156	</properties>
190
191	</table>
192	</section>	157	</section>
193		158
194	<section anchor="dir" name="How do I customize directory listings?">	159	<section anchor="dir" name="How do I customize directory listings?">
Lines 210-311 Link Here
210		175
211	<p>	176	<p>
212	Format:	177	Format:
213	<source>	178	</p>
214	<listing>	179	<source><![CDATA[ <listing>
215	<entries>	180	<entries>
216	<entry type='file\|dir' urlPath='aPath' size='###' date='gmt date'>	181	<entry type='file\|dir' urlPath='aPath' size='###' date='gmt date'>
217	fileName1	182	fileName1
218	</entry>	183	</entry>
219	<entry type='file\|dir' urlPath='aPath' size='###' date='gmt date'>	184	<entry type='file\|dir' urlPath='aPath' size='###' date='gmt date'>
220	fileName2	185	fileName2
221	</entry>	186	</entry>
222	...	187	...
223	</entries>	188	</entries>
224	<readme></readme>	189	<readme></readme>
225	</listing>	190	</listing>]]></source>
226	</source>
227	<ul>	191	<ul>
228	<li>size will be missing if <code>type='dir'</code></li>	192	<li>size will be missing if <code>type='dir'</code></li>
229	<li>Readme is a CDATA entry</li>	193	<li>Readme is a CDATA entry</li>
230	</ul>	194	</ul>
		195
		196	<p>
		197	The following is a sample xsl file which mimics the default tomcat behavior:
231	</p>	198	</p>
232	The following is a sample xsl file which mimics the default tomcat behavior:	199	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
233	<source>
234	<?xml version="1.0"?>
235		200
236	<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"	201	<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
237	version="1.0">	202	version="3.0">
238		203
239	<xsl:output method="xhtml" encoding="iso-8859-1" indent="no"/>	204	<xsl:output method="html" html-version="5.0"
		205	encoding="UTF-8" indent="no"
		206	doctype-system="about:legacy-compat"/>
240		207
241	<xsl:template match="listing">	208	<xsl:template match="listing">
242	<html>	209	<html>
243	<head>	210	<head>
244	<title>	211	<title>
245	Sample Directory Listing For	212	Sample Directory Listing For
246	<xsl:value-of select="@directory"/>	213	<xsl:value-of select="@directory"/>
247	</title>	214	</title>
248	<style>	215	<style>
249	h1{color : white;background-color : #0086b2;}	216	h1 {color : white;background-color : #0086b2;}
250	h3{color : white;background-color : #0086b2;}	217	h3 {color : white;background-color : #0086b2;}
251	body{font-family : sans-serif,Arial,Tahoma;	218	body {font-family : sans-serif,Arial,Tahoma;
252	color : black;background-color : white;}	219	color : black;background-color : white;}
253	b{color : white;background-color : #0086b2;}	220	b {color : white;background-color : #0086b2;}
254	a{color : black;} HR{color : #0086b2;}	221	a {color : black;} HR{color : #0086b2;}
255	</style>	222	table td { padding: 5px; }
256	</head>	223	</style>
257	<body>	224	</head>
258	<h1>Sample Directory Listing For	225	<body>
259	<xsl:value-of select="@directory"/>	226	<h1>Sample Directory Listing For
260	</h1>	227	<xsl:value-of select="@directory"/>
261	<hr size="1" />	228	</h1>
262	<table cellspacing="0"	229	<hr style="height: 1px;" />
263	width="100%"	230	<table style="width: 100%;">
264	cellpadding="5"	231	<tr>
265	align="center">	232	<th style="text-align: left;">Filename</th>
266	<tr>	233	<th style="text-align: center;">Size</th>
267	<th align="left">Filename</th>	234	<th style="text-align: right;">Last Modified</th>
268	<th align="center">Size</th>	235	</tr>
269	<th align="right">Last Modified</th>	236	<xsl:apply-templates select="entries"/>
270	</tr>	237	</table>
271	<xsl:apply-templates select="entries"/>	238	<xsl:apply-templates select="readme"/>
272	</table>	239	<hr style="height: 1px;" />
273	<xsl:apply-templates select="readme"/>	240	<h3>Apache Tomcat/8.0</h3>
274	<hr size="1" />	241	</body>
275	<h3>Apache Tomcat/7.0</h3>	242	</html>
276	</body>	243	</xsl:template>
277	</html>
278	</xsl:template>
279		244
280		245
281	<xsl:template match="entries">	246	<xsl:template match="entries">
282	<xsl:apply-templates select="entry"/>	247	<xsl:apply-templates select="entry"/>
283	</xsl:template>	248	</xsl:template>
284		249
285	<xsl:template match="readme">	250	<xsl:template match="readme">
286	<hr size="1" />	251	<hr style="height: 1px;" />
287	<pre><xsl:apply-templates/></pre>	252	<pre><xsl:apply-templates/></pre>
288	</xsl:template>	253	</xsl:template>
289		254
290	<xsl:template match="entry">	255	<xsl:template match="entry">
291	<tr>	256	<tr>
292	<td align="left">	257	<td style="text-align: left;">
293	<xsl:variable name="urlPath" select="@urlPath"/>	258	<xsl:variable name="urlPath" select="@urlPath"/>
294	<a href="{$urlPath}">	259	<a href="{$urlPath}">
295	<tt><xsl:apply-templates/></tt>	260	<pre><xsl:apply-templates/></pre>
296	</a>	261	</a>
297	</td>	262	</td>
298	<td align="right">	263	<td style="text-align: right;">
299	<tt><xsl:value-of select="@size"/></tt>	264	<pre><xsl:value-of select="@size"/></pre>
300	</td>	265	</td>
301	<td align="right">	266	<td style="text-align: right;">
302	<tt><xsl:value-of select="@date"/></tt>	267	<pre><xsl:value-of select="@date"/></pre>
303	</td>	268	</td>
304	</tr>	269	</tr>
305	</xsl:template>	270	</xsl:template>
306		271
307	</xsl:stylesheet>	272	</xsl:stylesheet>]]></source>
308	</source>
309		273
310	</section>	274	</section>
311		275

Lines 42-48 Link Here

(-)webapps/docs/jasper-howto.xml (-55 / +48 lines)
42		42
43	<p>Jasper 2 has been redesigned to significantly improve performance over	43	<p>Jasper 2 has been redesigned to significantly improve performance over
44	the original Jasper. In addition to general code improvements the following	44	the original Jasper. In addition to general code improvements the following
45	changes were made:	45	changes were made:</p>
46	<ul>	46	<ul>
47	<li><strong>JSP Custom Tag Pooling</strong> - The java objects instantiated	47	<li><strong>JSP Custom Tag Pooling</strong> - The java objects instantiated
48	for JSP Custom Tags can now be pooled and reused. This significantly boosts	48	for JSP Custom Tags can now be pooled and reused. This significantly boosts
Lines 61-68 Link Here
61	compilation. This compiler loads source dependencies from the container	61	compilation. This compiler loads source dependencies from the container
62	classloader. Ant and javac can still be used.</li>	62	classloader. Ant and javac can still be used.</li>
63	</ul>	63	</ul>
64	</p>
65		64
		65
66	<p>Jasper is implemented using the servlet class	66	<p>Jasper is implemented using the servlet class
67	<code>org.apache.jasper.servlet.JspServlet</code>.</p>	67	<code>org.apache.jasper.servlet.JspServlet</code>.</p>
68		68
Lines 71-83 Link Here
71	<section name="Configuration">	71	<section name="Configuration">
72		72
73	<p>By default Jasper is configured for use when doing web application	73	<p>By default Jasper is configured for use when doing web application
74	development. See the section <a href="#Production Configuration">	74	development. See the section <a href="#Production_Configuration">
75	Production Configuration</a> for information on configuring Jasper	75	Production Configuration</a> for information on configuring Jasper
76	for use on a production Tomcat server.</p>	76	for use on a production Tomcat server.</p>
77		77
78	<p>The servlet which implements Jasper is configured using init parameters	78	<p>The servlet which implements Jasper is configured using init parameters
79	in your global <code>$CATALINA_BASE/conf/web.xml</code>.	79	in your global <code>$CATALINA_BASE/conf/web.xml</code>.
80		80	</p>
81	<ul>	81	<ul>
82	<li><strong>checkInterval</strong> - If development is false and checkInterval	82	<li><strong>checkInterval</strong> - If development is false and checkInterval
83	is greater than zero, background compiles are enabled. checkInterval is the time	83	is greater than zero, background compiles are enabled. checkInterval is the time
Lines 198-205 Link Here
198	header is added by generated servlet. <code>true</code> or <code>false</code>,	198	header is added by generated servlet. <code>true</code> or <code>false</code>,
199	default <code>false</code>.</li>	199	default <code>false</code>.</li>
200	</ul>	200	</ul>
201	</p>
202		201
		202
203	<p>The Java compiler from Eclipse JDT in included as the default compiler. It is	203	<p>The Java compiler from Eclipse JDT in included as the default compiler. It is
204	an advanced Java compiler which will load all dependencies from the Tomcat class	204	an advanced Java compiler which will load all dependencies from the Tomcat class
205	loader, which will help tremendously when compiling on large installations with	205	loader, which will help tremendously when compiling on large installations with
Lines 222-233 Link Here
222	<code>java.lang.InternalError: name is too long to represent</code> exception	222	<code>java.lang.InternalError: name is too long to represent</code> exception
223	when compiling very large JSPs. If this is observed then it may be worked around	223	when compiling very large JSPs. If this is observed then it may be worked around
224	by using one of the following:	224	by using one of the following:
		225	</p>
225	<ul>	226	<ul>
226	<li>reduce the size of the JSP</li>	227	<li>reduce the size of the JSP</li>
227	<li>disable SMAP generation and JSR-045 support by setting	228	<li>disable SMAP generation and JSR-045 support by setting
228	<code>suppressSmap</code> to <code>true</code>.</li>	229	<code>suppressSmap</code> to <code>true</code>.</li>
229	</ul>	230	</ul>
230	</p>
231		231
232	</section>	232	</section>
233		233
Lines 239-245 Link Here
239	Jasper servlet becomes critical.</p>	239	Jasper servlet becomes critical.</p>
240		240
241	<p>When using Jasper 2 in a production Tomcat server you should consider making	241	<p>When using Jasper 2 in a production Tomcat server you should consider making
242	the following changes from the default configuration.	242	the following changes from the default configuration.</p>
243	<ul>	243	<ul>
244	<li><strong>development</strong> - To disable on access checks for JSP	244	<li><strong>development</strong> - To disable on access checks for JSP
245	pages compilation set this to <code>false</code>.</li>	245	pages compilation set this to <code>false</code>.</li>
Lines 251-257 Link Here
251	<li><strong>trimSpaces</strong> - To remove useless bytes from the response,	251	<li><strong>trimSpaces</strong> - To remove useless bytes from the response,
252	set this to <code>true</code>.</li>	252	set this to <code>true</code>.</li>
253	</ul>	253	</ul>
254	</p>
255		254
256	</section>	255	</section>
257		256
Lines 264-337 Link Here
264	download) to precompile a webapp:	263	download) to precompile a webapp:
265	</p>	264	</p>
266		265
267	<p>	266	<source><![CDATA[<project name="Webapp Precompilation" default="all" basedir=".">
268	<source>
269	<project name="Webapp Precompilation" default="all" basedir=".">
270		267
271	<import file="${tomcat.home}/bin/catalina-tasks.xml"/>	268	<import file="${tomcat.home}/bin/catalina-tasks.xml"/>
272		269
273	<target name="jspc">	270	<target name="jspc">
274		271
275	<jasper	272	<jasper
276	validateXml="false"	273	validateXml="false"
277	uriroot="${webapp.path}"	274	uriroot="${webapp.path}"
278	webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml"	275	webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml"
279	outputDir="${webapp.path}/WEB-INF/src" />	276	outputDir="${webapp.path}/WEB-INF/src" />
280		277
281	</target>	278	</target>
282		279
283	<target name="compile">	280	<target name="compile">
284		281
285	<mkdir dir="${webapp.path}/WEB-INF/classes"/>	282	<mkdir dir="${webapp.path}/WEB-INF/classes"/>
286	<mkdir dir="${webapp.path}/WEB-INF/lib"/>	283	<mkdir dir="${webapp.path}/WEB-INF/lib"/>
287		284
288	<javac destdir="${webapp.path}/WEB-INF/classes"	285	<javac destdir="${webapp.path}/WEB-INF/classes"
289	optimize="off"	286	optimize="off"
290	debug="on" failonerror="false"	287	debug="on" failonerror="false"
291	srcdir="${webapp.path}/WEB-INF/src"	288	srcdir="${webapp.path}/WEB-INF/src"
292	excludes="*/.smap">	289	excludes="*/.smap">
293	<classpath>	290	<classpath>
294	<pathelement location="${webapp.path}/WEB-INF/classes"/>	291	<pathelement location="${webapp.path}/WEB-INF/classes"/>
295	<fileset dir="${webapp.path}/WEB-INF/lib">	292	<fileset dir="${webapp.path}/WEB-INF/lib">
296	<include name="*.jar"/>	293	<include name="*.jar"/>
297	</fileset>	294	</fileset>
298	<pathelement location="${tomcat.home}/lib"/>	295	<pathelement location="${tomcat.home}/lib"/>
299	<fileset dir="${tomcat.home}/lib">	296	<fileset dir="${tomcat.home}/lib">
300	<include name="*.jar"/>	297	<include name="*.jar"/>
301	</fileset>	298	</fileset>
302	<fileset dir="${tomcat.home}/bin">	299	<fileset dir="${tomcat.home}/bin">
303	<include name="*.jar"/>	300	<include name="*.jar"/>
304	</fileset>	301	</fileset>
305	</classpath>	302	</classpath>
306	<include name="**" />	303	<include name="**" />
307	<exclude name="tags/**" />	304	<exclude name="tags/**" />
308	</javac>	305	</javac>
309		306
310	</target>	307	</target>
311		308
312	<target name="all" depends="jspc,compile">	309	<target name="all" depends="jspc,compile">
313	</target>	310	</target>
314		311
315	<target name="cleanup">	312	<target name="cleanup">
316	<delete>	313	<delete>
317	<fileset dir="${webapp.path}/WEB-INF/src"/>	314	<fileset dir="${webapp.path}/WEB-INF/src"/>
318	<fileset dir="${webapp.path}/WEB-INF/classes/org/apache/jsp"/>	315	<fileset dir="${webapp.path}/WEB-INF/classes/org/apache/jsp"/>
319	</delete>	316	</delete>
320	</target>	317	</target>
321		318
322	</project>	319	</project>]]></source>
323	</source>
324	</p>
325		320
326	<p>	321	<p>
327	The following command line can be used to run the script	322	The following command line can be used to run the script
328	(replacing the tokens with the Tomcat base path and the path to the webapp	323	(replacing the tokens with the Tomcat base path and the path to the webapp
329	which should be precompiled):<br/>	324	which should be precompiled):
330	<source>
331	$ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH>
332	</source>
333	</p>	325	</p>
		326	<source>$ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH></source>
334		327
		328
335	<p>	329	<p>
336	Then, the declarations and mappings for the servlets which were generated	330	Then, the declarations and mappings for the servlets which were generated
337	during the precompilation must be added to the web application deployment	331	during the precompilation must be added to the web application deployment
Lines 366-372 Link Here
366	<code>${webapp.path}/WEB-INF/classes/org/apache/jsp</code>.	360	<code>${webapp.path}/WEB-INF/classes/org/apache/jsp</code>.
367	</p>	361	</p>
368		362
369	<p><strong>Hints:</strong>	363	<p><strong>Hints:</strong></p>
370	<ul>	364	<ul>
371	<li> When you switch to another Tomcat release, then regenerate and recompile	365	<li> When you switch to another Tomcat release, then regenerate and recompile
372	your jsp's with the new Tomcat version.</li>	366	your jsp's with the new Tomcat version.</li>
Lines 377-383 Link Here
377	that changing from the defaults may affect performance, but it will vary	371	that changing from the defaults may affect performance, but it will vary
378	depending on the application.</li>	372	depending on the application.</li>
379	</ul>	373	</ul>
380	</p>
381	</section>	374	</section>
382		375
383	<section name="Optimisation">	376	<section name="Optimisation">