Added: tomcat/tc6.0.x/trunk/webapps/docs/appdev/source.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/appdev/source.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/appdev/source.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/appdev/source.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,306 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="source.html">
+
+ &project;
+
+ <properties>
+ <author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
+ <title>Source Organization</title>
+ </properties>
+
+<body>
+
+
+<section name="Directory Structure">
+
+ <blockquote><em>
+ <p>The description below uses the variable name $CATALINA_HOME
+ to refer to the directory into which you have installed Tomcat 5,
+ and is the base directory against which most relative paths are
+ resolved. However, if you have configured Tomcat 5 for multiple
+ instances by setting a CATALINA_BASE directory, you should use
+ $CATALINA_BASE instead of $CATALINA_HOME for each of these
+ references.</p>
+ </em></blockquote>
+
+<p>A key recommendation of this manual is to separate the directory
+hierarchy containing your source code (described in this section) from
+the directory hierarchy containing your deployable application
+(described in the preceding section). Maintaining this separation has
+the following advantages:</p>
+<ul>
+<li>The contents of the source directories can be more easily administered,
+ moved, and backed up if the "executable" version of the application
+ is not intermixed.
+ <br/><br/></li>
+<li>Source code control is easier to manage on directories that contain
+ only source files.
+ <br/><br/></li>
+<li>The files that make up an installable distribution of your
+ application are much easier to select when the deployment
+ hierarchy is separate.</li>
+</ul>
+
+<p>As we will see, the <code>ant</code> development tool makes the creation
+and processing of such directory hierarchies nearly painless.</p>
+
+<p>The actual directory and file hierarchy used to contain the source code
+of an application can be pretty much anything you like. However, the
+following organization has proven to be quite generally applicable, and is
+expected by the example <code>build.xml</code> configuration file that
+is discussed below. All of these components exist under a top level
+<em>project source directory</em> for your application:</p>
+<ul>
+<li><strong>docs/</strong> - Documentation for your application, in whatever
+ format your development team is using.<br/><br/></li>
+<li><strong>src/</strong> - Java source files that generate the servlets,
+ beans, and other Java classes that are unique to your application.
+ If your source code is organized in packages (<strong>highly</strong>
+ recommended), the package hierarchy should be reflected as a directory
+ structure underneath this directory.<br/><br/></li>
+<li><strong>web/</strong> - The static content of your web site (HTML pages,
+ JSP pages, JavaScript files, CSS stylesheet files, and images) that will
+ be accessible to application clients. This directory will be the
+ <em>document root</em> of your web application, and any subdirectory
+ structure found here will be reflected in the request URIs required to
+ access those files.<br/><br/></li>
+<li><strong>web/WEB-INF/</strong> - The special configuration files required
+ for your application, including the web application deployment descriptor
+ (<code>web.xml</code>, defined in the
+ <a href="http://java.sun.com/products/servlet";>Servlet Specification</a>),
+ tag library descriptors for custom tag libraries
+ you have created, and other resource files you wish to include within
+ your web application. Even though this directory appears to be a
+ subdirectory of your <em>document root</em>, the Servlet Specification
+ prohibits serving the contents of this directory (or any file it contains)
+ directly to a client request. Therefore, this is a good place to store
+ configuration information that is sensitive (such as database connection
+ usernames and passwords), but is required for your application to
+ operate successfully.</li>
+</ul>
+
+<p>During the development process, two additional directories will be
+created on a temporary basis:</p>
+<ul>
+<li><strong>build/</strong> - When you execute a default build
+ (<code>ant</code>), this directory will contain an exact image
+ of the files in the web application archive for this application.
+ Tomcat 5 allows you to deploy an application in an unpacked
+ directory like this, either by copying it to the
+ <code>$CATALINA_HOME/webapps</code> directory, or by <em>installing</em>
+ it via the "Manager" web application. The latter approach is very
+ useful during development, and will be illustrated below.
+ <br/><br/></li>
+<li><strong>dist/</strong> - When you execute the <code>ant dist</code>
+ target, this directory will be created. It will create an exact image
+ of the binary distribution for your web application, including an license
+ information, documentation, and README files that you have prepared.</li>
+</ul>
+
+<p>Note that these two directories should <strong>NOT</strong> be archived in
+your source code control system, because they are deleted and recreated (from
+scratch) as needed during development. For that reason, you should not edit
+any source files in these directories if you want to maintain a permanent
+record of the changes, because the changes will be lost the next time that a
+build is performed.</p>
+
+ <subsection name="External Dependencies">
+
+ <p>What do you do if your application requires JAR files (or other
+ resources) from external projects or packages? A common example is that
+ you need to include a JDBC driver in your web application, in order to
+ operate.</p>
+
+ <p>Different developers take different approaches to this problem.
+ Some will encourage checking a copy of the JAR files you depend on into
+ the source code control archives for every application that requires those
+ JAR files. However, this can cause significant management issues when you
+ use the same JAR in many applications - particular when faced with a need
+ to upgrade to a different version of that JAR file.</p>
+
+ <p>Therefore, this manual recommends that you <strong>NOT</strong> store
+ a copy of the packages you depend on inside the source control archives
+ of your applications. Instead, the external dependencies should be
+ integrated as part of the process of <strong>building</strong> your
+ application. In that way, you can always pick up the appropriate version
+ of the JAR files from wherever your development system administrator has
+ installed them, without having to worry about updating your application
+ every time the version of the dependent JAR file is changed.</p>
+
+ <p>In the example Ant <code>build.xml</code> file, we will demonstrate
+ how to define <em>build properties</em> that let you configure the locations
+ of the files to be copied, without having to modify <code>build.xml</code>
+ when these files change. The build properties used by a particular
+ developer can be customized on a per-application basis, or defaulted to
+ "standard" build properties stored in the developer's home directory.</p>
+
+ <p>In many cases, your development system administrator will have already
+ installed the required JAR files into Tomcat 5's <code>common/lib</code>
+ or <code>shared/lib</code> directories. If this has been done, you need
+ to take no actions at all - the example <code>build.xml</code> file
+ automatically constructs a compile classpath that includes these files.</p>
+
+ </subsection>
+
+</section>
+
+
+<section name="Source Code Control">
+
+<p>As mentioned earlier, it is highly recommended that you place all of the
+source files that comprise your application under the management of a
+source code control system like the Concurrent Version System (CVS). If you
+elect to do this, every directory and file in the source hierarchy should be
+registered and saved -- but none of the generated files. If you register
+binary format files (such as images or JAR libraries), be sure to indicate
+this to your source code control system.</p>
+
+<p>We recommended (in the previous section) that you should not store the
+contents of the <code>build/</code> and <code>dist/</code> directories
+created by your development process in the source code control system. An
+easy way to tell CVS to ignore these directories is to create a file named
+<code>.cvsignore</code> (note the leading period) in your top-level source
+directory, with the following contents:</p>
+<source>
+build
+dist
+build.properties
+</source>
+
+<p>The reason for mentioning <code>build.properties</code> here will be
+explained in the <a href="processes.html">Processes</a> section.</p>
+
+<p>Detailed instructions for your source code control environment are beyond
+the scope of this manual. However, the following steps are followed when
+using a command-line CVS client:</p>
+<ul>
+<li>To refresh the state of your source code to that stored in the
+ the source repository, go to your project source directory, and
+ execute <code>cvs update -dP</code>.
+ <br/><br/></li>
+<li>When you create a new subdirectory in the source code hierarchy, register
+ it in CVS with a command like <code>cvs add {subdirname}</code>.
+ <br/><br/></li>
+<li>When you first create a new source code file, navigate to the directory
+ that contains it, and register the new file with a command like
+ <code>cvs add {filename}</code>.
+ <br/><br/></li>
+<li>If you no longer need a particular source code file, navigate to the
+ containing directory and remove the file. Then, deregister it in CVS
+ with a command like <code>cvs remove {filename}</code>.
+ <br/><br/></li>
+<li>While you are creating, modifying, and deleting source files, changes
+ are not yet reflected in the server repository. To save your changes in
+ their current state, go to the project source directory
+ and execute <code>cvs commit</code>. You will be asked to write a brief
+ description of the changes you have just completed, which will be stored
+ with the new version of any updated source file.</li>
+</ul>
+
+<p>CVS, like other source code control systems, has many additional features
+(such as the ability to tag the files that made up a particular release, and
+support for multiple development branches that can later be merged). See the
+links and references in the <a href="introduction.html">Introduction</a> for
+more information.</p>
+
+</section>
+
+
+<section name="BUILD.XML Configuration File">
+
+<p>We will be using the <strong>ant</strong> tool to manage the compilation of
+our Java source code files, and creation of the deployment hierarchy. Ant
+operates under the control of a build file, normally called
+<code>build.xml</code>, that defines the processing steps required. This
+file is stored in the top-level directory of your source code hierarchy, and
+should be checked in to your source code control system.</p>
+
+<p>Like a Makefile, the <code>build.xml</code> file provides several
+"targets" that support optional development activities (such as creating
+the associated Javadoc documentation, erasing the deployment home directory
+so you can build your project from scratch, or creating the web application
+archive file so you can distribute your application. A well-constructed
+<code>build.xml</code> file will contain internal documentation describing
+the targets that are designed for use by the developer, versus those targets
+used internally. To ask Ant to display the project documentation, change to
+the directory containing the <code>build.xml</code> flie and type:</p>
+<source>
+ant -projecthelp
+</source>
+
+<p>To give you a head start, a <a href="build.xml.txt">basic build.xml file</a>
+is provided that you can customize and install in the project source directory
+for your application. This file includes comments that describe the various
+targets that can be executed. Briefly, the following targets are generally
+provided:</p>
+<ul>
+<li><strong>clean</strong> - This target deletes any existing
+ <code>build</code> and <code>dist</code> directories, so that they
+ can be reconstructed from scratch. This allows you to guarantee that
+ you have not made source code modifications that will result in
+ problems at runtime due to not recompiling all affected classes.
+ <br/><br/></li>
+<li><strong>compile</strong> - This target is used to compile any source code
+ that has been changed since the last time compilation took place. The
+ resulting class files are created in the <code>WEB-INF/classes</code>
+ subdirectory of your <code>build</code> directory, exactly where the
+ structure of a web application requires them to be. Because
+ this command is executed so often during development, it is normally
+ made the "default" target so that a simple <code>ant</code> command will
+ execute it.
+ <br/><br/></li>
+<li><strong>all</strong> - This target is a short cut for running the
+ <code>clean</code> target, followed by the <code>compile</code> target.
+ Thus, it guarantees that you will recompile the entire application, to
+ ensure that you have not unknowingly introduced any incompatible changes.
+ <br/><br/></li>
+<li><strong>javadoc</strong> - This target creates Javadoc API documentation
+ for the Java classes in this web application. The example
+ <code>build.xml</code> file assumes you want to include the API
+ documentation with your app distribution, so it generates the docs
+ in a subdirectory of the <code>dist</code> directory. Because you normally
+ do not need to generate the Javadocs on every compilation, this target is
+ usually a dependency of the <code>dist</code> target, but not of the
+ <code>compile</code> target.
+ <br/><br/></li>
+<li><strong>dist</strong> - This target creates a distribution directory for
+ your application, including any required documentation, the Javadocs for
+ your Java classes, and a web application archive (WAR) file that will be
+ delivered to system administrators who wish to install your application.
+ Because this target also depends on the <code>deploy</code> target, the
+ web application archive will have also picked up any external dependencies
+ that were included at deployment time.</li>
+</ul>
+
+<p>For interactive development and testing of your web application using
+Tomcat 5, the following additional targets are defined:</p>
+<ul>
+<li><strong>install</strong> - Tell the currently running Tomcat 5 to make
+ the application you are developing immediately available for execution
+ and testing. This action does not require Tomcat 5 to be restarted, but
+ it is also not remembered after Tomcat is restarted the next time.
+ <br/><br/></li>
+<li><strong>reload</strong> - Once the application is installed, you can
+ continue to make changes and recompile using the <code>compile</code>
+ target. Tomcat 5 will automatically recognize changes made to JSP pages,
+ but not to servlet or JavaBean classes - this command will tell Tomcat
+ to restart the currently installed application so that such changes are
+ recognized.
+ <br/><br/></li>
+<li><strong>remove</strong> - When you have completed your development and
+ testing activities, you can optionally tell Tomcat 5 to remove this
+ application from service.
+ </li>
+</ul>
+
+<p>Using the development and testing targets requires some additional
+one-time setup that is described on the next page.</p>
+
+</section>
+
+
+</body>
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/appdev/source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/appdev/web.xml.txt
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/appdev/web.xml.txt?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/appdev/web.xml.txt (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/appdev/web.xml.txt Fri Jul 7 15:40:04
2006
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!DOCTYPE web-app
+ PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+ "http://java.sun.com/dtd/web-app_2_3.dtd";>
+
+<web-app>
+
+
+ <!-- General description of your web application -->
+
+ <display-name>My Web Application</display-name>
+ <description>
+ This is version X.X of an application to perform
+ a wild and wonderful task, based on servlets and
+ JSP pages. It was written by Dave Developer
+ ([EMAIL PROTECTED]), who should be contacted for
+ more information.
+ </description>
+
+
+ <!-- Context initialization parameters that define shared
+ String constants used within your application, which
+ can be customized by the system administrator who is
+ installing your application. The values actually
+ assigned to these parameters can be retrieved in a
+ servlet or JSP page by calling:
+
+ String value =
+ getServletContext().getInitParameter("name");
+
+ where "name" matches the <param-name> element of
+ one of these initialization parameters.
+
+ You can define any number of context initialization
+ parameters, including zero.
+ -->
+
+ <context-param>
+ <param-name>webmaster</param-name>
+ <param-value>[EMAIL PROTECTED]</param-value>
+ <description>
+ The EMAIL address of the administrator to whom questions
+ and comments about this application should be addressed.
+ </description>
+ </context-param>
+
+
+ <!-- Servlet definitions for the servlets that make up
+ your web application, including initialization
+ parameters. With Tomcat, you can also send requests
+ to servlets not listed here with a request like this:
+
+ http://localhost:8080/{context-path}/servlet/{classname}
+
+ but this usage is not guaranteed to be portable. It also
+ makes relative references to images and other resources
+ required by your servlet more complicated, so defining
+ all of your servlets (and defining a mapping to them with
+ a servlet-mapping element) is recommended.
+
+ Servlet initialization parameters can be retrieved in a
+ servlet or JSP page by calling:
+
+ String value =
+ getServletConfig().getInitParameter("name");
+
+ where "name" matches the <param-name> element of
+ one of these initialization parameters.
+
+ You can define any number of servlets, including zero.
+ -->
+
+ <servlet>
+ <servlet-name>controller</servlet-name>
+ <description>
+ This servlet plays the "controller" role in the MVC architecture
+ used in this application. It is generally mapped to the ".do"
+ filename extension with a servlet-mapping element, and all form
+ submits in the app will be submitted to a request URI like
+ "saveCustomer.do", which will therefore be mapped to this servlet.
+
+ The initialization parameter namess for this servlet are the
+ "servlet path" that will be received by this servlet (after the
+ filename extension is removed). The corresponding value is the
+ name of the action class that will be used to process this request.
+ </description>
+ <servlet-class>com.mycompany.mypackage.ControllerServlet</servlet-class>
+ <init-param>
+ <param-name>listOrders</param-name>
+ <param-value>com.mycompany.myactions.ListOrdersAction</param-value>
+ </init-param>
+ <init-param>
+ <param-name>saveCustomer</param-name>
+ <param-value>com.mycompany.myactions.SaveCustomerAction</param-value>
+ </init-param>
+ <!-- Load this servlet at server startup time -->
+ <load-on-startup>5</load-on-startup>
+ </servlet>
+
+ <servlet>
+ <servlet-name>graph</servlet-name>
+ <description>
+ This servlet produces GIF images that are dynamically generated
+ graphs, based on the input parameters included on the request.
+ It is generally mapped to a specific request URI like "/graph".
+ </description>
+ </servlet>
+
+
+ <!-- Define mappings that are used by the servlet container to
+ translate a particular request URI (context-relative) to a
+ particular servlet. The examples below correspond to the
+ servlet descriptions above. Thus, a request URI like:
+
+ http://localhost:8080/{contextpath}/graph
+
+ will be mapped to the "graph" servlet, while a request like:
+
+ http://localhost:8080/{contextpath}/saveCustomer.do
+
+ will be mapped to the "controller" servlet.
+
+ You may define any number of servlet mappings, including zero.
+ It is also legal to define more than one mapping for the same
+ servlet, if you wish to.
+ -->
+
+ <servlet-mapping>
+ <servlet-name>controller</servlet-name>
+ <url-pattern>*.do</url-pattern>
+ </servlet-mapping>
+
+ <servlet-mapping>
+ <servlet-name>graph</servlet-name>
+ <url-pattern>/graph</url-pattern>
+ </servlet-mapping>
+
+
+ <!-- Define the default session timeout for your application,
+ in minutes. From a servlet or JSP page, you can modify
+ the timeout for a particular session dynamically by using
+ HttpSession.getMaxInactiveInterval(). -->
+
+ <session-config>
+ <session-timeout>30</session-timeout> <!-- 30 minutes -->
+ </session-config>
+
+
+</web-app>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/appdev/web.xml.txt
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/apr.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/apr.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/apr.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/apr.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,331 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="apr.html">
+
+ &project;
+
+ <properties>
+ <title>Apache Portable Runtime and Tomcat</title>
+ <author>Remy Maucherat</author>
+ </properties>
+
+<body>
+
+ <section name="Introduction">
+
+ <p>
+ Tomcat can use the <a href="http://apr.apache.org/";>Apache Portable
Runtime</a> to
+ provide superior scalability, performance, and better integration with
native server
+ technologies. The Apache Portable Runtime is a highly portable library
that is at
+ the heart of Apache HTTP Server 2.x. APR has many uses, including access
to advanced IO
+ functionality (such as sendfile, epoll and OpenSSL), OS level
functionality (random number
+ generation, system status, etc), and native process handling (shared
memory, NT
+ pipes and Unix sockets).
+ </p>
+
+ <p>
+ These features allows making Tomcat a general purpose webserver, will
enable much better
+ integration with other native web technologies, and overall make Java
much more viable as
+ a full fledged webserver platform rather than simply a backend focused
technology.
+ </p>
+
+ </section>
+
+ <section name="Installation">
+
+ <p>
+ APR support requires three main native components to be installed:
+ <ul>
+ <li>APR library</li>
+ <li>JNI wrappers for APR used by Tomcat (libtcnative)</li>
+ <li>OpenSSL libraries</li>
+ </ul>
+ </p>
+
+ <subsection name="Windows">
+
+ <p>
+ Windows binaries are provided for tcnative-1, which is a statically
compiled .dll which includes
+ OpenSSL and APR. It can be downloaded from <a
href="http://tomcat.heanet.ie/native/";>here</a>
+ as 32bit or AMD x86-64 binaries.
+ In security conscious production environments, it is recommended to use
separate shared dlls
+ for OpenSSL, APR, and libtcnative-1, and update them as needed according
to security bulletins.
+ Windows OpenSSL binaries are linked from the <a
href="http://www.openssl.org";>Official OpenSSL
+ website</a> (see related/binaries).
+ </p>
+
+ </subsection>
+
+ <subsection name="Linux">
+
+ <p>
+ Most Linux distributions will ship packages for APR and OpenSSL. The JNI
wrapper (libtcnative) will
+ then have to be compiled. It depends on APR, OpenSSL, and the Java
headers.
+ </p>
+
+ <p>
+ Requirements:
+ <ul>
+ <li>APR 1.2+ development headers (libapr1-dev package)</li>
+ <li>OpenSSL 0.9.7+ development headers (libssl-dev package)</li>
+ <li>JNI headers from Java compatible JDK 1.4+</li>
+ <li>GNU development environment (gcc, make)</li>
+ </ul>
+ </p>
+
+ <p>
+ The wrapper library sources are located in the Tomcat binary bundle, in
the
+ <code>bin/tomcat-native.tar.gz</code> archive.
+ Once the build environment is installed and the source archive is
extracted, the wrapper library
+ can be compiled using (from the folder containing the configure script):
+ <source>./configure && make && make install</source>
+ </p>
+
+ </subsection>
+
+ </section>
+
+ <section name="APR Components">
+
+ <p>
+ Once the libraries are properly installed and available to Java (if
loading fails, the library path
+ will be displayed), the Tomcat connectors will automatically use APR.
Configuration of the connectors
+ is similar to the regular connectors, but have a few extra attributes
which are used to configure
+ APR components. Note that the defaults should be well tuned for most use
cases, and additional
+ tweaking shouldn't be required.
+ </p>
+
+ <p>
+ When APR is enabled, the following features are also enabled in Tomcat:
+ <ul>
+ <li>Secure session ID generation by default on all platforms (platforms
other than Linux required
+ random number generation using a configured entropy)</li>
+ <li>OS level statistics on memory usage and CPU usage by the Tomcat
process are displayed by
+ the status servlet</li>
+ </ul>
+ </p>
+
+ </section>
+
+ <section name="APR Connectors Configuration">
+
+ <subsection name="HTTP">
+
+ <p>
+ When APR is enabled, the HTTP connector will use sendfile for hadling
large static files (all such
+ files will be sent ansychronously using high performance kernel level
calls), and will use
+ a socket poller for keepalive, increasing scalability of the server.
+ </p>
+
+ <p>
+ The following attributes are supported in the HTTP APR connector in
addition to the ones supported
+ in the regular HTTP connector:
+ </p>
+
+ <attributes>
+
+ <attribute name="firstReadTimeout" required="false">
+ <p>The first read of a request will be made using the specified timeout.
If no data is available
+ after the specified time, the socket will be placed in the poller. The
value of this attribute is
+ in ms. Setting this value to 0 or -1 will
+ increase scalability by always using a poller to handle keepalive, but
will have a minor impact
+ on latency (see the related pollTime attribute). The difference is that
with 0, the first read of
+ a request will be made using a short timeout, while with -1, the first
read will be made using the
+ regular socket timeout that is configured on the connector. Setting this
to -2 will cause
+ the connector to not use the poller for keepalive in most situations,
emulating the behavior of
+ the java.io HTTP connector.
+ The default value is -1. Note: on Windows, the actual value of
firstReadTimeout will
+ be 500 + the specified value, if the specified value is strictly
positive.</p>
+ </attribute>
+
+ <attribute name="pollTime" required="false">
+ <p>Duration of a poll call. Lowering this value will slightly decrease
latency of connections
+ being kept alive in some cases, but will use more CPU as more poll calls
are being made. The
+ default value is 2000 (5ms).</p>
+ </attribute>
+
+ <attribute name="pollerSize" required="false">
+ <p>Amount of sockets that the poller responsible for polling kept alive
connections can hold at a
+ given time. Extra connections will be closed right away. The default
value is 8192, corresponding to
+ 8192 keepalive connections.</p>
+ </attribute>
+
+ <attribute name="useSendfile" required="false">
+ <p>Use kernel level sendfile for certain static files. The default value
is true.</p>
+ </attribute>
+
+ <attribute name="sendfileSize" required="false">
+ <p>Amount of sockets that the poller responsible for sending static
files asynchronously can hold
+ at a given time. Extra connections will be closed right away without any
data being sent
+ (resulting in a zero length file on the client side). Note that in most
cases, sendfile is a call
+ that will return right away (being taken care of "synchonously" by the
kernel), and the sendfile
+ poller will not be used, so the amount of static files which can be sent
concurrently is much larger
+ than the specified amount. The default value is 1024.</p>
+ </attribute>
+
+ </attributes>
+
+ </subsection>
+
+ <subsection name="HTTPS">
+
+ <p>
+ When APR is enabled, the HTTPS connector will use a socket poller for
keepalive, increasing
+ scalability of the server. It also uses OpenSSL, which may be more
optimized than JSSE depending
+ on the processor being used, and can be complemented with many
commercial accelerator components.
+ Unlike the HTTP connector, the HTTPS connector cannot use sendfile to
optimize static file
+ processing.
+ </p>
+
+ <p>
+ The HTTPS APR connector has the same basic attributes than the HTTP APR
connector, but adds
+ OpenSSL specific ones. For the full details on using OpenSSL, please
refer to OpenSSL documentations
+ and the many books available for it (see the <a
href="http://www.openssl.org";>Official OpenSSL
+ website</a>). The SSL specific attributes for the connector are:
+ </p>
+
+ <attributes>
+
+ <attribute name="SSLEngine" required="false">
+ <p>
+ Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no
specific ENGINE.
+ The default value is off.
+ </p>
+ </attribute>
+ <attribute name="SSLProtocol" required="false">
+ <p>
+ Protocol which may be used for communicating with clients. The default
is "all", with
+ other acceptable values being "SSLv2", "SSLv3", "TLSv1", and
"SSLv2+SSLv3".
+ </p>
+ </attribute>
+ <attribute name="SSLCipherSuite" required="false">
+ <p>
+ Ciphers which may be used for communicating with clients. The default is
"ALL", with
+ other acceptable values being a list of ciphers, with ":" used as the
delimiter
+ (see OpenSSL documentation for the list of ciphers supported).
+ </p>
+ </attribute>
+ <attribute name="SSLCertificateFile" required="true">
+ <p>
+ Name of the file that contains the server certificate. The format is
PEM-encoded.
+ </p>
+ </attribute>
+ <attribute name="SSLCertificateKeyFile" required="false">
+ <p>
+ Name of the file that contains the server private key. The format is
PEM-encoded.
+ The default value is the value of "SSLCertificateFile" and in this case
both certificate
+ and private key have to be in this file (NOT RECOMMENDED).
+ </p>
+ </attribute>
+ <attribute name="SSLPassword" required="false">
+ <p>
+ Pass phrase for the encrypted private key. If "SSLPassword" is not
provided, the callback fonction
+ should prompt for the pass phrase.
+ </p>
+ </attribute>
+ <attribute name="SSLVerifyClient" required="false">
+ <p>
+ Ask client for certificate. The default is "none", meaning the client
will not have the opportunity
+ to submit a certificate. Other acceptable values include "optional",
"require" and "optionalNoCA".
+ </p>
+ </attribute>
+ <attribute name="SSLVerifyDepth" required="false">
+ <p>
+ Maximum verification depth for client certificates. The default is "10".
+ </p>
+ </attribute>
+ <attribute name="SSLCACertificateFile" required="false">
+ <p>
+ See <a
href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcacertificatefile";>the
mod_ssl documentation</a>.
+ </p>
+ </attribute>
+ <attribute name="SSLCACertificatePath" required="false">
+ <p>
+ See <a
href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcacertificatepath";>the
mod_ssl documentation</a>.
+ </p>
+ </attribute>
+ <attribute name="SSLCertificateChainFile" required="false">
+ <p>
+ See <a
href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcertificatechainfile";>the
mod_ssl documentation</a>.
+ </p>
+ </attribute>
+ <attribute name="SSLCARevocationFile" required="false">
+ <p>
+ See <a
href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcarevocationfile";>the
mod_ssl documentation</a>.
+ </p>
+ </attribute>
+ <attribute name="SSLCARevocationPath" required="false">
+ <p>
+ See <a
href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcarevocationpath";>the
mod_ssl documentation</a>.
+ </p>
+ </attribute>
+
+ </attributes>
+
+ <p>
+ An example SSL Connector declaration can be:
+ <source>
+ <Connector port="443" maxHttpHeaderSize="8192"
+ maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
+ enableLookups="false" disableUploadTimeout="true"
+ acceptCount="100" scheme="https" secure="true"
+ SSLEngine="on"
+ SSLCertificateFile="${catalina.base}/conf/localhost.crt"
+ SSLCertificateKeyFile="${catalina.base}/conf/localhost.key"
/></source>
+ </p>
+
+ </subsection>
+
+ <subsection name="AJP">
+
+ <p>
+ When APR is enabled, the AJP connector will use a socket poller for
keepalive, increasing
+ scalability of the server. As AJP is designed around a pool of
persistent (or almost
+ persistent) connections, this will reduce significantly the amount of
processing threads
+ needed by Tomcat. Unlike the HTTP connector, the AJP connector cannot
use sendfile to optimize
+ static file processing.
+ </p>
+
+ <p>
+ The following attributes are supported in the AJP APR connector in
addition to the ones supported
+ in the regular AJP connector:
+ </p>
+
+ <attributes>
+
+ <attribute name="firstReadTimeout" required="false">
+ <p>The first read of a request will be made using the specified timeout.
If no data is available
+ after the specified time, the socket will be placed in the poller. The
value of this attribute is
+ in ms. Setting this value to 0 or -1 will
+ increase scalability by always using a poller to handle keepalive, but
will have a minor impact
+ on latency (see the related pollTime attribute). The difference is that
with 0, the first read of
+ a request will be made using a short timeout, while with -1, the first
read will be made using the
+ regular socket timeout that is configured on the connector. Setting this
to -2 will cause
+ the connector to not use the poller for keepalive in most situations,
emulating the behavior of
+ the java.io HTTP connector.
+ The default value is -1. Note: on Windows, the actual value of
firstReadTimeout will
+ be 500 + the specified value, if the specified value is strictly
positive.</p>
+ </attribute>
+
+ <attribute name="pollTime" required="false">
+ <p>Duration of a poll call. Lowering this value will slightly decrease
latency of connections
+ being kept alive in some cases, but will use more CPU as more poll calls
are being made. The
+ default value is 2000 (5ms).</p>
+ </attribute>
+
+ <attribute name="pollerSize" required="false">
+ <p>Amount of sockets that the poller responsible for polling kept alive
connections can hold at a
+ given time. Extra connections will be closed right away. The default
value is 8192, corresponding to
+ 8192 keepalive connections.</p>
+ </attribute>
+
+ </attributes>
+
+ </subsection>
+
+ </section>
+
+</body>
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/apr.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/architecture/index.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/architecture/index.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/architecture/index.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/architecture/index.xml Fri Jul 7
15:40:04 2006
@@ -0,0 +1,53 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="index.html">
+
+ &project;
+
+ <properties>
+ <author email="[EMAIL PROTECTED]">Yoav Shapira</author>
+ <title>Table of Contents</title>
+ </properties>
+
+<body>
+
+
+<section name="Preface">
+
+<p>This section of the Tomcat documentation attempts to explain
+the architecture and design of the Tomcat server. It includes significant
+contributions from several tomcat developers:
+</p>
+<ul>
+<li>Yoav Shapira
+ (<a href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</a>)</li>
+<li>Jeanfrancois Arcand
+ (<a href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</a>)</li>
+<li>Filip Hanik
+ (<a href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</a>)</li>
+</ul>
+
+</section>
+
+
+<section name="Table of Contents">
+
+<p>The information presented is divided into the following sections:</p>
+<ul>
+<li><a href="overview.html"><strong>Overview</strong></a> -
+ An overview of the Tomcat server architecture with key terms
+ and concepts.</li>
+<li><a href="startup.html"><strong>Server Startup</strong></a> -
+ A detailed description, with sequence diagrams, of how the Tomcat
+ server starts up.</li>
+<li><a href="requestProcess.html"><strong>Request Process Flow</strong></a> -
+ A detailed description of how Tomcat handles a request.</li>
+</ul>
+
+</section>
+
+
+</body>
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/architecture/index.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/architecture/overview.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/architecture/overview.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/architecture/overview.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/architecture/overview.xml Fri Jul 7
15:40:04 2006
@@ -0,0 +1,123 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="overview.html">
+
+ &project;
+
+ <properties>
+ <author email="[EMAIL PROTECTED]">Yoav Shapira</author>
+ <title>Architecture Overview</title>
+ </properties>
+
+<body>
+
+
+<section name="Overview">
+<p>
+This page provides an overview of the Tomcat server architecture.
+</p>
+</section>
+
+<section name="Terms">
+
+<subsection name="Server">
+<p>
+In the Tomcat world, a
+<a href="../config/server.html">Server</a> represents the whole container.
+Tomcat provides a default implementation of the
+<a href="../catalina/docs/api/org/apache/catalina/Server.html">Server
interface.</a>,
+and this is rarely customized by users.
+</p>
+</subsection>
+
+<subsection name="Service">
+<p>
+A <a href="../config/service.html">Service</a> is an intermediate component
+which lives inside a Server and ties one or more Connectors to exactly one
+Engine. The Service element is rarely customized by users, as the default
+implementation is simple and sufficient:
+<a href="../catalina/docs/api/org/apache/catalina/Service.html">Service
interface</a>.
+</p>
+</subsection>
+
+<subsection name="Engine">
+<p>
+An
+<a href="../config/engine.html">Engine</a> represents request processing
+pipeline for a specific Service. As a Service may have multiple Connectors,
+the Engine received and processes all requests from these connectors, handing
+the response back to the appropriate connector for transmission to the client.
+The <a href="../catalina/docs/api/org/apache/catalina/Engine.html">Engine
interface</a>
+may be implemented to supply custom Engines, though this is uncommon.
+</p>
+<p>
+Note that the Engine may be used for Tomcat server clustering via the
+jvmRoute parameter. Read the Clustering documentation for more information.
+</p>
+</subsection>
+
+<subsection name="Host">
+<p>
+A <a href="../config/host.html">Host</a> is an association of a network name,
+e.g. www.yourcompany.com, to the Tomcat server. An Engine may contain
+multiple hosts, and the Host element also supports network aliases such as
+yourcompany.com and abc.yourcompany.com. Users rarely create custom
+<a href="../catalina/docs/api/org/apache/catalina/Host.html">Hosts</a>
+because the
+<a
href="../catalina/docs/api/org/apache/catalina/core/StandardHost.html">StandardHost
+implementation</a> provides significant additional functionality.
+</p>
+</subsection>
+
+<subsection name="Connector">
+<p>
+A Connector handles communications with the client. There are multiple
+connectors available with Tomcat, all of which implement the
+<a href="../catalina/docs/api/org/apache/catalina/Connector.html">Connector
+interface.</a> These include the
+<a href="../config/coyote.html">Coyote connector</a> which is used for
+most HTTP traffic, especially when running Tomcat as a standalone server,
+and the <a href="../config/jk2.html">JK2 connector</a> which implements
+the AJP procotol used when connecting Tomcat to an Apache HTTPD server.
+Creating a customized connector is a significant effort.
+</p>
+</subsection>
+
+<subsection name="Context">
+<p>
+A
+<a href="../config/context.html">Context</a>
+represents a web application. A Host may contain multiple
+contexts, each with a unique path. The
+<a href="../catalina/docs/api/org/apache/catalina/Context.html">Context
+interface</a> may be implemented to create custom Contexts, but
+this is rarely the case because the
+<a href="../catalina/docs/api/org/apache/catalina/core/StandardContext.html">
+StandardContext</a> provides significant additional functionality.
+</p>
+</subsection>
+</section>
+
+<section name="Comments">
+<p>
+Tomcat is designed to be a fast and efficient implementation of the
+Servlet Specification. Tomcat came about as the reference implementation
+of this specification, and has remained rigorous in adhering to the
+specification. At the same time, significant attention has been paid
+to Tomcat's performance and it is now on par with other servlet containers,
+including commercial ones.
+</p>
+<p>
+In recent releases of Tomcat, mostly starting with Tomcat 5,
+we have begun effots to make more aspects of Tomcat managable via
+JMX. In addition, the Manager and Admin webapps have been greatly
+enhanced and improved. Managability is a primary area of concern
+for us as the product matures and the specification becomes more
+stable.
+</p>
+</section>
+
+</body>
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/architecture/overview.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/architecture/project.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/architecture/project.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/architecture/project.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/architecture/project.xml Fri Jul 7
15:40:04 2006
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="Tomcat Architecture"
+ href="http://jakarta.apache.org/tomcat/";>
+
+ <title>Tomcat Architecture</title>
+
+ <logo href="/images/tomcat.gif">
+ The Tomcat Servlet/JSP Container
+ </logo>
+
+
+ <body>
+
+ <menu name="Links">
+ <item name="Docs Home" href="../index.html" />
+ </menu>
+
+ <menu name="Contents">
+ <item name="Contents" href="index.html" />
+ <item name="Overview" href="overview.html" />
+ <item name="Server Startup" href="startup.html" />
+ <item name="Request Process" href="requestProcess.html" />
+ </menu>
+
+ </body>
+</project>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/architecture/project.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/architecture/requestProcess.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/architecture/requestProcess.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/architecture/requestProcess.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/architecture/requestProcess.xml Fri Jul
7 15:40:04 2006
@@ -0,0 +1,53 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="requestProcess.html">
+
+ &project;
+
+ <properties>
+ <author email="[EMAIL PROTECTED]">Yoav Shapira</author>
+ <title>Request Process Flow</title>
+ </properties>
+
+<body>
+
+
+<section name="Request Process Flow">
+
+<p>
+This page describes the process used by Tomcat to handle
+an incoming request. This process is largely defined by
+the Servlet Specification, which outlines the order
+of events that must take place.
+</p>
+
+<subsection name="description">
+<p>
+TODO
+</p>
+</subsection>
+
+<subsection name="diagram">
+<p>
+A UML sequence diagram of the request process is available
+<a href="requestProcess/requestProcess.pdf">here.</a>
+</p>
+</subsection>
+
+<subsection name="comments">
+<p>
+The Servlet Specification provides many opportunities for
+listening in (using Listeners) or modiying (using Filters)
+the request handling process even before the request arrives
+at the servlet that will handle it.
+</p>
+
+</subsection>
+
+</section>
+
+
+</body>
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/architecture/requestProcess.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added:
tomcat/tc6.0.x/trunk/webapps/docs/architecture/requestProcess/requestProcess.pdf
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/architecture/requestProcess/requestProcess.pdf?rev=420006&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
tomcat/tc6.0.x/trunk/webapps/docs/architecture/requestProcess/requestProcess.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
