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

299
webapps/docs/funcspecs/fs-admin-apps.xml Normal file
View File

@@ -0,0 +1,299 @@
<?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="fs-admin-apps.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>Administrative Apps - Overall Requirements</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<subsection name="Introduction">
<p>The purpose of this specification is to define high level requirements
for administrative applications that can be used to manage the operation
of a running Tomcat container. A variety of <em>Access Methods</em>
to the supported administrative functionality shall be supported, to
meet varying requirements:</p>
<ul>
<li><em>As A Scriptable Web Application</em> - The existing
<code>Manager</code> web application provides a simple HTTP-based
interface for managing Tomcat through commands that are expressed
entirely through a request URI. This is useful in environments
where you wish to script administrative commands with tools that
can generate HTTP transactions.</li>
<li><em>As An HTML-Based Web Application</em> - Use an HTML presentation
to provide a GUI-like user interface for humans to interact with the
administrative capabilities.</li>
<li><em>As SOAP-Based Web Services</em> - The operational commands to
administer Tomcat are made available as web services that utilize
SOAP message formats.</li>
<li><em>As Java Management Extensions (JMX) Commands</em> - The operational
commands to administer Tomcat are made available through JMX APIs,
for integration into management consoles that utilize them.</li>
<li><em>Other Remote Access APIs</em> - Other remote access APIs, such
as JINI, RMI, and CORBA can also be utilized to access administrative
capabilities.</li>
</ul>
<p>Underlying all of the access methods described above, it is assumed
that the actual operations are performed either directly on the
corresponding Catalina components (such as calling the
<code>Deployer.deploy()</code> method to deploy a new web application),
or through a "business logic" layer that can be shared across all of the
access methods. This approach minimizes the cost of adding new
administrative capabilities later -- it is only necessary to add the
corresponding business logic function, and then write adapters to it for
all desired access methods.</p>
<p>The current status of this functional specification is
<strong>PROPOSED</strong>. It has not yet been discussed and
agreed to on the TOMCAT-DEV mailing list.</p>
</subsection>
<subsection name="External Specifications">
<p>The implementation of this functionality depends on the following
external specifications:</p>
<ul>
<li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/idl">
Java IDL</a> (for CORBA, included in the JDK)</li>
<li><a href="http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html">
Java Management Extensions</a></li>
<li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/rmi">
Remote Method Invocation</a> (Included in the JDK)</li>
</ul>
</subsection>
<subsection name="Implementation Requirements">
<p>The implementation of this functionality shall conform to the
following requirements:</p>
<ul>
<li>To the maximum extent feasible, all administrative functions,
and the access methods that support them, shall run portably
on all platforms where Tomcat itself runs.</li>
<li>In a default Tomcat distribution, all administrative capabilities
shall be disabled. It shall be necessary for a system
administrator to specifically enable the desired access methods
(such as by adding a username/password with a specific role to
the Tomcat user's database.</li>
<li>Administrative functions shall be realized as direct calls to
corresponding Catalina APIs, or through a business logic layer
that is independent of the access method used to initiate it.</li>
<li>The common business logic components shall be implemented in
package <code>org.apache.catalina.admin</code>.</li>
<li>The common business logic components shall be built as part of the
standard Catalina build process, and made visible in the
Catalina class loader.</li>
<li>The Java components required for each access method shall be
implemented in subpackages of <code>org.apache.catalina.admin</code>.
</li>
<li>The build scripts should treat each access method as optional,
so that it will be built only if the corresponding required
APIs are present at build time.</li>
<li>It shall be possible to save the configured state of the running
Tomcat container such that this state can be reproduced when the
container is shut down and restarted.</li>
<li>Administrative commands to start up and shut down the overall
Tomcat container are <strong>out of scope</strong> for the
purposes of these applications. It is assumed that other
(usually platform-specific) mechanisms will be used for container
startup and shutdown.</li>
</ul>
</subsection>
</section>
<section name="Dependencies">
<subsection name="Environmental Dependencies">
<p>The following environmental dependencies must be met in order for
administrative applications to operate correctly:</p>
<ul>
<li>For access methods that require creation of server sockets, the
appropriate ports must be configured and available.</li>
</ul>
</subsection>
<subsection name="Container Dependencies">
<p>Correct operation of administrative applications depends on the
following specific features of the surrounding container:</p>
<ul>
<li>To the maximum extent feasible, Catalina components that offer
direct administrative APIs and property setters shall support
"live" changes to their operation, without requiring a container
restart.</li>
</ul>
</subsection>
<subsection name="External Technologies">
<p>The availability of the following technologies can be assumed
for the implementation and operation of the various access methods
and the corresponding administrative business logic:<br/>
<strong>FIXME</strong> - This list below is totally outdated, but nobody
cares about the administrative app anymore. It is removed and unsupported
since Tomcat 6.0.</p>
<ul>
<li><a href="http://www.oracle.com/technetwork/java/javase/overview/index.html">
Java Standard Edition</a> (Version 1.2 or later)</li>
<li><a href="https://www.jcp.org/jsr/detail/154.jsp">Servlet 2.4</a>
(supported natively by Tomcat 5)</li>
<li><a href="https://www.jcp.org/jsr/detail/152.jsp">JavaServer Pages 2.0</a>
(supported natively by Tomcat 5)</li>
<li><a href="https://jakarta.apache.org/taglibs/doc/standard-doc/intro.html">JavaServer Pages Standard Tag Library 1.0 (Jakarta Taglibs-Standard 1.0.3)</a></li>
<li><a href="https://struts.apache.org/">Struts Framework</a>
(Version 1.0) - MVC Framework for Web Applications</li>
<li><strong>TO BE DETERMINED</strong> - Application for hosting SOAP
based web services</li>
</ul>
</subsection>
</section>
<section name="Functionality">
<subsection name="Properties of Administered Objects">
<p>Functional requirements for administrative applications are specified
in terms of <em>Administered Objects</em>, whose definitions and detailed
properties are listed <a href="fs-admin-objects.html">here</a>. In general,
Administered Objects correspond to components in the Catalina architecture,
but these objects are defined separately here for the following reasons:</p>
<ul>
<li>It is possible that the administrative applications do not expose
every possible configurable facet of the underlying components.</li>
<li>In some cases, an Administered Object (from the perspective of an
administrative operation) is realized by more than one Catalina
component, at a finer-grained level of detail.</li>
<li>It is necessary to represent the configuration information for a
component separately from the component itself (for instance, in
order to store that configuration information for later use).</li>
<li>It is necessary to represent configuration information (such as
a Default Context) when there is no corresponding component instance.
</li>
<li>Administered Objects, when realized as Java classes, will include
methods for administrative operations that have no correspondence
to operations performed by the corresponding actual components.</li>
</ul>
<p>It is assumed that the reader is familiar with the overall component
architecture of Catalina. For further information, see the corresponding
Developer Documentation. To distinguish names that are used as both
<em>Administered Objects</em> and <code>Components</code>, different
font presentations are utilized. Default values for many properties
are listed in [square brackets].</p>
</subsection>
<subsection name="Supported Administrative Operations">
<p>The administrative operations that are available are described in terms
of the corresponding Administered Objects (as defined above), in a manner
that is independent of the access method by which these operations are
requested. In general, such operations are relevant only in the context
of a particular Administered Object (and will most likely be realized as
method calls on the corresponding Administered Object classes), so they
are organized based on the currently "focused" administered object.
The available Supported Operations are documented
<a href="fs-admin-opers.html">here</a>.</p>
</subsection>
<subsection name="Access Method Specific Requirements">
<h5>Scriptable Web Application</h5>
<p>An appropriate subset of the administrative operations described above
shall be implemented as commands that can be performed by the "Manager"
web application. <strong>FIXME</strong> - Enumerate them.</p>
<p>In addition, this web application shall conform to the following
requirements:</p>
<ul>
<li>All request URIs shall be protected by security constraints that
require a security role to be assigned for processing.</li>
<li>The default user database shall <strong>not</strong> contain any
user that has been assigned a security role.</li>
</ul>
<h5>HTML-Based Web Application</h5>
<p>The entire suite of administrative operations described above shall be
made available through a web application designed for human interaction.
In addition, this web application shall conform to the following
requirements:</p>
<ul>
<li>Must be implemented using servlet, JSP, and MVC framework technologies
described under "External Technologies", above.</li>
<li>Prompts and error messages must be internationalizable to multiple
languages.</li>
<li>Rendered HTML must be compatible with Netscape Navigator (version 4.7
or later) and Internet Explorer (version 5.0 or later).</li>
</ul>
</subsection>
</section>
<section name="Testable Assertions">
<p><strong>FIXME</strong> - Complete this section.</p>
</section>
</body>
</document>

485
webapps/docs/funcspecs/fs-admin-objects.xml Normal file
View File

@@ -0,0 +1,485 @@
<?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="fs-admin-objects.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>Administrative Apps - Administered Objects</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Administered Objects Overview">
<p>This document defines the <em>Administered Objects</em> that represent
the internal architectural components of the Catalina servlet container.
Associated with each is a set of <a href="fs-admin-opers.html">Supported
Operations</a> that can be performed when the administrative application is
"focused" on a particular configurable object.</p>
<p>The following Administered Objects are defined:</p>
<ul>
<li><a href="#Access_Logger">Access Logger</a></li>
<li><a href="#Connector">Connector</a></li>
<li><a href="#Context">Context</a></li>
<li><a href="#Default_Context">Default Context</a></li>
<li><a href="#Default_Deployment_Descriptor">Default Deployment Descriptor</a></li>
<li><a href="#Engine">Engine</a></li>
<li><a href="#Environment_Entry">Environment Entry</a></li>
<li><a href="#Host">Host</a></li>
<li><a href="#JDBC_Resource">JDBC Resource</a></li>
<li><a href="#Loader">Loader</a></li>
<li><a href="#Manager">Manager</a></li>
<li><a href="#Realm">Realm</a></li>
<li><a href="#Request_Filter">Request Filter</a></li>
<li><a href="#Server">Server</a></li>
<li><a href="#Service">Service</a></li>
</ul>
</section>
<section name="Access Logger">
<p>An <em>Access Logger</em> is an optional <code>Valve</code> that can
create request access logs in the same formats as those provided by
web servers. Such access logs are useful input to hit count and user
access tracking analysis programs. An Access Logger can be attached to
an <em>Engine</em>, a <em>Host</em>, a <em>Context</em>, or a <em>Default
Context</em>.</p>
<p>The standard component implementing an <em>Access Logger</em> is
<code>org.apache.catalina.valves.AccessLogValve</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>directory</code> - Absolute or relative (to $CATALINA_BASE) path
of the directory into which access log files are created.
[logs].</li>
<li><code>pattern</code> - Pattern string defining the fields to be
included in the access log output, or "common" for the standard
access log pattern. See
<code>org.apache.catalina.valves.AccessLogValve</code> for more
information. [common]</li>
<li><code>prefix</code> - Prefix added to the beginning of each log file
name created by this access logger.</li>
<li><code>resolveHosts</code> - Should IP addresses be resolved to host
names in the log? [false]</li>
<li><code>suffix</code> - Suffix added to the end of each log file name
created by this access logger.</li>
</ul>
</section>
<section name="Connector">
<p>A <em>Connector</em> is the representation of a communications endpoint
by which requests are received from (and responses returned to) a Tomcat
client. The administrative applications shall support those connectors
that are commonly utilized in Tomcat installations, as described in detail
below.</p>
<p>For standalone use, the standard connector supporting the HTTP/1.1
protocol is <code>org.apache.catalina.connectors.http.HttpConnector</code>.
It supports the following configurable properties:</p>
<ul>
<li><code>acceptCount</code> - The maximum queue length of incoming
connections that have not yet been accepted. [10]</li>
<li><code>address</code> - For servers with more than one IP address, the
address upon which this connector should listen. [All Addresses]</li>
<li><code>bufferSize</code> - Default input buffer size (in bytes) for
requests created by this Connector. [2048]</li>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>enableLookups</code> - Should we perform DNS lookups on remote
IP addresses when <code>request.getRemoteHost()</code> is called?
[false]</li>
<li><code>maxProcessors</code> - The maximum number of processor threads
supported by this connector. [20]</li>
<li><code>minProcessors</code> - The minimum number of processor threads
to be created at container startup. [5]</li>
<li><code>port</code> - TCP/IP port number on which this Connector should
listen for incoming requests. [8080]</li>
<li><code>proxyName</code> - Host name to be returned when an application
calls <code>request.getServerName()</code>. [Value of Host: header]</li>
<li><code>proxyPort</code> - Port number to be returned when an application
calls <code>request.getServerPort()</code>. [Same as <code>port</code>]
</li>
</ul>
</section>
<section name="Context">
<p>A <em>Context</em> is the representation of an individual web application,
which is associated with a corresponding <em>Host</em>. Note that the
administrable properties of a <em>Context</em> do <strong>not</strong>
include any settings from inside the web application deployment descriptor
for that application.</p>
<p>The standard component implementing a <em>Context</em> is
<code>org.apache.catalina.core.StandardContext</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>cookies</code> - Should be use cookies for session identifier
communication? [true]</li>
<li><code>crossContext</code> - Should calls to
<code>ServletContext.getServletContext()</code> return the actual
context responsible for the specified path? [false]</li>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>docBase</code> - The absolute or relative (to the
<code>appBase</code> of our owning <em>Host</em>) pathname of a
directory containing an unpacked web application, or of a web
application archive (WAR) file.</li>
<li><code>override</code> - Should settings in this <em>Context</em>
override corresponding settings in the <em>Default Context</em>?
[false]</li>
<li><code>path</code> - Context path for this web application, or an empty
string for the root application of a <em>Host</em>. [Inferred from
directory or WAR file name]</li>
<li><code>reloadable</code> - Should Tomcat monitor classes in the
<code>/WEB-INF/classes</code> directory for changes, and reload the
application if they occur? [false]</li>
<li><code>useNaming</code> - Should Tomcat provide a JNDI naming context,
containing preconfigured entries and resources, corresponding to the
requirements of the Java2 Enterprise Edition specification? [true]</li>
<li><code>workDir</code> - Absolute pathname of a scratch directory that is
provided to this web application. [Automatically assigned relative to
$CATALINA_BASE/work]</li>
</ul>
<p>Each <em>Context</em> is owned by a parent <em>Host</em>, and is
associated with:</p>
<ul>
<li>An optional <em>Access Logger</em> that logs all requests processed
by this web application.</li>
<li>Zero or more <em>Environment Entries</em> representing environment
entries for the JNDI naming context associated with a web
application.</li>
<li>Zero or more <em>JDBC Resources</em> representing database connection
pools associated with a web application.</li>
<li>A <em>Loader</em> representing the web application class loader used
by this web application.</li>
<li>A <em>Manager</em> representing the session manager used by this
web application.</li>
<li>An optional <em>Realm</em> used to provide authentication and access
control information for this web application.</li>
<li>Zero or more <em>Request Filters</em> used to limit access to this
web application based on remote host name or IP address.</li>
</ul>
</section>
<section name="Default Context">
<p>A <em>Default Context</em> represents a subset of the configurable
properties of a <em>Context</em>, and is used to set defaults for those
properties when web applications are automatically deployed. A <em>Default
Context</em> object can be associated with an <em>Engine</em> or a
<em>Host</em>. The following configurable properties are supported:</p>
<ul>
<li><code>cookies</code> - Should be use cookies for session identifier
communication? [true]</li>
<li><code>crossContext</code> - Should calls to
<code>ServletContext.getServletContext()</code> return the actual
context responsible for the specified path? [false]</li>
<li><code>reloadable</code> - Should Tomcat monitor classes in the
<code>/WEB-INF/classes</code> directory for changes, and reload the
application if they occur? [false]</li>
<li><code>useNaming</code> - Should Tomcat provide a JNDI naming context,
containing preconfigured entries and resources, corresponding to the
requirements of the Java2 Enterprise Edition specification? [true]</li>
</ul>
<p>Each <em>Default Context</em> is owned by a parent <em>Engine</em> or
<em>Host</em>, and is associated with:</p>
<ul>
<li>Zero or more <em>Environment Entries</em> representing environment
entries for the JNDI naming context associated with a web
application.</li>
<li>Zero or more <em>JDBC Resources</em> representing database connection
pools associated with a web application.</li>
<li>An optional <em>Loader</em> representing default configuration
properties for the Loader component of deployed web applications.</li>
<li>An optional <em>Manager</em> representing default configuration
properties for the Manager component of deployed web applications.</li>
</ul>
</section>
<section name="Default Deployment Descriptor">
<p>Default web application characteristics are configured in a special
deployment descriptor named <code>$CATALINA_BASE/conf/web.xml</code>. This
section describes the configurable components that may be stored there.</p>
<p><strong>FIXME</strong> - Complete the description of default servlets,
default mappings, default MIME types, and so on.</p>
</section>
<section name="Engine">
<p>An <em>Engine</em> is the representation of the entire Catalina
servlet container, and processes all requests for all of the associated
virtual hosts and web applications.</p>
<p>The standard component implementing an <em>Engine</em> is
<code>org.apache.catalina.core.StandardEngine</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>defaultHost</code> - Name of the <em>Host</em> to which requests
will be directed if the requested host is unknown. [localhost]</li>
<li><code>name</code> - Logical name of this engine. [Tomcat Stand-Alone]
</li>
</ul>
<p>Each <em>Engine</em> is owned by a parent <em>Service</em>, and is
associated with:</p>
<ul>
<li>An optional <em>Access Logger</em> that logs all requests processed
by the entire container.</li>
<li>A <em>Default Context</em>, representing default properties of a
<em>Context</em> for automatically deployed applications for all
associated <em>Hosts</em> (unless overridden by a subordinate
component).</li>
<li>One or more <em>Hosts</em> representing individual virtual hosts
supported by this container.</li>
<li>A <em>Realm</em> used to provide authentication and access control
information for all virtual hosts and web applications (unless
overridden by a subordinate component).</li>
<li>Zero or more <em>Request Filters</em> used to limit access to the
entire container based on remote host name or IP address.</li>
</ul>
</section>
<section name="Environment Entry">
<p>An <em>Environment Entry</em> is the representation of a
<code>&lt;env-entry&gt;</code> element from a web application deployment
descriptor. It will cause the creation of a corresponding entry in the
JNDI naming context provided to the corresponding <em>Context</em>. The
following configurable properties are supported:</p>
<ul>
<li><code>description</code> - Description of this environment entry.</li>
<li><code>name</code> - Environment entry name (relative to the
<code>java:comp/env</code> context)</li>
<li><code>type</code> - Environment entry type (must be one of the fully
qualified Java classes listed in the servlet spec).</li>
<li><code>value</code> - Environment entry value (must be convertible from
String to the specified <code>type</code>.</li>
</ul>
</section>
<section name="Host">
<p>A <em>Host</em> is the representation of an individual virtual host,
which has a unique set of associated web applications.</p>
<p>The standard component implementing a <em>Host</em> is
<code>org.apache.catalina.core.StandardHost</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>aliases</code> - Zero or more DNS names that are also associated
with this host (for example, a particular host might be named
<code>www.mycompany.com</code> with an alias <code>company.com</code>).
</li>
<li><code>appBase</code> - Absolute or relative (to $CATALINA_BASE) path
to a directory from which web applications will be automatically
deployed.</li>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>name</code> - DNS Name of the virtual host represented by this
object.</li>
<li><code>unpackWARs</code> - Should web application archive files
deployed by this virtual host be unpacked first? [true]</li>
</ul>
<p>Each <em>Host</em> is owned by a parent <em>Engine</em>, and is
associated with:</p>
<ul>
<li>An optional <em>Access Logger</em> that logs all requests processed
by this virtual host.</li>
<li>One or more <em>Contexts</em> representing the web applications
operating on this <em>Host</em>.</li>
<li>A <em>Default Context</em> representing default <em>Context</em>
properties for web applications that are automatically deployed
by this <em>Host</em>.</li>
<li>A optional <em>Realm</em> used to provide authentication and access
control information for all web applications associated with this
virtual host (unless overridden by a subordinate component).</li>
</ul>
<p><strong>FIXME</strong> - Should we support configuration of the
User Web Applications functionality?</p>
</section>
<section name="JDBC Resource">
<p>A <em>JDBC Resources</em> represents a database connection pool (i.e.
an implementation of <code>javax.sql.DataSource</code> that will be
configured and made available in the JNDI naming context associated with
a web application.</p>
<p><strong>FIXME</strong> - properties of this administered object</p>
</section>
<section name="Loader">
<p>A <em>Loader</em> represents a web application class loader that will
be utilized to provide class loading services for a particular
<em>Context</em>.</p>
<p>The standard component implementing a <em>Loader</em> is
<code>org.apache.catalina.loader.WebappLoader</code>. It supports
the following configurable properties:</p>
<ul>
<li><code>reloadable</code> - Should this class loader check for modified
classes and initiate automatic reloads? [Set automatically from the
<code>reloadable</code> property of the corresponding <em>Context</em>]
</li>
</ul>
<p>Each <em>Loader</em> is owned by a parent <em>Context</em>.</p>
</section>
<section name="Manager">
<p>A <em>Manager</em> represents a session manager that will be associated
with a particular web application. <strong>FIXME</strong> - Add support
for advanced session managers and their associated Stores.</p>
<p>The standard component implementing a <em>Manager</em> is
<code>org.apache.catalina.session.StandardManager</code>. It supports
the following configurable properties:</p>
<ul>
<li><code>maxActiveSessions</code> - The maximum number of active sessions
that are allowed, or -1 for no limit. [-1]</li>
</ul>
<p>Each <em>Manager</em> is owned by a parent <em>Context</em>.</p>
</section>
<section name="Realm">
<p>A <em>Realm</em> represents a "database" of information about authorized
users, their passwords, and the security roles assigned to them. This will
be used by the container in the implementation of container-managed security
in accordance with the Servlet Specification. Several alternative
implementations are supported.</p>
<p><code>org.apache.catalina.realm.MemoryRealm</code> initializes its user
information from a simple XML file at startup time. If changes are made
to the information in this file, the corresponding web applications using
it must be restarted for the changes to take effect. It supports the
following configurable properties:</p>
<ul>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>pathname</code> - Absolute or relative (to $CATALINA_BASE) path to
the XML file containing our user information. [conf/tomcat-users.xml]
</li>
</ul>
<p><code>org.apache.catalina.realm.JDBCRealm</code> uses a relational
database (accessed via JDBC APIs) to contain the user information. Changes
in the contents of this database take effect immediately; however, the roles
assigned to a particular user are calculated only when the user initially
logs on (and not per request). The following configurable properties
are supported:</p>
<ul>
<li><code>connectionName</code> - Database username to use when establishing
a JDBC connection.</li>
<li><code>connectionPassword</code> - Database password to use when
establishing a JDBC connection.</li>
<li><code>connectionURL</code> - Connection URL to use when establishing
a JDBC connection.</li>
<li><code>driverName</code> - Fully qualified Java class name of the JDBC
driver to be utilized.</li>
<li><code>roleNameCol</code> - Name of the column, in the User Roles table,
which contains the role name.</li>
<li><code>userCredCol</code> - Name of the column, in the Users table,
which contains the password (encrypted or unencrypted).</li>
<li><code>userNameCol</code> - Name of the column, in both the Users and
User Roles tables, that contains the username.</li>
<li><code>userRoleTable</code> - Name of the User Roles table, which contains
one row per security role assigned to a particular user. This table must
contain the columns specified by the <code>userNameCol</code> and
<code>roleNameCol</code> properties.</li>
<li><code>userTable</code> - Name of the Users table, which contains one row
per authorized user. This table must contain the columns specified by
the <code>userNameCol</code> and <code>userCredCol</code> properties.
</li>
</ul>
<p><strong>FIXME</strong> - Should we provide mechanisms to edit the contents
of a "tomcat-users.xml" file through the admin applications?</p>
<p>Each <em>Realm</em> is owned by a parent <em>Engine</em>, <em>Host</em>,
or <em>Context</em>.</p>
</section>
<section name="Request Filter">
<p><strong>FIXME</strong> - complete this entry</p>
</section>
<section name="Server">
<p><strong>FIXME</strong> - complete this entry</p>
</section>
<section name="Service">
<p><strong>FIXME</strong> - complete this entry</p>
</section>
</body>
</document>

342
webapps/docs/funcspecs/fs-admin-opers.xml Normal file
View File

@@ -0,0 +1,342 @@
<?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="fs-admin-opers.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>Administrative Apps - Supported Operations</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Supported Operations Overview">
<p>This document defines the <em>Supported Operations</em> that may
be performed against the <a href="fs-admin-objects.html">Administered
Objects</a> that are supported by Tomcat administrative applications.
Not all operations are required to be available through every administrative
application that is implemented. However, if a given operation is available,
it should operate consistently with the descriptions found here.</p>
<p>Supported Operations are described for the following Administered
Objects:</p>
<ul>
<li><a href="#Access_Logger">Access Logger</a></li>
<li><a href="#Connector">Connector</a></li>
<li><a href="#Context">Context</a></li>
<li><a href="#Default_Context">Default Context</a></li>
<li><a href="#Engine">Engine</a></li>
<li><a href="#Environment_Entry">Environment Entry</a></li>
<li><a href="#Host">Host</a></li>
<li><a href="#JDBC_Resource">JDBC Resource</a></li>
<li><a href="#Loader">Loader</a></li>
<li><a href="#Manager">Manager</a></li>
<li><a href="#Realm">Realm</a></li>
<li><a href="#Request_Filter">Request Filter</a></li>
<li><a href="#Server">Server</a></li>
<li><a href="#Service">Service</a></li>
</ul>
</section>
<section name="Access Logger">
<p>From the perspective of a particular <em>Access Logger</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Engine</em>, <em>Host</em>, or
<em>Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Connector">
<p>From the perspective of a particular <em>Connector</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Service</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Context">
<p>From the perspective of a particular <em>Context</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Host</em>.</li>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Access Logger</em> associated
with this object.</li>
<li>Edit the configurable properties of the associated <em>Access
Logger</em>.</li>
<li>Remove the associated <em>Access Logger</em>.</li>
<li>Create and configure a new <em>Environment Entry</em> associated
with this object.</li>
<li>Select and edit the configurable properties of an associated
<em>Environment Entry</em>.</li>
<li>Remove an associated <em>Environment Entry</em>.</li>
<li>Create and configure a new <em>JDBC Resource</em> associated
with this object.</li>
<li>Select and edit the configurable properties of an associated
<em>JDBC Resource</em>.</li>
<li>Remove an associated <em>JDBC Resource</em>.</li>
<li>Create and configure a new <em>Loader</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Loader</em>.</li>
<li>Remove the associated <em>Loader</em>.</li>
<li>Create and configure a new <em>Manager</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Manager</em>.</li>
<li>Remove the associated <em>Manager</em>.</li>
<li>Create and configure a new <em>Realm</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Realm</em>.</li>
<li>Remove the associated <em>Realm</em>.</li>
<li>Create and configure a new <em>Request Filter</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an
associated <em>Request Filter</em></li>
<li>Remove an associated <em>Request Filter</em>.</li>
</ul>
</section>
<section name="Default Context">
<p>From the perspective of a particular <em>Default Context</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Engine</em> or <em>Host</em>.</li>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Environment Entry</em> associated
with this object.</li>
<li>Select and edit the configurable properties of an associated
<em>Environment Entry</em>.</li>
<li>Remove an associated <em>Environment Entry</em>.</li>
<li>Create and configure a new <em>JDBC Resource</em> associated
with this object.</li>
<li>Select and edit the configurable properties of an associated
<em>JDBC Resource</em>.</li>
<li>Remove an associated <em>JDBC Resource</em>.</li>
</ul>
</section>
<section name="Engine">
<p>From the perspective of a particular <em>Engine</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Service</em>.</li>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Access Logger</em> associated
with this object.</li>
<li>Edit the configurable properties of the associated <em>Access
Logger</em>.</li>
<li>Remove the associated <em>Access Logger</em>.</li>
<li>Create and configure a new <em>Default Context</em> associated
with this object.</li>
<li>Edit the configurable properties of the associated <em>Default
Context</em>.</li>
<li>Remove the associated <em>Default Context</em>.</li>
<li>Create and configure a new <em>Host</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an
associated <em>Host</em>.</li>
<li>Remove an associated <em>Host</em>.</li>
<li>Create and configure a new <em>Realm</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Realm</em>.</li>
<li>Remove the associated <em>Realm</em>.</li>
<li>Create and configure a new <em>Request Filter</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an
associated <em>Request Filter</em></li>
<li>Remove an associated <em>Request Filter</em>.</li>
</ul>
</section>
<section name="Environment Entry">
<p>From the perspective of a particular <em>Environment Entry</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Context</em> or <em>Default Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Host">
<p>From the perspective of a particular <em>Host</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Engine</em>.</li>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Access Logger</em> associated
with this object.</li>
<li>Edit the configurable properties of the associated <em>Access
Logger</em>.</li>
<li>Remove the associated <em>Access Logger</em>.</li>
<li>Create and configure a new <em>Context</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an associated
<em>Context</em>.</li>
<li>Remove an associated <em>Context</em>.</li>
<li>Create and configure a new <em>Default Context</em> associated
with this object.</li>
<li>Edit the configurable properties of the associated <em>Default
Context</em>.</li>
<li>Remove the associated <em>Default Context</em>.</li>
<li>Create and configure a new <em>Realm</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Realm</em>.</li>
<li>Remove the associated <em>Realm</em>.</li>
<li>Create and configure a new <em>Request Filter</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an
associated <em>Request Filter</em></li>
<li>Remove an associated <em>Request Filter</em>.</li>
</ul>
</section>
<section name="JDBC Resource">
<p>From the perspective of a particular <em>JDBC Resource</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Context</em> or <em>Default Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Loader">
<p>From the perspective of a particular <em>Loader</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Manager">
<p>From the perspective of a particular <em>Manager</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Realm">
<p>From the perspective of a particular <em>Realm</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Engine</em>, <em>Host</em>, or
<em>Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Request Filter">
<p>From the perspective of a particular <em>Request Filter</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Engine</em>, <em>Host</em>, or
<em>Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Server">
<p>From the perspective of the overall <em>Server</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Service</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an associated
<em>Service</em>.</li>
</ul>
</section>
<section name="Service">
<p>From the perspective of a particular <em>Service</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Server</em>.</li>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Connector</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an associated
<em>Connector</em>.</li>
<li>Remove an associated <em>Connector</em>.</li>
<li>Create and configure a new <em>Engine</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Engine</em>.</li>
<li>Remove the associated <em>Engine</em>.</li>
</ul>
</section>
</body>
</document>

270
webapps/docs/funcspecs/fs-default.xml Normal file
View File

@@ -0,0 +1,270 @@
<?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="fs-default.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>Default Servlet</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<subsection name="Introduction">
<p>The purpose of the <strong>Default Servlet</strong> is to serve
static resources of a web application in response to client requests.
As the name implies, it is generally configured as the "default"
servlet for a web application, by being mapped to a URL pattern "/".</p>
</subsection>
<subsection name="External Specifications">
<p>The following external specifications have provisions which
partially define the correct behavior of the default servlet:</p>
<ul>
<li><a href="https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html">
Servlet Specification</a> (Version 3.1)</li>
<li><a href="https://www.rfc-editor.org/rfc/rfc2046.txt">Multipurpose
Internet Mail Extensions (MIME) Part Two: Media Types</a></li>
<li><a href="https://www.rfc-editor.org/rfc/rfc2616.txt">Hypertext
Transfer Protocol &#x2013; HTTP/1.1</a></li>
</ul>
</subsection>
<subsection name="Implementation Requirements">
<p>The implementation of this functionality shall conform to the
following requirements:</p>
<ul>
<li>Must be implemented as a servlet.</li>
<li>Must support configurable parameters for debugging detail level,
input buffer size, output buffer size, whether or not to produce
directory listings when no welcome file is present, and whether or not
modifications are supported via DELETE and PUT.</li>
<li>Log debugging and operational messages (suitably internationalized)
via the <code>getServletContext().log()</code> method.</li>
</ul>
</subsection>
</section>
<section name="Dependencies">
<subsection name="Environmental Dependencies">
<p>The following environmental dependencies must be met in order for
the default servlet to operate correctly:</p>
<ul>
<li>The default servlet must be registered in the application deployment
descriptor (or the default deployment descriptor in file
<code>$CATALINA_BASE/conf/web.xml</code>) using a "default servlet"
servlet mapping, signified by URL pattern "/".</li>
</ul>
</subsection>
<subsection name="Container Dependencies">
<p>Correct operation of the default servlet depends on the following
specific features of the surrounding container:</p>
<ul>
<li>The container shall provide a servlet context attribute that
lists the welcome file names that have been defined for this
web application.</li>
<li>The container shall provide a servlet context attribute that
contains a <code>javax.naming.directory.DirContext</code>
implementation representing the static resources of this
web application.</li>
</ul>
</subsection>
</section>
<section name="Functionality">
<subsection name="Initialization Functionality">
<p>The following processing must be performed when the <code>init()</code>
method of the default servlet is called:</p>
<ul>
<li>Process and sanity check configuration parameters.</li>
</ul>
</subsection>
<subsection name="Per-Request Functionality">
<p>For all HTTP request methods, the resource path is determined from
the path information provided to this request, either as request attribute
<code>javax.servlet.include.path_info</code> (for a request dispatcher
access to a static resource) or by calling
<code>request.getPathInfo()</code> directly.</p>
<p>On each HTTP DELETE request processed by this servlet, the following
processing shall be performed:</p>
<ul>
<li>If modifications to the static resources are not allowed (set by a
configuration parameter), return HTTP status 403 (forbidden).</li>
<li>If an attempt is made to delete a resource from <code>/META-INF</code>
or <code>/WEB-INF</code>, return HTTP status 403 (forbidden).</li>
<li>If the requested resource does not exist, return HTTP status 404
(not found)</li>
<li>Unbind the resource from the directory context containing the
static resources for this web application. If successful, return
HTTP status 204 (no content). Otherwise, return HTTP status 405
(method not allowed).</li>
</ul>
<p>On each HTTP GET request processed by this servlet, the following
processing shall be performed:</p>
<ul>
<li>If the request is for a resource under <code>/META-INF</code> or
<code>/WEB-INF</code>, return HTTP status 404 (not found).</li>
<li>If the requested resource does not exist, return HTTP status 404
(not found).</li>
<li>If the requested resource is not a directory, but the resource
path ends in "/" or "\", return HTTP status 404 (not found).</li>
<li>If the requested resource is a directory:
<ul>
<li>If the request path does not end with "/", redirect to a
corresponding path with "/" appended so that relative references
in welcome files are resolved correctly.</li>
<li>If one of the specified welcome files exists, redirect to the
path for that welcome file so that it will be served explicitly.
</li>
</ul></li>
<li>If the request being processed contains an <code>If-Range</code>
header, perform the processing described in the HTTP/1.1 specification
to determine whether the client's information is up to date.</li>
<li>Determine the content type of the response, by looking up the
corresponding MIME type in our servlet context.</li>
<li>If the requested resource is a directory:
<ul>
<li>If directory listings are suppressed, return HTTP status 404
(not found).</li>
<li>Set the content type to <code>text/html</code>.</li>
</ul></li>
<li>Determine the range(s) to be returned, based on the existence of
any <code>If-Range</code> and <code>Range</code> headers.</li>
<li>If the requested resource is a directory, include an <code>ETag</code>
header in the response, with the value calculated based on the content
of the directory.</li>
<li>Include a <code>Last-Modified</code> header in the response documenting
the date/time that the resource was last modified.</li>
<li>Unless we are processing a HEAD request, include the appropriate
content (or content ranges) in the response.</li>
</ul>
<p>On each HTTP HEAD request processed by this servlet, the following
processing shall be performed:</p>
<ul>
<li>Processed identically to an HTTP GET request, except that the data
content is not transmitted after the headers.</li>
</ul>
<p>On each HTTP POST request processed by this servlet, the following
processing shall be performed:</p>
<ul>
<li>Processed identically to an HTTP GET request.</li>
</ul>
<p>On each HTTP PUT request processed by this servlet, the following
processing shall be performed:</p>
<ul>
<li>If modifications to the static resources are not allowed (set by a
configuration parameter), return HTTP status 403 (forbidden).</li>
<li>If an attempt is made to delete a resource from <code>/META-INF</code>
or <code>/WEB-INF</code>, return HTTP status 403 (forbidden).</li>
<li>Create a new resource from the body of this request.</li>
<li>Bind or rebind the specified path to the new resource (depending on
whether it currently exists or not). Return HTTP status as follows:
<ul>
<li>If binding was unsuccessful, return HTTP status 409 (conflict).
</li>
<li>If binding was successful and the resource did not previously
exist, return HTTP status 201 (created).</li>
<li>If binding was successful and the resource previously existed,
return HTTP status 204 (no content).</li>
</ul></li>
</ul>
</subsection>
<subsection name="Finalization Functionality">
<p>No specific processing is required when the <code>destroy()</code>
method is called:</p>
</subsection>
</section>
<section name="Testable Assertions">
<p>In addition to the assertions implied by the functionality requirements
listed above, the following additional assertions shall be tested to
validate the behavior of the default servlet:</p>
<ul>
<li>Requests for resources that do not exist in the web application must
return HTTP status 404 (not found).</li>
<li>The default servlet must operate identically for web applications that
are run out of a WAR file directly, or from an unpacked directory
structure.</li>
<li>If the web application is running out of an unpacked directory
structure, the default servlet must recognize cases where the resource
has been updated through external means.</li>
</ul>
</section>
</body>
</document>

266
webapps/docs/funcspecs/fs-jdbc-realm.xml Normal file
View File

@@ -0,0 +1,266 @@
<?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="fs-jdbc-realm.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>JDBCRealm</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<subsection name="Introduction">
<p>The purpose of the <strong>JDBCRealm</strong> implementation is to
provide a mechanism by which Tomcat can acquire information needed
to authenticate web application users, and define their security roles,
from a relational database accessed via JDBC APIs. For integration
with Catalina, the resulting class(es) must implement the
<code>org.apache.catalina.Realm</code> interface.</p>
<p>This specification reflects a combination of functionality that is
already present in the <code>org.apache.catalina.realm.JDBCRealm</code>
class, as well as requirements for enhancements that have been
discussed. Where appropriate, requirements statements are marked
<em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>
<p>The current status of this functional specification is
<strong>PROPOSED</strong>. It has not yet been discussed and
agreed to on the TOMCAT-DEV mailing list.</p>
</subsection>
<subsection name="External Specifications">
<p>The implementation of this functionality depends on the following
external specifications:</p>
<ul>
<li><a href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html">
Java Database Connectivity</a> (version 2.0 or later)</li>
<li><a href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html">
Java Database Connectivity Optional Package</a> (version 2.0 or later)</li>
</ul>
</subsection>
<subsection name="Implementation Requirements">
<p>The implementation of this functionality shall conform to the
following requirements:</p>
<ul>
<li>Be realized in one or more implementation classes.</li>
<li>Implement the <code>org.apache.catalina.Realm</code> interface.
[Current]</li>
<li>Implement the <code>org.apache.catalina.Lifecycle</code>
interface. [Current]</li>
<li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
base class.</li>
<li>Live in the <code>org.apache.catalina.realm</code> package.
[Current]</li>
<li>Support a configurable debugging detail level. [Current]</li>
<li>Log debugging and operational messages (suitably internationalized)
via the <code>getContainer().log()</code> method. [Current]</li>
</ul>
</subsection>
</section>
<section name="Dependencies">
<subsection name="Environmental Dependencies">
<p>The following environmental dependencies must be met in order for
JDBCRealm to operate correctly:</p>
<ul>
<li>The desire to utilize JDBCRealm must be registered in
<code>$CATALINA_BASE/conf/server.xml</code>, in a
<code>&lt;Realm&gt;</code> element that is nested inside a
corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
or <code>&lt;Context&gt;</code> element.</li>
</ul>
</subsection>
<subsection name="Container Dependencies">
<p>Correct operation of JDBCRealm depends on the following
specific features of the surrounding container:</p>
<ul>
<li>Interactions with <code>JDBCRealm</code> will be initiated by
the appropriate <code>Authenticator</code> implementation, based
on the login method that is selected.</li>
<li><code>JDBCRealm</code> must have the JDBC standard API classes
available to it. For a JDK 1.2 or later container, these APIs
are included in the standard platform.</li>
<li>When connection pooling is implemented, <code>JDBCRealm</code>
must have the JDBC Optional Package (version 2.0 or later) APIs
available to it. This library is available as a separate
download (and will be included in Tomcat binary distributions).</li>
</ul>
</subsection>
</section>
<section name="Functionality">
<subsection name="Overview of Operation">
<p>The main purpose of <code>JDBCRealm</code> is to allow Catalina to
authenticate users, and look up the corresponding security roles, from
the information found in a relational database accessed via JDBC APIs.
For maximum flexibility, the details of how this is done (for example,
the names of the required tables and columns) should be configurable.</p>
<p>Each time that Catalina needs to authenticate a user, it will call
the <code>authenticate()</code> method of this Realm implementation,
passing the username and password that were specified by the user. If
we find the user in the database (and match on the password), we accumulate
all of the security roles that are defined for this user, and create a
new <code>GenericPrincipal</code> object to be returned. If the user
is not authenticated, we return <code>null</code> instead. The
<code>GenericUser</code> object caches the set of security roles that
were owned by this user at the time of authentication, so that calls to
<code>isUserInRole()</code> can be answered without going back to the
database every time.</p>
</subsection>
<subsection name="Detailed Functional Requirements">
<h3>Configurable Properties</h3>
<p>The implementation shall support the following properties
that can be configured with JavaBeans property setters:</p>
<ul>
<li>Configuration parameters defining the JDBC driver to use, the
database connection URL to be accessed, and the username/password
to use for logging in. [Current]</li>
<li>Configuration parameters describing the connection pool to be
created to support simultaneous authentications. [Requested]</li>
<li>Name of the tables to be searched for users and roles. [Current]</li>
<li>Name of the columns to be used for usernames, passwords, and
role names. [Current]</li>
</ul>
<h3>Lifecycle Functionality</h3>
<p>The following processing must be performed when the <code>start()</code>
method is called:</p>
<ul>
<li>Establish a connection to the configured database, using the
configured username and password. [Current]</li>
<li>Configure and establish a connection pool of connections to the
database. [Requested]</li>
</ul>
<p>The following processing must be performed when the <code>stop()</code>
method is called:</p>
<ul>
<li>Close any opened connections to the database.</li>
</ul>
<h3>Method authenticate() Functionality</h3>
<p>When <code>authenticate()</code> is called, the following processing
is required:</p>
<ul>
<li>Acquire the one and only connection [Current] or acquire a connection
from the connection pool [Requested].</li>
<li>Select the one and only row from the user's table for this user,
and retrieve the corresponding password column. If zero rows (or
more than one row) are found, return <code>null</code>.</li>
<li>Authenticate the user by comparing the (possibly encrypted) password
value that was received against the password presented by the user.
If there is no match, return <code>null</code>.</li>
<li>Acquire a <code>List</code> of the security roles assigned to the
authenticated user by selecting from the roles table.</li>
<li>Construct a new instance of class
<code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
constructor arguments: this realm instance, the authenticated
username, and a <code>List</code> of the security roles associated
with this user.</li>
<li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
<code>GenericPrincipal</code> objects for a particular user, because
the information in the directory server might have changed since the
last time this user was authenticated.</li>
<li>Return the newly constructed <code>GenericPrincipal</code>.</li>
</ul>
<h3>Method hasRole() Functionality</h3>
<p>When <code>hasRole()</code> is called, the following processing
is required:</p>
<ul>
<li>The <code>principal</code> that is passed as an argument SHOULD
be one that we returned (instanceof class
<code>org.apache.catalina.realm.GenericPrincipal</code>, with a
<code>realm</code> property that is equal to our instance.</li>
<li>If the passed <code>principal</code> meets these criteria, check
the specified role against the list returned by
<code>getRoles()</code>, and return <code>true</code> if the
specified role is included; otherwise, return <code>false</code>.</li>
<li>If the passed <code>principal</code> does not meet these criteria,
return <code>false</code>.</li>
</ul>
</subsection>
</section>
<section name="Testable Assertions">
<p>In addition to the assertions implied by the functionality requirements
listed above, the following additional assertions shall be tested to
validate the behavior of <code>JDBCRealm</code>:</p>
<ul>
</ul>
</section>
</body>
</document>

417
webapps/docs/funcspecs/fs-jndi-realm.xml Normal file
View File

@@ -0,0 +1,417 @@
<?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="fs-jndi-realm.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>JNDIRealm</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<subsection name="Introduction">
<p>The purpose of the <strong>JNDIRealm</strong> implementation is to
provide a mechanism by which Tomcat can acquire information needed
to authenticate web application users, and define their security roles,
from a directory server or other service accessed via JNDI APIs. For
integration with Catalina, this class must implement the
<code>org.apache.catalina.Realm</code> interface.</p>
<p>This specification reflects a combination of functionality that is
already present in the <code>org.apache.catalina.realm.JNDIRealm</code>
class, as well as requirements for enhancements that have been
discussed. Where appropriate, requirements statements are marked
<em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>
<p>The current status of this functional specification is
<strong>PROPOSED</strong>. It has not yet been discussed and
agreed to on the TOMCAT-DEV mailing list.</p>
<p>The code in the current version of <code>JNDIRealm</code>, and the
ideas expressed in this functional specification, are the results of
contributions from many individuals, including (alphabetically):</p>
<ul>
<li>Holman, John &lt;j.g.holman@qmw.ac.uk&gt;</li>
<li>Lockhart, Ellen &lt;elockhart@home.com&gt;</li>
<li>McClanahan, Craig &lt;craigmcc@apache.org&gt;</li>
</ul>
</subsection>
<subsection name="External Specifications">
<p>The implementation of this functionality depends on the following
external specifications:</p>
<ul>
<li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jndi/index.html">
Java Naming and Directory Interface</a> (version 1.2.1 or later)</li>
</ul>
</subsection>
<subsection name="Implementation Requirements">
<p>The implementation of this functionality shall conform to the
following requirements:</p>
<ul>
<li>Be realized in one or more implementation classes.</li>
<li>Implement the <code>org.apache.catalina.Realm</code> interface.
[Current]</li>
<li>Implement the <code>org.apache.catalina.Lifecycle</code>
interface. [Current]</li>
<li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
base class.</li>
<li>Live in the <code>org.apache.catalina.realm</code> package.
[Current]</li>
<li>Support a configurable debugging detail level. [Current]</li>
<li>Log debugging and operational messages (suitably internationalized)
via the <code>getContainer().log()</code> method. [Current]</li>
</ul>
</subsection>
</section>
<section name="Dependencies">
<subsection name="Environmental Dependencies">
<p>The following environmental dependencies must be met in order for
JNDIRealm to operate correctly:</p>
<ul>
<li>The desire to utilize JNDIRealm must be registered in
<code>$CATALINA_BASE/conf/server.xml</code>, in a
<code>&lt;Realm&gt;</code> element that is nested inside a
corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
or <code>&lt;Context&gt;</code> element.</li>
<li>If the <em>Administrator Login</em> operational mode is selected,
the configured administrator username and password must be configured
in the corresponding directory server.</li>
<li>If the <em>Username Login</em> operational mode is selected,
the corresponding directory server must be configured to accept
logins with the username and password that will be passed to
<code>JNDIRealm</code> by the appropriate <code>Authenticator</code>.
</li>
</ul>
</subsection>
<subsection name="Container Dependencies">
<p>Correct operation of JNDIRealm depends on the following
specific features of the surrounding container:</p>
<ul>
<li>Interactions with <code>JNDIRealm</code> will be initiated by
the appropriate <code>Authenticator</code> implementation, based
on the login method that is selected.</li>
</ul>
</subsection>
</section>
<section name="Functionality">
<subsection name="Operational Modes">
<p>The completed <code>JNDIRealm</code> must support two major operational
modes in order to support all of the required use cases. For the purposes
of this document, the modes are called <em>administrator login</em> and
<em>Username Login</em>. They are described further in the following
paragraphs.</p>
<p>For <em>Administrator Login</em> mode, <code>JNDIRealm</code> will be
configured to establish one or more connections (using a connection pool)
to an appropriate directory server, using JNDI APIs, under a "system
administrator" username and password. This is similar to the approach
normally used to configure <code>JDBCRealm</code> to access authentication
and access control information in a database. It is assumed that the
system administrator username and password that are configured provide
sufficient privileges within the directory server to read (but not modify)
the username, password, and assigned roles for each valid user of the
web application associated with this <code>Realm</code>. The password
can be stored in cleartext, or in one of the digested modes supported by
the <code>org.apache.catalina.realm.RealmBase</code> base class.</p>
<p>For <em>Username Login</em> mode, <code>JNDIRealm</code> does not
normally remain connected to the directory server. Instead, whenever a
user is to be authenticated, a connection to the directory server
(using the username and password received from the authenticator) is
attempted. If this connection is successful, the user is assumed to be
successfully authenticated. This connection is then utilized to read
the corresponding security roles associated with this user, and the
connection is then broken.</p>
<p><strong>NOTE</strong> - <em>Username Login</em> mode cannot be used
if you have selected login method <code>DIGEST</code> in your web
application deployment descriptor (<code>web.xml</code>) file. This
restriction exists because the cleartext password is never available
to the container, so it is not possible to bind to the directory server
using the user's username and password.</p>
<p>Because these operational modes work so differently, the functionality
for each mode will be described separately. Whether or not both modes
are actually supported by a single class (versus a class per mode) is
an implementation detail left to the designer.</p>
<p><strong>NOTE</strong> - The current implementation only implements
part of the <em>Administrator Lookup</em> mode requirements. It does
not support the <em>Username Lookup</em> mode at all, at this point.</p>
</subsection>
<subsection name="Administrator Login Mode Functionality">
<h3>Configurable Properties</h3>
<p>The implementation shall support the following properties
that can be configured with JavaBeans property setters:</p>
<ul>
<li><code>connectionURL</code> - URL of the directory server we will
be contacting.</li>
<li><code>contextFactory</code> - Fully qualified class name of the JNDI
context factory used to retrieve our InitialContext.
[com.sun.jndi.ldap.LdapCtxFactory]</li>
<li>Additional configuration properties required to establish the
appropriate connection. [Requested]</li>
<li>Connection pool configuration properties. [Requested]</li>
<li>Configuration properties defining how a particular user is
authenticated. The following capabilities should be supported:
<ul>
<li>Substitute the specified username into a string. [Requested]</li>
<li>Retrieve the distinguished name (DN) of an authorized user via an
LDAP search string with a replacement placeholder for the
username, and comparison of the password to a configurable
attribute retrieved from the search result. [Current]</li>
</ul></li>
<li>Configuration properties defining how the roles associated with a
particular authenticated user can be retrieved. The following
approaches should be supported:
<ul>
<li>Retrieve a specified attribute (possibly multi-valued)
from an LDAP search expression,
with a replacement placeholder for the DN of the user.
[Current]</li>
<li>Retrieve a set of role names that are defined implicitly (by
selecting principals that match a search pattern) rather than
explicitly (by finding a particular attribute value).
[Requested]</li>
</ul></li>
</ul>
<h3>Lifecycle Functionality</h3>
<p>The following processing must be performed when the <code>start()</code>
method is called:</p>
<ul>
<li>Establish a connection to the configured directory server, using the
configured system administrator username and password. [Current]</li>
<li>Configure and establish a connection pool of connections to the
directory server. [Requested]</li>
</ul>
<p>The following processing must be performed when the <code>stop()</code>
method is called:</p>
<ul>
<li>Close any opened connections to the directory server.</li>
</ul>
<h3>Method authenticate() Functionality</h3>
<p>When <code>authenticate()</code> is called, the following processing
is required:</p>
<ul>
<li>Acquire the one and only connection [Current] or acquire a connection
from the connection pool [Requested].</li>
<li>Authenticate the user by retrieving the user's Distinguished Name,
based on the specified username and password.</li>
<li>If the user was not authenticated, release the allocated connection
and return <code>null</code>.</li>
<li>Acquire a <code>List</code> of the security roles assigned to the
authenticated user.</li>
<li>Construct a new instance of class
<code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
constructor arguments: this realm instance, the authenticated
username, and a <code>List</code> of the security roles associated
with this user.</li>
<li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
<code>GenericPrincipal</code> objects for a particular user, because
the information in the directory server might have changed since the
last time this user was authenticated.</li>
<li>Return the newly constructed <code>GenericPrincipal</code>.</li>
</ul>
<h3>Method hasRole() Functionality</h3>
<p>When <code>hasRole()</code> is called, the following processing
is required:</p>
<ul>
<li>The <code>principal</code> that is passed as an argument SHOULD
be one that we returned (instanceof class
<code>org.apache.catalina.realm.GenericPrincipal</code>, with a
<code>realm</code> property that is equal to our instance.</li>
<li>If the passed <code>principal</code> meets these criteria, check
the specified role against the list returned by
<code>getRoles()</code>, and return <code>true</code> if the
specified role is included; otherwise, return <code>false</code>.</li>
<li>If the passed <code>principal</code> does not meet these criteria,
return <code>false</code>.</li>
</ul>
</subsection>
<subsection name="Username Login Mode Functionality">
<h3>Configurable Properties</h3>
<p>The implementation shall support the following properties
that can be configured with JavaBeans property setters:</p>
<ul>
<li><code>connectionURL</code> - URL of the directory server we will
be contacting.</li>
<li><code>contextFactory</code> - Fully qualified class name of the JNDI
context factory used to retrieve our InitialContext.
[com.sun.jndi.ldap.LdapCtxFactory]</li>
<li>Additional configuration properties required to establish the
appropriate connection. [Requested]</li>
<li>Connection pool configuration properties. [Requested]</li>
<li>Configuration properties defining if and how a user might be looked
up before binding to the directory server. The following approaches
should be supported:
<ul>
<li>No previous lookup is required - username specified by the user
is the same as that used to authenticate to the directory
server.</li>
<li>Substitute the specified username into a string.</li>
<li>Search the directory server based on configured criteria to
retrieve the distinguished name of the user, then attempt to
bind with that distinguished name.</li>
</ul></li>
<li>Configuration properties defining how the roles associated with a
particular authenticated user can be retrieved. The following
approaches should be supported:
<ul>
<li>Retrieve a specified attribute (possibly multi-valued)
from an LDAP search expression,
with a replacement placeholder for the DN of the user.
[Current]</li>
</ul></li>
</ul>
<h3>Lifecycle Functionality</h3>
<p>The following processing must be performed when the <code>start()</code>
method is called:</p>
<ul>
<li>None required.</li>
</ul>
<p>The following processing must be performed when the <code>stop()</code>
method is called:</p>
<ul>
<li>None required.</li>
</ul>
<h3>Method authenticate() Functionality</h3>
<p>When <code>authenticate()</code> is called, the following processing
is required:</p>
<ul>
<li>Attempt to bind to the directory server, using the username and
password provided by the user.</li>
<li>If the user was not authenticated, release the allocated connection
and return <code>null</code>.</li>
<li>Acquire a <code>List</code> of the security roles assigned to the
authenticated user.</li>
<li>Construct a new instance of class
<code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
constructor arguments: this realm instance, the authenticated
username, and a <code>List</code> of the security roles associated
with this user.</li>
<li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
<code>GenericPrincipal</code> objects for a particular user, because
the information in the directory server might have changed since the
last time this user was authenticated.</li>
<li>Return the newly constructed <code>GenericPrincipal</code>.</li>
</ul>
<h3>Method hasRole() Functionality</h3>
<p>When <code>hasRole()</code> is called, the following processing
is required:</p>
<ul>
<li>The <code>principal</code> that is passed as an argument SHOULD
be one that we returned (instanceof class
<code>org.apache.catalina.realm.GenericPrincipal</code>, with a
<code>realm</code> property that is equal to our instance.</li>
<li>If the passed <code>principal</code> meets these criteria, check
the specified role against the list returned by
<code>getRoles()</code>, and return <code>true</code> if the
specified role is included; otherwise, return <code>false</code>.</li>
<li>If the passed <code>principal</code> does not meet these criteria,
return <code>false</code>.</li>
</ul>
</subsection>
</section>
<section name="Testable Assertions">
<p>In addition to the assertions implied by the functionality requirements
listed above, the following additional assertions shall be tested to
validate the behavior of <code>JNDIRealm</code>:</p>
<ul>
</ul>
</section>
</body>
</document>

253
webapps/docs/funcspecs/fs-memory-realm.xml Normal file
View File

@@ -0,0 +1,253 @@
<?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="fs-memory-realm.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>MemoryRealm</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<subsection name="Introduction">
<p>The purpose of the <strong>MemoryRealm</strong> implementation is to
provide a mechanism by which Tomcat can acquire information needed
to authenticate web application users, and define their security roles,
from a simple text-based configuration file in XML format. This is
intended to simplify the initial installation and operation of Tomcat,
without the complexity of configuring a database or directory server
based Realm. It is not intended for production use.</p>
<p>This specification reflects a combination of functionality that is
already present in the <code>org.apache.catalina.realm.MemoryRealm</code>
class, as well as requirements for enhancements that have been
discussed. Where appropriate, requirements statements are marked
<em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>
<p>The current status of this functional specification is
<strong>PROPOSED</strong>. It has not yet been discussed and
agreed to on the TOMCAT-DEV mailing list.</p>
</subsection>
<subsection name="External Specifications">
<p>The implementation of this functionality depends on the following
external specifications:</p>
<ul>
<li>None</li>
</ul>
</subsection>
<subsection name="Implementation Requirements">
<p>The implementation of this functionality shall conform to the
following requirements:</p>
<ul>
<li>Be realized in one or more implementation classes.</li>
<li>Implement the <code>org.apache.catalina.Realm</code> interface.
[Current]</li>
<li>Implement the <code>org.apache.catalina.Lifecycle</code>
interface. [Current]</li>
<li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
base class.</li>
<li>Live in the <code>org.apache.catalina.realm</code> package.
[Current]</li>
<li>Support a configurable debugging detail level. [Current]</li>
<li>Log debugging and operational messages (suitably internationalized)
via the <code>getContainer().log()</code> method. [Current]</li>
</ul>
</subsection>
</section>
<section name="Dependencies">
<subsection name="Environmental Dependencies">
<p>The following environmental dependencies must be met in order for
MemoryRealm to operate correctly:</p>
<ul>
<li>The desire to utilize MemoryRealm must be registered in
<code>$CATALINA_BASE/conf/server.xml</code>, in a
<code>&lt;Realm&gt;</code> element that is nested inside a
corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
or <code>&lt;Context&gt;</code> element. (This is already
included in the default <code>server.xml</code> file.)</li>
</ul>
</subsection>
<subsection name="Container Dependencies">
<p>Correct operation of MemoryRealm depends on the following
specific features of the surrounding container:</p>
<ul>
<li>Interactions with <code>MemoryRealm</code> will be initiated by
the appropriate <code>Authenticator</code> implementation, based
on the login method that is selected.</li>
<li><code>MemoryRealm</code> must have an XML parser compatible with
the JAXP/1.1 APIs available to it. This is normally accomplished
by placing the corresponding JAR files in directory
<code>$CATALINA_HOME/lib</code>.</li>
</ul>
</subsection>
</section>
<section name="Functionality">
<subsection name="Overview of Operation">
<p>The main purpose of <code>MemoryRealm</code> is to allow Catalina to
authenticate users, and look up the corresponding security roles, from
the information found in an XML-format configuration file. The format
of this file is described below. When a <code>MemoryRealm</code>
instance is started, it will read the contents of this XML file and create
an "in memory database" of all the valid users and their associated
security roles.</p>
<p>Each time that Catalina needs to authenticate a user, it will call
the <code>authenticate()</code> method of this Realm implementation,
passing the username and password that were specified by the user. If
we find the user in the database (and match on the password), we accumulate
all of the security roles that are defined for this user, and create a
new <code>GenericPrincipal</code> object to be returned. If the user
is not authenticated, we return <code>null</code> instead. The
<code>GenericUser</code> object caches the set of security roles that
were owned by this user at the time of authentication, so that calls to
<code>isUserInRole()</code> can be answered without going back to the
database every time.</p>
</subsection>
<subsection name="Detailed Functional Requirements">
<h3>Configurable Properties</h3>
<p>The implementation shall support the following properties
that can be configured with JavaBeans property setters:</p>
<ul>
<li>Configurable debugging detail level.</li>
<li>Configurable file pathname (absolute or relative to
<code>$CATALINA_BASE</code> of the XML file containing our
defined users. [<code>conf/tomcat-users.xml</code>].</li>
</ul>
<h3>Lifecycle Functionality</h3>
<p>The following processing must be performed when the <code>start()</code>
method is called:</p>
<ul>
<li>Open and parse the specified XML file.</li>
<li>Create an in-memory database representation of the XML file
contents.</li>
<li><strong>NOTE</strong> - There is no requirement to recognize
subsequent changes to the contents of the XML file.</li>
</ul>
<p>The following processing must be performed when the <code>stop()</code>
method is called:</p>
<ul>
<li>Release object references to the in-memory database representation.</li>
</ul>
<h3>Method authenticate() Functionality</h3>
<p>When <code>authenticate()</code> is called, the following processing
is required:</p>
<ul>
<li>Select the one and only "user" instance from the in-memory database,
based on matching the specified username. If there is no such
instance, return <code>null</code>.</li>
<li>Authenticate the user by comparing the (possibly encrypted) password
value that was received against the password presented by the user.
If there is no match, return <code>null</code>.</li>
<li>Construct a new instance of class
<code>org.apache.catalina.realm.GenericPrincipal</code> (if not
already using this as the internal database representation) that
contains the authenticated username and a <code>List</code> of the
security roles associated with this user.</li>
<li>Return the newly constructed <code>GenericPrincipal</code>.</li>
</ul>
<h3>Method hasRole() Functionality</h3>
<p>When <code>hasRole()</code> is called, the following processing
is required:</p>
<ul>
<li>The <code>principal</code> that is passed as an argument SHOULD
be one that we returned (instanceof class
<code>org.apache.catalina.realm.GenericPrincipal</code>, with a
<code>realm</code> property that is equal to our instance.</li>
<li>If the passed <code>principal</code> meets these criteria, check
the specified role against the list returned by
<code>getRoles()</code>, and return <code>true</code> if the
specified role is included; otherwise, return <code>false</code>.</li>
<li>If the passed <code>principal</code> does not meet these criteria,
return <code>false</code>.</li>
</ul>
</subsection>
</section>
<section name="Testable Assertions">
<p>In addition to the assertions implied by the functionality requirements
listed above, the following additional assertions shall be tested to
validate the behavior of <code>MemoryRealm</code>:</p>
<ul>
</ul>
</section>
</body>
</document>

70
webapps/docs/funcspecs/index.xml Normal file
View File

@@ -0,0 +1,70 @@
<?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="Catalina Functional Specifications">
<p>This documentation area includes <em>functional specifications</em> for
many features supported by the <strong>Catalina</strong> servlet container
portion of Tomcat. In most cases, these features are not documented in the
underlying Servlet or JSP specifications, so a definition of the expected
correct behavior is important both to implementors of those features, and to
test writers trying to decide what to test.</p>
<p>The functional specifications are divided into the following categories
in the menu (to the left):</p>
<ul>
<li><em>Administrative Apps</em> - Overall requirements for supporting an
ability to configure and operate a Tomcat installation through tools,
as well as detailed requirements for the tools themselves.</li>
<li><em>Internal Servlets</em> - Requirements for Catalina features that are
implemented as internal, container-managed, servlets.</li>
<li><em>Realm Implementations</em> - Requirements for the implementations of
the <code>org.apache.catalina.Realm</code> interface (providing access to
collections of users, passwords and roles) that are included in the
standard Tomcat distribution.</li>
</ul>
<p><em>NOTE</em> - In some cases, the contents of these functional specs has
been "reverse engineered" from existing implementations. This exercise is
still useful, because it provides an introduction to <strong>what</strong>
Catalina does, without being as concerned with <strong>how</strong> this is
accomplished.</p>
<p><strong>TODO</strong> - Obviously, this area has a long way to go before
it is complete. Contributions are welcome!</p>
</section>
</body>
</document>

698
webapps/docs/funcspecs/mbean-names.xml Normal file
View File

@@ -0,0 +1,698 @@
<?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="mbean-names.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<author email="amyroh@apache.org">Amy Roh</author>
<title>Tomcat MBean Names</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Background">
<p>We will be using <em>JMX MBeans</em> as the technology for
implementing manageability of Tomcat.</p>
<p>One of the key concepts of JMX is that each management bean has a unique
name in the MBeanServer's registry, and that management applications can
utilize these names to retrieve the MBean of interest to them for a
particular management operation. This document proposes a naming convention
for MBeans that allows easy calculation of the name for a particular MBean.
For background information on JMX MBean names, see the <em>Java Management
Extensions Instrumentation and Agent Specification</em>, version 1.0,
section 6. In particular, we will be discussing the String Representation of
<code>ObjectName</code> instances.</p>
</section>
<section name="Catalina Object Hierarchy">
<p>Tomcat's servlet container implementation, called Catalina, can be
represented as a hierarchy of objects that contain references to each other.
The object hierarchy can be represented as a tree, or (isomorphically) based
on the nesting of configuration elements in the <code>conf/server.xml</code>
file that is traditionally used to configure Tomcat stand-alone.</p>
<p>The valid component nestings for Catalina are depicted in the following
table, with columns that contain the following values:</p>
<ul>
<li><em>Pattern</em> - Nesting pattern of XML elements (in the
<code>conf/server.xml</code> file) used to configure this component.</li>
<li><em>Cardinality</em> - Minimum and maximum number of occurrences of
this element at this nesting position, which also corresponds to the
minimum and maximum number of Catalina components.</li>
<li><em>Identifier</em> - Name of the JavaBeans property of this component
that represents the unique identifier (within the nested hierarchy),
if any.</li>
<li><em>MBean ObjectName</em> - The portion of the MBean object name that
appears <strong>after</strong> the domain name. For now, it should be
assumed that all of these MBeans appear in the default JMX domain.</li>
</ul>
<p>In the <em>MBean ObjectName</em> descriptions, several types of symbolic
expressions are utilized to define variable text that is replaced by
corresponding values:</p>
<ul>
<li><em>${GROUP}</em> - One of the standard MBean names of the specified
"group" category. For example, the expression <code>${REALM}</code>
represents the values like <code>JDBCRealm</code> and <code>JAASRealm</code>
that identify the various MBeans for possible <code>Realm</code> components.</li>
<li><em>${name}</em> - Replaced by the value of property <code>name</code>
from the current component.</li>
<li><em>${parent.name}</em> - Replaced by the value of property
<code>name</code> from a parent of the current component, with the
parent's type identified by <em>parent</em>.</li>
<li><em>${###}</em> - An arbitrary numeric identifier that preserves
order but has no other particular meaning. In general, the server will
assign numeric values to existing instances with large gaps into which
new items can be configured if desired.</li>
</ul>
<table class="defaultTable">
<tr>
<th>Pattern</th>
<th>Cardinality</th>
<th>Identifier</th>
<th>MBean ObjectName</th>
</tr>
<tr>
<td>Server</td>
<td style="text-align: center;">1..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${SERVER}</code></td>
</tr>
<tr>
<td>Server / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}</code></td>
</tr>
<tr>
<td>Server / Service</td>
<td style="text-align: center;">1..n</td>
<td style="text-align: center;"><code class="noHighlight">name</code></td>
<td><code class="noHighlight">type=${SERVICE}, name=${name}</code></td>
</tr>
<tr>
<td>Server / Service / Connector</td>
<td style="text-align: center;">1..n</td>
<td style="text-align: center;"><code class="noHighlight">address, port</code></td>
<td><code class="noHighlight">type=${CONNECTOR}, service=${service}, port=${port},
address=${address}</code></td>
</tr>
<tr>
<td>Server / Service / Connector / Factory</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td>(Only defined explicitly for an SSL connector, but can be treated
as part of the connector component)</td>
</tr>
<tr>
<td>Server / Service / Connector / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}, service=${service},
port=${connector.port}, address=${connector.address}</code></td>
</tr>
<tr>
<td>Server / Service / Engine</td>
<td style="text-align: center;">1..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${ENGINE}, service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host</td>
<td style="text-align: center;">1..n</td>
<td style="text-align: center;"><code class="noHighlight">name</code></td>
<td><code class="noHighlight">type=${HOST}, host=${name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context</td>
<td style="text-align: center;">1..n</td>
<td style="text-align: center;"><code class="noHighlight">path</code></td>
<td><code class="noHighlight">type=${CONTEXT}, context=${name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}, context=${context.name},
host=${host.name}, service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Loader</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LOADER}, context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Manager</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${MANAGER}, context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Realm</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${REALM}, context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Resources</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${RESOURCES}, context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Valve</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${VALVE}, sequence=${###}, context=${context.name},
host=${host.name}, service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Wrapper</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">j2eeType=Servlet,name=${name},
WebModule=//${host.name}/${context.name},
J2EEApplication=${context.J2EEApplication},
J2EEServer=${context.J2EEServer}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / WrapperLifecycle</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${WRAPPER-LIFECYCLE}, sequence=${###},
context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / WrapperListener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${WRAPPER-LISTENER}, sequence=${###},
context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Realm</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${REALM}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Valve</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${VALVE}, sequence=${###},
host=${host.name}, service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}</code>
(<strong>FIXME</strong> - disambiguate from Server / Service /
Listener)</td>
</tr>
<tr>
<td>Server / Service / Engine / Realm</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${REALM}, service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Valve</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${VALVE}, sequence=${###},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}</code>
(<strong>FIXME</strong> - disambiguate from Server / Service /
Engine / Listener)</td>
</tr>
</table>
</section>
<section name="MBean Groups and Names">
<p>The following MBean names shall be defined in the resource file
<code>/org/apache/catalina/mbeans/mbeans-descriptors.xml</code> (and
therefore available for use within the Administration/Configuration
web application for Tomcat):</p>
<table class="defaultTable">
<tr>
<th>MBean Name</th>
<th>Group Name</th>
<th>Catalina Interface</th>
<th>Implementation Class</th>
</tr>
<tr>
<td><code class="noHighlight">AccessLogValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.AccessLogValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">BasicAuthenticator</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.authenticator.BasicAuthenticator</code></td>
</tr>
<tr>
<td><code class="noHighlight">CertificatesValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.CertificatesValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">ContextConfig</code></td>
<td style="text-align: center;"><code class="noHighlight">LISTENER</code></td>
<td><code class="noHighlight">org.apache.catalina.LifecycleListener</code></td>
<td><code class="noHighlight">org.apache.catalina.startup.ContextConfig</code></td>
</tr>
<tr>
<td><code class="noHighlight">ContextEnvironment</code></td>
<td style="text-align: center;"><code class="noHighlight">RESOURCES</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextEnvironment</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextEnvironment</code></td>
</tr>
<tr>
<td><code class="noHighlight">ContextResource</code></td>
<td style="text-align: center;"><code class="noHighlight">RESOURCES</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextResource</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextResource</code></td>
</tr>
<tr>
<td><code class="noHighlight">ContextResourceLink</code></td>
<td style="text-align: center;"><code class="noHighlight">RESOURCES</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextResourceLink</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextResourceLink</code></td>
</tr>
<tr>
<td><code class="noHighlight">CoyoteConnector</code></td>
<td style="text-align: center;"><code class="noHighlight">CONNECTOR</code></td>
<td><code class="noHighlight">org.apache.catalina.Connector</code></td>
<td><code class="noHighlight">org.apache.coyote.tomcat4.CoyoteConnector</code></td>
</tr>
<tr>
<td><code class="noHighlight">DigestAuthenticator</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.authenticator.DigestAuthenticator</code></td>
</tr>
<tr>
<td><code class="noHighlight">EngineConfig</code></td>
<td style="text-align: center;"><code class="noHighlight">LISTENER</code></td>
<td><code class="noHighlight">org.apache.catalina.LifecycleListener</code></td>
<td><code class="noHighlight">org.apache.catalina.startup.EngineConfig</code></td>
</tr>
<tr>
<td><code class="noHighlight">ErrorReportValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.ErrorReportValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">ErrorDispatcherValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.ErrorDispatcherValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">FormAuthenticator</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.authenticator.FormAuthenticator</code></td>
</tr>
<tr>
<td><code class="noHighlight">Group</code></td>
<td style="text-align: center;"><code class="noHighlight">GROUP</code></td>
<td><code class="noHighlight">org.apache.catalina.Group</code></td>
<td><code class="noHighlight">org.apache.catalina.Group</code></td>
</tr>
<tr>
<td><code class="noHighlight">HostConfig</code></td>
<td style="text-align: center;"><code class="noHighlight">LISTENER</code></td>
<td><code class="noHighlight">org.apache.catalina.LifecycleListener</code></td>
<td><code class="noHighlight">org.apache.catalina.startup.HostConfig</code></td>
</tr>
<tr>
<td><code class="noHighlight">HttpConnector10</code></td>
<td style="text-align: center;"><code class="noHighlight">CONNECTOR</code></td>
<td><code class="noHighlight">org.apache.catalina.Connector</code></td>
<td><code class="noHighlight">org.apache.catalina.connector.http10.HttpConnector</code></td>
</tr>
<tr>
<td><code class="noHighlight">HttpConnector11</code></td>
<td style="text-align: center;"><code class="noHighlight">CONNECTOR</code></td>
<td><code class="noHighlight">org.apache.catalina.Connector</code></td>
<td><code class="noHighlight">org.apache.catalina.connector.http.HttpConnector</code></td>
</tr>
<tr>
<td><code class="noHighlight">JAASRealm</code></td>
<td style="text-align: center;"><code class="noHighlight">REALM</code></td>
<td><code class="noHighlight">org.apache.catalina.Realm</code></td>
<td><code class="noHighlight">org.apache.catalina.realm.JAASRealm</code></td>
</tr>
<tr>
<td><code class="noHighlight">JDBCRealm</code></td>
<td style="text-align: center;"><code class="noHighlight">REALM</code></td>
<td><code class="noHighlight">org.apache.catalina.Realm</code></td>
<td><code class="noHighlight">org.apache.catalina.realm.JDBCRealm</code></td>
</tr>
<tr>
<td><code class="noHighlight">JDBCUserDatabase</code></td>
<td style="text-align: center;"><code class="noHighlight">USERDATABASE</code></td>
<td><code class="noHighlight">org.apache.catalina.users.JDBCUserDatabase</code></td>
<td><code class="noHighlight">org.apache.catalina.users.JDBCUserDatabase</code></td>
</tr>
<tr>
<td><code class="noHighlight">JNDIRealm</code></td>
<td style="text-align: center;"><code class="noHighlight">REALM</code></td>
<td><code class="noHighlight">org.apache.catalina.Realm</code></td>
<td><code class="noHighlight">org.apache.catalina.realm.JNDIRealm</code></td>
</tr>
<tr>
<td><code class="noHighlight">MBeanFactory</code></td>
<td style="text-align: center;"><code class="noHighlight"></code></td>
<td><code class="noHighlight"></code></td>
<td><code class="noHighlight">org.apache.catalina.mbeans.MBeanFactory</code></td>
</tr>
<tr>
<td><code class="noHighlight">MemoryRealm</code></td>
<td style="text-align: center;"><code class="noHighlight">REALM</code></td>
<td><code class="noHighlight">org.apache.catalina.Realm</code></td>
<td><code class="noHighlight">org.apache.catalina.realm.MemoryRealm</code></td>
</tr>
<tr>
<td><code class="noHighlight">MemoryUserDatabase</code></td>
<td style="text-align: center;"><code class="noHighlight">USERDATABASE</code></td>
<td><code class="noHighlight">org.apache.catalina.users.MemoryUserDatabase</code></td>
<td><code class="noHighlight">org.apache.catalina.users.MemoryUserDatabase</code></td>
</tr>
<tr>
<td><code class="noHighlight">NamingContextListener</code></td>
<td style="text-align: center;"><code class="noHighlight">LISTENER</code></td>
<td><code class="noHighlight">org.apache.catalina.LifecycleListener</code></td>
<td><code class="noHighlight">org.apache.catalina.core.NamingContextListener</code></td>
</tr>
<tr>
<td><code class="noHighlight">NamingResources</code></td>
<td style="text-align: center;"><code class="noHighlight">RESOURCES</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.NamingResources</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.NamingResources</code></td>
</tr>
<tr>
<td><code class="noHighlight">NonLoginAuthenticator</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.authenticator.NonLoginAuthenticator</code></td>
</tr>
<tr>
<td><code class="noHighlight">PersistentManager</code></td>
<td style="text-align: center;"><code class="noHighlight">MANAGER</code></td>
<td><code class="noHighlight">org.apache.catalina.Manager</code></td>
<td><code class="noHighlight">org.apache.catalina.session.PersistentManager</code></td>
</tr>
<tr>
<td><code class="noHighlight">RemoteAddrValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.RemoteAddrValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">RemoteHostValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.RemoteHostValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">RequestDumperValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.RequestDumperValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">Role</code></td>
<td style="text-align: center;"><code class="noHighlight">ROLE</code></td>
<td><code class="noHighlight">org.apache.catalina.Role</code></td>
<td><code class="noHighlight">org.apache.catalina.Role</code></td>
</tr>
<tr>
<td><code class="noHighlight">SingleSignOn</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.SingleSignOn</code></td>
</tr>
<tr>
<td><code class="noHighlight">SSLAuthenticator</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.authenticator.SSLAuthenticator</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardContext</code></td>
<td style="text-align: center;"><code class="noHighlight">CONTEXT</code></td>
<td><code class="noHighlight">org.apache.catalina.Context</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardContext</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardContextValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardContextValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardEngine</code></td>
<td style="text-align: center;"><code class="noHighlight">ENGINE</code></td>
<td><code class="noHighlight">org.apache.catalina.Engine</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardEngine</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardEngineValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardEngineValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardHost</code></td>
<td style="text-align: center;"><code class="noHighlight">HOST</code></td>
<td><code class="noHighlight">org.apache.catalina.Host</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardHost</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardHostValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardHostValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardManager</code></td>
<td style="text-align: center;"><code class="noHighlight">MANAGER</code></td>
<td><code class="noHighlight">org.apache.catalina.Manager</code></td>
<td><code class="noHighlight">org.apache.catalina.session.StandardManager</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardServer</code></td>
<td style="text-align: center;"><code class="noHighlight">SERVER</code></td>
<td><code class="noHighlight">org.apache.catalina.Server</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardServer</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardService</code></td>
<td style="text-align: center;"><code class="noHighlight">SERVICE</code></td>
<td><code class="noHighlight">org.apache.catalina.Service</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardService</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardWrapper</code></td>
<td style="text-align: center;"><code class="noHighlight">WRAPPER</code></td>
<td><code class="noHighlight">org.apache.catalina.Wrapper</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardWrapper</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardWrapperValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardWrapperValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">User</code></td>
<td style="text-align: center;"><code class="noHighlight">USER</code></td>
<td><code class="noHighlight">org.apache.catalina.User</code></td>
<td><code class="noHighlight">org.apache.catalina.User</code></td>
</tr>
<tr>
<td><code class="noHighlight">UserDatabaseRealm</code></td>
<td style="text-align: center;"><code class="noHighlight">REALM</code></td>
<td><code class="noHighlight">org.apache.catalina.Realm</code></td>
<td><code class="noHighlight">org.apache.catalina.realm.UserDatabaseRealm</code></td>
</tr>
<tr>
<td><code class="noHighlight">WebappLoader</code></td>
<td style="text-align: center;"><code class="noHighlight">LOADER</code></td>
<td><code class="noHighlight">org.apache.catalina.Loader</code></td>
<td><code class="noHighlight">org.apache.catalina.loader.WebappLoader</code></td>
</tr>
</table>
</section>
<section name="JSR-88 Cross Reference">
<p>The deployment objects in the JSR-88 API object hierarchy correspond
to the specified MBean names or groups as follows:</p>
<table class="defaultTable">
<tr>
<th>JSR-88 API Object</th>
<th>MBean Name or Group</th>
<th>Comments</th>
</tr>
<tr>
<td><code class="noHighlight">DeployableObject</code></td>
<td><code class="noHighlight">${CONTEXT}</code></td>
<td>Context deployment info plus the corresponding WAR file</td>
</tr>
<tr>
<td><code class="noHighlight">Target</code></td>
<td><code class="noHighlight">${HOST}</code></td>
<td></td>
</tr>
</table>
</section>
</body>
</document>

56
webapps/docs/funcspecs/project.xml Normal file
View File

@@ -0,0 +1,56 @@
<?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="Catalina Functional Specifications"
href="https://tomcat.apache.org/">
<title>Catalina Functional Specifications</title>
<logo href="/images/tomcat.gif">
Catalina Functional Specifications
</logo>
<body>
<menu name="Links">
<item name="Docs Home" href="../index.html"/>
<item name="Functional Specs" href="index.html"/>
<item name="FAQ" href="https://wiki.apache.org/tomcat/FAQ" />
<item name="User Comments" href="#comments_section"/>
</menu>
<menu name="Administrative Apps">
<item name="Overall Requirements" href="fs-admin-apps.html"/>
<item name="Tomcat MBean Names" href="mbean-names.html"/>
<item name="Administered Objects" href="fs-admin-objects.html"/>
<item name="Supported Operations" href="fs-admin-opers.html"/>
</menu>
<menu name="Internal Servlets">
<item name="Default Servlet" href="fs-default.html"/>
</menu>
<menu name="Realm Implementations">
<item name="JDBC Realm" href="fs-jdbc-realm.html"/>
<item name="JNDI Realm" href="fs-jndi-realm.html"/>
<item name="Memory Realm" href="fs-memory-realm.html"/>
</menu>
</body>
</project>