You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2012/03/25 21:53:01 UTC
svn commit: r1305110 [3/10] - in /tomcat/site/trunk/docs/tomcat-3.3-doc: ./
appdev/ appdev/sample/ appdev/sample/etc/ appdev/sample/lib/
appdev/sample/src/ appdev/sample/web/ appdev/sample/web/images/ images/
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/faq
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/faq?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/faq (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/faq Sun Mar 25 19:52:59 2012
@@ -0,0 +1,352 @@
+Some Frequently Asked Questions (FAQ) on Tomcat
+-----------------------------------------------
+
+Q: I am getting a 404 Error, what does it mean?
+
+A: In simple terms, it means the server was not able to locate
+ the resource you requested. This can occur because of five
+ reasons:
+
+ * One, the URL you typed was wrong or has a typo.
+ * Two, the URL you requested could not be resolved with
+ the current "docBase". If you are trying to run your own
+ "web-application" please read the questions related to
+ "installing your own web-application" in this FAQ.
+ * Three, you're using JDK 1.1.x on a Windows platform. It's
+ a known bug (see Readme) that the server doesn't serve files
+ in this configuration. Use JDK 1.2.x instead.
+ * Four, on a Windows platform you have installed Tomcat in
+ a directory with a path part longer than 8 characters, e.g.
+ C:\Program Files\jakarta, and run the "startup" script from
+ a command tool after you have cd'd to the directory using
+ the short form of the name, e.g.
+
+ > cd C:\Progra~1\jakarta
+ > startup
+
+ If you cd using the long name it works fine, e.g.
+
+ > cd "C:\Program Files\jakarta"
+ > startup
+
+ * Five, on a Unix platform, you are attempting to access a file
+ that is a symbolic link.
+
+ The last three cases are caused by a test in
+ org.apache.tomcat.core.DefaultServlet to see whether the absolute
+ name of a file equals the canonical name. This test is intended
+ to solve a serious security problem, where mixed case or additional
+ characters in a file name can get Tomcat to serve the source
+ file instead of the processed file for JSP files on a Windows
+ platform. This test should be replaced with a solution that doesn't
+ have the above side effects.
+
+
+Q: I am getting a 500 Error, what does it mean?
+
+A: In simple terms, it means that there was some "Internal Server
+ Error" while processing your request. You need to study carefully
+ the trace at the server window to find out more about the error.
+
+ These errors can occur while translating your jsp source to a
+ servlet. These are translation-time errors and occur mostly because
+ of some syntax error in the jsp file or in the generated java file.
+ Please use the error-message at the server-window for debugging.
+
+ Errors can also occur at request-time. Again, the information about
+ specific problem/exception can be obtained by looking at the
+ server-side trace.
+
+
+Q: What do I need in my CLASSPATH?
+
+A: All you need is a correct version of JDK (1.1.x or 1.2).
+
+ Since the JSP engine also uses 'javac' it needs to be in the CLASSPATH.
+ If you are using JDK 1.1.x it will automatically be included. If
+ you are using JDK 1.2 you will need to set JAVA_HOME to the directory
+ where JDK is installed or alternately you can put "tools.jar" in your
+ CLASSPATH.
+
+ All other classes, jar files that are needed, are put by the startserver
+ script and you don't need to worry about them.
+
+
+Q: Where are the classes for JSPs and Servlets?
+
+A: lib classes:
+
+ tomcat.jar -- Executable jar for starting Tomcat
+ stop-tomcat.jar -- Executable jar for stopping Tomcat
+
+ lib/common classes
+
+ core_util.jar -- Utility classes used by apps and container
+ jasper-runtime.jar -- JSP Engine runtime classes
+ servlet.jar -- Public APIs for Servlets and JSP
+ tomcat_core.jar -- Tomcat web server core classes
+
+ lib/container classes
+
+ facade22.jar -- Servlet Engine classes.
+ jasper.jar -- JSP Engine translation classes
+ jaxp.jar -- Public APIs for XML parser interface
+ parser.jar -- Public XML parser reference implementation
+ tomcat_modules.jar -- Tomcat module classes
+ tomcat_util.jar -- Utility classes.
+ tomcat-startup.jar -- Tomcat start/stop classes
+
+
+Q: Can I combine these classes with other webservers?
+
+A: The JSP engine uses just the public portion of the Java Servlet 2.2
+ API. In theory, it could run on other servlet engines that support
+ the Servlet 2.2 API but we have not tested this release on any servlet
+ engine other than the one in Tomcat.
+
+
+Q: Where do I put my jsp sources and beans?
+
+A: If you just want to test JSPs without creating a separate web-application
+ you can use the default "example" application. If you want to create
+ a new web-application please read "how to install a new web-application?".
+
+ To use the default, put all your JSP source under /examples/jsp, either
+ in the same directory or under a new subdirectory of /examples/jsp (as
+ done in the included examples). Put all your beans (class files) under
+ /examples/WEB-INF/jsp/beans appropriately (as done for the included
+ beans). The startserver script will automatically add these classes to
+ the CLASSPATH at runtime.
+
+ If your server is already running, you will need to stop and restart it.
+ You can invoke your jsps using http://locahost:8080/examples/jsp/yours.jsp
+
+
+Q: What is a web-application? How can I install a new web-application?
+
+A: A web-application is a collection of resources such as jsps, servlets,
+ html files, images, etc. which are mapped to a specific "URI" prefix.
+
+ For example, all the resources related to baseball can be assembled
+ into a "baseball" directory and correspondingly all the requests that
+ start with "/baseball" can be mapped to this application.
+
+ A new application can be added to Tomcat by editing server.xml file.
+ To add "baseball" application you can make the following additions to
+ the file (at the appropriate place):
+
+ <Context path="/baseball" docBase="<baseball>"
+ debug="0" reloadable="true"/>
+
+ Replace <baseball> with an absolute path to the "baseball" directory,
+ or a relative path that is relative to the Tomcat home directory.
+
+ Please read "server.xml" for more details.
+
+ In addition, thanks to the AutoSetup interceptor, you may create or
+ copy the "baseball" directory to the "webapps" directory found under
+ the Tomcat home directory. When placed there, it will be served
+ automcatically with the default settings. A <Context ... /> entry
+ in the server.xml is not required unless you want to override the
+ default settings.
+
+ a) To install servlets within a web-application, you can do the following:
+
+ * Once a servlet has been compiled, it can be added to Tomcat by:
+ determine which "web application" context you'd like to add the servlet
+ to
+
+ add the servlet class file to the
+ WEBAPP/WEB-INF/classes directory
+
+ * In order to define a name and init params for the newly installed
+ servlet you need to also:
+
+ register the servlet with a <servlet> element in the
+ WEBAPP/WEB-INF/web.xml file
+
+ you can optionally map your servlet
+ to uri requests relative to the context
+ within it is located by adding a <servlet-mapping>
+ element in the WEBAPP/WEB-INF/web.xml
+ file
+
+ * And finally restart the server
+
+ You can access your new servlet via a URI similiar
+ to the following:
+
+ http://localhost:8080/WEBAPP/servlet/SERVLET-NAME
+
+ If you've associated a URI path mapping to your
+ servlet you can access it via a URI similiar to the
+ following:
+
+ http://localhost:8080/WEBAPP/foo.EXTENSION
+
+ - or -
+
+ http://localhost:8080/WEBAPP/MAP-PATH
+
+ where:
+
+ WEBAPP = the web-application URI name
+ SERVLET-NAME = the base name of a servlet
+ EXTENSION = a file time extension
+ MAP-PATH = associated URI MAP path
+
+ b) To install jsps and beans within a web-application you can do
+ the following:
+
+ * Put the jsp sources in any directory under /WEBAPP.
+
+ * Make sure that the compiled beans are in the CLASSPATH. This can
+ be done either by setting the CLASSPATH manually or by editing
+ the startup script.
+
+ * And finally restart the server.
+
+ You can invoke your new jsp via a URI similar to the following:
+
+ http://localhost:8080/WEBAPP/yourfile.jsp
+
+
+Q: How are the URIs mapped at the server?
+
+A: First, the web-server will match the beginning of the requested URI
+ against the prefixes of all contexts (web-applications). If no context
+ matches, it will use the default context instead.
+
+
+Q: What do different init parameters for the JSP engine mean?
+
+ * keepgenerated:
+ Whether to keep the generated java file or not. Can take a
+ value of true/false. If value is true, then the generated files
+ are kept, otherwise they are deleted. The default is true.
+
+ * scratchdir:
+ The work dir which will be created for storing all the
+ generated code. This can be set to any dir. That directory will be
+ created under the docbase.
+
+ * largefile:
+ Can take a value of true/false. If the file is really large then
+ all the static html is stored is a separate data file if the value
+ of this param is set to true. If true, this setting overrides
+ the mappedfile param. The default is false.
+
+ * mappedfile:
+ Can take a value of true/false. If you prefer each line of static
+ html be output separately, set this parameter true. If largefile
+ is set true, this param is ignored. If neither largefile or
+ mappedfile is true, the static html is output in blocks up to 32K
+ in length. The default is false.
+
+ * sendErrToClient:
+ Can take a value of true/false. If set to true then all
+ the compilation/parsing errors will be sent as part of the response
+ to the client. The default is false.
+
+ * ieClassId:
+ This is used with the plugin. This is a particular id that is
+ set to activate the plugin. The default value for IE 4 and 5 are
+ set as of now. This is for future use in case the classId for IE
+ changes in the future.
+
+ * classdebuginfo:
+ Whether to include debugging information in the class file. Can take
+ a value of true/false. If the value is true, then class debugging
+ information is included in the servlet class file when it is
+ compiled. The default is false.
+
+
+ To set any of these to a value other than the default you need to
+ explicitely define the JSP engine servlet and a mapping for the
+ .jps extension in WEBAPP/WEB-INF/web.xml, e.g.
+
+ <servlet>
+ <servlet-name>
+ jsp
+ </servlet-name>
+ <servlet-class>
+ org.apache.jasper.servlet.JspServlet
+ </servlet-class>
+ <init-param>
+ <param-name>
+ keepgenerated
+ </param-name>
+ <param-value>
+ true
+ </param-value>
+ </init-param>
+ <init-param>
+ <param-name>
+ sendErrToClient
+ </param-name>
+ <param-value>
+ true
+ </param-value>
+ </init-param>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>
+ jsp
+ </servlet-name>
+ <url-pattern>
+ *.jsp
+ </url-pattern>
+ </servlet-mapping>
+
+
+Q. I have a bean with a property whose second letter is capitalized.
+ Why won't my JSP page that uses this bean compile?
+
+A. This may not happen often, but can be difficult to determine why.
+ The reason is found in the Java Beans specification, where in section
+ "8.8 Capitalization of inferred names" it states:
+
+ Thus when we extract a property or event name from the middle of an
+ existing Java name, we normally convert the first character to lower
+ case. However to support the occasional use of all upper-case names,
+ we check if the first two characters of the name are both upper case
+ and if so leave it alone.
+
+ This means that if you have a bean with a setter method of "setXLoc",
+ then the inferred property is "XLoc", not "xLoc". If you used this
+ bean in a JSP page and you tried to use "xLoc" as the property, it
+ would not compile. Using "XLoc" as the property would succeed.
+
+ If you insist on using "xLoc" on the JSP page, you can make this possible
+ by creating a BeanInfo class for the bean. The following is an example
+ of such a BeanInfo class for a simple bean called Coordinate. It
+ explicitly defines the properties of the bean to be "xLoc" and "yLoc".
+
+ import java.beans.*;
+ public class CoordinateBeanInfo extends SimpleBeanInfo
+ {
+ private final static Class beanClass = Coordinate.class;
+
+ public PropertyDescriptor[] getPropertyDescriptors()
+ {
+ try {
+ PropertyDescriptor xLocDesc =
+ new PropertyDescriptor("xLoc",beanClass,"getXLoc","setXLoc");
+ PropertyDescriptor yLocDesc =
+ new PropertyDescriptor("yLoc",beanClass,"getYLoc","setYLoc");
+
+ PropertyDescriptor [] pdv = { xLocDesc, yLocDesc };
+ return pdv;
+ } catch (IntrospectionException e) {
+ throw new Error(e.toString());
+ }
+ }
+ }
+
+
+Q. Whey I run Tomcat, my JVM gives me segmentation fault of segmentation
+ violation errors. Should I be reporting a Tomcat bug?
+
+A. No. This is surely a JVM problem. Possible solutions are to switch to
+ another JVM, apply relevant patches to your OS or find out if there are
+ any particular environmental settings required.
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/images/banner.gif
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/images/banner.gif?rev=1305110&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/images/banner.gif
------------------------------------------------------------------------------
svn:mime-type = image/gif
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/images/tomcat.gif
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/images/tomcat.gif?rev=1305110&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/images/tomcat.gif
------------------------------------------------------------------------------
svn:mime-type = image/gif
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/in-process-howto.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/in-process-howto.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/in-process-howto.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/in-process-howto.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,219 @@
+<html>
+
+<head>
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed 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.
+-->
+<title>In-Process Howto</title>
+<link rel="stylesheet" href="style.css">
+</head>
+
+<body>
+
+<h1>In-Process HowTo</h1>
+
+<p>By Gal Shachor <shachor@il.ibm.com></p>
+
+<p>This document explains how to set up Netscape/IIS web servers so that
+Tomcat will run inside the web server process. <b>It assumes that you have
+already followed the instructions in the web server specific howto and
+configured it to use Tomcat as an out of process servlet container.</b>
+</p>
+
+<p>
+Normally Tomcat is running in one process and the web servers runs in another;
+this however requires the web server to communicate using some IPC mechanism
+such as TCP/IP. <br>
+
+When Tomcat is running inside the web server process, requests for servlet
+execution are passed using JNI (and performance improves).
+</p>
+
+<p>
+<b>Note:</b> Running the JVM inside the web server is not always a good
+idea. Sure it gives the best performance, but is lacks the stability
+associated with the out of process mode of operation. When deciding to run
+in-process make sure that top speed is what you need.
+</p>
+
+<h2>Document Conventions and Assumptions</h2>
+
+<p><tomcat_home> is the root directory of tomcat. Your Tomcat
+installation should have the following subdirectories:
+
+<ol>
+ <li><tomcat_home>\conf - Where you can place various configuration files</li>
+ <li><tomcat_home>\webapps - Containing example applications </li>
+ <li><tomcat_home>\bin - Where you place web server plugins </li>
+</ol>
+
+<p>In all the examples in this document <tomcat_home> will be d:\tomcat.</p>
+
+<p>A <tt>worker</tt> is defined to be a Tomcat process that accepts work from
+the web server.</p>
+
+<h2>Supported Configuration</h2>
+
+<p>For in-process operation you will have to use the Netscape/IIS
+redirectors, look at their supported configuration sections.
+
+<p>The in-process adapter was tested using JDK1.1.7b/IBM's JDK 1.1.7/JDK1.2.2/JDK
+ 1.3.0/JDK 1.3.1</p>
+
+<h2>Installation</h2>
+
+<p>The in-process adapter is not part of the "official" build of Jakarta, You
+ can obtain the code and binaries needed for it by accessing <a href="http://jakarta.apache.org/builds/tomcat/release/v3.3/bin/win32/i386/">http://jakarta.apache.org/builds/tomcat/release/v3.3/bin/win32/i386/</a>.
+ The adapter related file is <tt>jni_connect.dll</tt>.</p>
+
+<p>The Tomcat JNI adapter requires the following actions:
+
+<ol>
+ <li>Putting jni_connect.dll in the bin directory - jni_connect.dll is used
+ to issue callbacks from Tomcat back to the web server, either obtain a
+ pre-built DLL or build it yourself (see the build section).</li>
+ <li>Update <tt>workers.properties</tt> and add the JNI worker - The JNI worker
+ needs several configuration items, you will need to add those to the worker
+ properties file.</li>
+ <li>Updating server.xml - You need to instruct Tomcat to use the JNI connection
+ handlers.</li>
+ <li>Directing context(s) to the in-process Tomcat - You need to instruct
+ the redirector to send work to the in-process Tomcat</li>
+ <li>Restart your server (so changes will take effect)</li>
+</ol>
+
+
+<h3>Putting jni_connect.dll in the bin directory</h3>
+
+<p> Put jni_connect.dll inside <tt><tomcat_home>\bin\native</tt></p>
+
+<h3>Update worker.properties and add the JNI worker</h3>
+<p> You should provide the JNI worker with several settings, some are mandatory
+ and some are an option... </p>
+<ol>
+ <li>You <b>should</b> define a JNI worker.<br>
+ Set the <tt>worker.list</tt> property to point on a worker named <tt>inprocess</tt>:
+ <tt>worker.list=inprocess</tt><br>
+ Announce that the worker named <tt>jni</tt> is of type <tt>jni</tt>: <tt>worker.inprocess.type=jni</tt>
+ <li>You <b>should</b> set a classpath to be use by the in-process Tomcat.<br>
+ To set the classpath use the <tt>worker.name.class_path</tt> property, for
+ example:<br>
+ <tt>worker.inprocess.class_path=d:\tomcat\lib\tomcat.jar</tt><br>
+ <b>Note</b>: Do not forget to include the JDK's tools.jar in your classpath.
+ </li>
+ <li>You <b>should</b> provide a full path to the dll implementing the JVM. For
+ JDK1.1.x it is javai.dll, for JDK1.2.x and up it is jvm.dll. For example:<br>
+ <tt>worker.inprocess.jvm_lib=d:\sdk\jdk1.2.2\jre\bin\classic\jvm.dll</tt>
+ </li>
+ <li>You <b>should</b> provide command line options for Tomcat; you must provide
+ a -config option to specify your JNI configured server.xml. For example:<br>
+ <tt>worker.inprocess.cmd_line=start</tt></li>
+ <li>You can specify additional Java system properties. For example:<br>
+ <tt>worker.inprocess.sysprops=java.compiler=NONE</tt> </li>
+ <li>You can specify files to by used by the JVM for stdout and stderr. For example:<br>
+ <tt>worker.inprocess.stdout=d:\tomcat\logs\inprocess.stdout</tt><br>
+ <tt>worker.inprocess.stderr=d:\tomcat\logs\inprocess.stderr</tt> </li>
+ <li>You can specify additional PATH, to be use when loading dlls (useful when
+ you are using native code). For example:<br>
+ <tt>worker.inprocess.ld_path=d:\SQLLIB\bin</tt><br>
+ <tt>worker.inprocess.ld_path=d:\my\native\code</tt> </li>
+</ol>
+You can find a preconfigured worker file (<tt>workers.properties</tt>) under <tt>tomcat/conf/jk</tt>.
+you should only need to change the variable <tt>workers.tomcat_home</tt> and <tt>workerks.java_home</tt>
+and modify the <tt>workers.list</tt> line adding the <tt>inprocess</tt> preconfigured
+worker to activate jni.
+<h3>Update server.xml</h3>
+<p> By default Tomcat reads the file <tt><tomcat_home>\conf\server.xml</tt>.
+ This file defines among other things the contexts and connectors used by Tomcat.
+ In order to work in-process you will have to add the following line :</p>
+<p><tt><JniConnector/></tt> </p>
+<p>This line adds a JNI connector to Tomcat. </p>
+The default <tt>server.xml</tt> under <tt>jakarta-tomcat/conf</tt> already contains
+the needed configurations, the JNI Connector will not be active if tomcat is not
+started by JNI.
+<h3>Redirect contexts to the JNI workers</h3>
+<p>You will need to select the contexts that you wish to serve using your
+jni worker.</p>
+
+<p>On Netscape you can do that by modifying the lines in the servlet
+configuration object to reflect redirect work to the new JNI worker.
+For example:
+<pre>
+ <Object name=servlet>
+ ObjectType fn=force-type type=text/plain
+ Service fn="jk_service" worker="inprocess"
+ </Object>
+</pre>
+<p></p>
+
+<p>On IIS you will have to modify your <tt>uriworkermap.propeties</tt> file to
+ mount contexts to the JNI worker. For example:</p>
+
+<tt>/examples/*=inprocess</tt>
+<p>When you are done restart your server. That's all, you should now be able
+to execute Tomcat in-process.</p>
+
+<h2>Building the JNI connector dll</h2>
+
+<p>The JNI connector was developed using Visual C++ Ver.6.0, so having this
+environment is a prereq if you want to perform a custom build. You will also
+need a JDK installation (the jre is not good enough) in order to use
+the JDK's include files.</p>
+
+<p>The steps that you need to take are:
+
+<ol>
+ <li>Change directory to the JNI connector source directory.</li>
+ <li>Make sure that the environment variable <tt>JAVA_HOME</tt> is set and
+ points to your JDK installation</li>
+ <li>Execute the following command:<br>
+ <tt>MSDEV jni_connect.dsp /MAKE ALL</tt><br>
+ If msdev is not in your path, enter the full path to msdev.exe</li>
+</ol>
+
+<p>This will build both release and debug versions of the JNI connector. </p>
+
+<p>An alternative will be to open the jni_connect workspace file
+(jni_connect.dsw) in msdev and build it using the build menu.</p>
+
+<h2>How does it work? </h2>
+Working in-process requires both the server redirector
+(IIS-Tomcat/Netscape-Tomcat) and the in-process connector. The server
+redirector can direct work to different workers based on their name; now
+that we added the JNI worker the server redirector can forward it work...
+
+The basic operation is this:
+<ol>
+ <li>During the initialization the server redirector starts the JNI worker.</li>
+ <li>Upon startup the JNI worker creates a JVM inside the web server and
+ starts Tomcat in it.</li>
+ <li>For each in-coming request for a servlet, the server redirector will
+ check which worker is responsible for the specific context. If this worker
+ is the JNI worker then the request is assigned to it.</li>
+ <li>The JNI worker attaches to the JVM and submits the request into the
+ Tomcat engine (using the JNIEndpointConnector). Tomcat will then execute
+ the request.</li>
+ <li>The server redirector collects the response from the JNI worker and
+ returns it to the browser.</li>
+</ol>
+
+
+<h2>Feedback</h2>
+
+<p>Please send feedback, bug report or any additional information to
+<tt>tomcat-dev@jakarta.apache.org</tt>.
+</p>
+</body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/in-process-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/index.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/index.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/index.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/index.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,124 @@
+
+<html>
+ <head>
+ <!-- $Id: index.html,v 1.14 2004/03/03 06:16:43 billbarker Exp $ -->
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed 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.
+-->
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <link rel="stylesheet" href="style.css">
+ <title>Tomcat Documentation</title>
+ </head>
+ <body link="#0000ff" vlink="#800080">
+ <!-- Banner element, all hail the Project! -->
+ <table border="0" width="100%" cellspacing="0" cellpadding="0">
+ <tr>
+ <td width="50%">
+ <p align="left">
+ <a href="http://jakarta.apache.org/index.html">
+ <img src="images/banner.gif"
+ width="505"
+ height="48"
+ alt="The Jakarta Project"
+ border="0"></a>
+ </td>
+ <td width="50%">
+ <p align="right"><img border="0" src="images/tomcat.gif" width="100" height="71" alt="The mighty Tomcat - Meow!"></p>
+ </td>
+ </tr>
+ </table>
+
+<h1>Tomcat Documentation</h1>
+<ul>
+
+<li> <a href="readme">Tomcat 3.3 Release Notes</a></li>
+<li> <a href="readme-3.3.1">Tomcat 3.3.1 Release Notes</a></li>
+<li> <a href="readme-3.3.2">Tomcat 3.3.2 Release Notes</a><br> </li>
+
+<li> Using Tomcat
+ <ul>
+ <li> <A HREF="tomcat-ug.html">Tomcat User's Guide</A> - How to install,
+ configure, and deploy Tomcat.</li>
+ <li><a href="serverxml.html">Server.xml Configuration in Tomcat 3.3</a> -
+ Details about configuring the server.xml file.</li>
+ <li><a href="JDBCRealm-howto.html">JDBC Realms</a> - Use a set of
+ configurable tables inside an RDBMS to store validation data.</li>
+ <li><a href="tomcat-security.html">Using the Java SecurityManager with Tomcat</a>
+ - Use of a SecurityManager while running Tomcat can protect your server
+ from Trojan servlets, JSPs, JSP beans, and tag libraries.</li>
+ <li><a href="Tomcat-Workers-HowTo.html">Tomcat Workers</a> - How to work
+ with "Tomcat workers," and the worker.properties file.<br>
+ </li>
+ <li><a href="tomcat-ssl-howto.html">Tomcat and SSL</a> - Using SSL with
+ Tomcat 3.3, including configuring web connectors.<br>
+ </li>
+ </ul>
+</li>
+<li>Using Tomcat in Windows - documentation specific to running Tomcat in a
+ Win32 environment
+ <ul>
+ <li><a href="NT-Service-howto.html">The Jakarta NT Service</a> - Wrapping an
+ NT Service around Tomcat.</li>
+ <li><a href="in-process-howto.html">In-process HOWTO</a> - How to set up
+ Netscape/IIS web servers so that Tomcat will run inside the web server
+ process.<br>
+ </li>
+ </ul>
+</li>
+<li>Integrating Tomcat with a Web Server
+ <ul>
+ <li><a href="jk2/">JK Documentation</a> - How to setup and configure
+ <code>mod_jk</code> and <code>mod_jk2</code> for use with Tomcat.</li>
+ <li><a href="tomcat-apache-howto.html">Apache</a>
+ <ul>
+ <li><a href="mod_jk-howto.html">mod_jk</a> - Installation and
+ configuration</li>
+ </ul>
+ </li>
+ <li><a href="tomcat-iis-howto.html">Internet Information Server</a></li>
+ <li><a href="tomcat-netscape-howto.html">Netscape<br>
+ </a> </li>
+ </ul>
+</li>
+<li> <A HREF="appdev/contents.html">Application Development manual</A> - The
+ steps required to build and deploy web applications within Tomcat ( somewhat
+ out of date).<br>
+</li>
+<li><a href="internal.html">Tomcat Internals</a> - The design of Tomcat 3.x and
+ the reasons behind it.<br>
+ </li>
+<li>Other Resources
+ <ul>
+ <li><a href="faq">Frequently Asked Questions</a></li>
+ <li><a href="http://jakarta.apache.org/getinvolved/mail.html">Mailing lists<br>
+ </a> </li>
+ </ul>
+</li>
+
+</ul>
+
+ <table width="100%" border="0" cellpadding="10" cellspacing="0">
+ <tr>
+ <td>
+ <p class="fineprint">
+ Copyright ©1999-2000 The Apache Software Foundation<br>
+ <a href="http://jakarta.apache.org/legal.html">Legal Stuff They Make Us Say</a><br>
+ <a href="http://jakarta.apache.org/contact.html">Contact Information</a> </p>
+ </td>
+ </tr>
+ </table>
+
+ </body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/internal.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/internal.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/internal.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/internal.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,824 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed 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.
+-->
+ <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
+ <TITLE>Internal Tomcat</TITLE>
+ <META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Linux)">
+ <META NAME="CREATED" CONTENT="20000906;23560700">
+ <META NAME="CHANGEDBY" CONTENT="Costin Manolache">
+ <META NAME="CHANGED" CONTENT="20000912;12453100">
+ <STYLE>
+ <!--
+ TH P { color: #000000; font-family: "Times New Roman", "Times", serif; font-style: normal }
+ TD P { color: #000000; font-family: "Times New Roman", "Times", serif; font-style: normal }
+ H2 { color: #0033cc; font-family: "Arial", "Helvetica", sans-serif; font-style: normal }
+ H3 { color: #0033cc; font-family: "Arial", "Helvetica", sans-serif; font-style: normal; font-weight: medium }
+ P { color: #000000; font-family: "Times New Roman", "Times", serif; font-style: normal }
+ DD { color: #000000 }
+ DT { color: #000000 }
+ -->
+ </STYLE>
+</HEAD>
+<BODY TEXT="#000000" BGCOLOR="#ffffff">
+<H2>1. Introduction</H2>
+<P>This document tries to document the design of tomcat-3 and the
+reasons behind this. Tomcat is the result of a long evolution, with
+many people with different perspectives contributing code and ideas.
+Most of the code in tomcat was rewritten 2 or 3 times in the last
+year, with many experiments and prototypes developed off-line. It is
+important to distinguish between the actual patterns and ideas and
+the implementation - the later will change and did changed a lot.</P>
+<HR>
+<H2>2. Goals</H2>
+<UL>
+ <LI><P><B>Correctness</B>. Implement the Servlet and JSP
+ specification as accurate as possible.
+ </P>
+ <LI><P><B>Code quality</B> and clarity must match Apache's
+ standards. We also want a bit more comments and documentation :-)</P>
+ <LI><P><B>Security</B>. User applications will run in applet-like
+ sandboxes, and shouldn't be able to get out of the box. Servlet API
+ is the only API ( I am aware of ) that can provide this kind of
+ feature. That means an ISP should be able to let its users to deploy
+ WARs without having to worry about the system security or about the
+ possible interference between the users. It also means companies can
+ use JSPs and applications without having to review them for security
+ flaws ( and in complex web servers this is extremely difficult and
+ expensive ).
+ </P>
+ <LI><P><B>Embedability</B>. The code must be embedable, acting as a
+ servlet container for various applications. There are 2 services
+ tomcat provides - servlet services for Web servers ( like Apache )
+ and http and servlet services for standalone applications. Tomcat
+ should be usable as a component providing web services for
+ applications ( in the form of the standalone server or in
+ association with a web server), allowing applications to provide
+ servlet-based interfaces. For example it should be possible to
+ create a web-based configuration for an IDE by just starting tomcat
+ and using servlets that access the application's internal APIs. We
+ also want to embed tomcat in existing web servers, providing generic
+ web programming using servlet and JSP for Apache, etc.</P>
+</UL>
+<UL>
+ <LI><P><B>Performance</B>. As in Apache, the performance is less
+ important than code quality and must come from using the right
+ algorithms and data structures, not by low-level hacking. We want to
+ focus on the critical path and be sure we add the smallest overhead
+ possible, while making sure that only applications that make use of
+ special features are paying the price for it.</P>
+ <LI><P><B>Integration</B> with the current Web infrastructure. Web
+ applications will run on the web, and we want to make sure we do can
+ work with existing code and provide a smooth transition. We want to
+ take advantage of the existing optimizations and maturity of web
+ servers like apache, and make sure most of the modules and
+ extensions work well with tomcat.</P>
+ <LI><P><B>Modular structure</B>. The core should be small and as
+ simple as possible ( but not simpler :-), and the most functionality
+ must be provided in modules. By choosing the right modules we can
+ use it in toasters or big servers. Multiple versions of the same
+ module can be optimized for various VMs or special environments.
+ </P>
+ <LI><P><B>Reusable components</B> wherever possible. Functionality
+ that is generic enough should have minimal dependencies on tomcat
+ core. This even more visible starting with tomcat3.3, where we tried
+ to clearly identify the "modules" and build a collection
+ of general-purpose and independent components that can be used in
+ any other project without any relation with tomcat. Having a
+ component that is reviewed, tested and enhanced in more than one
+ project is worth the price of slightly looser integration, and the
+ facade pattern helps integrating independent components without
+ changing their interfaces ( making them dependent on tomcat).</P>
+</UL>
+<HR>
+<H2>3. Design Patterns</H2>
+<H3>Chain of responsibility</H3>
+<P>"Avoids coupling the sender of a request to its receiver by
+giving more than one object a chacne to handle it". In our case
+the servlet API implementation and the request processing ( mapping,
+auth, etc) are handler by the Interceptors. The operation is chained
+and passed along until one interceptor handles it.</P>
+<P>Interceptors are the mechanism used to implement and extend
+tomcat. It avoids coupling the sender of the request ( tomcat core,
+servlets ) with the actual receiver ( one of the modules handling the
+requested operation ). The module that actually provide the
+implementation is not known.
+</P>
+<P>There are 2 important reasons for choosing this pattern for
+tomcat.</P>
+<P>The exact same pattern is used in IIS in the form of filters, NES
+as SAFs and Apache as modules and hooks. This is the main tool of
+extending those servers. It also allows the integration between
+tomcat and web servers ( since the same pattern is used tomcat, will
+be able to reuse existing code and provide server extensions ). The
+fact that this works well in existing high performance and the
+extensibility it provides was a very strong argument.</P>
+<P>We also want to integrate tomcat with applications and external
+packages that may provide various services. This will be a deployment
+decision, and the core and basic modules shouldn't depend on any
+particular handler implementation. An example is authentication - the
+service can be provided by the default tomcat interceptor that use a
+static xml file, by the native web server, by JAAS, or a private API
+if tomcat is embedded in applications.</P>
+<P>The implementation consists in Interceptors and Events ( possibly
+in 3.3 or 3.4 ). See also Strategy.
+</P>
+<H3>Strategy</H3>
+<P>"Define a family of algorithms, encapsulate each one and make
+them interchangeable".
+</P>
+<P>This allows an easy evolution of tomcat and simplifies the
+development in an open source environment. We were able to isolate
+the original implementation of tomcat 3.0 and re-implement individual
+components while maintaining the overall stability. We started with a
+code that was very hard to read because of many incremental changes
+and fixes, but was extremely stable and very well tested. By using
+this pattern we moved the ugly algorithm in a module and then
+provided better implementations.
+</P>
+<P>Separating the actual algorithm from the code that calls it
+allowed us to focus on what was important for the problem, and remove
+the dependencies.
+</P>
+<P>It allows us to provide alternative implementations for each
+service ( we have 2-3 authentication modules, 3-4 mapping
+interceptors were developed and expect more improvements) and decide
+on a particular implementation based on stability and performance,
+after the code is ready.
+</P>
+<P>We can choose a set of components that are best tuned for our
+application - for example we can use a mapping interceptor ( that
+parses and matches the request against a set of mapping rules ) that
+is optimized for memory usage or one tuned for speed. An ISP will
+choose a specialized algorithms that is able to deal with large
+number of web applications - for example by loading the mappings for
+a certain application only when needed ( and maintaining a cache of
+mappings for frequent access)</P>
+<P>One particular application is the use of existing algorithms
+implemented in native servers. Most web servers have highly tuned
+algorithms ( not a surprise ), and this seems great for lazy
+programmers - we can get very fast code without too much work.
+</P>
+<P>This is implemented in RequestInterceptors - see also Chain Of
+Responsibility.
+</P>
+<H3>Observer</H3>
+<P>This pattern defines a one-to-many dependency between core objects
+( Context, ContextManager ) and modules ( Interceptors). When the
+core object change it's state all the dependents will be notified and
+updated automatically.</P>
+<P>Tomcat state changes at runtime - and all the modules interested
+in a particular state can be notified and change their internal (
+possibly optimized ) data structures. That means the core can be kept
+simple, without advanced data structures, while modules can use Trees
+( JDK1.2 collections) or other complex representations.
+</P>
+<P>It also enable us to keep the core compatible with JDK1.1, while
+taking advantage of all "modern" features ( this works
+together with the Strategy pattern in separating the algorithm/data
+from the caller)</P>
+<P>It also allows a simpler core, without any optimization that may
+affect the code readability. The complex structures are in modules -
+the Observer will keep the information in sync.
+</P>
+<P>The implementation is done in ContextInterceptor ( that will
+probably be replaced by a more standard Event/Listener model in 3.3
+or 3.4). ContextManager, Context, Container will send notifications
+each time their state changes, and interceptors will alter their
+internal state.</P>
+<H3>Adapter</H3>
+<P>It converts the interfaces of a class into the interface
+tomcat.core expects. This is the main enabler for "integration
+with other applications" requirement.</P>
+<P>Adapter is very important for allowing tomcat to reuse external
+APIs and modules, without requiring them to change and without
+changing tomcat ( and making it dependent of a particular
+API/application). It allows us to use multiple APIs for various tasks
+- for example authentication can be done using JAAS, J2EE APIs, other
+proprietary APIs or using the web server. Instead of hard-coding a
+Realm interface and attempting to fit everything under it ( JAAS is a
+good candidate for such a "generic auth API ", but it's too
+much for simple cases ) we just build adapters for whatever API we
+have to integrate with.</P>
+<P>This pattern is also used in integration with the web server, with
+Request, Response, Container acting as adapters for the equivalent
+objects in web servers.</P>
+<P>This is used in conjunction with "Chain of responsibility"
+and "Strategy" to enable "lazy programming" ( or
+reuse of existing APIs :-).</P>
+<P>A number of Interceptors are using Adapter for their
+implementation. J2EEInterceptor is a very good example of adapter -
+on one side it knows tomcat interface ( Interceptor), and the other
+side knows J2EE interfaces.
+</P>
+<H3>Proxy</H3>
+<P>"It provides a "surrogate" or placeholder for
+another object to control access to it". This is the main tool
+in isolating the tomcat internals from servlets and user
+applications. While some form of class loader hacks can also be used
+to enhance that, this pattern is a very clean mechanism and combined
+with the Facade provides many other advantages.
+</P>
+<P>It also has an important role in performance, by allowing us to
+delay expensive operations until they are needed ( String creation )
+and use the more efficient interface in core ( see also Facade).
+</P>
+<P>The Servlet API was designed for easy to use and security for
+application developers, while the constraints and requirements in
+tomcat.core are very different.</P>
+<P>This pattern is used in JDK1.3 to create a type-safe
+implementation of interfaces ( no down-casting allowed ).</P>
+<P><B>Why?</B> Security was the original reason, but this pattern is
+at the core of many performance optimizations and will allow a large
+number of features.
+</P>
+<H3>Facade</H3>
+<P>Converts the interface of a class into another. In particular,
+this is used to present web applications with the (right) servlet
+API, while using more efficient interfaces for the core.</P>
+<P>The "facade" name was used ( wrongly ) in many security
+discussions and in all interfaces, in fact "Proxy" is
+responsible for security while facade is important for performance
+and to implement the servlet API on top of a set of internal APIs.
+For example HttpServletRequest combines access to a number of core
+interfaces.</P>
+<P><B>Why? </B><SPAN STYLE="font-weight: medium">The servlet API has
+certain goals and requirement that are oriented toward the servlet
+developer. The web server and tomcat.core have different
+requirements, and by using the right API we can provide a number of
+optimizations. For example it is possible to avoid String over-use,
+to use more specialized components, and to use adapters for the
+(native)</SPAN> web servers.</P>
+<P>Another very important benefit of Facade consist in insuring an
+independence between the current servlet API ( that change with a
+certain speed ) and the internal representation, and also allows one
+tomcat instance to support multiple "profiles" of servlet
+API. For example the transition between servlet 2.2 and 2.3 can be
+smooth, by allowing 2.2 webapps to run in the same container. This
+way the users will not have to rewrite ( or recompile ) all their
+applications every time the spec changes. This can allow tomcat 3.3
+to support both servlet 2.2 and servlet 2.3 APIs.</P>
+<HR>
+<H2>4. Main Components ( tomcat.core )</H2>
+<H3>Request/Response</H3>
+<P>This is the tomcat representation of a request. It acts as an
+"Adapter" for the underlying application's representation -
+in the case of a web server it is the java representation of
+(request_rec *) for example, if tomcat is embedded in a non-web
+application it represent the application's notion of request.</P>
+<P>This is a passive object, with all operations delegated to
+modules. It is important to make as much as possible "lazy"
+evaluations, and keeps the code very simple.</P>
+<P>The objects are not a replication of HttpServletRequest and
+HttpServletResponse. The javax interfaces are designed for web
+application developers, while core have different needs. It would be
+very difficult to implement HttpServletRequest as an adapter for
+request_rec, and it would have a big impact on performance to be
+restricted to the String-based representation ( that is required for
+applications - security reasons, etc).</P>
+<P>For example, in tomcat 3.2 we started to expose the internal
+buffers and we'll make more use of this - instead of using the
+Stream/Writer interfaces, core components will have direct control
+over the buffering and char/byte translation.
+</P>
+<P>XXX It may be a good idea for the core to use concepts similar
+with web servers - i.e. only Request, and add Connection to represent
+the http connection data. The only reason to have Request/Response is
+to match the servlet model, but the role of core is to match the
+model used by the web server. A picture would be great.
+</P>
+<H3>OutputBuffer</H3>
+<P>The idea is to have full control over tomcat buffering and over
+char/byte translation, as this is one of the most expensive
+operations ( according to empirical tests ). It should allow to plug
+external byte/char convertors. As we know, multiple copy from buffer
+to buffer proved to be an important factor in many systems. It
+doesn't show up in tomcat 3.2 because other factors are too big, but
+as we approach the limits it will be one of the most important issue.</P>
+<P>An important feature will be the integration of jasper and other
+template systems, where "static" text can be delivered to
+the server directly, without intermediary buffers, and the binary
+representation ( encoding) can be pre-computed.</P>
+<H3>MessageBytes</H3>
+<P>This is a very special and important component of tomcat3. The
+first problem it tried to solve was the conversion from byte to
+chars. The charset is known very late ( either when Content-Type
+header is parsed or even later, when the user sets it in servlet
+2.3), and converting the received bytes to Strings can't be done
+(corectly ) until the encoding is determined.</P>
+<P>MessageBytes have another benefit - it's a great mechanism to
+avoid Garbage Collection costs. Most of the time the user will not
+access all the headers, and probably neither most of the request
+information ( url components, etc). That means a "HelloWorld"
+servlet ( or any servlet that just display some info) will require no
+String allocations when MessageBytes are used - as oposed to 30-40
+Strings allocated ( and GC ) before.</P>
+<P>Another ( probably less visible ) benefit is the parsing of the
+request. Parsing using String proved to lead to inefficient code -
+Java provides general purpose utilities like StringTokenizer or
+substring() / indexOf(), but they are designed as "general
+purpose", with different goals in mind. The parsing code in
+tomcat 3.0 used those mechanisms and that resulted in 100+ String
+allocations per request.</P>
+<P>Note that String is a very important class in Java - it have the
+special characteristic of beeing "imutable". That has big
+implications from a security point of view, and most Servlet API
+methods are using String as result type/parameter. On the other side
+String is extremely expensive for server-side operation - it can't be
+recycled. See also the discussion on GarbageCollection and memory.
+</P>
+<H3>Context</H3>
+<P>Context is the representation of a web application. It have all
+the properties that are definable in web.xml and server.xml.
+</P>
+<P>The current implementation is complex and has much more than that
+- this have to change.</P>
+<P>The context is associated with a Request after the contextMap()
+callback completes. By default the mapping interceptor ( SimpleMapper
+in the default case ) will implement this hook, but other
+interceptors can provide extra functionality ( support for ~user,
+dynamic addition of contexts when the first request is made, etc )
+</P>
+<H3>Container</H3>
+<P>It represent a group of URLs sharing a common set of properties.
+It's analog with per_dir configuration in apache. The "standard"
+properties in servlet spec are the handler ( specified in servlet
+mappings) and the security properties.
+</P>
+<P>The Container is associated with a Request after the requestMap()
+hook completes. SimpleMapper is the "core"<BR>implementation
+of this hook, providing support for prefix, exact and extension
+mappings. Other interceptors can provide optimized mappings for
+particular subsets ( like JspIntercepor ) or implement custom mapping
+schemes.
+</P>
+<P>This is a very important operation ( it should be the most
+expensive part of the processing - unfortunately we still have to
+eliminate few other hotspots before this will happen ). We exepect
+alternate implementations using more advanced data structures and
+alghoritms ( Trees, etc ). See also the discussion on "evolution".
+</P>
+<P>In tomcat 3.3 it is possible to specify per context and container
+interceptors - after the mapping, tomcat will know what is the
+container where the request belongs and can invoke specialized
+interceptors defined only for that particular set of URLs. This is
+similar with what all other web servers provide ( the order is
+similar with NES).
+</P>
+<H3>ContextManager</H3>
+<P>Main entry point for tomcat execution. It coordinates the activity
+of modules.
+</P>
+<P>In tomcat, the application embedding tomcat ( web server, generic
+application, tomcat standalone server) have control over execution.
+Embedding tomcat requires an adapter that will construct the
+Request/Response adapters and use ContextManager to process the
+request.</P>
+<P><BR><BR>
+</P>
+<P>XXX Probably a better name would be Server, or TomcatContainer.
+</P>
+<H3>Interceptor</H3>
+<P>The interceptors represents the building blocks and extension
+mechansim for tomcat. Most of tomcat functionality is implemented
+using modules. Modules operate on tomcat's core objects and can hook
+in and extend tomcat. They are designed around "Chain of
+Responsibility" and "Strategy" patterns, and inspired
+from Apache hooks, with influences from ISAPI ( filters ) and NSAPI (
+saf) . As you know most of Apache ( including the core ) is
+implemented using a simple hook mechanism.
+</P>
+<P>One interesting sub-project is to make sure interceptors are
+interoperable with major web server mechansims - and play the same
+role as mod_perl for example: allow easy server extension using Java
+( i.e. provide access to all the full power of native server
+modules).
+</P>
+<P>You can control all aspects of request processing - parsing,
+authentication, authorization, sessions, response commit ( before
+headers are sent), buffer commit ( before any buffer is sent - it can
+be used to support HTTP1.1 for example !), before and after body.</P>
+<P>Interceptors are also used to provide integration with web servers
+( in tomcat <=3.2 a special "Connector" interface was
+used, but we found that Connector was in fact a subset of Interceptor
+and web integration requires more then just start/stop, so using the
+same mechanism is a better idea).</P>
+<P>Currently tomcat defines a number of hooks - other will be added
+as needed:</P>
+<UL>
+ <LI><P>contextMap</P>
+ <LI><P>requestMap</P>
+ <LI><P>XXX add the other, descrition</P>
+</UL>
+<H3>Helpers ( tomcat.helpers )</H3>
+<P>In order to keep the core as simple and readable as possible, the
+few functions that are implemented inside core ( instead of using
+interceptors ) are implemented in specialized helpers. For example
+reading the form data, encoding, etc. The helpers are grouped by
+functionality and the intention is to allow easy evolution - it is
+possible to rewrite or replace them with minimal effect on the rest
+of tomcat. This is one way to make sure team development works and
+new contributors can improve tomcat without the fear of broking the
+core.</P>
+<HR>
+<H2>5. Execution paths ( ContextManager and core )</H2>
+<H3>Initialization</H3>
+<P>XXX server intialization and configuration, context
+add/init/shutdown/remove, etc</P>
+<H3>Request processing</H3>
+<P STYLE="margin-bottom: 0in">Each web request is received by the web
+adapter, which will provide the Request/Response adapters. It will
+then call ContextManager.service(), and tomcat core will begin
+processing the request. A similar path happens for request that are
+not generated by a HTTP transaction - like sub-requests or non-web
+requests ( when tomcat is embedded in applications != web servers )</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<UL>
+ <LI><P>Request parsing. Context Manager will delegate ( "Chain
+ of responsibility" ) the parsing to a number of Interceptors,
+ each having a chance to process the request. Tomcat provides a
+ default implementation based on the mappings defined in the spec and
+ static configuration ( server.xml ), and also provide an interceptor
+ that will add all directories in webapp automatically. Other
+ interceptors may provide other features - like automatically adding
+ "~user", etc. See also the performance discussion. It is
+ possible to have different mapping algorithms ( "Strategy"
+ ), including using the web server native mappers if tomcat is
+ integrated with a web server.</P>
+ <LI><P>As result of mapping, a number of patterns and rules will be
+ applied to the request and to determine a "Container"
+ where the request belongs. The container encapsulate a set of
+ properties, including the request handler, security constraints, and
+ any other special attributes.
+ </P>
+ <LI><P>ContextManager will then delegate the authorization to a set
+ of Interceptors. If a certain role is required, tomcat will call the
+ authentication chain, where an adapter to an authentication API will
+ do the task ( "Strategy" )</P>
+ <LI><P>Handler will be called. Expensive/complex operation will be
+ handled by modules ( isUserInRole() for example is handled by the
+ authorization chain ). This is the place where more filtering can be
+ done ( like in Jigsaw or JWS servlet chains ), but so far we haven't
+ found the need.</P>
+</UL>
+<P ALIGN=LEFT>During request processing, tomcat will send
+notifications ("Observer") to interested modules about the
+current stage of the processing, for example allowing the modules to
+set transactions contexts ( J2EE interceptor ) or instrument tomcat (
+timing <B>individual</B> operations for fine tuning ).</P>
+<P ALIGN=LEFT>This model is identical with the one used in Apache,
+IIS and NES ( we tried to represent all notifications, so it tries to
+be a union, not intersection). <B>Why? </B><SPAN STYLE="font-weight: medium">Performance
+was the original reason, and the fact that the model was well-known
+and polished, so more trust-worthy then alternative models. It also
+turned out that the code organization improved a lot by using the
+"Strategy" pattern ( compared with tomcat 3.0 ), and many
+optimizations became possible. </SPAN>
+</P>
+<P ALIGN=LEFT STYLE="font-weight: medium">Another reason is related
+with the idea of making tomcat a real web-server extension, allowing
+people to develop web server modules ( filter, SAF, hooks) in java
+using a clean API. There are many ways to implement a web server, but
+this design choose Apache, IIS and NES as model, and tries to allow
+bi-directional code reuse.</P>
+<HR>
+<H2>6. Interceptors ( tomcat.context, tomcat.request)</H2>
+<H3>Standard modules</H3>
+<UL>
+ <LI><P><B>SimpleMapper</B><SPAN STYLE="font-weight: medium"> hooks
+ into contextMap and requestMap and implements the standard mapping
+ rules defined in the servlet API. It is not a particulary fast
+ module, but it's well tested and stable. Most of the current code is
+ derived and can be traced back to tomcat 3.0. We hope that other
+ solutions will show up and will evolve to replace SimpleMapper.</SPAN></P>
+ <LI><P STYLE="font-weight: medium"><B>LoaderInterceptor</B> will set
+ the context ClassLoader. There are 2 modules - one that provide a
+ custom class loader to be used with JDK1.1 and one that plugs JDK1.2
+ URLClassLoader.
+ </P>
+</UL>
+<H3>Adding custom modules</H3>
+<H3>Revolution by Evolution</H3>
+<P>By using the "Strategy" pattern it is possible to
+provide alternative alghoritms and implementations without affecting
+the core modules. In time the new "strategies" can be
+tested ( by first using them on experimental sytes, then in
+production ) and eventually replace the "core" modules.
+</P>
+<P>Tomcat is designed such that the core will have a minimal role in
+how the request is processed. We try to keep the number of methods
+and structures as small as possible, while "evolving" the
+core based on the use cases and needs of various modules. We expect
+that 3.3 or 3.4 will have a stable core.</P>
+<P>This method allowed a smooth evolution from tomcat3.0 who had a
+very complex and ugly (!) code, due to numerous additions and fixes.
+It is a standard form of refactoring that proved very useful.</P>
+<P><BR><BR>
+</P>
+<HR>
+<H2>7. Reusable Components ( tomcat.util )</H2>
+<P>Tomcat tries as much as possible to keep most of the code in
+standalone components, that have no dependency on tomcat.core. For
+example, the class loader, the session manager, the TCP server,
+authentication - all of them can easily be used in different
+architectures, and don't (shouldn't ) have any reference to core
+interfaces.</P>
+<P>There are many reasons for this: we think tomcat should focus on
+implementing the servlet API and shouldn't reinvent the wheel, and we
+also think all those components should be generic enough to be used
+in other servers.</P>
+<P>For example, most servlet container allows you to plug in a
+session manager. Session manager have ( shouldn't have ) too much
+need for knowing about the container internals - it is a special form
+of object database. Most of the time is better to write code
+independent of a particular container and using adapters to hook into
+different containers.</P>
+<H3>ThreadPool</H3>
+<P><BR><BR>
+</P>
+<HR>
+<H2>8. Security</H2>
+<P>XXX Move to separate document!
+</P>
+<P>The Proxy and FacadeManager plays a very important role in
+insuring security, by providing control of the communication between
+webapps and tomcat internals. It is possible to augment that with a
+special class loader mechanism ( for paranoid administrators), but
+most of the information that is available suggest the proxy is a very
+effective design pattern for this.</P>
+<P>Since tomcat.core runs with special (java) privileges, it is
+important to make sure the code is safe and the user can't call
+arbitrary methods. That will require a serious review over what
+methods are public, and how internal object instances can be accessed
+from outside. FacadeManager should be the only point of entry.</P>
+<P>We do need to provide a certain internal API to applications that
+will allow enhanced performance - for example Jasper can make use of
+the internal buffers, etc.</P>
+<H3>Existing risks and problems</H3>
+<DL>
+ <DT>Isolation. It is possbile for an application to store the
+ reference to the HttpServletRequests it receives in a Hashtable. If
+ the server is using recycling, the "bad" application will
+ end up with references to all active requests, and will be able to
+ access parameters and informations of other web applications.
+ </DT><DD>
+ In tomcat the HttpServletRequest is a proxy and a facade for the
+ real request. Tomcat will recycle the Request object, and can (
+ based on a config option) create new HttpServletRequestFacades for
+ each request.</DD><DT>
+ Constructor access. It is possible that an application will use the
+ current internal APIs to gain unauthorized access and call internal
+ APIs</DT><DD>
+ The only way to get access to internal APIs is using a special
+ context/request attribute. We allow only "trusted"
+ applications to call the method, and return null if the trusted flag
+ is not set. We need to carefully review the code to be sure no other
+ way to access the internals is possible, and reduce the number of
+ public constructors and public methods. We also need to add a (
+ JDK1.1 compatible ) mechanism to do security checks when objects are
+ constructed. ( for example add a TomcatSecurity object with empty
+ methods for 1.1 and using TomcatPermission and the 1.2 security
+ system for 1.2.
+ </DD><DT>
+ DOS - large body with POST data</DT><DD>
+ Tomcat will read the full body when a POST is processed. We need to
+ set upper limits or at least warn of possible abuse.</DD><DT>
+ DOS - general</DT><DD>
+ There are many possible DOS attacks, we need to identify them and
+ provide mechanisms to reduce the effect.</DD><HR>
+</DL>
+<H2>9. Embedding tomcat</H2>
+<P>Use the tomcat APIs to create ContextManager and set it up or stop
+it. Integration with your configuration API is very simple - tomcat
+doesn't care how you set it up, as long as the right object are
+created and the setter methods are called.</P>
+<P>All integration is done using the "Adapter" pattern -
+the Interceptors provide you with hooks into all tomcat internals,
+and you can control every aspect of request processing.</P>
+<HR>
+<H2>10. Integration with Web servers</H2>
+<P>Most commercial web sites run on one of the 4 big web servers, and
+we want to make sure tomcat can work well with those. After all, most
+people are using servlets for web applications :-)</P>
+<P>There are huge problems, even with the current architecture. For
+example the mapping defined in servlet 2.2 is different from the
+mapping used in the current web servers, form based login is very
+difficult to integrate ( and will require a lot of native code to
+protect non-java resources using the same authentication ).</P>
+<P>Most of the problems still require a lot of work, but we hope that
+the current architecture will be able to handle that. A bigger goal
+will be to transform the Interceptors into real web server
+extensions, so people can develop hooks/modules/SAF/filters in java
+instead of C ( or mod_perl ).</P>
+<H3>Tomcat and other Web Servers
+</H3>
+<P>Tomcat design is based on the features of Apache modules/hooks,
+ISAPI and NSAPI. We tried to not limit ourself to what is common to
+all. In time it is likely that tomcat will have more hooks and
+provide the same level of extensibility as the other servers. We
+tried to add the hooks by following "when somebody needs it "
+rule - and so far a number of callbacks are still to be added.</P>
+<P>Please read the Apache, IIS and NES documentations & code, as.
+Except for using different names and Java-style for interfaces, the
+model is the same.
+</P>
+<P>The mapping is:
+</P>
+<TABLE WIDTH=100% BORDER=1 CELLPADDING=4 CELLSPACING=3>
+ <COL WIDTH=51*>
+ <COL WIDTH=51*>
+ <COL WIDTH=51*>
+ <COL WIDTH=51*>
+ <COL WIDTH=51*>
+ <THEAD>
+ <TR VALIGN=TOP>
+ <TH WIDTH=20%>
+ <P>Tomcat</P>
+ </TH>
+ <TH WIDTH=20%>
+ <P>Apache</P>
+ </TH>
+ <TH WIDTH=20%>
+ <P>ISAPI</P>
+ </TH>
+ <TH WIDTH=20%>
+ <P>NSAPI</P>
+ </TH>
+ <TH WIDTH=20%>
+ <P>Other</P>
+ </TH>
+ </TR>
+ </THEAD>
+ <TBODY>
+ <TR VALIGN=TOP>
+ <TD WIDTH=20%>
+ <P>Request / Response
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P>request_rec<BR>conn_rec</P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ </TR>
+ <TR VALIGN=TOP>
+ <TD WIDTH=20%>
+ <P>ServletWrapper</P>
+ </TD>
+ <TD WIDTH=20%>
+ <P>Handler</P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ </TR>
+ <TR VALIGN=TOP>
+ <TD WIDTH=20%>
+ <P>Context</P>
+ </TD>
+ <TD WIDTH=20%>
+ <P>server_rec /<BR>per_dir_config</P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ </TR>
+ <TR VALIGN=TOP>
+ <TD WIDTH=20%>
+ <P>Container
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P>per_dir_config</P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ </TR>
+ <TR VALIGN=TOP>
+ <TD WIDTH=20%>
+ <P>Interceptor</P>
+ </TD>
+ <TD WIDTH=20%>
+ <P>Module / hooks</P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ </TR>
+ <TR VALIGN=TOP>
+ <TD WIDTH=20%>
+ <P>ContextManager</P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=20%>
+ <P><BR>
+ </P>
+ </TD>
+ </TR>
+ </TBODY>
+</TABLE>
+<P><BR><BR>
+</P>
+<HR>
+<P>Missing:</P>
+<UL>
+ <LI><P>pictures/UML diagrams</P>
+ <LI><P>policy-based security - it's standard, but need to add more
+ info about the implementation</P>
+ <LI><P>Relation with JDK1.2 / JDK1.1 - based on the thread on
+ tomcat-dev</P>
+ <LI><P>Current RequestMapper arch and future - based on the mails
+ from carlos@aper.net</P>
+ <LI><P>reloading/class loaders - I'm working on cleaning up the
+ implementation, I'll add documentation after that</P>
+ <LI><P>Request notes - I have to clean up the actual design and
+ implementation first, make it a standalone utility</P>
+ <LI><P>Real numbers - this will be slow and change as we implement
+ tomcat3.3. We'll have a complete set before October ( ApacheCon). We
+ need to keep track of the effect on performance of all important
+ changes we do, and also the overhead.</P>
+ <LI><P>In-detail documentation for all stand-alone components. Those
+ are un-likely to change too much and is important to explain they
+ are independent of tomcat.</P>
+ <LI><P>In particular, XMLMapper and the configuration, mentions of
+ JNDI configuration.</P>
+ <LI><P>Module life cycle + picture</P>
+ <LI><P>The authentication module.</P>
+ <LI><P>Integration with apache - config generation,etc -
+ unfortunately we don't know yet very well how to do it.</P>
+</UL>
+</BODY>
+</HTML>
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/internal.html
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org