source: nutchez-0.1/tomcat/webapps/docs/funcspecs/fs-invoker.html @ 180

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

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