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