open-source/apache-tomcat-8.5.51
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
xieyinlu
2024-11-30 19:03:49 +08:00
commit 1e6763c160
3806 changed files with 737676 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
webapps/docs/META-INF/context.xml Normal file
View File

@@ -0,0 +1,18 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<Context antiResourceLocking="false" />

29
webapps/docs/WEB-INF/web.xml Normal file
View File

@@ -0,0 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1"
metadata-complete="true">
<display-name>Tomcat Documentation</display-name>
<description>
Tomcat Documentation.
</description>
</web-app>

88
webapps/docs/aio.xml Normal file
View File

@@ -0,0 +1,88 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="aio.html">
&project;
<properties>
<title>Advanced IO and Tomcat</title>
<author>Remy Maucherat</author>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
<b>IMPORTANT NOTE: Usage of these features requires using the
HTTP connectors. The AJP connectors do not support them.</b>
</p>
</section>
<section name="Asynchronous writes">
<p>
When using HTTP connectors (based on APR or NIO/NIO2),
Tomcat supports using sendfile to send large static files.
These writes, as soon as the system load increases, will be performed
asynchronously in the most efficient way. Instead of sending a large response using
blocking writes, it is possible to write content to a static file, and write it
using a sendfile code. A caching valve could take advantage of this to cache the
response data in a file rather than store it in memory. Sendfile support is
available if the request attribute <code>org.apache.tomcat.sendfile.support</code>
is set to <code>Boolean.TRUE</code>.
</p>
<p>
Any servlet can instruct Tomcat to perform a sendfile call by setting the appropriate
request attributes. It is also necessary to correctly set the content length
for the response. When using sendfile, it is best to ensure that neither the
request or response have been wrapped, since as the response body will be sent later
by the connector itself, it cannot be filtered. Other than setting the 3 needed
request attributes, the servlet should not send any response data, but it may use
any method which will result in modifying the response header (like setting cookies).
</p>
<ul>
<li><code>org.apache.tomcat.sendfile.filename</code>: Canonical filename of the file which will be sent as
a String</li>
<li><code>org.apache.tomcat.sendfile.start</code>: Start offset as a Long</li>
<li><code>org.apache.tomcat.sendfile.end</code>: End offset as a Long</li>
</ul>
<p>
In addition to setting these parameters it is necessary to set the content-length header.
Tomcat will not do that for you, since you may have already written data to the output stream.
</p>
<p>
Note that the use of sendfile will disable any compression that Tomcat may
otherwise have performed on the response.
</p>
</section>
</body>
</document>

34
webapps/docs/annotationapi/index.html Normal file
View File

@@ -0,0 +1,34 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>API docs</title>
</head>
<body>
The Annotation API Javadoc is not installed by default. Download and install
the "fulldocs" package to get it.
You can also access the javadoc online in the Tomcat
<a href="https://tomcat.apache.org/tomcat-@VERSION_MAJOR_MINOR@-doc/">
documentation bundle</a>.
</body>
</html>

34
webapps/docs/api/index.html Normal file
View File

@@ -0,0 +1,34 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>API docs</title>
</head>
<body>
Tomcat's internal javadoc is not installed by default. Download and install
the "fulldocs" package to get it.
You can also access the javadoc online in the Tomcat
<a href="https://tomcat.apache.org/tomcat-@VERSION_MAJOR_MINOR@-doc/">
documentation bundle</a>.
</body>
</html>

508
webapps/docs/appdev/build.xml.txt Normal file
View File

File diff suppressed because it is too large Load Diff

249
webapps/docs/appdev/deployment.xml Normal file
View File

