| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="default-servlet.html"> |
| |
| &project; |
| |
| <properties> |
| <author email="funkman@apache.org">Tim Funk</author> |
| <title>Default Servlet Reference</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Table of Contents"> |
| <toc/> |
| </section> |
| |
| <section anchor="what" name="What is the DefaultServlet"> |
| The default servlet is the servlet which serves static resources as well |
| as serves the directory listings (if directory listings are enabled). |
| |
| </section> |
| |
| <section anchor="where" name="Where is it declared?"> |
| It is declared globally in <i>$CATALINA_HOME/conf/web.xml</i>. |
| By default here is it's declaration: |
| <source> |
| <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>true</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> |
| |
| So by default, the default servlet is loaded at webapp startup and |
| directory listings are enabled and debugging is turned off. |
| </section> |
| |
| <section anchor="change" name="What can I change?"> |
| The DefaultServlet allows the following initParamters: |
| |
| <table border="1"> |
| <tr> |
| <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. |
| </td> |
| </tr> |
| <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> |
| <br /> |
| Welcome files are part of the servlet api. |
| <br /> |
| <b>WARNING:</b> Listings of directories containing many entries are |
| expensive. Multiple requests for large directory listings can consume |
| significant proportions of server resources. |
| </td> |
| </tr> |
| <tr> |
| <th valign='top'>readmeFile</th> |
| <td valign='top'> |
| 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. default value is null |
| </td> |
| </tr> |
| <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 disabled by per webapp by also declaring the |
| default servlet in your local webapp's web.xml. The format |
| of the xml is shown below. |
| </td> |
| </tr> |
| <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. |
| This overrides <code>globalXsltFile</code>. If this value |
| is present but a file does not exist, then |
| <code>globalXsltFile</code> will be used. If |
| <code>globalXsltFile</code> does not exist, then the default |
| directory listing will be shown. |
| </td> |
| </tr> |
| <tr> |
| <th valign='top'>input</th> |
| <td valign='top'> |
| Input buffer size (in bytes) when reading |
| resources to be served. [2048] |
| </td> |
| </tr> |
| <tr> |
| <th valign='top'>output</th> |
| <td valign='top'> |
| Output buffer size (in bytes) when writing |
| resources to be served. [2048] |
| </td> |
| </tr> |
| <tr> |
| <th valign='top'>readonly</th> |
| <td valign='top'> |
| Is this context "read only", so HTTP commands like PUT and |
| DELETE are rejected? [true] |
| </td> |
| </tr> |
| <tr> |
| <th valign='top'>fileEncoding</th> |
| <td valign='top'> |
| File encoding to be used when reading static resources. |
| [platform default] |
| </td> |
| </tr> |
| <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] |
| </td> |
| </tr> |
| <tr> |
| <th valign='top'>useAcceptRanges</th> |
| <td valign='top'> |
| If true, the Accept-Ranges header will be set when appropriate for the |
| response. [true] |
| </td> |
| </tr> |
| |
| </table> |
| </section> |
| |
| <section anchor="dir" name="How do I customize directory listings?"> |
| <p>You can override DefaultServlet with you own implementation and use that |
| in your web.xml declaration. If you |
| can understand what was just said, we will assume you can read the code |
| to DefaultServlet servlet and make the appropriate adjustments. (If not, |
| then that method isn't for you) |
| </p> |
| <p> |
| You can use either <code>localXsltFile</code> or |
| <code>globalXsltFile</code> and DefaultServlet will create |
| an xml document and run it through an xsl transformation based |
| on the values provided in <code>localXsltFile</code> and |
| <code>globalXsltFile</code>. <code>localXsltFile</code> is first |
| checked, followed by <code>globalXsltFile</code>, then default |
| behaviors takes place. |
| </p> |
| |
| <p> |
| Format: |
| <source> |
| <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> |
| <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: |
| <source> |
| <?xml version="1.0"?> |
| |
| <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" |
| version="1.0"> |
| |
| <xsl:output method="xhtml" encoding="iso-8859-1" indent="no"/> |
| |
| <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;} |
| </style> |
| </head> |
| <body> |
| <h1>Sample Directory Listing For |
| <xsl:value-of select="@directory"/> |
| </h1> |
| <hr size="1" /> |
| <table cellspacing="0" |
| width="100%" |
| cellpadding="5" |
| align="center"> |
| <tr> |
| <th align="left">Filename</th> |
| <th align="center">Size</th> |
| <th align="right">Last Modified</th> |
| </tr> |
| <xsl:apply-templates select="entries"/> |
| </table> |
| <xsl:apply-templates select="readme"/> |
| <hr size="1" /> |
| <h3>Apache Tomcat/5.0</h3> |
| </body> |
| </html> |
| </xsl:template> |
| |
| |
| <xsl:template match="entries"> |
| <xsl:apply-templates select="entry"/> |
| </xsl:template> |
| |
| <xsl:template match="readme"> |
| <hr size="1" /> |
| <pre><xsl:apply-templates/></pre> |
| </xsl:template> |
| |
| <xsl:template match="entry"> |
| <tr> |
| <td align="left"> |
| <xsl:variable name="urlPath" select="@urlPath"/> |
| <a href="{$urlPath}"> |
| <tt><xsl:apply-templates/></tt> |
| </a> |
| </td> |
| <td align="right"> |
| <tt><xsl:value-of select="@size"/></tt> |
| </td> |
| <td align="right"> |
| <tt><xsl:value-of select="@date"/></tt> |
| </td> |
| </tr> |
| </xsl:template> |
| |
| </xsl:stylesheet> |
| </source> |
| |
| </section> |
| |
| <section anchor="secure" name="How do I secure directory listings?"> |
| Use web.xml in each individual webapp. See the security section of the |
| Servlet specification. |
| |
| </section> |
| |
| </body> |
| |
| </document> |