source: nutchez-0.1/tomcat/webapps/docs/funcspecs/fs-default.html @ 186

Last change on this file since 186 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 13.8 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications - Default Servlet</title><meta value="Craig McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2      Catalina Functional Specifications
3    " align="right" src="../images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Functional Specs</a></li></ul><p><strong>Administrative Apps</strong></p><ul><li><a href="fs-admin-apps.html">Overall Requirements</a></li><li><a href="mbean-names.html">Tomcat MBean Names</a></li><li><a href="fs-admin-objects.html">Administered Objects</a></li><li><a href="fs-admin-opers.html">Supported Operations</a></li></ul><p><strong>Internal Servlets</strong></p><ul><li><a href="fs-default.html">Default Servlet</a></li><li><a href="fs-invoker.html">Invoker Servlet</a></li></ul><p><strong>Realm Implementations</strong></p><ul><li><a href="fs-jdbc-realm.html">JDBC Realm</a></li><li><a href="fs-jndi-realm.html">JNDI Realm</a></li><li><a href="fs-memory-realm.html">Memory Realm</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Catalina Functional Specifications</h1><h2>Default Servlet</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/fs-default.html"><img alt="Printer Friendly Version" border="0" src="../images/printer.gif"><br>print-friendly<br>version
4                    </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
5
6
7  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
8
9    <p>The purpose of the <strong>Default Servlet</strong> is to serve
10    static resources of a web application in response to client requests.
11    As the name implies, it is generally configured as the "default"
12    servlet for a web application, by being mapped to a URL pattern "/".</p>
13
14  </blockquote></td></tr></table>
15
16
17  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="External Specifications"><strong>External Specifications</strong></a></font></td></tr><tr><td><blockquote>
18
19    <p>The following external specifications have provisions which
20    partially define the correct behavior of the default servlet:</p>
21    <ul>
22    <li><a href="http://java.sun.com/products/servlet/download.html">
23        Servlet Specification</a> (Version 2.3 PFD2)</li>
24    <li><a href="http://www.rfc-editor.org/rfc/rfc2046.txt">Multipurpose
25        Internet Mail Extensions (MIME) Part Two: Media Types</a></li>
26    <li><a href="http://www.rfc-editor.org/rfc/rfc2616.txt">Hypertext
27        Transfer Protocol -- HTTP/1.1</a></li>
28    </ul>
29
30  </blockquote></td></tr></table>
31
32
33  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Implementation Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote>
34
35    <p>The implementation of this functionality shall conform to the
36    following requirements:</p>
37    <ul>
38    <li>Must be implemented as a servlet.</li>
39    <li>Must support configurable parameters for debugging detail level,
40        input buffer size, output buffer size, whether or not to produce
41        directory listings when no welcome file is present, and whether or not
42        modifications are supported via DELETE and PUT.</li>
43    <li>Log debugging and operational messages (suitably internationalized)
44        via the <code>getServletContext().log()</code> method.</li>
45    </ul>
46
47  </blockquote></td></tr></table>
48
49
50</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote>
51
52
53  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Environmental Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote>
54
55    <p>The following environmental dependencies must be met in order for
56    the default servlet to operate correctly:</p>
57    <ul>
58    <li>The default servlet must be registered in the application deployment
59        descriptor (or the default deployment descriptor in file
60        <code>$CATALINA_BASE/conf/web.xml</code>) using a "default servlet"
61        servlet mapping, signified by URL pattern "/".</li>
62    </ul>
63
64  </blockquote></td></tr></table>
65
66
67  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Container Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>
68
69    <p>Correct operation of the default servlet depends on the following
70    specific features of the surrounding container:</p>
71    <ul>
72    <li>The container shall provide a servlet context attribute that
73        lists the welcome file names that have been defined for this
74        web application.</li>
75    <li>The container shall provide a servlet context attribute that
76        contains a <code>javax.naming.directory.DirContext</code>
77        implementation representing the static resources of this
78        web application.</li>
79    </ul>
80
81  </blockquote></td></tr></table>
82
83
84</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote>
85
86
87  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Initialization Functionality"><strong>Initialization Functionality</strong></a></font></td></tr><tr><td><blockquote>
88
89    <p>The following processing must be performed when the <code>init()</code>
90    method of the invoker servlet is called:</p>
91    <ul>
92    <li>Process and sanity check configuration parameters.</li>
93    </ul>
94
95  </blockquote></td></tr></table>
96
97
98  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Per-Request Functionality"><strong>Per-Request Functionality</strong></a></font></td></tr><tr><td><blockquote>
99
100
101    <p>For all HTTP request methods, the resource path is determined from
102    the path information provided to this request, either as request attribute
103    <code>javax.servlet.include.path_info</code> (for a request dispatcher
104    access to a static resource) or by calling
105    <code>request.getPathInfo()</code> directly.</p>
106
107    <p>On each HTTP DELETE request processed by this servlet, the following
108    processing shall be performed:</p>
109    <ul>
110    <li>If modifications to the static resources are not allowed (set by a
111        configuration parameter), return HTTP status 403 (forbidden).</li>
112    <li>If an attempt is made to delete a resource from <code>/META-INF</code>
113        or <code>/WEB-INF</code>, return HTTP status 403 (forbidden).</li>
114    <li>If the requested resource does not exist, return HTTP status 404
115        (not found)</li>
116    <li>Unbind the resource from the directory context containing the
117        static resources for this web application.  If successful, return
118        HTTP status 204 (no content).  Otherwise, return HTTP status 405
119        (method not allowed).</li>
120    </ul>
121
122
123    <p>On each HTTP GET request processed by this servlet, the following
124    processing shall be performed:</p>
125    <ul>
126    <li>If the request is for a resource under <code>/META-INF</code> or
127        <code>/WEB-INF</code>, return HTTP status 404 (not found).</li>
128    <li>If the requested resource does not exist, return HTTP status 404
129        (not found).</li>
130    <li>If the requested resource is not a directory, but the resource
131        path ends in "/" or "\", return HTTP status 404 (not found).</li>
132    <li>If the requested resource is a directory:
133        <ul>
134        <li>If the request path does not end with "/", redirect to a
135            corresponding path with "/" appended so that relative references
136            in welcome files are resolved correctly.</li>
137        <li>If one of the specified welcome files exists, redirect to the
138            path for that welcome file so that it will be served explicitly.
139            </li>
140        </ul></li>
141    <li>If the request being processed contains an <code>If-Range</code>
142        header, perform the processing described in the HTTP/1.1 specification
143        to determine whether the client's information is up to date.</li>
144    <li>Determine the content type of the response, by looking up the
145        corresponding MIME type in our servlet context.</li>
146    <li>If the requested resource is a directory:
147        <ul>
148        <li>If directory listings are suppressed, return HTTP status 404
149            (not found).</li>
150        <li>Set the content type to <code>text/html</code>.</li>
151        </ul></li>
152    <li>Determine the range(s) to be returned, based on the existence of
153        any <code>If-Range</code> and <code>Range</code> headers.</li>
154    <li>If the requested resource is a directory, include an <code>ETag</code>
155        header in the response, with the value calculated based on the content
156        of the directory.</li>
157    <li>Include a <code>Last-Modified</code> header in the response documenting
158        the date/time that the resource was last modified.</li>
159    <li>Unless we are processing a HEAD request, include the appropriate
160        content (or content ranges) in the response.</li>
161    </ul>
162
163    <p>On each HTTP HEAD request processed by this servlet, the following
164    processing shall be performed:</p>
165    <ul>
166    <li>Processed identically to an HTTP GET request, except that the data
167        content is not transmitted after the headers.</li>
168    </ul>
169
170    <p>On each HTTP POST request processed by this servlet, the following
171    processing shall be performed:</p>
172    <ul>
173    <li>Processed identically to an HTTP GET request.</li>
174    </ul>
175
176
177    <p>On each HTTP PUT request processed by this servlet, the following
178    processing shall be perfomred:</p>
179    <ul>
180    <li>If modifications to the static resources are not allowed (set by a
181        configuration parameter), return HTTP status 403 (forbidden).</li>
182    <li>If an attempt is made to delete a resource from <code>/META-INF</code>
183        or <code>/WEB-INF</code>, return HTTP status 403 (forbidden).</li>
184    <li>Create a new resource from the body of this request.</li>
185    <li>Bind or rebind the specified path to the new resource (depending on
186        whether it currently exists or not).  Return HTTP status as follows:
187        <ul>
188        <li>If binding was unsuccessful, return HTTP status 409 (conflict).
189            </li>
190        <li>If binding was successful and the resource did not previously
191            exist, return HTTP status 201 (created).</li>
192        <li>If binding was successful and the resource previously existed,
193            return HTTP status 204 (no content).</li>
194        </ul></li>
195    </ul>
196
197  </blockquote></td></tr></table>
198
199
200  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Finalization Functionality"><strong>Finalization Functionality</strong></a></font></td></tr><tr><td><blockquote>
201
202    <p>No specific processing is required when the <code>destroy()</code>
203    method is called:</p>
204
205  </blockquote></td></tr></table>
206
207
208</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Testable Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote>
209
210  <p>In addition the the assertions implied by the functionality requirements
211  listed above, the following additional assertions shall be tested to
212  validate the behavior of the invoker servlet:</p>
213  <ul>
214  <li>Requests for resources that do not exist in the web application must
215      return HTTP status 404 (not found).</li>
216  <li>The default servlet must operate identically for web applications that
217      are run out of a WAR file directly, or from an unpacked directory
218      structure.</li>
219  <li>If the web application is running out of an unpacked directory
220      structure, the default servlet must recognize cases where the resource
221      has been updated through external means.</li>
222  </ul>
223
224</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
225        Copyright &copy; 1999-2008, Apache Software Foundation
226        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.