Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / fd5ee81fec460cbe9ad65f300b0faf1bf03c19bc / . / tomcat-uid / webapps / docs / funcspecs / fs-invoker.html
blob: 9a6419b6b2c3aa857dd1c0fab848751f245e47f4 [file] [log] [blame]
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications (6.0.39) - Invoker Servlet</title><meta name="author" content="Craig McClanahan"><style type="text/css" media="print">
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
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.39, Jan 27 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>Invoker 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>
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>Invoker Servlet</strong> is to allow a
14 web application to dynamically register new <em>servlet definitions</em>
15 that correspond with a <code>&lt;servlet&gt;</code> element in the
16 <code>/WEB-INF/web.xml</code> deployment descriptor, and execute
17 requests utilizing the new servlet definitions. From the perspective
18 of the newly registered servlets, all servlet lifecycle requirements
19 of the Servlet Specification (such as calling <code>init()</code> and
20 <code>destroy()</code> at the correct times) will be respected.</p>
21
22 </blockquote></td></tr></table>
23
24
25 <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>
26
27 <p>I do not know of any formal specification of the behavior of an
28 invoker servlet that is publicly available. Anyone know of one?</p>
29
30 </blockquote></td></tr></table>
31
32
33 <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>
34
35 <p>The implementation of this functionality shall conform to the
36 following requirements:</p>
37 <ul>
38 <li>Implemented as a servlet.</li>
39 <li>Exist in the <code>org.apache.catalina.servlets</code> package
40 so that it can be loaded by the Catalina class loader.</li>
41 <li>Implement the <code>org.apache.catalina.ContainerServlet</code>
42 interface, so that it gains knowledge of the <code>Wrapper</code>
43 that is responsible for itself and, therefore, access to other
44 internal Catalina components.</li>
45 <li>Support a configurable debugging detail level.</li>
46 <li>Log debugging and operational messages (suitably internationalized)
47 via the <code>getServletContext().log()</code> method.</li>
48 </ul>
49
50 </blockquote></td></tr></table>
51
52
53</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>
54
55
56 <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>
57
58 <p>The following environmental dependencies must be met in order for
59 the Invoker servlet to operate correctly:</p>
60 <ul>
61 <li>The invoker servlet must be registered in the application deployment
62 descriptor (or the default deployment descriptor in file
63 <code>$CATALINA_BASE/conf/web.xml</code>) using a "path mapped"
64 servlet mapping. The historical default mapping is to URL pattern
65 "<code>/servlet/*</code>", although the invoker servlet must operate
66 correctly with an arbitrary mapping.</li>
67 </ul>
68
69 </blockquote></td></tr></table>
70
71
72 <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>
73
74 <p>Correct operation of the invoker servlet depends on the following
75 specific features of the surrounding container:</p>
76 <ul>
77 <li>Correct support for the <code>ContainerServlet</code> interface,
78 including calling <code>setWrapper()</code> <strong>before</strong>
79 the <code>init()</code> method of the invoker servlet is called.</li>
80 <li>The web application class loader must be stored as the context
81 class loader of the request processing thread.</li>
82 </ul>
83
84 </blockquote></td></tr></table>
85
86
87</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>
88
89
90 <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>
91
92 <p>The following processing must be performed when the <code>init()</code>
93 method of the invoker servlet is called:</p>
94 <ul>
95 <li>Ensure that the container has called <code>setWrapper()</code>. If
96 not, throw a permanent <code>UnavailableException</code>.</li>
97 <li>Look up and cache the <code>Context</code> that corresponds to our
98 <code>Wrapper</code>. This is the component with which new servlet
99 definitions and mappings will be registered.</li>
100 </ul>
101
102 </blockquote></td></tr></table>
103
104
105 <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>
106
107 <p>On each request, the following processing shall be performed:</p>
108 <ol>
109 <li>Calculate the <code>{ServletPath}</code> for this request, either from
110 request attribute <code>javax.servlet.include.servlet_path</code> or
111 by calling <code>request.getServletPath()</code>.</li>
112 <li>Calculate the <code>{PathInfo}</code> for this request, either from
113 request attribute <code>javax.servlet.include.path_info</code> or
114 by calling <code>request.getPathInfo()</code>. If the calculated
115 <code>{PathInfo}</code> is null, return HTTP status 400
116 (bad request).</li>
117 <li>Parse the calculated <code>{PathInfo}</code> value as follows:
118 <ol>
119 <li>Ignore the leading slash character.</li>
120 <li>Accumulate characters up to the next '/' (if any) as the
121 <code>{ServletSelector}</code>.</li>
122 <li>If a '/' was encountered, accumulate all characters from that
123 slash (inclusive) to the end of the string as
124 <code>{PathRemainder}</code>. If no slash was encountered,
125 set <code>{PathRemainder}</code> to a zero-length string.</li>
126 </ol></li>
127 <li>Determine whether <code>{ServletSelector}</code> is the name of an
128 existing servlet definition, and process it as follows:
129 <ol>
130 <li>Ask our associated <code>Context</code> to find and return a
131 child <code>Wrapper</code> named <code>{ServletSelector}</code>.
132 </li>
133 <li>If there is no such child, skip to the next major step.</li>
134 <li>Register a new servlet mapping for this <code>Wrapper</code>,
135 using a URL pattern calculated as follows:
136 <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code>
137 + "/*"</li>
138 <li>Create a request dispatcher using a path calculated as follows:
139 <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code>
140 + <code>{PathRemainder}</code></li>
141 <li>Forward this request to the created request dispatcher, and
142 exit from this request.</li>
143 </ol></li>
144 <li>Assume that <code>{ServletSelector}</code> is the fully qualified
145 name of a Java class that implements <code>javax.servlet.Servlet</code>
146 and process it as follows:
147 <ol>
148 <li>Synthesize a new <code>{ServletName}</code> for the servlet
149 definition that will be created.</li>
150 <li>If there is already a child <code>Wrapper</code> associated with
151 this name, return HTTP status 500 (internal server error), because
152 a mapping should have already been created for this servlet.</li>
153 <li>Attempt to load a class named <code>{ServletSelector}</code> from
154 the web application class loader (i.e. the context class loader
155 for our current thread). If this fails, return HTTP status 404
156 (not found).</li>
157 <li>Instantiate an instance of this class. If an error occurs,
158 return HTTP status 404 (not found).</li>
159 <li>If this class does not implement the
160 <code>javax.servlet.Servlet</code> interface, return HTTP status
161 404 (not found).</li>
162 <li>Create and register a new <code>Wrapper</code> child with our
163 <code>Context</code>, under name <code>{ServletName}</code>.</li>
164 <li>Register a new servlet mapping for this <code>Wrapper</code>,
165 using a URL pattern calculated as follows:
166 <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code>
167 + "/*"</li>
168 <li>Create a request dispatcher using a path calculated as follows:
169 <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code>
170 + <code>{PathRemainder}</code></li>
171 <li>Forward this request to the created request dispatcher, and
172 exit from this request.</li>
173 </ol></li>
174 </ol>
175
176 </blockquote></td></tr></table>
177
178
179 <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>
180
181 <p>No specific processing is required when the <code>destroy()</code>
182 method is called:</p>
183
184 </blockquote></td></tr></table>
185
186
187</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>
188
189 <p>In addition the the assertions implied by the functionality requirements
190 listed above, the following additional assertions shall be tested to
191 validate the behavior of the invoker servlet:</p>
192 <ul>
193 <li>It is possible to access an existing servlet definition by name
194 through the invoker. The existing servlet definition can include
195 either a <code>&lt;servlet-class&gt;</code> or
196 <code>&lt;jsp-file&gt;</code> subelement.</li>
197 <li>When an existing servlet definition is accessed by name, the request
198 will be ultimately processed by the same servlet instance that would
199 have processed it had a mapping to that servlet definition been used
200 on the request directly.</li>
201 <li>It is possible to access an anonymous servlet by class name
202 through the invoker.</li>
203 <li>When an anonymous servlet is accessed, the servlet instance is processed
204 according to the lifecycle requirements of the Servlet Specification.
205 </li>
206 <li>When an anonymous servlet is accessed, the servlet instance receives
207 a <code>ServletConfig</code> instance with no servlet initialization
208 parameters.</li>
209 <li>It is possible to utilize the invoker servlet via a direct request.</li>
210 <li>It is possible to utilize the invoker servlet via a call to
211 <code>RequestDispatcher.forward()</code>, or the corresponding
212 <code>&lt;jsp:forward&gt;</code> tag in a JSP page.</li>
213 <li>It is possible to utilize the invoker servlet via a call to
214 <code>RequestDispatcher.include()</code>, or the corresponding
215 <code>&lt;jsp:include&gt;</code> tag in a JSP page.</li>
216 <li>It is possible to use any HTTP method (including GET and POST) that
217 is supported by the Servlet class that is ultimately executed.</li>
218 <li>The invoker servlet should never be asked to process a second or
219 subsequent request for the same <code>{ServletSelector}</code> (because
220 it will have registered an appropriate servlet mapping.</li>
221 </ul>
222
223</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>
224 Copyright &copy; 1999-2014, Apache Software Foundation
225 </em></font></div></td></tr></table></body></html>