@@ -0,0 +1,249 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="deployment.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Deployment</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Background">
<p>Before describing how to organize your source code directories,
it is useful to examine the runtime organization of a web application.
Prior to the Servlet API Specification, version 2.2, there was little
consistency between server platforms. However, servers that conform
to the 2.2 (or later) specification are required to accept a
<em>Web Application Archive</em> in a standard format, which is discussed
further below.</p>
<p>A web application is defined as a hierarchy of directories and files
in a standard layout. Such a hierarchy can be accessed in its "unpacked"
form, where each directory and file exists in the filesystem separately,
or in a "packed" form known as a Web ARchive, or WAR file. The former format
is more useful during development, while the latter is used when you
distribute your application to be installed.</p>
<p>The top-level directory of your web application hierarchy is also the
<em>document root</em> of your application. Here, you will place the HTML
files and JSP pages that comprise your application's user interface. When the
system administrator deploys your application into a particular server, he
or she assigns a <em>context path</em> to your application (a later section
of this manual describes deployment on Tomcat). Thus, if the
system administrator assigns your application to the context path
<code>/catalog</code>, then a request URI referring to
<code>/catalog/index.html</code> will retrieve the <code>index.html</code>
file from your document root.</p>
</section>
<section name="Standard Directory Layout">
<p>To facilitate creation of a Web Application Archive file in the required
format, it is convenient to arrange the "executable" files of your web
application (that is, the files that Tomcat actually uses when executing
your app) in the same organization as required by the WAR format itself.
To do this, you will end up with the following contents in your
application's "document root" directory:</p>
<ul>
<li><strong>*.html, *.jsp, etc.</strong> - The HTML and JSP pages, along
with other files that must be visible to the client browser (such as
JavaScript, stylesheet files, and images) for your application.
In larger applications you may choose to divide these files into
a subdirectory hierarchy, but for smaller apps, it is generally
much simpler to maintain only a single directory for these files.
<br/><br/></li>
<li><strong>/WEB-INF/web.xml</strong> - The <em>Web Application Deployment
Descriptor</em> for your application. This is an XML file describing
the servlets and other components that make up your application,
along with any initialization parameters and container-managed
security constraints that you want the server to enforce for you.
This file is discussed in more detail in the following subsection.
<br/><br/></li>
<li><strong>/WEB-INF/classes/</strong> - This directory contains any Java
class files (and associated resources) required for your application,
including both servlet and non-servlet classes, that are not combined
into JAR files. If your classes are organized into Java packages,
you must reflect this in the directory hierarchy under
<code>/WEB-INF/classes/</code>. For example, a Java class named
<code>com.mycompany.mypackage.MyServlet</code>
would need to be stored in a file named
<code>/WEB-INF/classes/com/mycompany/mypackage/MyServlet.class</code>.
<br/><br/></li>
<li><strong>/WEB-INF/lib/</strong> - This directory contains JAR files that
contain Java class files (and associated resources) required for your
application, such as third party class libraries or JDBC drivers.</li>
</ul>
<p>When you install an application into Tomcat (or any other 2.2 or later
Servlet container), the classes in the <code>WEB-INF/classes/</code>
directory, as well as all classes in JAR files found in the
<code>WEB-INF/lib/</code> directory, are made visible to other classes
within your particular web application. Thus, if
you include all of the required library classes in one of these places (be
sure to check licenses for redistribution rights for any third party libraries
you utilize), you will simplify the installation of your web application --
no adjustment to the system class path (or installation of global library
files in your server) will be necessary.</p>
<p>Much of this information was extracted from Chapter 9 of the Servlet
API Specification, version 2.3, which you should consult for more details.</p>
</section>
<section name="Shared Library Files">
<p>Like most servlet containers, Tomcat also supports mechanisms to install
library JAR files (or unpacked classes) once, and make them visible to all
installed web applications (without having to be included inside the web
application itself). The details of how Tomcat locates and shares such
classes are described in the
<a href="../class-loader-howto.html">Class Loader How-To</a> documentation.
The location commonly used within a Tomcat installation for shared code is
<strong>$CATALINA_HOME/lib</strong>. JAR files placed here are visible both to
web applications and internal Tomcat code. This is a good place to put JDBC
drivers that are required for both your application or internal Tomcat use
(such as for a JDBCRealm).</p>
<p>Out of the box, a standard Tomcat installation includes a variety
of pre-installed shared library files, including:</p>
<ul>
<li>The <em>Servlet 3.1</em> and <em>JSP 2.3</em> APIs that are fundamental
to writing servlets and JavaServer Pages.<br/><br/></li>
</ul>
</section>
<section name="Web Application Deployment Descriptor">
<p>As mentioned above, the <code>/WEB-INF/web.xml</code> file contains the
Web Application Deployment Descriptor for your application. As the filename
extension implies, this file is an XML document, and defines everything about
your application that a server needs to know (except the <em>context path</em>,
which is assigned by the system administrator when the application is
deployed).</p>
<p>The complete syntax and semantics for the deployment descriptor is defined
in Chapter 13 of the Servlet API Specification, version 2.3. Over time, it
is expected that development tools will be provided that create and edit the
deployment descriptor for you. In the meantime, to provide a starting point,
a <a href="web.xml.txt" target="_blank">basic web.xml file</a>
is provided. This file includes comments that describe the purpose of each
included element.</p>
<p><strong>NOTE</strong> - The Servlet Specification includes a Document
Type Descriptor (DTD) for the web application deployment descriptor, and
Tomcat enforces the rules defined here when processing your application's
<code>/WEB-INF/web.xml</code> file. In particular, you <strong>must</strong>
enter your descriptor elements (such as <code>&lt;filter&gt;</code>,
<code>&lt;servlet&gt;</code>, and <code>&lt;servlet-mapping&gt;</code> in
the order defined by the DTD (see Section 13.3).</p>
</section>
<section name="Tomcat Context Descriptor">
<p>A /META-INF/context.xml file can be used to define Tomcat specific
configuration options, such as an access log, data sources, session manager
configuration and more. This XML file must contain one Context element, which
will be considered as if it was the child of the Host element corresponding
to the Host to which the web application is being deployed. The
<a href="../config/context.html">Tomcat configuration documentation</a> contains
information on the Context element.</p>
</section>
<section name="Deployment With Tomcat">
<p><em>The description below uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
not configured Tomcat for multiple instances by setting a CATALINA_BASE
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
the directory into which you have installed Tomcat.</em></p>
<p>In order to be executed, a web application must be deployed on
a servlet container. This is true even during development.
We will describe using Tomcat to provide the execution environment.
A web application can be deployed in Tomcat by one of the following
approaches:</p>
<ul>
<li><em>Copy unpacked directory hierarchy into a subdirectory in directory
<code>$CATALINA_BASE/webapps/</code></em>. Tomcat will assign a
context path to your application based on the subdirectory name you
choose. We will use this technique in the <code>build.xml</code>
file that we construct, because it is the quickest and easiest approach
during development. Be sure to restart Tomcat after installing or
updating your application.
<br/><br/></li>
<li><em>Copy the web application archive file into directory
<code>$CATALINA_BASE/webapps/</code></em>. When Tomcat is started, it will
automatically expand the web application archive file into its unpacked
form, and execute the application that way. This approach would typically
be used to install an additional application, provided by a third party
vendor or by your internal development staff, into an existing
Tomcat installation. <strong>NOTE</strong> - If you use this approach,
and wish to update your application later, you must both replace the
web application archive file <strong>AND</strong> delete the expanded
directory that Tomcat created, and then restart Tomcat, in order to reflect
your changes.
<br/><br/></li>
<li><em>Use the Tomcat "Manager" web application to deploy and undeploy
web applications</em>. Tomcat includes a web application, deployed
by default on context path <code>/manager</code>, that allows you to
deploy and undeploy applications on a running Tomcat server without
restarting it. See <a href="../manager-howto.html">Manager App How-To</a>
for more information on using the Manager web application.<br/><br/></li>
<li><em>Use "Manager" Ant Tasks In Your Build Script</em>. Tomcat
includes a set of custom task definitions for the <code>Ant</code>
build tool that allow you to automate the execution of commands to the
"Manager" web application. These tasks are used in the Tomcat deployer.
<br/><br/></li>
<li><em>Use the Tomcat Deployer</em>. Tomcat includes a packaged tool
bundling the Ant tasks, and can be used to automatically precompile JSPs
which are part of the web application before deployment to the server.
<br/><br/></li>
</ul>
<p>Deploying your app on other servlet containers will be specific to each
container, but all containers compatible with the Servlet API Specification
(version 2.2 or later) are required to accept a web application archive file.
Note that other containers are <strong>NOT</strong> required to accept an
unpacked directory structure (as Tomcat does), or to provide mechanisms for
shared library files, but these features are commonly available.</p>
</section>
</body>
</document>

79
webapps/docs/appdev/index.xml Normal file
View File

@@ -0,0 +1,79 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="index.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Table of Contents</title>
</properties>
<body>
<section name="Preface">
<p>This manual includes contributions from many members of the Tomcat Project
developer community. The following authors have provided significant content:
</p>
<ul>
<li>Craig R. McClanahan
(<a href="mailto:craigmcc@apache.org">craigmcc@apache.org</a>)</li>
</ul>
</section>
<section name="Table of Contents">
<p>The information presented is divided into the following sections:</p>
<ul>
<li><a href="introduction.html"><strong>Introduction</strong></a> -
Briefly describes the information covered here, with
links and references to other sources of information.</li>
<li><a href="installation.html"><strong>Installation</strong></a> -
Covers acquiring and installing the required software
components to use Tomcat for web application development.</li>
<li><a href="deployment.html"><strong>Deployment Organization</strong></a> -
Discusses the standard directory layout for a web application
(defined in the Servlet API Specification), the Web Application
Deployment Descriptor, and options for integration with Tomcat
in your development environment.</li>
<li><a href="source.html"><strong>Source Organization</strong></a> -
Describes a useful approach to organizing the source code
directories for your project, and introduces the
<code>build.xml</code> used by Ant to manage compilation.</li>
<li><a href="processes.html"><strong>Development Processes</strong></a> -
Provides brief descriptions of typical development processes
utilizing the recommended deployment and source organizations.</li>
<li><a href="sample/" target="_blank"><strong>Example Application</strong></a> -
This directory contains a very simple, but functionally complete,
"Hello, World" application built according to the principles
described in this manual. You can use this application to
practice using the described techniques.</li>
</ul>
</section>
</body>
</document>

105
webapps/docs/appdev/installation.xml Normal file
View File

@@ -0,0 +1,105 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="installation.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>Installation</title>
</properties>
<body>
<section name="Installation">
<p>In order to use Tomcat for developing web applications, you must first
install it (and the software it depends on). The required steps are outlined
in the following subsections.</p>
<subsection name="JDK">
<p>Tomcat <version-major-minor/> was designed to run on Java <min-java-version/> or later.
</p>
<p>Compatible JDKs for many platforms (or links to where they can be found)
are available at
<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a>.</p>
</subsection>
<subsection name="Tomcat">
<p>Binary downloads of the <strong>Tomcat</strong> server are available from
<a href="https://tomcat.apache.org/">https://tomcat.apache.org/</a>.
This manual assumes you are using the most recent release
of Tomcat <version-major/>. Detailed instructions for downloading and installing
Tomcat are available <a href="../setup.html">here</a>.</p>
<p>In the remainder of this manual, example shell scripts assume that you have
set an environment variable <code>CATALINA_HOME</code> that contains the
pathname to the directory in which Tomcat has been installed. Optionally, if
Tomcat has been configured for multiple instances, each instance will have its
own <code>CATALINA_BASE</code> configured.</p>
</subsection>
<subsection name="Ant">
<p>Binary downloads of the <strong>Ant</strong> build tool are available from
<a href="https://ant.apache.org/">https://ant.apache.org/</a>.
This manual assumes you are using Ant 1.8 or later. The instructions may
also be compatible with other versions, but this has not been tested.</p>
<p>Download and install Ant.
Then, add the <code>bin</code> directory of the Ant distribution to your
<code>PATH</code> environment variable, following the standard practices for
your operating system platform. Once you have done this, you will be able to
execute the <code>ant</code> shell command directly.</p>
</subsection>
<subsection name="CVS">
<p>Besides the required tools described above, you are strongly encouraged
to download and install a <em>source code control</em> system, such as the
<strong>Concurrent Version System</strong> (CVS), to maintain historical
versions of the source files that make up your web application. Besides
the server, you will also need appropriate client
tools to check out source code files, and check in modified versions.</p>
<p>Detailed instructions for installing and using source code control
applications is beyond the scope of this manual. However, CVS server and
client tools for many platforms (along with documentation) can be downloaded
from <a href="http://www.cvshome.org/">http://www.cvshome.org/</a>.</p>
</subsection>
</section>
</body>
</document>

92
webapps/docs/appdev/introduction.xml Normal file
View File

@@ -0,0 +1,92 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="introduction.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Introduction</title>
</properties>
<body>
<section name="Overview">
<p>Congratulations! You've decided to (or been told to) learn how to
build web applications using servlets and JSP pages, and picked the
Tomcat server to use for your learning and development. But now what
do you do?</p>
<p>This manual is a primer covering the basic steps of using Tomcat to
set up a development environment, organize your source code, and then
build and test your application. It does not discuss architectures or
recommended coding practices for web application development,
or provide in depth instructions on operating the development
tools that are discussed. References to sources of additional information
are included in the following subsections.</p>
<p>The discussion in this manual is aimed at developers who will be using
a text editor along with command line tools to develop and debug their
applications. As such, the recommendations are fairly generic &#x2013; but you
should easily be able to apply them in either a Windows-based or Unix-based
development environment. If you are utilizing an Integrated Development
Environment (IDE) tool, you will need to adapt the advice given here to
the details of your particular environment.</p>
</section>
<section name="Links">
<p>The following links provide access to selected sources of online
information, documentation, and software that is useful in developing
web applications with Tomcat.</p>
<ul>
<li><p><a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr245/index2.html">https://jcp.org/aboutJava/communityprocess/mrel/jsr245/index2.html</a> -
<i>JavaServer Pages (JSP) Specification, Version 2.3</i>. Describes
the programming environment provided by standard implementations
of the JavaServer Pages (JSP) technology. In conjunction with
the Servlet API Specification (see below), this document describes
what a portable API page is allowed to contain. Specific
information on scripting (Chapter 9), tag extensions (Chapter 7),
and packaging JSP pages (Appendix A) is useful. The Javadoc
API Documentation is included in the specification, and with the
Tomcat download.</p></li>
<li><p><a href="http://jcp.org/aboutJava/communityprocess/final/jsr340/index.html">http://jcp.org/aboutJava/communityprocess/final/jsr340/index.html</a> -
<i>Servlet API Specification, Version 3.1</i>. Describes the
programming environment that must be provided by all servlet
containers conforming to this specification. In particular, you
will need this document to understand the web application
directory structure and deployment file (Chapter 10), methods of
mapping request URIs to servlets (Chapter 12), container managed
security (Chapter 13), and the syntax of the <code>web.xml</code>
Web Application Deployment Descriptor (Chapter 14). The Javadoc
API Documentation is included in the specification, and with the
Tomcat download.</p></li>
</ul>
</section>
</body>
</document>

304
webapps/docs/appdev/processes.xml Normal file
View File

@@ -0,0 +1,304 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="processes.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Development Processes</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Development Processes">
<p>Although application development can take many forms, this manual proposes
a fairly generic process for creating web applications using Tomcat. The
following sections highlight the commands and tasks that you, as the developer
of the code, will perform. The same basic approach works when you have
multiple programmers involved, as long as you have an appropriate source code
control system and internal team rules about who is working on what parts
of the application at any given time.</p>
<p>The task descriptions below assume that you will be using CVS for source
code control, and that you have already configured access to the appropriate
CVS repository. Instructions for doing this are beyond the scope of this
manual. If you are using a different source code control environment, you
will need to figure out the corresponding commands for your system.</p>
<subsection name="One-Time Setup of Ant and Tomcat for Development">
<p>In order to take advantage of the special Ant tasks that interact with the
<em>Manager</em> web application, you need to perform the following tasks
once (no matter how many web applications you plan to develop).</p>
<ul>
<li><p><em>Configure the Ant custom tasks</em>. The implementation code for the
Ant custom tasks is in a JAR file named
<code>$CATALINA_HOME/lib/catalina-ant.jar</code>, which must be
copied in to the <code>lib</code> directory of your Ant installation.
</p></li>
<li><p><em>Define one or more Tomcat users</em>. The <em>Manager</em> web
application runs under a security constraint that requires a user to be
logged in, and have the security role <code>manager-script</code> assigned
to him or her. How such users are defined depends on which Realm you have
configured in Tomcat's <code>conf/server.xml</code> file -- see the
<a href="../realm-howto.html">Realm Configuration How-To</a> for more
information. You may define any number of users (with any username
and password that you like) with the <code>manager-script</code> role.
</p></li>
</ul>
</subsection>
<subsection name="Create Project Source Code Directory">
<p>The first step is to create a new project source directory, and customize
the <code>build.xml</code> and <code>build.properties</code> files you will
be using. The directory structure is described in <a href="source.html">the
previous section</a>, or you can use the
<a href="sample/">sample application</a> as a starting point.</p>
<p>Create your project source directory, and define it within your CVS
repository. This might be done by a series of commands like this, where
<code>{project}</code> is the name under which your project should be
stored in the CVS repository, and {username} is your login username:</p>
<source><![CDATA[cd {my home directory}
mkdir myapp <-- Assumed "project source directory"
cd myapp
mkdir docs
mkdir src
mkdir web
mkdir web/WEB-INF
cvs import -m "Initial Project Creation" {project} \
{username} start]]></source>
<p>Now, to verify that it was created correctly in CVS, we will perform a
checkout of the new project:</p>
<source><![CDATA[cd ..
mv myapp myapp.bu
cvs checkout {project}]]></source>
<p>Next, you will need to create and check in an initial version of the
<code>build.xml</code> script to be used for development. For getting
started quickly and easily, base your <code>build.xml</code> on the
<a href="build.xml.txt">basic build.xml file</a>, included with this manual,
or code it from scratch.</p>
<source><![CDATA[cd {my home directory}
cd myapp
emacs build.xml <-- if you want a real editor :-)
cvs add build.xml
cvs commit]]></source>
<p>Until you perform the CVS commit, your changes are local to your own
development directory. Committing makes those changes visible to other
developers on your team that are sharing the same CVS repository.</p>
<p>The next step is to customize the Ant <em>properties</em> that are
named in the <code>build.xml</code> script. This is done by creating a
file named <code>build.properties</code> in your project's top-level
directory. The supported properties are listed in the comments inside
the sample <code>build.xml</code> script. At a minimum, you will generally
need to define the <code>catalina.home</code> property defining where
Tomcat is installed, and the manager application username and password.
You might end up with something like this:</p>
<source># Context path to install this application on
app.path=/hello
# Tomcat installation directory
catalina.home=/usr/local/apache-tomcat-<version-major-minor/>
# Manager webapp username and password
manager.username=myusername
manager.password=mypassword</source>
<p>In general, you will <strong>not</strong> want to check the
<code>build.properties</code> file in to the CVS repository, because it
is unique to each developer's environment.</p>
<p>Now, create the initial version of the web application deployment
descriptor. You can base <code>web.xml</code> on the
<a href="web.xml.txt">basic web.xml file</a>, or code it from scratch.</p>
<source><![CDATA[cd {my home directory}
cd myapp/web/WEB-INF
emacs web.xml
cvs add web.xml
cvs commit]]></source>
Note that this is only an example web.xml file. The full definition
of the deployment descriptor file is in the
<a href="https://wiki.apache.org/tomcat/Specifications">Servlet Specification.</a>
</subsection>
<subsection name="Edit Source Code and Pages">
<p>The edit/build/test tasks will generally be your most common activities
during development and maintenance. The following general principles apply.
As described in <a href="source.html">Source Organization</a>, newly created
source files should be located in the appropriate subdirectory, under your
project source directory.</p>
<p>Whenever you wish to refresh your development directory to reflect the
work performed by other developers, you will ask CVS to do it for you:</p>
<source><![CDATA[cd {my home directory}
cd myapp
cvs update -dP]]></source>
<p>To create a new file, go to the appropriate directory, create the file,
and register it with CVS. When you are satisfied with it's contents (after
building and testing is successful), commit the new file to the repository.
For example, to create a new JSP page:</p>
<source><![CDATA[cd {my home directory}
cd myapp/web <-- Ultimate destination is document root
emacs mypage.jsp
cvs add mypage.jsp
... build and test the application ...
cvs commit]]></source>
<p>Java source code that is defined in packages must be organized in a
directory hierarchy (under the <strong>src/</strong> subdirectory) that
matches the package names. For example, a Java class named
<code>com.mycompany.mypackage.MyClass.java</code> should be stored in file
<code>src/com/mycompany/mypackage/MyClass.java</code>.
Whenever you create a new subdirectory, don't forget to
register it with CVS.</p>
<p>To edit an existing source file, you will generally just start editing
and testing, then commit the changed file when everything works. Although
CVS can be configured to required you to "check out" or "lock" a file you
are going to be modifying, this is generally not used.</p>
</subsection>
<subsection name="Build the Web Application">
<p>When you are ready to compile the application, issue the following
commands (generally, you will want a shell window open that is set to
the project source directory, so that only the last command is needed):</p>
<source><![CDATA[cd {my home directory}
cd myapp <-- Normally leave a window open here
ant]]></source>
<p>The Ant tool will be execute the default "compile" target in your
<code>build.xml</code> file, which will compile any new or updated Java
code. If this is the first time you compile after a "build clean",
it will cause everything to be recompiled.</p>
<p>To force the recompilation of your entire application, do this instead:</p>
<source><![CDATA[cd {my home directory}
cd myapp
ant all]]></source>
<p>This is a very good habit immediately before checking in changes, to
make sure that you have not introduced any subtle problems that Javac's
conditional checking did not catch.</p>
</subsection>
<subsection name="Test Your Web Application">
<p>To test your application, you will want to install it under Tomcat. The
quickest way to do that is to use the custom Ant tasks that are included in
the sample <code>build.xml</code> script. Using these commands might follow
a pattern like this:</p>
<ul>
<li><p><em>Start Tomcat if needed</em>. If Tomcat is not already running,
you will need to start it in the usual way.
</p></li>
<li><p><em>Compile your application</em>. Use the <code>ant compile</code>
command (or just <code>ant</code>, since this is the default). Make
sure that there are no compilation errors.
</p></li>
<li><p><em>Install the application</em>. Use the <code>ant install</code>
command. This tells Tomcat to immediately start running your app on
the context path defined in the <code>app.path</code> build property.
Tomcat does <strong>NOT</strong> have to be restarted for this to
take effect.
</p></li>
<li><p><em>Test the application</em>. Using your browser or other testing
tools, test the functionality of your application.
</p></li>
<li><p><em>Modify and rebuild as needed</em>. As you discover that changes
are required, make those changes in the original <strong>source</strong>
files, not in the output build directory, and re-issue the
<code>ant compile</code> command. This ensures that your changes will
be available to be saved (via <code>cvs commit</code>) later on --
the output build directory is deleted and recreated as necessary.
</p></li>
<li><p><em>Reload the application</em>. Tomcat will recognize changes in
JSP pages automatically, but it will continue to use the old versions
of any servlet or JavaBean classes until the application is reloaded.
You can trigger this by executing the <code>ant reload</code> command.
</p></li>
<li><p><em>Remove the application when you are done</em>. When you are through
working on this application, you can remove it from live execution by
running the <code>ant remove</code> command.
</p></li>
</ul>
<p>Do not forget to commit your changes to the source code repository when
you have completed your testing!</p>
</subsection>
<subsection name="Creating a Release">
<p>When you are through adding new functionality, and you've tested everything
(you DO test, don't you :-), it is time to create the distributable version
of your web application that can be deployed on the production server. The
following general steps are required:</p>
<ul>
<li><p>Issue the command <code>ant all</code> from the project source
directory, to rebuild everything from scratch one last time.
</p></li>
<li><p>Use the <code>cvs tag</code> command to create an identifier for
all of the source files utilized to create this release. This allows
you to reliably reconstruct a release (from sources) at a later
time.
</p></li>
<li><p>Issue the command <code>ant dist</code> to create a distributable
web application archive (WAR) file, as well as a JAR file containing
the corresponding source code.
</p></li>
<li><p>Package the contents of the <code>dist</code> directory using the
<strong>tar</strong> or <strong>zip</strong> utility, according to
the standard release procedures used by your organization.
</p></li>
</ul>
</subsection>
</section>
</body>
</document>

48
webapps/docs/appdev/project.xml Normal file
View File

@@ -0,0 +1,48 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<project name="Application Developer's Guide"
href="https://tomcat.apache.org/">
<title>Application Developer's Guide</title>
<logo href="/images/tomcat.gif">
The Apache Tomcat Servlet/JSP Container
</logo>
<body>
<menu name="Links">
<item name="Docs Home" href="../index.html"/>
<item name="App Dev Guide Home" href="index.html"/>
<item name="FAQ" href="https://wiki.apache.org/tomcat/FAQ" />
<item name="User Comments" href="#comments_section"/>
</menu>
<menu name="Contents">
<item name="Contents" href="index.html"/>
<item name="Introduction" href="introduction.html"/>
<item name="Installation" href="installation.html"/>
<item name="Deployment" href="deployment.html"/>
<item name="Source Code" href="source.html"/>
<item name="Processes" href="processes.html"/>
<item name="Example App" href="sample/"/>
</menu>
</body>
</project>

17
webapps/docs/appdev/sample/docs/README.txt Normal file
View File

@@ -0,0 +1,17 @@
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
This is a dummy README file for the sample
web application.

55
webapps/docs/appdev/sample/index.html Normal file
View File

@@ -0,0 +1,55 @@
<!DOCTYPE html>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<html>
<head>
<meta charset="UTF-8" />
<meta name="author" content="Ben Souther" />
<title>Sample Application</title>
</head>
<body>
<h2>Sample Application</h2>
<p>
The example app has been packaged as a war file and can be downloaded
<a href="sample.war">here</a> (Note: make sure your browser doesn't
change file extension or append a new one).
</p>
<p>
The easiest way to run this application is simply to move the war file
to your <b>CATALINA_BASE/webapps</b> directory. A default Tomcat install
will automatically expand and deploy the application for you. You can
view it with the following URL (assuming that you're running tomcat on
port 8080 which is the default):
<br />
<a href="http://localhost:8080/sample">http://localhost:8080/sample</a>
</p>
<p>
If you just want to browse the contents, you can unpack the war file
with the <b>jar</b> command.
</p>
<pre>
jar -xvf sample.war
</pre>
<p>
Note: <b>CATALINA_BASE</b> is usually the directory in which you
unpacked the Tomcat distribution. For more information on
<b>CATALINA_HOME</b>, <b>CATALINA_BASE</b> and the difference between
them see <b>RUNNING.txt</b> in the directory you unpacked your Tomcat
distribution.
</p>
</body>
</html>

BIN
webapps/docs/appdev/sample/sample.war Normal file
View File

Binary file not shown.

83
webapps/docs/appdev/sample/src/mypackage/Hello.java Normal file
View File

@@ -0,0 +1,83 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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.
*/
package mypackage;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
/**
* Simple servlet to validate that the Hello, World example can
* execute servlets. In the web application deployment descriptor,
* this servlet must be mapped to correspond to the link in the
* "index.html" file.
*
* @author Craig R. McClanahan <Craig.McClanahan@eng.sun.com>
*/
public final class Hello extends HttpServlet {
private static final long serialVersionUID = 1L;
/**
* Respond to a GET request for the content produced by
* this servlet.
*
* @param request The servlet request we are processing
* @param response The servlet response we are producing
*
* @exception IOException if an input/output error occurs
* @exception ServletException if a servlet error occurs
*/
@Override
public void doGet(HttpServletRequest request,
HttpServletResponse response)
throws IOException, ServletException {
response.setContentType("text/html");
response.setCharacterEncoding("UTF-8");
try (PrintWriter writer = response.getWriter()) {
writer.println("<!DOCTYPE html><html>");
writer.println("<head>");
writer.println("<meta charset=\"UTF-8\" />");
writer.println("<title>Sample Application Servlet Page</title>");
writer.println("</head>");
writer.println("<body>");
writer.println("<div style=\"float: left; padding: 10px;\">");
writer.println("<img src=\"images/tomcat.gif\" alt=\"\" />");
writer.println("</div>");
writer.println("<h1>Sample Application Servlet</h1>");
writer.println("<p>");
writer.println("This is the output of a servlet that is part of");
writer.println("the Hello, World application.");
writer.println("</p>");
writer.println("</body>");
writer.println("</html>");
}
}
}

40
webapps/docs/appdev/sample/web/WEB-INF/web.xml Normal file
View File

@@ -0,0 +1,40 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1">
<display-name>Hello, World Application</display-name>
<description>
This is a simple web application with a source code organization
based on the recommendations of the Application Developer's Guide.
</description>
<servlet>
<servlet-name>HelloServlet</servlet-name>
<servlet-class>mypackage.Hello</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>HelloServlet</servlet-name>
<url-pattern>/hello</url-pattern>
</servlet-mapping>
</web-app>

37
webapps/docs/appdev/sample/web/hello.jsp Normal file
View File

@@ -0,0 +1,37 @@
<%--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
--%>
<%@ page session="false" pageEncoding="UTF-8" contentType="text/html; charset=UTF-8" %>
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>Sample Application JSP Page</title>
</head>
<body>
<div style="float: left; padding: 10px;">
<img src="images/tomcat.gif" alt="" />
</div>
<h1>Sample Application JSP Page</h1>
This is the output of a JSP page that is part of the Hello, World
application.
<%= new String("Hello!") %>
</body>
</html>

BIN
webapps/docs/appdev/sample/web/images/tomcat.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 KiB

39
webapps/docs/appdev/sample/web/index.html Normal file
View File

@@ -0,0 +1,39 @@
<!DOCTYPE html><!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<html>
<head>
<meta charset="UTF-8" />
<title>Sample "Hello, World" Application</title>
</head>
<body>
<div style="float: left; padding: 10px;">
<img src="images/tomcat.gif" alt="" />
</div>
<h1>Sample "Hello, World" Application</h1>
<p>This is the home page for a sample application used to illustrate the
source directory organization of a web application utilizing the principles
outlined in the Application Developer's Guide.
<p>To prove that they work, you can execute either of the following links:</p>
<ul>
<li>To a <a href="hello.jsp">JSP page</a>.</li>
<li>To a <a href="hello">servlet</a>.</li>
</ul>
</body>
</html>

317
webapps/docs/appdev/source.xml Normal file
View File

@@ -0,0 +1,317 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="source.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Source Organization</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Directory Structure">
<p><em>The description below uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
not configured Tomcat for multiple instances by setting a CATALINA_BASE
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
the directory into which you have installed Tomcat.</em></p>
<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><p>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.
</p></li>
<li><p>Source code control is easier to manage on directories that contain
only source files.
</p></li>
<li><p>The files that make up an installable distribution of your
application are much easier to select when the deployment
hierarchy is separate.</p></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="https://wiki.apache.org/tomcat/Specifications">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 allows you to deploy an application in an unpacked
directory like this, either by copying it to the
<code>$CATALINA_BASE/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 the <code>lib</code> directory of Tomcat.
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> file 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, the following additional targets are defined:</p>
<ul>
<li><strong>install</strong> - Tell the currently running Tomcat to make
the application you are developing immediately available for execution
and testing. This action does not require Tomcat 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 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 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>

166
webapps/docs/appdev/web.xml.txt Normal file
View File

@@ -0,0 +1,166 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!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
(dave@mycompany.com), 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>myaddress@mycompany.com</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 names 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>

170
webapps/docs/apr.xml Normal file
View File

@@ -0,0 +1,170 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="apr.html">
&project;
<properties>
<title>Apache Portable Runtime (APR) based Native library for Tomcat</title>
<author>Remy Maucherat</author>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
Tomcat can use the <a href="https://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:
</p>
<ul>
<li>APR library</li>
<li>JNI wrappers for APR used by Tomcat (libtcnative)</li>
<li>OpenSSL libraries</li>
</ul>
<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="https://tomcat.apache.org/download-native.cgi">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="https://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:
</p>
<ul>
<li>APR 1.2+ development headers (libapr1-dev package)</li>
<li>OpenSSL 1.0.2+ 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>
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):
</p>
<source>./configure &amp;&amp; make &amp;&amp; make install</source>
</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:
</p>
<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>
</section>
<section name="APR Lifecycle Listener Configuration">
<p>See <a href="config/listeners.html#APR_Lifecycle_Listener_-_org.apache.catalina.core.AprLifecycleListener">the
listener configuration</a>.</p>
</section>
<section name="APR Connectors Configuration">
<subsection name="HTTP/HTTPS">
<p>For HTTP configuration, see the <a href="config/http.html">HTTP</a>
connector configuration documentation.</p>
<p>For HTTPS configuration, see the
<a href="config/http.html#SSL_Support">HTTPS</a> connector configuration
documentation.</p>
<p>An example SSL Connector declaration is:</p>
<source><![CDATA[<Connector port="443" maxHttpHeaderSize="8192"
maxThreads="150"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
SSLEnabled="true"
SSLCertificateFile="${catalina.base}/conf/localhost.crt"
SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" />]]></source>
</subsection>
<subsection name="AJP">
<p>For AJP configuration, see the <a href="config/ajp.html">AJP</a>
connector configuration documentation.</p>
</subsection>
</section>
</body>
</document>

69
webapps/docs/architecture/index.xml Normal file
View File

@@ -0,0 +1,69 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="index.html">
&project;
<properties>
<author email="yoavs@apache.org">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:yoavs@apache.org">yoavs@apache.org</a>)</li>
<li>Jeanfrancois Arcand
(<a href="mailto:jfarcand@apache.org">jfarcand@apache.org</a>)</li>
<li>Filip Hanik
(<a href="mailto:fhanik@apache.org">fhanik@apache.org</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>

138
webapps/docs/architecture/overview.xml Normal file
View File

@@ -0,0 +1,138 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="overview.html">
&project;
<properties>
<author email="yoavs@apache.org">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="../api/org/apache/catalina/Server.html">Server interface</a>
which 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="../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 receives and processes all requests from these connectors, handing
the response back to the appropriate connector for transmission to the client.
The <a href="../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="../api/org/apache/catalina/Host.html">Hosts</a>
because the
<a href="../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. These include the
<a href="../config/http.html">HTTP connector</a> which is used for
most HTTP traffic, especially when running Tomcat as a standalone server,
and the <a href="../config/ajp.html">AJP connector</a> which implements
the AJP protocol used when connecting Tomcat to a web server such as
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="../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="../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 efforts to make more aspects of Tomcat manageable via
JMX. In addition, the Manager and Admin webapps have been greatly
enhanced and improved. Manageability is a primary area of concern
for us as the product matures and the specification becomes more
stable.
</p>
</section>
</body>
</document>

45
webapps/docs/architecture/project.xml Normal file
View File

@@ -0,0 +1,45 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<project name="Apache Tomcat 8 Architecture"
href="https://tomcat.apache.org/">
<title>Apache Tomcat 8 Architecture</title>
<logo href="/images/tomcat.gif">
The Apache Tomcat Servlet/JSP Container
</logo>
<body>
<menu name="Links">
<item name="Docs Home" href="../index.html" />
<item name="Architecture Home" href="index.html"/>
<item name="FAQ" href="https://wiki.apache.org/tomcat/FAQ" />
<item name="User Comments" href="#comments_section"/>
</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>

74
webapps/docs/architecture/requestProcess.xml Normal file
View File

@@ -0,0 +1,74 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="requestProcess.html">
&project;
<properties>
<author email="yoavs@apache.org">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="diagrams">
<p>
A UML sequence diagram of the request process is available
<a href="requestProcess/request-process.png">here.</a>
</p>
<p>
A UML sequence diagram of the authentication process is available
<a href="requestProcess/authentication-process.png">here.</a>
</p>
</subsection>
<subsection name="comments">
<p>
The Servlet Specification provides many opportunities for
listening in (using Listeners) or modifying (using Filters)
the request handling process even before the request arrives
at the servlet that will handle it.
</p>
</subsection>
</section>
</body>
</document>

BIN
webapps/docs/architecture/requestProcess/authentication-process.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
webapps/docs/architecture/requestProcess/request-process.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 107 KiB

73
webapps/docs/architecture/startup.xml Normal file
View File

@@ -0,0 +1,73 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="startup.html">
&project;
<properties>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>Startup</title>
</properties>
<body>
<section name="Server Startup">
<p>
This page describes how the Tomcat server starts up. There are several
different ways to start tomcat, including:
</p>
<ul>
<li>From the command line.</li>
<li>From a Java program as an embedded server.</li>
<li>Automatically as a Windows service.</li>
</ul>
<subsection name="description">
<p>
A text description of the startup procedure is available
<a href="startup/serverStartup.txt">here.</a>
</p>
</subsection>
<subsection name="diagram">
<p>
A UML sequence diagram of the startup procedure is available
<a href="startup/serverStartup.pdf">here.</a>
</p>
</subsection>
<subsection name="comments">
<p>
The startup process can be customized in many ways, both
by modifying Tomcat code and by implementing your own
LifecycleListeners which are then registered in the server.xml
configuration file.
</p>
</subsection>
</section>
</body>
</document>

BIN
webapps/docs/architecture/startup/serverStartup.pdf Normal file
View File

Binary file not shown.

139
webapps/docs/architecture/startup/serverStartup.txt Normal file
View File

@@ -0,0 +1,139 @@
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
Tomcat Startup Sequence
Sequence 1. Start from Command Line
Class: org.apache.catalina.startup.Bootstrap
What it does:
a) Set up classloaders
commonLoader (common)-> System Loader
sharedLoader (shared)-> commonLoader -> System Loader
catalinaLoader(server) -> commonLoader -> System Loader
(by default the commonLoader is used for the
sharedLoader and the serverLoader)
b) Load startup class (reflection)
org.apache.catalina.startup.Catalina
setParentClassloader -> sharedLoader
Thread.contextClassloader -> catalinaLoader
c) Bootstrap.daemon.init() complete
Sequence 2. Process command line argument (start, stop)
Class: org.apache.catalina.startup.Bootstrap (assume command->start)
What it does:
a) Catalina.setAwait(true);
b) Catalina.load()
b1) initDirs() -> set properties like
catalina.home
catalina.base == catalina.home (most cases)
b2) initNaming
setProperty(javax.naming.Context.INITIAL_CONTEXT_FACTORY,
org.apache.naming.java.javaURLContextFactory ->default)
b3) createStartDigester()
Configures a digester for the main server.xml elements like
org.apache.catalina.core.StandardServer (can change of course :)
org.apache.catalina.deploy.NamingResources
Stores naming resources in the J2EE JNDI tree
org.apache.catalina.LifecycleListener
implements events for start/stop of major components
org.apache.catalina.core.StandardService
The single entry for a set of connectors,
so that a container can listen to multiple connectors
ie, single entry
org.apache.catalina.Connector
Connectors to listen for incoming requests only
It also adds the following rulesets to the digester
NamingRuleSet
EngineRuleSet
HostRuleSet
ContextRuleSet
b4) Load the server.xml and parse it using the digester
Parsing the server.xml using the digester is an automatic
XML-object mapping tool, that will create the objects defined in server.xml
Startup of the actual container has not started yet.
b5) Assigns System.out and System.err to the SystemLogHandler class
b6) Calls initialize on all components, this makes each object register itself with the
JMX agent.
During the process call the Connectors also initialize the adapters.
The adapters are the components that do the request pre-processing.
Typical adapters are HTTP1.1 (default if no protocol is specified,
org.apache.coyote.http11.Http11NioProtocol)
AJP1.3 for mod_jk etc.
c) Catalina.start()
c1) Starts the NamingContext and binds all JNDI references into it
c2) Starts the services under <Server> which are:
StandardService -> starts Engine (ContainerBase -> Realm,Cluster etc)
c3) StandardHost (started by the service)
Configures an ErrorReportValve to do proper HTML output for different HTTP
errors codes
Starts the Valves in the pipeline (at least the ErrorReportValve)
Configures the StandardHostValve,
this valves ties the Webapp Class loader to the thread context
it also finds the session for the request
and invokes the context pipeline
Starts the HostConfig component
This component deploys all the webapps
(webapps & conf/Catalina/localhost/*.xml)
HostConfig will create a Digester for your context, this digester
will then invoke ContextConfig.start()
The ContextConfig.start() will process the default web.xml (conf/web.xml)
and then process the applications web.xml (WEB-INF/web.xml)
c4) During the lifetime of the container (StandardEngine) there is a background thread that
keeps checking if the context has changed. If a context changes (timestamp of war file,
context xml file, web.xml) then a reload is issued (stop/remove/deploy/start)
d) Tomcat receives a request on an HTTP port
d1) The request is received by a separate thread which is waiting in the ThreadPoolExecutor
class. It is waiting for a request in a regular ServerSocket.accept() method.
When a request is received, this thread wakes up.
d2) The ThreadPoolExecutor assigns the a TaskThread to handle the request.
It also supplies a JMX object name to the catalina container (not used I believe)
d3) The processor to handle the request in this case is Coyote Http11Processor,
and the process method is invoked.
This same processor is also continuing to check the input stream of the socket
until the keep alive point is reached or the connection is disconnected.
d4) The HTTP request is parsed using an internal buffer class (Http11InputBuffer)
The buffer class parses the request line, the headers, etc and store the result in a
Coyote request (not an HTTP request) This request contains all the HTTP info, such
as servername, port, scheme, etc.
d5) The processor contains a reference to an Adapter, in this case it is the
CoyoteAdapter. Once the request has been parsed, the Http11Processor
invokes service() on the adapter. In the service method, the Request contains a
CoyoteRequest and CoyoteResponse (null for the first time)
The CoyoteRequest(Response) implements HttpRequest(Response) and HttpServletRequest(Response)
The adapter parses and associates everything with the request, cookies, the context through a
Mapper, etc
d6) When the parsing is finished, the CoyoteAdapter invokes its container (StandardEngine)
and invokes the invoke(request,response) method.
This initiates the HTTP request into the Catalina container starting at the engine level
d7) The StandardEngine.invoke() simply invokes the container pipeline.invoke()
d8) By default the engine only has one valve the StandardEngineValve, this valve simply
invokes the invoke() method on the Host pipeline (StandardHost.getPipeLine())
d9) the StandardHost has two valves by default, the StandardHostValve and the ErrorReportValve
d10) The standard host valve associates the correct class loader with the current thread
It also retrieves the Manager and the session associated with the request (if there is one)
If there is a session access() is called to keep the session alive
d11) After that the StandardHostValve invokes the pipeline on the context associated
with the request.
d12) The first valve that gets invoked by the Context pipeline is the FormAuthenticator
valve. Then the StandardContextValve gets invoke.
The StandardContextValve invokes any context listeners associated with the context.
Next it invokes the pipeline on the Wrapper component (StandardWrapperValve)
d13) During the invocation of the StandardWrapperValve, the JSP wrapper (Jasper) gets invoked
This results in the actual compilation of the JSP.
And then invokes the actual servlet.
e) Invocation of the servlet class

55
webapps/docs/balancer-howto.xml Normal file
View File

@@ -0,0 +1,55 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="balancer-howto.html">
&project;
<properties>
<author email="yoavs@apache.org">Yoav Shapira</author>
<author>Remy Maucherat</author>
<author>Andy Oliver</author>
<title>Load Balancer How-To</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Using the JK 1.2.x native connector">
Please refer to the JK 1.2.x documentation.
</section>
<section name="Using Apache HTTP Server 2.x with mod_proxy">
Please refer to the mod_proxy documentation for Apache HTTP Server 2.2. This supports either
HTTP or AJP load balancing. This new version of mod_proxy is also usable with
Apache HTTP Server 2.0, but mod_proxy will have to be compiled separately using the code
from Apache HTTP Server 2.2.
</section>
</body>
</document>

280
webapps/docs/building.xml Normal file
View File

@@ -0,0 +1,280 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<title>Building Tomcat</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
Building Apache Tomcat from source is very easy, and is the first step to
contributing to Tomcat. The complete and comprehensive instructions are
provided in the file <a href="BUILDING.txt">BUILDING.txt</a>.
The following is a quick step by step guide.
</p>
</section>
<section name="Download a Java Development Kit (JDK) version 7">
<p>
Building Apache Tomcat requires a JDK (version 7) to be installed. You can download one from<br />
<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a><br/>
<a href="http://openjdk.java.net/install/index.html">http://openjdk.java.net/install/index.html</a><br/>
or another JDK vendor.
</p>
<p>
<b>IMPORTANT</b>: Set an environment variable JAVA_HOME to the pathname of the
directory into which you installed the JDK release.
</p>
</section>
<section name="Install Apache Ant 1.9.8 or later">
<p>
Download a binary distribution of Ant 1.9.8 or later from
<a href="https://ant.apache.org/bindownload.cgi">here</a>.
</p>
<p>
Unpack the binary distribution into a convenient location so that the
Ant release resides in its own directory (conventionally named
<code>apache-ant-1.9.x</code>). For the remainder of this guide,
the symbolic name <code>${ant.home}</code> is used to refer to the full pathname of
the Ant installation directory.
</p>
<p>
<b>IMPORTANT</b>: Create an ANT_HOME environment variable to point the directory <code>${ant.home}</code>,
and modify the PATH environment variable to include directory
<code>${ant.home}/bin</code> in its list. This makes the <code>ant</code> command line script
available, which will be used to actually perform the build.
</p>
</section>
<section name="Checkout or obtain the Tomcat source code">
<p>
Tomcat SVN repository URL:
<a href="https://svn.apache.org/repos/asf/tomcat/tc8.5.x/trunk/">https://svn.apache.org/repos/asf/tomcat/tc8.5.x/trunk/</a>
</p>
<p>
Tomcat source packages:
<download>https://tomcat.apache.org/download-<version-major/>0.cgi</download>.
</p>
<p>
Checkout the source using SVN, selecting a tag for released version or
trunk for the current development code, or download and unpack a
source package. For the remainder of this guide, the symbolic name
<code>${tomcat.source}</code> is used to refer to the
location where the source has been placed.
</p>
</section>
<section name="Configure download area">
<p>
Building Tomcat involves downloading a number of libraries that it depends on.
It is strongly recommended to configure download area for those libraries.
</p>
<p>
By default the build is configured to download the dependencies into the
<code>${user.home}/tomcat-build-libs</code> directory. You can change this
(see below) but it must be an absolute path.
</p>
<p>
The build is controlled by creating a
<code>${tomcat.source}/build.properties</code> file. It can be used to
redefine any property that is present in <code>build.properties.default</code>
and <code>build.xml</code> files. The <code>build.properties</code> file
does not exist by default. You have to create it.
</p>
<p>
The download area is defined by property <code>base.path</code>. For example:
</p>
<source><![CDATA[# ----- Default Base Path for Dependent Packages -----
# Replace this path with the directory path where
# dependencies binaries should be downloaded.
base.path=/home/me/some-place-to-download-to]]></source>
<p>
Different versions of Tomcat are allowed to share the same download area.
</p>
<p>
Another example:
</p>
<source>base.path=${user.dir}/../libraries-tomcat<version-major-minor/></source>
<p>
Users who access the Internet through a proxy must use the properties
file to indicate to Ant the proxy configuration:
</p>
<source><![CDATA[# ----- Proxy setup -----
proxy.host=proxy.domain
proxy.port=8080
proxy.use=on]]></source>
</section>
<section name="Building Tomcat">
<p>
Use the following commands to build Tomcat:
</p>
<p>
<code>cd ${tomcat.source}</code><br/>
<code>ant</code>
</p>
<p>
Once the build has completed successfully, a usable Tomcat installation will have been
produced in the <code>${tomcat.source}/output/build</code> directory, and can be started
and stopped with the usual scripts.
</p>
</section>
<section name="Building with Eclipse">
<p>
<b>IMPORTANT:</b> This is not a supported means of building Tomcat; this information is
provided without warranty :-).
The only supported means of building Tomcat is with the Ant build described above.
However, some developers like to work on Java code with a Java IDE,
and the following steps have been used by some developers.
</p>
<p>
<b>NOTE:</b> This will not let you build everything under Eclipse;
the build process requires use of Ant for the many stages that aren't
simple Java compilations.
However, it will allow you to view and edit the Java code,
get warnings, reformat code, perform refactorings, run Tomcat
under the IDE, and so on.
</p>
<p>
<b>WARNING:</b> Do not forget to create and configure
<code>${tomcat.source}/build.properties</code> file as described above
before running any Ant targets.
</p>
<p>
Sample Eclipse project files and launch targets are provided in the
<code>res/ide-support/eclipse</code> directory of the source tree.
The instructions below will automatically copy these into the required locations.
</p>
<p>
An Ant target is provided as a convenience to download all binary dependencies, and to create
the Eclipse project and classpath files in the root of the source tree.
</p>
<p>
<code>cd ${tomcat.source}</code><br/>
<code>ant ide-eclipse</code>
</p>
<p>
Start Eclipse and create a new Workspace.
</p>
<p>
Open the <em>Preferences</em> dialog and then select <em>Java-&gt;Build Path-&gt;Classpath
Variables</em> to add two new <em>Classpath Variables</em>:
</p>
<table class="defaultTable">
<tr><td>TOMCAT_LIBS_BASE</td><td>The same location as the <code>base.path</code>
setting in <code>build.properties</code>, where the binary dependencies have been downloaded</td></tr>
<tr><td>ANT_HOME</td><td>the base path of Ant 1.9.8 or later</td></tr>
</table>
<p>
Use <em>File-&gt;Import</em> and choose <em>Existing Projects into Workspace</em>.
From there choose the root directory of the Tomcat source tree (<code>${tomcat.source}</code>)
and import the Tomcat project located there.
</p>
<p>
<code>start-tomcat</code> and <code>stop-tomcat</code> launch configurations are provided in
<code>res/ide-support/eclipse</code> and will be available in the <em>Run-&gt;Run Configurations</em>
dialog. Use these to start and stop Tomcat from Eclipse.
If you want to configure these yourself (or are using a different IDE)
then use <code>org.apache.catalina.startup.Bootstrap</code> as the main class,
<code>start</code>/<code>stop</code> etc. as program arguments, and specify <code>-Dcatalina.home=...</code>
(with the name of your build directory) as VM arguments.
</p>
<p>
Tweaking a few formatting preferences will make it much easier to keep consistent with Tomcat
coding conventions (and have your contributions accepted):
</p>
<table class="defaultTable">
<tr><td>Java -&gt; Code Style -> Formatter -&gt; Edit...</td>
<td>Tab policy: Spaces only<br/>Tab and Indentation size: 4</td></tr>
<tr><td>General -&gt; Editors -> Text Editors</td>
<td>Displayed tab width: 2<br/>Insert spaces for tabs<br/>Show whitespace characters (optional)</td></tr>
<tr><td>XML -&gt; XML Files -> Editor</td><td>Indent using spaces<br/>Indentation size: 2</td></tr>
<tr><td>Ant -&gt; Editor -> Formatter</td><td>Tab size: 2<br/>Use tab character instead of spaces: unchecked</td></tr>
</table>
<p>
The recommended configuration of Compiler Warnings is documented in
<code>res/ide-support/eclipse/java-compiler-errors-warnings.txt</code> file.
</p>
</section>
<section name="Building with other IDEs">
<p>
The same general approach should work for most IDEs; it has been reported
to work in IntelliJ IDEA, for example.
</p>
</section>
</body>
</document>

168
webapps/docs/cgi-howto.xml Normal file
View File

@@ -0,0 +1,168 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cgi-howto.html">
&project;
<properties>
<title>CGI How To</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The CGI (Common Gateway Interface) defines a way for a web server to
interact with external content-generating programs, which are often
referred to as CGI programs or CGI scripts.
</p>
<p>Within Tomcat, CGI support can be added when you are using Tomcat as your
HTTP server and require CGI support. Typically this is done
during development when you don't want to run a web server like
Apache httpd.
Tomcat's CGI support is largely compatible with Apache httpd's,
but there are some limitations (e.g., only one cgi-bin directory).
</p>
<p>CGI support is implemented using the servlet class
<code>org.apache.catalina.servlets.CGIServlet</code>. Traditionally,
this servlet is mapped to the URL pattern "/cgi-bin/*".</p>
<p>By default CGI support is disabled in Tomcat.</p>
</section>
<section name="Installation">
<p><strong>CAUTION</strong> - CGI scripts are used to execute programs
external to the Tomcat JVM. If you are using the Java SecurityManager this
will bypass your security policy configuration in <code>catalina.policy.</code></p>
<p>To enable CGI support:</p>
<ol>
<li><p>There are commented-out sample servlet and servlet-mapping elements for
CGI servlet in the default <code>$CATALINA_BASE/conf/web.xml</code> file.
To enable CGI support in your web application, copy that servlet and
servlet-mapping declarations into <code>WEB-INF/web.xml</code> file of your
web application.</p>
<p>Uncommenting the servlet and servlet-mapping in
<code>$CATALINA_BASE/conf/web.xml</code> file enables CGI for all installed
web applications at once.</p>
</li>
<li><p>Set <code>privileged="true"</code> on the Context element for your
web application.</p>
<p>Only Contexts which are marked as privileged are allowed to use the
CGI servlet. Note that modifying the global <code>$CATALINA_BASE/conf/context.xml</code>
file affects all web applications. See
<a href="config/context.html">Context documentation</a> for details.</p>
</li>
</ol>
</section>
<section name="Configuration">
<p>There are several servlet init parameters which can be used to
configure the behaviour of the CGI servlet.</p>
<ul>
<li><strong>cgiMethods</strong> - Comma separated list of HTTP methods. Requests
using one of these methods will be passed to the CGI script for the script to
generate the response. The default value is <code>GET,POST</code>. Use
<code>*</code> for the script to handle all requests regardless of method.
Unless over-ridden by the configuration of this parameter, requests using HEAD,
OPTIONS or TRACE will have handled by the superclass.</li>
<li><strong>cgiPathPrefix</strong> - The CGI search path will start at
the web application root directory + File.separator + this prefix.
By default there is no value, which results in the web application root
directory being used as the search path. The recommended value is
<code>WEB-INF/cgi</code></li>
<li><strong>cmdLineArgumentsDecoded</strong> - If command line argumemnts
are enabled (via <strong>enableCmdLineArguments</strong>) and Tomcat is running
on Windows then each individual decoded command line argument must match this
pattern else the request will be rejected. This is to protect against known
issues passing command line arguments from Java to Windows. These issues can
lead to remote code execution. For more information on these issues see
<a href="https://codewhitesec.blogspot.com/2016/02/java-and-command-line-injections-in-windows.html">Markus
Wulftange&apos;s blog</a> and this archived
<a href="https://web.archive.org/web/20161228144344/https://blogs.msdn.microsoft.com/twistylittlepassagesallalike/2011/04/23/everyone-quotes-command-line-arguments-the-wrong-way/">blog
by Daniel Colascione</a>.</li>
<li><strong>cmdLineArgumentsEncoded</strong> - If command line argumemnts
are enabled (via <strong>enableCmdLineArguments</strong>) individual encoded
command line argument must match this pattern else the request will be rejected.
The default matches the allowed values defined by RFC3875 and is
<code>[a-zA-Z0-9\Q%;/?:@&amp;,$-_.!~*'()\E]+</code></li>
<li><strong>enableCmdLineArguments</strong> - Are command line arguments
generated from the query string as per section 4.4 of 3875 RFC? The default is
<code>false</code>.</li>
<li><strong>environment-variable-</strong> - An environment to be set for the
execution environment of the CGI script. The name of variable is taken from the
parameter name. To configure an environment variable named FOO, configure a
parameter named environment-variable-FOO. The parameter value is used as the
environment variable value. The default is no environment variables.</li>
<li><strong>executable</strong> - The name of the executable to be used to
run the script. You may explicitly set this parameter to be an empty string
if your script is itself executable (e.g. an exe file). Default is
<code>perl</code>.</li>
<li><strong>executable-arg-1</strong>, <strong>executable-arg-2</strong>,
and so on - additional arguments for the executable. These precede the
CGI script name. By default there are no additional arguments.</li>
<li><strong>envHttpHeaders</strong> - A regular expression used to select the
HTTP headers passed to the CGI process as environment variables. Note that
headers are converted to upper case before matching and that the entire header
name must match the pattern. Default is
<code>ACCEPT[-0-9A-Z]*|CACHE-CONTROL|COOKIE|HOST|IF-[-0-9A-Z]*|REFERER|USER-AGENT</code>
</li>
<li><strong>parameterEncoding</strong> - Name of the parameter encoding
to be used with the CGI servlet. Default is
<code>System.getProperty("file.encoding","UTF-8")</code>. That is the system
default encoding, or UTF-8 if that system property is not available.</li>
<li><strong>passShellEnvironment</strong> - Should the shell environment
variables from Tomcat process (if any) be passed to the CGI script? Default is
<code>false</code>.</li>
<li><strong>stderrTimeout</strong> - The time (in milliseconds) to wait for
the reading of stderr to complete before terminating the CGI process. Default
is <code>2000</code>.</li>
</ul>
<p>The CGI script executed depends on the configuration of the CGI Servlet and
how the request is mapped to the CGI Servlet. The CGI search path starts at the
web application root directory + File.separator + cgiPathPrefix. The
<strong>pathInfo</strong> is then searched unless it is <code>null</code> - in
which case the <strong>servletPath</strong> is searched.</p>
<p>The search starts with the first path segment and expands one path segment
at a time until no path segments are left (resulting in a 404) or a script is
found. Any remaining path segments are passed to the script in the
<strong>PATH_INFO</strong> environment variable.</p>
</section>
</body>
</document>

7757
webapps/docs/changelog.xml Normal file
View File

File diff suppressed because it is too large Load Diff

292
webapps/docs/class-loader-howto.xml Normal file
View File

@@ -0,0 +1,292 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="class-loader-howto.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>Class Loader How-To</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<p>Like many server applications, Tomcat installs a variety of class loaders
(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow
different portions of the container, and the web applications running on the
container, to have access to different repositories of available classes and
resources. This mechanism is used to provide the functionality defined in the
Servlet Specification, version 2.4&#160;&#8212; in particular, Sections 9.4
and 9.6.</p>
<p>In a Java environment, class loaders are
arranged in a parent-child tree. Normally, when a class loader is asked to
load a particular class or resource, it delegates the request to a parent
class loader first, and then looks in its own repositories only if the parent
class loader(s) cannot find the requested class or resource. Note, that the
model for web application class loaders <em>differs</em> slightly from this,
as discussed below, but the main principles are the same.</p>
<p>When Tomcat is started, it creates a set of class loaders that are
organized into the following parent-child relationships, where the parent
class loader is above the child class loader:</p>
<source> Bootstrap
|
System
|
Common
/ \
Webapp1 Webapp2 ...</source>
<p>The characteristics of each of these class loaders, including the source
of classes and resources that they make visible, are discussed in detail in
the following section.</p>
</section>
<section name="Class Loader Definitions">
<p>As indicated in the diagram above, Tomcat creates the following class
loaders as it is initialized:</p>
<ul>
<li><p><strong>Bootstrap</strong> &#8212; This class loader contains the basic
runtime classes provided by the Java Virtual Machine, plus any classes from
JAR files present in the System Extensions directory
(<code>$JAVA_HOME/jre/lib/ext</code>). <em>Note</em>: some JVMs may
implement this as more than one class loader, or it may not be visible
(as a class loader) at all.</p></li>
<li><p><strong>System</strong> &#8212; This class loader is normally initialized
from the contents of the <code>CLASSPATH</code> environment variable. All
such classes are visible to both Tomcat internal classes, and to web
applications. However, the standard Tomcat startup scripts
(<code>$CATALINA_HOME/bin/catalina.sh</code> or
<code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
of the <code>CLASSPATH</code> environment variable itself, and instead
build the System class loader from the following repositories:
</p>
<ul>
<li><p><em>$CATALINA_HOME/bin/bootstrap.jar</em> &#8212; Contains the
main() method that is used to initialize the Tomcat server, and the
class loader implementation classes it depends on.</p></li>
<li><p><em>$CATALINA_BASE/bin/tomcat-juli.jar</em> or
<em>$CATALINA_HOME/bin/tomcat-juli.jar</em> &#8212; Logging
implementation classes. These include enhancement classes to
<code>java.util.logging</code> API, known as Tomcat JULI,
and a package-renamed copy of Apache Commons Logging library
used internally by Tomcat.
See <a href="logging.html">logging documentation</a> for more
details.</p>
<p>If <code>tomcat-juli.jar</code> is present in
<em>$CATALINA_BASE/bin</em>, it is used instead of the one in
<em>$CATALINA_HOME/bin</em>. It is useful in certain logging
configurations</p></li>
<li><p><em>$CATALINA_HOME/bin/commons-daemon.jar</em> &#8212; The classes
from <a href="https://commons.apache.org/daemon/">Apache Commons
Daemon</a> project.
This JAR file is not present in the <code>CLASSPATH</code> built by
<code>catalina.bat</code>|<code>.sh</code> scripts, but is referenced
from the manifest file of <em>bootstrap.jar</em>.</p></li>
</ul>
</li>
<li><p><strong>Common</strong> &#8212; This class loader contains additional
classes that are made visible to both Tomcat internal classes and to all
web applications.</p>
<p>Normally, application classes should <strong>NOT</strong>
be placed here. The locations searched by this class loader are defined by
the <code>common.loader</code> property in
$CATALINA_BASE/conf/catalina.properties. The default setting will search the
following locations in the order they are listed:</p>
<ul>
<li>unpacked classes and resources in <code>$CATALINA_BASE/lib</code></li>
<li>JAR files in <code>$CATALINA_BASE/lib</code></li>
<li>unpacked classes and resources in <code>$CATALINA_HOME/lib</code></li>
<li>JAR files in <code>$CATALINA_HOME/lib</code></li>
</ul>
<p>By default, this includes the following:</p>
<ul>
<li><em>annotations-api.jar</em> &#8212; JavaEE annotations classes.</li>
<li><em>catalina.jar</em> &#8212; Implementation of the Catalina servlet
container portion of Tomcat.</li>
<li><em>catalina-ant.jar</em> &#8212; Tomcat Catalina Ant tasks.</li>
<li><em>catalina-ha.jar</em> &#8212; High availability package.</li>
<li><em>catalina-storeconfig.jar</em> &#8212; Generation of XML
configuration files from current state</li>
<li><em>catalina-tribes.jar</em> &#8212; Group communication package.</li>
<li><em>ecj-*.jar</em> &#8212; Eclipse JDT Java compiler.</li>
<li><em>el-api.jar</em> &#8212; EL 3.0 API.</li>
<li><em>jasper.jar</em> &#8212; Tomcat Jasper JSP Compiler and Runtime.</li>
<li><em>jasper-el.jar</em> &#8212; Tomcat Jasper EL implementation.</li>
<li><em>jsp-api.jar</em> &#8212; JSP 2.3 API.</li>
<li><em>servlet-api.jar</em> &#8212; Servlet 3.1 API.</li>
<li><em>tomcat-api.jar</em> &#8212; Several interfaces defined by Tomcat.</li>
<li><em>tomcat-coyote.jar</em> &#8212; Tomcat connectors and utility classes.</li>
<li><em>tomcat-dbcp.jar</em> &#8212; Database connection pool
implementation based on package-renamed copy of Apache Commons Pool 2
and Apache Commons DBCP 2.</li>
<li><em>tomcat-i18n-**.jar</em> &#8212; Optional JARs containing resource bundles
for other languages. As default bundles are also included in each
individual JAR, they can be safely removed if no internationalization
of messages is needed.</li>
<li><em>tomcat-jdbc.jar</em> &#8212; An alternative database connection pool
implementation, known as Tomcat JDBC pool. See
<a href="jdbc-pool.html">documentation</a> for more details.</li>
<li><em>tomcat-util.jar</em> &#8212; Common classes used by various components of
Apache Tomcat.</li>
<li><em>tomcat-websocket.jar</em> &#8212; WebSocket 1.1 implementation</li>
<li><em>websocket-api.jar</em> &#8212; WebSocket 1.1 API</li>
</ul></li>
<li><p><strong>WebappX</strong> &#8212; A class loader is created for each web
application that is deployed in a single Tomcat instance. All unpacked
classes and resources in the <code>/WEB-INF/classes</code> directory of
your web application, plus classes and resources in JAR files
under the <code>/WEB-INF/lib</code> directory of your web application,
are made visible to this web application, but not to other ones.</p></li>
</ul>
<p>As mentioned above, the web application class loader diverges from the
default Java delegation model (in accordance with the recommendations in the
Servlet Specification, version 2.4, section 9.7.2 Web Application Classloader).
When a request to load a
class from the web application's <em>WebappX</em> class loader is processed,
this class loader will look in the local repositories <strong>first</strong>,
instead of delegating before looking. There are exceptions. Classes which are
part of the JRE base classes cannot be overridden. There are some exceptions
such as the XML parser components which can be overridden using the appropriate
JVM feature which is the endorsed standards override feature for Java &lt;= 8
and the upgradeable modules feature for Java 9+.
Lastly, the web application class loader will always delegate first for JavaEE
API classes for the specifications implemented by Tomcat
(Servlet, JSP, EL, WebSocket). All other class loaders in Tomcat follow the
usual delegation pattern.</p>
<p>Therefore, from the perspective of a web application, class or resource
loading looks in the following repositories, in this order:</p>
<ul>
<li>Bootstrap classes of your JVM</li>
<li><em>/WEB-INF/classes</em> of your web application</li>
<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
<li>System class loader classes (described above)</li>
<li>Common class loader classes (described above)</li>
</ul>
<p>If the web application class loader is
<a href="config/loader.html">configured</a> with
<code>&lt;Loader delegate=&quot;true&quot;/&gt;</code>
then the order becomes:</p>
<ul>
<li>Bootstrap classes of your JVM</li>
<li>System class loader classes (described above)</li>
<li>Common class loader classes (described above)</li>
<li><em>/WEB-INF/classes</em> of your web application</li>
<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
</ul>
</section>
<section name="XML Parsers and Java">
<p>Starting with Java 1.4 a copy of JAXP APIs and an XML parser are packed
inside the JRE. This has impacts on applications that wish to use their own
XML parser.</p>
<p>In old versions of Tomcat, you could simply replace the XML parser
in the Tomcat libraries directory to change the parser
used by all web applications. However, this technique will not be effective
when you are running modern versions of Java, because the usual class loader
delegation process will always choose the implementation inside the JDK in
preference to this one.</p>
<p>Java &lt;= 8 supports a mechanism called the "Endorsed Standards Override
Mechanism" to allow replacement of APIs created outside of the JCP
(i.e. DOM and SAX from W3C). It can also be used to update the XML parser
implementation. For more information, see:
<a href="http://docs.oracle.com/javase/1.5.0/docs/guide/standards/index.html">
http://docs.oracle.com/javase/1.5.0/docs/guide/standards/index.html</a>. For
Java 9+, use the upgradeable modules feature.</p>
<p>Tomcat utilizes the endorsed mechanism by including the system property setting
<code>-Djava.endorsed.dirs=$JAVA_ENDORSED_DIRS</code> in the
command line that starts the container. The default value of this option is
<em>$CATALINA_HOME/endorsed</em>. This <em>endorsed</em> directory is not
created by default. Note that the endorsed feature is no longer supported
with Java 9 and the above system property will only be set if either the
directory <em>$CATALINA_HOME/endorsed</em> exists, or the variable
<code>JAVA_ENDORSED_DIRS</code> has been set.
</p>
<p>Note that overriding any JRE component carries risk. If the overriding
component does not provide a 100% compatible API (e.g. the API provided by
Xerces is not 100% compatible with the XML API provided by the JRE) then there
is a risk that Tomcat and/or the deployed application will experience errors.</p>
</section>
<section name="Running under a security manager">
<p>When running under a security manager the locations from which classes
are permitted to be loaded will also depend on the contents of your policy
file. See <a href="security-manager-howto.html">Security Manager How-To</a>
for further information.</p>
</section>
<section name="Advanced configuration">
<p>A more complex class loader hierarchy may also be configured. See the diagram
below. By default, the <strong>Server</strong> and <strong>Shared</strong>
class loaders are not defined and the simplifed hierarchy shown above is used.
This more complex hierarchy may be use by defining values for the
<code>server.loader</code> and/or <code>shared.loader</code> properties in
<code>conf/catalina.properties</code>.</p>
<source>
Bootstrap
|
System
|
Common
/ \
Server Shared
/ \
Webapp1 Webapp2 ...</source>
<p>The <strong>Server</strong> class loader is only visible to Tomcat internals
and is completely invisible to web applications.</p>
<p>The <strong>Shared</strong> class loader is visible to all web applications
and may be used to shared code across all web applications. However, any updates
to this shared code will require a Tomcat restart.</p>
</section>
</body>
</document>

689
webapps/docs/cluster-howto.xml Normal file
View File

File diff suppressed because it is too large Load Diff

118
webapps/docs/comments.xml Normal file
View File

@@ -0,0 +1,118 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="comments.html">
&project;
<properties>
<title>Documentation User Comments</title>
</properties>
<body>
<section name="Introduction">
<p>The Tomcat documentation integrates the
<a href="https://comments.apache.org/help.html">Apache Comments System</a>.
It allows users to add comments to most documentation pages. The comments
section can be found at the end of each page.</p>
</section>
<section name="Allowed Content">
<p>Please use the Apache Comments System responsibly. We can only provide
this service to the community as long as it isn't misused.</p>
<p>The comments are not for general Q&amp;A.
Comments should be pointed towards suggestions on improving the documentation
or server. Questions on how to use Apache Tomcat should be directed
to our <a href="https://tomcat.apache.org/lists.html">mailing lists</a>.</p>
<p>Comments may be removed by moderators if they are either
implemented or considered invalid/off-topic.</p>
<p>HTML is not allowed in comments, and will just display as raw source code
if attempted. Links that do not point to an Apache site (*.apache.org) will
need approval by a moderator before the comment is visible to regular visitors.</p>
</section>
<section name="License">
<p>Any submitted comments must be contributed under the terms of the
<a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
</section>
<section name="Verified Users">
<p>Verified users gain the Apache feather next to their name,
and may post comments with links in them without requiring approval
by a moderator before the comments are shown. Being a verified user
in itself does not give you moderating rights. If you are interested
in becoming a verified user, please contact us on the
<a href="https://tomcat.apache.org/lists.html#tomcat-users">users mailing list</a>.</p>
<p>All ASF committers are automatically verified users.</p>
</section>
<section name="Moderators">
<p>Moderators are allowed to mark comments as "Resolved", "Invalid"
or "Sticky", remove marks, approve comments e.g. if they contain
a link, and delete comments. Moderators can also subscribe to new
comments and comment updates and use the dashboard to gain some
overview over all comments of a site.</p>
<p>To use the moderation features, you need to login to the comments
system. Furthermore you will need to allow cookies to be set for
comments.apache.org (this is done using a secure https cookie). Once
logged in as a moderator you will see additional moderation
options attached to each comment.</p>
<p>If you are a long time follower of the Apache Tomcat projects
and you are interested in becoming a moderator, please contact us on the
<a href="https://tomcat.apache.org/lists.html#tomcat-users">users mailing list</a>.</p>
</section>
<section name="Privacy Policy">
<p>No data except what you personally submit is kept on record.
A cookie is used to keep track of moderators and other people
who wish to create an account to avoid having to enter their
credentials whenever they wish to post a comment.</p>
<p>To prevent spam and unsolicited comments, we use a digest of
visitors' IPs to keep track of comments posted by them.</p>
<p>Entering an email address when you post a comment is completely
optional, and will not be shared with anyone. If you enter an
email address, it will be used to notify you when someone posts
a reply to one of your comments, provided you have registered
an account and validated your email address.</p>
</section>
</body>
</document>

888
webapps/docs/config/ajp.xml Normal file
View File

File diff suppressed because it is too large Load Diff

548
webapps/docs/config/automatic-deployment.xml Normal file
View File

File diff suppressed because it is too large Load Diff

146
webapps/docs/config/cluster-channel.xml Normal file
View File

@@ -0,0 +1,146 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-channel.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Channel object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
The cluster channel is the main component of a small framework we've nicknamed Apache Tribes.<br/>
The channel manages a set of sub components and together they create a group communication framework.<br/>
This framework is then used internally by the components that need to send messages between different Tomcat instances.
<br/>
A few examples of these components would be the SimpleTcpCluster that does the messaging for the DeltaManager,
or the BackupManager that uses a different replication strategy. The ReplicatedContext object does also
use the channel object to communicate context attribute changes.
</section>
<section name="Nested Components">
<p><b><a href="cluster-membership.html">Channel/Membership</a>:</b> <br/>
The Membership component is responsible for auto discovering new nodes in the cluster
and also to provide for notifications for any nodes that have not responded with a heartbeat.
The default implementation uses multicast.<br/>
In the membership component you configure how your nodes, aka. members, are to be discovered and/or
divided up.
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
<p><b><a href="cluster-sender.html">Channel/Sender</a>:</b> <br/>
The Sender component manages all outbound connections and data messages that are sent
over the network from one node to another.
This component allows messages to be sent in parallel.
The default implementation uses TCP client sockets, and socket tuning for outgoing messages are
configured here.<br/>
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
<p><b><a href="cluster-sender.html#transport">Channel/Sender/Transport</a>:</b> <br/>
The Transport component is the bottom IO layer for the sender component.
The default implementation uses non-blocking TCP client sockets.<br/>
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
<p><b><a href="cluster-receiver.html">Channel/Receiver</a>:</b> <br/>
The receiver component listens for messages from other nodes.
Here you will configure the cluster thread pool, as it will dispatch incoming
messages to a thread pool for faster processing.
The default implementation uses non-blocking TCP server sockets.<br/>
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
<p><b><a href="cluster-interceptor.html">Channel/Interceptor</a>:</b> <br/>
The channel will send messages through an interceptor stack. Because of this, you have the ability to
customize the way messages are sent and received, and even how membership is handled.<br/>
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
The default value here is <code>org.apache.catalina.tribes.group.GroupChannel</code> and is
currently the only implementation available.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.GroupChannel Attributes">
<attributes>
<attribute name="heartbeat" required="false">
Flag whether the channel manages its own heartbeat.
If set to true, the channel start a local thread for the heart beat.
If set this flag to false, you must set SimpleTcpCluster#heartbeatBackgroundEnabled
to true. default value is true.
</attribute>
<attribute name="heartbeatSleeptime" required="false">
If heartbeat == true, specifies the interval of heartbeat thread in milliseconds.
The default is 5000 (5 seconds).
</attribute>
<attribute name="optionCheck" required="false">
If set to true, the GroupChannel will check the option flags that each
interceptor is using. Reports an error if two interceptor share the same
flag. The default is false.
</attribute>
<attribute name="jmxEnabled" required="false">
Flag whether the channel components register with JMX or not.
The default value is true.
</attribute>
<attribute name="jmxDomain" required="false">
if <code>jmxEnabled</code> set to true, specifies the jmx domain which
this channel should be registered. The ClusterChannel is used as the
default value.
</attribute>
<attribute name="jmxPrefix" required="false">
if <code>jmxEnabled</code> set to true, specifies the jmx prefix which
will be used with channel ObjectName.
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

105
webapps/docs/config/cluster-deployer.xml Normal file
View File

@@ -0,0 +1,105 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-deployer.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Deployer object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The Farm War Deployer can deploy and undeploy web applications on the other
nodes in the cluster.</p>
<p><strong>Note:</strong> FarmWarDeployer can be configured at host level
cluster only.
</p>
</section>
<section name="org.apache.catalina.ha.deploy.FarmWarDeployer">
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
The cluster deployer class, currently only one is available,
<code>org.apache.catalina.ha.deploy.FarmWarDeployer.</code>
</attribute>
<attribute name="deployDir" required="true">
Deployment directory. This is the pathname of a directory where deploy
the web applications. You may specify an absolute pathname, or a
pathname that is relative to the $CATALINA_BASE directory. In the
current implementation, this attribute must be the same value as the
<strong>Host's appBase</strong>.
</attribute>
<attribute name="tempDir" required="true">
The temporaryDirectory to store binary data when downloading a war from
the cluster. You may specify an absolute pathname, or a pathname that is
relative to the $CATALINA_BASE directory.
</attribute>
<attribute name="watchDir" required="false">
This is the pathname of a directory where watch for changes(add/modify/remove)
of web applications. You may specify an absolute pathname, or a pathname
that is relative to the $CATALINA_BASE directory.
<strong>Note: </strong> if <strong>watchEnabled</strong> is false, this
attribute will have no effect.
</attribute>
<attribute name="watchEnabled" required="false">
Set to true if you want to watch for changes of web applications.
Only when this attribute set to true, you can trigger a deploy/undeploy
of web applications. The flag's value defaults to false.
</attribute>
<attribute name="processDeployFrequency" required="false">
Frequency of the Farm watchDir check. Cluster wide deployment will be
done once for the specified amount of backgroundProcess calls (ie, the
lower the amount, the most often the checks will occur). The minimum
value is 1, and the default value is 2.
<strong>Note: </strong> if <strong>watchEnabled</strong> is false, this
attribute will have no effect.
</attribute>
<attribute name="maxValidTime" required="false">
The maximum valid time(in seconds) of FileMessageFactory.
FileMessageFactory will be removed immediately after receiving the
complete WAR file but when failing to receive a FileMessage which was
sent dividing, FileMessageFactory will leak without being removed.
FileMessageFactory that is leaking will be automatically removed after
maxValidTime. If a negative value specified, FileMessageFactory will
never be removed. If the attribute is not provided, a default of 300
seconds (5 minutes) is used.
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

320
webapps/docs/config/cluster-interceptor.xml Normal file
View File

@@ -0,0 +1,320 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-interceptor.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Channel Interceptor object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
Apache Tribes supports an interceptor architecture to intercept both messages and membership notifications.
This architecture allows decoupling of logic and opens the way for some very useful feature add ons.
</p>
</section>
<section name="Available Interceptors">
<ul>
<li><code>org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.NonBlockingCoordinator</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.OrderInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.SimpleCoordinator</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.TwoPhaseCommitInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.GzipInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.EncryptInterceptor</code></li>
</ul>
</section>
<section name="Static Membership">
<p>
In addition to dynamic discovery, Apache Tribes also supports static membership, with membership verification.
To achieve this add the <code>org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor</code>
after the <code>org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</code> interceptor.
Inside the <code>StaticMembershipInterceptor</code> you can add the static members you wish to have.
The <code>TcpFailureDetector</code> will do a health check on the static members,and also monitor them for crashes
so they will have the same level of notification mechanism as the members that are automatically discovered.</p>
<source><![CDATA[ <Interceptor className="org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor">
<LocalMember className="org.apache.catalina.tribes.membership.StaticMember"
domain="staging-cluster"
uniqueId="{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1}"/>
<Member className="org.apache.catalina.tribes.membership.StaticMember"
port="5678"
securePort="-1"
host="tomcat01.mydomain.com"
domain="staging-cluster"
uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/>
</Interceptor>]]></source>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
Required, as there is no default
</attribute>
<attribute name="optionFlag" required="false">
If you want the interceptor to trigger on certain message depending on the message's option flag,
you can setup the interceptors flag here.
The default value is <code>0</code>, meaning this interceptor will trigger on all messages.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor Attributes">
<attributes>
<attribute name="domain" required="true">
The logical cluster domain that this Interceptor accepts.
Two different type of values are possible:<br/>
1. Regular string values like &quot;staging-domain&quot; or &quot;tomcat-cluster&quot; will be converted into bytes
using ISO-8859-1 encoding.<br/>
2. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="logInterval" required="false">
This value indicates the interval for logging for messages from different domains.
The default is 100, which means that to log per 100 messages.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor Attributes">
<attributes>
<attribute name="expire" required="false">
How long do we keep the fragments in memory and wait for the rest to arrive.
The default is 60000 ms.
</attribute>
<attribute name="maxSize" required="false">
The maximum message size in bytes. If the message size exceeds this value, this interceptor fragments the message and sends them.
If it is less than this value, this interceptor does not fragment the message and sent in as one message. The default is 1024*100.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor Attributes">
<attributes>
<attribute name="optionFlag" required="false">
The default and hard coded value is <code>8 (org.apache.catalina.tribes.Channel.SEND_OPTIONS_ASYNCHRONOUS)</code>.
The dispatcher will trigger on this value only, as it is predefined by Tribes.
</attribute>
<attribute name="alwaysSend" required="false">
What behavior should be executed when the dispatch queue is full. If <code>true</code> (default), then the message is
is sent synchronously, if <code>false</code> an error is thrown.
</attribute>
<attribute name="maxQueueSize" required="false">
Size in bytes of the dispatch queue, the default value is <code> 1024*1024*64 (64MB)</code> sets the maximum queue size for the dispatch queue
if the queue fills up, one can trigger the behavior, if <code>alwaysSend</code> is set to true, the message will be sent synchronously
if the flag is false, an error is thrown
</attribute>
<attribute name="maxThreads" required="false">
The maximum number of threads in this pool, default is 10.
</attribute>
<attribute name="maxSpareThreads" required="false">
The number of threads to keep in the pool, default is 2.
</attribute>
<attribute name="keepAliveTime" required="false">
Maximum number of milliseconds of until Idle thread terminates. Default value is 5000(5 seconds).
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector Attributes">
<attributes>
<attribute name="connectTimeout" required="false">
Specifies the timeout, in milliseconds, to use when attempting a TCP connection
to the suspect node. Default is 1000.
</attribute>
<attribute name="performSendTest" required="false">
If true is set, send a test message to the suspect node. Default is true.
</attribute>
<attribute name="performReadTest" required="false">
If true is set, read the response of the test message that sent. Default is false.
<strong>Note:</strong> if <code>performSendTest</code> is false, this attribute will have no effect.
</attribute>
<attribute name="readTestTimeout" required="false">
Specifies the timeout, in milliseconds, to use when performing a read test
to the suspicious node. Default is 5000.
</attribute>
<attribute name="removeSuspectsTimeout" required="false">
The maximum time(in seconds) for remove from removeSuspects. Member of
removeSuspects will be automatically removed after removeSuspectsTimeout.
If a negative value specified, the removeSuspects members never be
removed until disappeared really. If the attribute is not provided,
a default of 300 seconds (5 minutes) is used.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor Attributes">
<attributes>
<attribute name="interval" required="false">
If useThread == true, defines the interval of sending a ping message.
default is 1000 ms.
</attribute>
<attribute name="useThread" required="false">
Flag of whether to start a thread for sending a ping message.
If set to true, this interceptor will start a local thread for sending a ping message.
if set to false, channel heartbeat will send a ping message.
default is false.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor Attributes">
<attributes>
<attribute name="interval" required="false">
Defines the interval in number of messages when we are to report the throughput statistics.
The report is logged to the <code>org.apache.juli.logging.LogFactory.getLog(ThroughputInterceptor.class)</code>
logger under the <code>INFO</code> level.
Default value is to report every <code>10000</code> messages.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.EncryptInterceptor Attributes">
<p>
The EncryptInterceptor adds encryption to the channel messages carrying
session data between nodes. Added in Tomcat 9.0.13.
</p>
<p>
If using the <code>TcpFailureDetector</code>, the <code>EncryptInterceptor</code>
<i>must</i> be inserted into the interceptor chain <i>before</i> the
<code>TcpFailureDetector</code>. This is because when validating cluster
members, <code>TcpFailureDetector</code> writes channel data directly
to the other members without using the remainder of the interceptor chain,
but on the receiving side, the message still goes through the chain (in reverse).
Because of this asymmetry, the <code>EncryptInterceptor</code> must execute
<i>before</i> the <code>TcpFailureDetector</code> on the sender and <i>after</i>
it on the receiver, otherwise message corruption will occur.
</p>
<attributes>
<attribute name="encryptionAlgorithm" required="false">
The encryption algorithm to be used, including the mode and padding. Please see
<a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html">https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html</a>
for the standard JCA names that can be used.
EncryptInterceptor currently supports the following
<a href="https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation">block-cipher modes</a>:
CBC, OFB, CFB, and GCM.
The length of the key will specify the flavor of the encryption algorithm
to be used, if applicable (e.g. AES-128 versus AES-256).
The default algorithm is <code>AES/CBC/PKCS5Padding</code>.
</attribute>
<attribute name="encryptionKey" required="true">
The key to be used with the encryption algorithm.
The key should be specified as hex-encoded bytes of the appropriate
length for the algorithm (e.g. 16 bytes / 32 characters / 128 bits for
AES-128, 32 bytes / 64 characters / 256 bits for AES-256, etc.).
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<subsection name="StaticMember Attributes">
<p><b>LocalMember:</b> <br/>
Static member that is the local member of the static cluster group.
</p>
<attributes>
<attribute name="className" required="true">
Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
</attribute>
<attribute name="port" required="false">
There is no need to set.
The value of this attribute inherits from the cluster receiver setting.
</attribute>
<attribute name="securePort" required="false">
There is no need to set.
The value of this attribute inherits from the cluster receiver setting.
</attribute>
<attribute name="host" required="false">
There is no need to set.
The value of this attribute inherits from the cluster receiver setting.
</attribute>
<attribute name="domain" required="false">
The logical cluster domain for that this static member listens for cluster messages.
Two different type of values are possible:<br/>
1. Regular string values like &quot;staging-domain&quot; or &quot;tomcat-cluster&quot; will be converted into bytes
using ISO-8859-1 encoding.
2. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="uniqueId" required="true">
A universally uniqueId for this static member.
The values must be 16 bytes in the following form:<br/>
1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br/>
</attribute>
</attributes>
<p><b>Member:</b> <br/>
Static member that add to the static cluster group.
</p>
<attributes>
<attribute name="className" required="true">
Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
</attribute>
<attribute name="port" required="true">
The port that this static member listens to for cluster messages
</attribute>
<attribute name="securePort" required="false">
The secure port this static member listens to for encrypted cluster messages
default value is <code>-1</code>, this value means the member is not listening on a secure port
</attribute>
<attribute name="host" required="true">
The host (or network interface) that this static member listens for cluster messages.
Three different type of values are possible:<br/>
1. IP address in the form of &quot;216.123.1.23&quot;<br/>
2. Hostnames like &quot;tomcat01.mydomain.com&quot; or &quot;tomcat01&quot; as long as they resolve correctly<br/>
3. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="domain" required="false">
The logical cluster domain for that this static member listens for cluster messages.
Two different type of values are possible:<br/>
1. Regular string values like &quot;staging-domain&quot; or &quot;tomcat-cluster&quot; will be converted into bytes
using ISO-8859-1 encoding.<br/>
2. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="uniqueId" required="true">
A universally uniqueId for this static member.
The values must be 16 bytes in the following form:<br/>
1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br/>
</attribute>
</attributes>
</subsection>
<!--TODO Document all the interceptors-->
</section>
</body>
</document>

72
webapps/docs/config/cluster-listener.xml Normal file
View File

@@ -0,0 +1,72 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-listener.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The ClusterListener object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
The <code>org.apache.catalina.ha.ClusterListener</code> base class
lets you listen in on messages that are received by the <code>Cluster</code> component.
</p>
</section>
<section name="org.apache.catalina.ha.session.ClusterSessionListener">
<p>
When using the DeltaManager, the messages are received by the Cluster object and are propagated to the
to the manager through this listener.
</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

293
webapps/docs/config/cluster-manager.xml Normal file
View File

@@ -0,0 +1,293 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-manager.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The ClusterManager object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>A cluster manager is an extension to Tomcat's session manager interface,
<code>org.apache.catalina.Manager</code>.
A cluster manager must implement the
<code>org.apache.catalina.ha.ClusterManager</code> and is solely responsible
for how the session is replicated.<br/>
There are currently two different managers, the
<code>org.apache.catalina.ha.session.DeltaManager</code> replicates deltas of
session data to all members in the cluster. This implementation is proven and
works very well, but has a limitation as it requires the cluster members to be
homogeneous, all nodes must deploy the same applications and be exact
replicas. The <code>org.apache.catalina.ha.session.BackupManager</code> also
replicates deltas but only to one backup node. The location of the backup node
is known to all nodes in the cluster. It also supports heterogeneous
deployments, so the manager knows at what locations the web application is
deployed.</p>
</section>
<section name="The &lt;Manager&gt;">
<p>The <code>&lt;Manager&gt;</code> element defined inside the
<code>&lt;Cluster&gt;</code> element is the template defined for all web
applications that are marked <code>&lt;distributable/&gt;</code> in their
<code>web.xml</code> file. However, you can still override the manager
implementation on a per web application basis, by putting the
<code>&lt;Manager&gt;</code> inside the <code>&lt;Context&gt;</code> element
either in the <code><a href="context.html">context.xml</a></code> file or the
<code><a href="index.html">server.xml</a></code> file.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
</attribute>
<attribute name="name" required="false">
<b>The name of this cluster manager, the name is used to identify a
session manager on a node. The name might get modified by the
<code>Cluster</code> element to make it unique in the container.</b>
</attribute>
<attribute name="notifyListenersOnReplication" required="false">
Set to <code>true</code> if you wish to have session listeners notified
when session attributes are being replicated or removed across Tomcat
nodes in the cluster.
</attribute>
<attribute name="processExpiresFrequency" required="false">
<p>Frequency of the session expiration, and related manager operations.
Manager operations will be done once for the specified amount of
backgroundProcess calls (i.e., the lower the amount, the more often the
checks will occur). The minimum value is 1, and the default value is 6.
</p>
</attribute>
<attribute name="secureRandomClass" required="false">
<p>Name of the Java class that extends
<code>java.security.SecureRandom</code> to use to generate session IDs.
If not specified, the default value is
<code>java.security.SecureRandom</code>.</p>
</attribute>
<attribute name="secureRandomProvider" required="false">
<p>Name of the provider to use to create the
<code>java.security.SecureRandom</code> instances that generate session
IDs. If an invalid algorithm and/or provider is specified, the Manager
will use the platform default provider and the default algorithm. If not
specified, the platform default provider will be used.</p>
</attribute>
<attribute name="secureRandomAlgorithm" required="false">
<p>Name of the algorithm to use to create the
<code>java.security.SecureRandom</code> instances that generate session
IDs. If an invalid algorithm and/or provider is specified, the Manager
will use the platform default provider and the default algorithm. If not
specified, the default algorithm of SHA1PRNG will be used. If the
default algorithm is not supported, the platform default will be used.
To specify that the platform default should be used, do not set the
secureRandomProvider attribute and set this attribute to the empty
string.</p>
</attribute>
<attribute name="recordAllActions" required="false">
<p>Flag whether send all actions for session across Tomcat cluster
nodes. If set to false, if already done something to the same attribute,
make sure don't send multiple actions across Tomcat cluster nodes.
In that case, sends only the actions that have been added at last.
Default is <code>false</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.ha.session.DeltaManager Attributes">
<attributes>
<attribute name="expireSessionsOnShutdown" required="false">
When a web application is being shutdown, Tomcat issues an expire call
to each session to notify all the listeners. If you wish for all
sessions to expire on all nodes when a shutdown occurs on one node, set
this value to <code>true</code>.
Default value is <code>false</code>.
</attribute>
<attribute name="maxActiveSessions" required="false">
The maximum number of active sessions that will be created by this
Manager, or -1 (the default) for no limit. For this manager, all
sessions are counted as active sessions irrespective if whether or not
the current node is the primary node for the session.
</attribute>
<attribute name="notifySessionListenersOnReplication" required="false">
Set to <code>true</code> if you wish to have session listeners notified
when sessions are created and expired across Tomcat nodes in the
cluster.
</attribute>
<attribute name="notifyContainerListenersOnReplication" required="false">
Set to <code>true</code> if you wish to have container listeners notified
across Tomcat nodes in the cluster.
</attribute>
<attribute name="stateTransferTimeout" required="false">
The time in seconds to wait for a session state transfer to complete
from another node when a node is starting up.
Default value is <code>60</code> seconds.
</attribute>
<attribute name="sendAllSessions" required="false">
Flag whether send sessions as split blocks.
If set to <code>true</code>, send all sessions as one big block.
If set to <code>false</code>, send sessions as split blocks.
Default value is <code>true</code>.
</attribute>
<attribute name="sendAllSessionsSize" required="false">
The number of sessions in a session block message. This value is
effective only when <code>sendAllSessions</code> is <code>false</code>.
Default is <code>1000</code>.
</attribute>
<attribute name="sendAllSessionsWaitTime" required="false">
Wait time between sending of session block messages. This value is
effective only when <code>sendAllSessions</code> is <code>false</code>.
Default is <code>2000</code> milliseconds.
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
replicated. An attribute will only be replicated if its name matches
this pattern. If the pattern is zero length or <code>null</code>, all
attributes are eligible for replication. The pattern is anchored so the
session attribute name must fully match the pattern. As an example, the
value <code>(userName|sessionHistory)</code> will only replicate the
two session attributes named <code>userName</code> and
<code>sessionHistory</code>. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
replicated. An attribute will only be replicated if the implementation
class name of the value matches this pattern. If the pattern is zero
length or <code>null</code>, all attributes are eligible for
replication. The pattern is anchored so the fully qualified class name
must fully match the pattern. If not specified, the default value of
<code>null</code> will be used unless a <code>SecurityManager</code> is
enabled in which case the default will be
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
</attribute>
<attribute name="stateTimestampDrop" required="false">
When this node sends a <code>GET_ALL_SESSIONS</code> message to other
node, all session messages that are received as a response are queued.
If this attribute is set to <code>true</code>, the received session
messages (except any <code>GET_ALL_SESSIONS</code> sent by other nodes)
are filtered by their timestamp. A message is dropped if it is not a
<code>GET_ALL_SESSIONS</code> message and its timestamp is earlier than
the timestamp of our <code>GET_ALL_SESSIONS</code> message.
If set to <code>false</code>, all queued session messages are handled.
Default is <code>true</code>.
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<p>If <strong>sessionAttributeNameFilter</strong> or
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
attribute, should this be logged at <code>WARN</code> level? If
<code>WARN</code> level logging is disabled then it will be logged at
<code>DEBUG</code>. The default value of this attribute is
<code>false</code> unless a <code>SecurityManager</code> is enabled in
which case the default will be <code>true</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.ha.session.BackupManager Attributes">
<attributes>
<attribute name="mapSendOptions" required="false">
The backup manager uses a replicated map, this map is sending and
receiving messages. You can setup the flag for how this map is sending
messages, the default value is <code>6</code>(synchronous).<br/>
Note that if you use asynchronous messaging it is possible for update
messages for a session to be processed by the receiving node in a
different order to the order in which they were sent.
</attribute>
<attribute name="maxActiveSessions" required="false">
The maximum number of active sessions that will be created by this
Manager, or -1 (the default) for no limit. For this manager, only
sessions where the current node is the primary node for the session are
considered active sessions.
</attribute>
<attribute name="rpcTimeout" required="false">
Timeout for RPC message used for broadcast and transfer state from
another map.
Default value is <code>15000</code> milliseconds.
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
replicated. An attribute will only be replicated if its name matches
this pattern. If the pattern is zero length or <code>null</code>, all
attributes are eligible for replication. The pattern is anchored so the
session attribute name must fully match the pattern. As an example, the
value <code>(userName|sessionHistory)</code> will only replicate the
two session attributes named <code>userName</code> and
<code>sessionHistory</code>. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
replicated. An attribute will only be replicated if the implementation
class name of the value matches this pattern. If the pattern is zero
length or <code>null</code>, all attributes are eligible for
replication. The pattern is anchored so the fully qualified class name
must fully match the pattern. If not specified, the default value of
<code>null</code> will be used unless a <code>SecurityManager</code> is
enabled in which case the default will be
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
</attribute>
<attribute name="terminateOnStartFailure" required="false">
Set to true if you wish to terminate replication map when replication
map fails to start. If replication map is terminated, associated context
will fail to start. If you set this attribute to false, replication map
does not end. It will try to join the map membership in the heartbeat.
Default value is <code>false</code> .
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<p>If <strong>sessionAttributeNameFilter</strong> or
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
attribute, should this be logged at <code>WARN</code> level? If
<code>WARN</code> level logging is disabled then it will be logged at
<code>DEBUG</code>. The default value of this attribute is
<code>false</code> unless a <code>SecurityManager</code> is enabled in
which case the default will be <code>true</code>.</p>
</attribute>
<attribute name="accessTimeout" required="false">
The timeout for a ping message. If a remote map does not respond within
this timeout period, its regarded as disappeared.
Default value is <code>5000</code> milliseconds.
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<h3>All Manager Implementations</h3>
<p>All Manager implementations allow nesting of a
<strong>&lt;SessionIdGenerator&gt;</strong> element. It defines
the behavior of session id generation. All implementations
of the <a href="sessionidgenerator.html">SessionIdGenerator</a> allow the
following attributes:
</p>
<attributes>
<attribute name="sessionIdLength" required="false">
<p>The length of the session ID may be changed with the
<strong>sessionIdLength</strong> attribute.
</p>
</attribute>
</attributes>
</section>
</body>
</document>

170
webapps/docs/config/cluster-membership.xml Normal file
View File

@@ -0,0 +1,170 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-membership.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Membership object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
The membership component in the Apache Tribes <a href="cluster-channel.html">Channel</a> is responsible
for dynamic discovery of other members(nodes) in the cluster.
</p>
</section>
<section name="Default Implementation">
<p>
The default implementation of the cluster group notification is built on top of multicast heartbeats
sent using UDP packets to a multicast IP address.
Cluster members are grouped together by using the same multicast address/port combination.
Each member sends out a heartbeat with a given interval (<code>frequency</code>), and this
heartbeat is used for dynamic discovery.
In a similar fashion, if a heartbeat has not been received in a timeframe specified by <code>dropTime</code>
ms. a member is considered suspect and the channel and any membership listener will be notified.
</p>
</section>
<section name="Attributes">
<subsection name="Multicast Attributes">
<attributes>
<attribute name="className" required="true">
<p>
The default value is <code>org.apache.catalina.tribes.membership.McastService</code>
and is currently the only implementation.
This implementation uses multicast heartbeats for member discovery.
</p>
</attribute>
<attribute name="address" required="false">
<p>
The multicast address that the membership will broadcast its presence and listen
for other heartbeats on. The default value is <code>228.0.0.4</code>
Make sure your network is enabled for multicast traffic.<br/>
The multicast address, in conjunction with the <code>port</code> is what
creates a cluster group. To divide up your farm into several different group, or to
split up QA from production, change the <code>port</code> or the <code>address</code>
<br/>Previously known as mcastAddr.
</p>
</attribute>
<attribute name="port" required="false">
<p>
The multicast port, the default value is <code>45564</code><br/>
The multicast port, in conjunction with the <code>address</code> is what
creates a cluster group. To divide up your farm into several different group, or to
split up QA from production, change the <code>port</code> or the <code>address</code>
</p>
</attribute>
<attribute name="frequency" required="false">
<p>
The frequency in milliseconds in which heartbeats are sent out. The default value is <code>500</code> ms.<br/>
In most cases the default value is sufficient. Changing this value, simply changes the interval in between heartbeats.
</p>
</attribute>
<attribute name="dropTime" required="false">
<p>
The membership component will time out members and notify the Channel if a member fails to send a heartbeat within
a give time. The default value is <code>3000</code> ms. This means, that if a heartbeat is not received from a
member in that timeframe, the membership component will notify the cluster of this.<br/>
On a high latency network you may wish to increase this value, to protect against false positives.<br/>
Apache Tribes also provides a <a href="cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.TcpFailureDetector_Attributes"><code>TcpFailureDetector</code></a> that will
verify a timeout using a TCP connection when a heartbeat timeout has occurred. This protects against false positives.
</p>
</attribute>
<attribute name="bind" required="false">
<p>
Use this attribute if you wish to bind your multicast traffic to a specific network interface.
By default, or when this attribute is unset, it tries to bind to <code>0.0.0.0</code> and sometimes on multihomed hosts
this becomes a problem.
</p>
</attribute>
<attribute name="ttl" required="false">
<p>
The time-to-live setting for the multicast heartbeats.
This setting should be a value between 0 and 255. The default value is VM implementation specific.
</p>
</attribute>
<attribute name="domain" required="false">
<p>
Apache Tribes has the ability to logically group members into domains, by using this domain attribute.
The <code>org.apache.catalina.tribes.Member.getDomain()</code> method returns the value specified here.
</p>
</attribute>
<attribute name="soTimeout" required="false">
<p>
The sending and receiving of heartbeats is done on a single thread, hence to avoid blocking this thread forever,
you can control the <code>SO_TIMEOUT</code> value on this socket.<br/>
If a value smaller or equal to 0 is presented, the code will default this value to frequency
</p>
</attribute>
<attribute name="recoveryEnabled" required="false">
<p>
In case of a network failure, Java multicast socket don't transparently fail over, instead the socket will continuously
throw IOException upon each receive request. When recoveryEnabled is set to true, this will close the multicast socket
and open a new socket with the same properties as defined above.<br/>
The default is <code>true</code>. <br/>
</p>
</attribute>
<attribute name="recoveryCounter" required="false">
<p>
When <code>recoveryEnabled==true</code> this value indicates how many
times an error has to occur before recovery is attempted. The default is
<code>10</code>. <br/>
</p>
</attribute>
<attribute name="recoverySleepTime" required="false">
<p>
When <code>recoveryEnabled==true</code> this value indicates how long time (in milliseconds)
the system will sleep in between recovery attempts, until it recovers successfully.
The default is <code>5000</code> (5 seconds). <br/>
</p>
</attribute>
<attribute name="localLoopbackDisabled" required="false">
<p>
Membership uses multicast, it will call <code>java.net.MulticastSocket.setLoopbackMode(localLoopbackDisabled)</code>.
When <code>localLoopbackDisabled==true</code> multicast messages will not reach other nodes on the same local machine.
The default is <code>false</code>. <br/>
</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

171
webapps/docs/config/cluster-receiver.xml Normal file
View File

@@ -0,0 +1,171 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-receiver.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Receiver object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
The receiver component is responsible for receiving cluster messages.
As you might notice through the configuration, is that the receiving of messages
and sending of messages are two different components, this is different from many other
frameworks, but there is a good reason for it, to decouple the logic for how messages are sent from
how messages are received.<br/>
The receiver is very much like the Tomcat Connector, its the base of the thread pool
for incoming cluster messages. The receiver is straight forward, but all the socket settings
for incoming traffic are managed here.
</p>
</section>
<section name="Blocking vs Non-Blocking Receiver">
<p>
The receiver supports both a non blocking, <code>org.apache.catalina.tribes.transport.nio.NioReceiver</code>, and a
blocking, <code>org.apache.catalina.tribes.transport.bio.BioReceiver</code>. It is preferred to use the non blocking receiver
to be able to grow your cluster without running into thread starvation.<br/>
Using the non blocking receiver allows you to with a very limited thread count to serve a large number of messages.
Usually the rule is to use 1 thread per node in the cluster for small clusters, and then depending on your message frequency
and your hardware, you'll find an optimal number of threads peak out at a certain number.
</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
The implementation of the receiver component. Two implementations available,
<code>org.apache.catalina.tribes.transport.nio.NioReceiver</code> and
<code>org.apache.catalina.tribes.transport.bio.BioReceiver</code>.<br/>
The <code>org.apache.catalina.tribes.transport.nio.NioReceiver</code> is the
preferred implementation
</attribute>
<attribute name="address" required="false">
The address (network interface) to listen for incoming traffic.
Same as the bind address. The default value is <code>auto</code> and translates to
<code>java.net.InetAddress.getLocalHost().getHostAddress()</code>.
</attribute>
<attribute name="direct" required="false">
Possible values are <code>true</code> or <code>false</code>.
Set to true if you want the receiver to use direct bytebuffers when reading data
from the sockets.
</attribute>
<attribute name="port" required="false">
The listen port for incoming data. The default value is <code>4000</code>.
To avoid port conflicts the receiver will automatically bind to a free port within the range of
<code> port &lt;= bindPort &lt; port+autoBind</code>
So for example, if port is 4000, and autoBind is set to 10, then the receiver will open up
a server socket on the first available port in the range 4000-4009.
</attribute>
<attribute name="autoBind" required="false">
Default value is <code>100</code>.
Use this value if you wish to automatically avoid port conflicts the cluster receiver will try to open a
server socket on the <code>port</code> attribute port, and then work up <code>autoBind</code> number of times.
</attribute>
<attribute name="securePort" required="false">
The secure listen port. This port is SSL enabled. If this attribute is omitted no SSL port is opened up.
There default value is unset, meaning there is no SSL socket available.
</attribute>
<attribute name="udpPort" required="false">
The UDP listen port. If this attribute is omitted no UDP port is opened up.
There default value is unset, meaning there is no UDP listener available.
</attribute>
<attribute name="selectorTimeout" required="false">
The value in milliseconds for the polling timeout in the <code>NioReceiver</code>. On older versions of the JDK
there have been bugs, that should all now be cleared out where the selector never woke up.
The default value is a very high <code>5000</code> milliseconds.
</attribute>
<attribute name="maxThreads" required="false">
The maximum number of threads in the receiver thread pool. The default value is <code>15</code>
Adjust this value relative to the number of nodes in the cluster, the number of messages being exchanged and
the hardware you are running on. A higher value doesn't mean more efficiency, tune this value according to your
own test results.
</attribute>
<attribute name="minThreads" required="false">
Minimum number of threads to be created when the receiver is started up. Default value is <code>6</code>
</attribute>
<attribute name="maxIdleTime" required="false">
Maximum number of milliseconds of until Idle thread terminates. Default value is <code>60000</code> milliseconds.
</attribute>
<attribute name="ooBInline" required="false">
Boolean value for the socket OOBINLINE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="rxBufSize" required="false">
The receiver buffer size on the receiving sockets. Value is in bytes, the default value is <code>43800</code> bytes.
</attribute>
<attribute name="txBufSize" required="false">
The sending buffer size on the receiving sockets. Value is in bytes, the default value is <code>25188</code> bytes.
</attribute>
<attribute name="udpRxBufSize" required="false">
The receive buffer size on the datagram socket.
Default value is <code>25188</code> bytes.
</attribute>
<attribute name="udpTxBufSize" required="false">
The send buffer size on the datagram socket.
Default value is <code>43800</code> bytes.
</attribute>
<attribute name="soKeepAlive" required="false">
Boolean value for the socket SO_KEEPALIVE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soLingerOn" required="false">
Boolean value to determine whether to use the SO_LINGER socket option.
Possible values are <code>true</code> or <code>false</code>. Default value is <code>true</code>.
</attribute>
<attribute name="soLingerTime" required="false">
Sets the SO_LINGER socket option time value. The value is in seconds.
The default value is <code>3</code> seconds.
</attribute>
<attribute name="soReuseAddress" required="false">
Boolean value for the socket SO_REUSEADDR option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="tcpNoDelay" required="false">
Boolean value for the socket TCP_NODELAY option. Possible values are <code>true</code> or <code>false</code>.
The default value is <code>true</code>
</attribute>
<attribute name="timeout" required="false">
Sets the SO_TIMEOUT option on the socket. The value is in milliseconds and the default value is <code>3000</code>
milliseconds.
</attribute>
<attribute name="useBufferPool" required="false">
Boolean value whether to use a shared buffer pool of cached <code>org.apache.catalina.tribes.io.XByteBuffer</code>
objects. If set to true, the XByteBuffer that is used to pass a message up the channel, will be recycled at the end
of the requests. This means that interceptors in the channel must not maintain a reference to the object
after the <code>org.apache.catalina.tribes.ChannelInterceptor#messageReceived</code> method has exited.
</attribute>
</attributes>
</subsection>
<subsection name="NioReceiver">
</subsection>
<subsection name="BioReceiver">
</subsection>
</section>
</body>
</document>

181
webapps/docs/config/cluster-sender.xml Normal file
View File

@@ -0,0 +1,181 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-sender.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Sender object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
The channel sender component is responsible for delivering outgoing cluster messages over the network.
In the default implementation, <code>org.apache.catalina.tribes.transport.ReplicationTransmitter</code>,
the sender is a fairly empty shell with not much logic around a fairly complex <code>&lt;Transport&gt;</code>
component the implements the actual delivery mechanism.
</p>
</section>
<section name="Concurrent Parallel Delivery">
<p>
In the default <code>transport</code> implementation, <code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code>,
Apache Tribes implements what we like to call &quot;Concurrent Parallel Delivery&quot;.
This means that we can send a message to more than one destination at the same time(parallel), and
deliver two messages to the same destination at the same time(concurrent). Combine these two and we have
&quot;Concurrent Parallel Delivery&quot;.
</p>
<p>
When is this useful? The simplest example we can think of is when part of your code is sending a 10MB message,
like a war file being deployed, and you need to push through a small 10KB message, say a session being replicated,
you don't have to wait for the 10MB message to finish, as a separate thread will push in the small message
transmission at the same time. Currently there is no interrupt, pause or priority mechanism available, but check back soon.
</p>
</section>
<section name="Nested Elements">
<p>
The nested element <code>&lt;Transport&gt;</code> is not required, but encouraged, as this is where
you would set all the socket options for the outgoing messages. Please see its attributes below.
There are two implementations, in a similar manner to the <a href="cluster-receiver.html">receiver</a>, one is non-blocking
based and the other is built using blocking IO. <br/>
<code>org.apache.catalina.tribes.transport.bio.PooledMultiSender</code> is the blocking implementation and
<code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code>.
Parallel delivery is not available for the blocking implementation due to the fact that it is blocking a thread on sending data.
</p>
</section>
<section name="Attributes">
<subsection name="Common Sender Attributes">
<attributes>
<attribute name="className" required="true">
Required, only available implementation is <code>org.apache.catalina.tribes.transport.ReplicationTransmitter</code>
</attribute>
</attributes>
</subsection>
<subsection name="Common Transport Attributes">
<attributes>
<attribute name="className" required="true">
Required, an implementation of the <code>org.apache.catalina.tribes.transport.MultiPointSender</code>.<br/>
Non-blocking implementation is <code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code><br/>
Blocking implementation is <code>org.apache.catalina.tribes.transport.bio.PooledMultiSender</code>
</attribute>
<attribute name="rxBufSize" required="false">
The receive buffer size on the socket.
Default value is <code>25188</code> bytes.
</attribute>
<attribute name="txBufSize" required="false">
The send buffer size on the socket.
Default value is <code>43800</code> bytes.
</attribute>
<attribute name="udpRxBufSize" required="false">
The receive buffer size on the datagram socket.
Default value is <code>25188</code> bytes.
</attribute>
<attribute name="udpTxBufSize" required="false">
The send buffer size on the datagram socket.
Default value is <code>43800</code> bytes.
</attribute>
<attribute name="directBuffer" required="false">
Possible values are <code>true</code> or <code>false</code>.
Set to true if you want the receiver to use direct bytebuffers when writing data
to the sockets. Default value is <code>false</code>
</attribute>
<attribute name="keepAliveCount" required="false">
The number of requests that can go through the socket before the socket is closed, and reopened
for the next request. The default value is <code>-1</code>, which is unlimited.
</attribute>
<attribute name="keepAliveTime" required="false">
The number of milliseconds a connection is kept open after its been opened.
The default value is <code>-1</code>, which is unlimited.
</attribute>
<attribute name="timeout" required="false">
Sets the SO_TIMEOUT option on the socket. The value is in milliseconds and the default value is <code>3000</code>
milliseconds.(3 seconds) This timeout starts when a message send attempt is starting, until the transfer has been completed.
For the NIO sockets, this will mean, that the caller can guarantee that we will not attempt sending the message
longer than this timeout value. For the blocking IO implementation, this translated directly to the soTimeout.<br/>
A timeout will not spawn a retry attempt, in order to guarantee the return of the application thread.
</attribute>
<attribute name="maxRetryAttempts" required="false">
How many times do we retry a failed message, that received a IOException at the socket level.
The default value is <code>1</code>, meaning we will retry a message that has failed once.
In other words, we will attempt a message send no more than twice. One is the original send, and one is the
<code>maxRetryAttempts</code>.
</attribute>
<attribute name="ooBInline" required="false">
Boolean value for the socket OOBINLINE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soKeepAlive" required="false">
Boolean value for the socket SO_KEEPALIVE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soLingerOn" required="false">
Boolean value to determine whether to use the SO_LINGER socket option.
Possible values are <code>true</code> or <code>false</code>. Default value is <code>true</code>.
</attribute>
<attribute name="soLingerTime" required="false">
Sets the SO_LINGER socket option time value. The value is in seconds.
The default value is <code>3</code> seconds.
</attribute>
<attribute name="soReuseAddress" required="false">
Boolean value for the socket SO_REUSEADDR option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soTrafficClass" required="false">
Sets the traffic class level for the socket, the value is between 0 and 255.
Default value is <code>int soTrafficClass = 0x04 | 0x08 | 0x010;</code>
Different values are defined in <a href="http://docs.oracle.com/javase/7/docs/api/java/net/Socket.html#setTrafficClass(int)">
java.net.Socket#setTrafficClass(int)</a>.
</attribute>
<attribute name="tcpNoDelay" required="false">
Boolean value for the socket TCP_NODELAY option. Possible values are <code>true</code> or <code>false</code>.
The default value is <code>true</code>
</attribute>
<attribute name="throwOnFailedAck" required="false">
Boolean value, default value is <code>true</code>.
If set to true, the sender will throw a <code>org.apache.catalina.tribes.RemoteProcessException</code>
when we receive a negative ack from the remote member.
Set to false, and Tribes will treat a positive ack the same way as a negative ack, that the message was received.
</attribute>
</attributes>
</subsection>
<subsection name="Common PooledSender Attributes">
<attributes>
<attribute name="poolSize" required="false">
The maximum number of concurrent connections from A to B.
The value is based on a per-destination count.
The default value is <code>25</code>
</attribute>
<attribute name="maxWait" required="false">
The maximum number of milliseconds that the senderPool will wait when
there are no available senders. The default value is <code>3000</code>
milliseconds.(3 seconds).
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

170
webapps/docs/config/cluster-valve.xml Normal file
View File

@@ -0,0 +1,170 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-valve.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Valve object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
A cluster valve is no different from any other <a href="valve.html">Tomcat <code>Valve</code></a>.
The cluster valves are interceptors in the invocation chain for HTTP requests, and the clustering implementation
uses these valves to make intelligent decision around data and when data should be replicated.
</p>
<p>
A cluster valve must implement the <code>org.apache.catalina.ha.ClusterValve</code> interface.
This is a simple interface that extends the <code>org.apache.catalina.Valve</code> interface.
</p>
</section>
<section name="org.apache.catalina.ha.tcp.ReplicationValve">
The <code>ReplicationValve</code> will notify the cluster at the end of an HTTP request
so that the cluster can make a decision whether there is data to be replicated or not.
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
Set value to <code>org.apache.catalina.ha.tcp.ReplicationValve</code>
</attribute>
<attribute name="filter" required="false">
For known file extensions or urls, you can use this Valve to notify the
cluster that the session has not been modified during this request and
the cluster doesn't have to probe the session managers for changes. If
the request matches this filter pattern, the cluster assumes there has
been no session change. An example filter would look like <code>
filter=&quot;.*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt&quot;
</code>. The filter is a regular expression using
<code>java.util.regex</code>.
</attribute>
<attribute name="primaryIndicator" required="false">
Boolean value, so to true, and the replication valve will insert a request attribute with the name
defined by the <code>primaryIndicatorName</code> attribute.
The value inserted into the request attribute is either <code>Boolean.TRUE</code> or
<code>Boolean.FALSE</code>
</attribute>
<attribute name="primaryIndicatorName" required="false">
Default value is <code>org.apache.catalina.ha.tcp.isPrimarySession</code>
The value defined here is the name of the request attribute that contains the boolean value
if the session is primary on this server or not.
</attribute>
<attribute name="statistics" required="false">
Boolean value. Set to <code>true</code> if you want the valve to collect request statistics.
Default value is <code>false</code>
</attribute>
</attributes>
</subsection>
</section>
<section name="org.apache.catalina.ha.session.JvmRouteBinderValve">
In case of a mod_jk failover, the <code>JvmRouteBinderValve</code> will replace the
<code>jvmWorker</code> attribute in the session Id, to make future requests stick to this
node. If you want fallback capability, don't enable this valve, but if you want your failover to stick,
and for mod_jk not to have to keep probing the node that went down, you use this valve.
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
<code>org.apache.catalina.ha.session.JvmRouteBinderValve</code>
</attribute>
<attribute name="enabled" required="false">
Default value is <code>true</code>
Runtime attribute to turn on and off turn over of the session's jvmRoute value.
</attribute>
<attribute name="sessionIdAttribute" required="false">
Old sessionid before failover is registered in request attributes with this attribute.
Default attribute name is <code>org.apache.catalina.ha.session.JvmRouteOrignalSessionID</code>.
</attribute>
</attributes>
</subsection>
</section>
<section name="org.apache.catalina.ha.authenticator.ClusterSingleSignOn">
The <code>ClusterSingleSignOn</code> supports feature of single sign on in cluster.
By using <code>ClusterSingleSignOn</code>, the security identity authenticated
by one web application is recognized by other web applications on the same virtual host,
and it is propagated to other nodes in the cluster.
<p>See the <a href="host.html#Single_Sign_On">Single Sign On</a> special
feature on the <strong>Host</strong> element for more information.</p>
<p><strong>Note:</strong> ClusterSingleSignOn can be configured at host level cluster only.
</p>
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This MUST be set to
<strong>org.apache.catalina.ha.authenticator.ClusterSingleSignOn</strong>.</p>
</attribute>
<attribute name="cookieDomain" required="false">
<p>Sets the host domain to be used for sso cookies.</p>
</attribute>
<attribute name="mapSendOptions" required="false">
<p>The Valve uses a replicated map. You can setup the flag for how this
map sends messages. The default value is <code>6</code> (synchronous).
Note that if you use asynchronous messaging it is possible for update
messages to be processed by the receiving node in a different order to
the order in which they were sent.</p>
</attribute>
<attribute name="requireReauthentication" required="false">
<p>Default false. Flag to determine whether each request needs to be
reauthenticated to the security <strong>Realm</strong>. If "true", this
Valve uses cached security credentials (username and password) to
reauthenticate to the <strong>Realm</strong> each request associated
with an SSO session. If "false", the Valve can itself authenticate
requests based on the presence of a valid SSO cookie, without
rechecking with the <strong>Realm</strong>.</p>
</attribute>
<attribute name="rpcTimeout" required="false">
<p>The Valve uses a replicated map. This is the timeout for messages
that transfer state to/from the other nodes in the cluster. If not
specified, a default value of <code>15000</code> milliseconds is used.
</p>
</attribute>
<attribute name="terminateOnStartFailure" required="false">
<p>Set to <code>true</code> if you wish this Valve to fail if the
underlying replication fails to start. If the Valve fails, then the
associated container will fail to start. If you set this attribute to
false, and the underlying replications fails to start, the Valve will
start and it will attempt to join the cluster and start replication as
part of the heartbeat process. If not specified, the default value of
<code>false</code> is used.</p>
</attribute>
<attribute name="accessTimeout" required="false">
The timeout for a ping message. If a remote map does not respond within
this timeout period, its regarded as disappeared.
Default value is <code>5000</code> milliseconds.
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

Some files were not shown because too many files have changed in this diff Show More