Catalina Functional Specifications

Apache Tomcat 7

Version 7.0.63, Jun 30 2015
Apache Logo

Links

Administrative Apps

Internal Servlets

Realm Implementations

Administrative Apps - Administered Objects

Table of Contents
Administered Objects Overview

This document defines the Administered Objects that represent the internal architectural components of the Catalina servlet container. Associated with each is a set of Supported Operations that can be performed when the administrative application is "focused" on a particular configurable object.

The following Administered Objects are defined:

Access Logger

An Access Logger is an optional Valve 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 Engine, a Host, a Context, or a Default Context.

The standard component implementing an Access Logger is org.apache.catalina.valves.AccessLogValve. It supports the following configurable properties:

  • debug - Debugging detail level. [0]
  • directory - Absolute or relative (to $CATALINA_BASE) path of the directory into which access log files are created. [logs].
  • pattern - Pattern string defining the fields to be included in the access log output, or "common" for the standard access log pattern. See org.apache.catalina.valves.AccessLogValve for more information. [common]
  • prefix - Prefix added to the beginning of each log file name created by this access logger.
  • resolveHosts - Should IP addresses be resolved to host names in the log? [false]
  • suffix - Suffix added to the end of each log file name created by this access logger.
Connector

A Connector 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.

For standalone use, the standard connector supporting the HTTP/1.1 protocol is org.apache.catalina.connectors.http.HttpConnector. It supports the following configurable properties:

  • acceptCount - The maximum queue length of incoming connections that have not yet been accepted. [10]
  • address - For servers with more than one IP address, the address upon which this connector should listen. [All Addresses]
  • bufferSize - Default input buffer size (in bytes) for requests created by this Connector. [2048]
  • debug - Debugging detail level. [0]
  • enableLookups - Should we perform DNS lookups on remote IP addresses when request.getRemoteHost() is called? [false]
  • maxProcessors - The maximum number of processor threads supported by this connector. [20]
  • minProcessors - The minimum number of processor threads to be created at container startup. [5]
  • port - TCP/IP port number on which this Connector should listen for incoming requests. [8080]
  • proxyName - Host name to be returned when an application calls request.getServerName(). [Value of Host: header]
  • proxyPort - Port number to be returned when an application calls request.getServerPort(). [Same as port]
Context

A Context is the representation of an individual web application, which is associated with a corresponding Host. Note that the administrable properties of a Context do not include any settings from inside the web application deployment descriptor for that application.

The standard component implementing a Context is org.apache.catalina.core.StandardContext. It supports the following configurable properties:

  • cookies - Should be use cookies for session identifier communication? [true]
  • crossContext - Should calls to ServletContext.getServletContext() return the actual context responsible for the specified path? [false]
  • debug - Debugging detail level. [0]
  • docBase - The absolute or relative (to the appBase of our owning Host) pathname of a directory containing an unpacked web application, or of a web application archive (WAR) file.
  • override - Should settings in this Context override corresponding settings in the Default Context? [false]
  • path - Context path for this web application, or an empty string for the root application of a Host. [Inferred from directory or WAR file name]
  • reloadable - Should Tomcat monitor classes in the /WEB-INF/classes directory for changes, and reload the application if they occur? [false]
  • useNaming - Should Tomcat provide a JNDI naming context, containing preconfigured entries and resources, corresponding to the requirements of the Java2 Enterprise Edition specification? [true]
  • workDir - Absolute pathname of a scratch directory that is provided to this web application. [Automatically assigned relative to $CATALINA_BASE/work]

Each Context is owned by a parent Host, and is associated with:

  • An optional Access Logger that logs all requests processed by this web application.
  • Zero or more Environment Entries representing environment entries for the JNDI naming context associated with a web application.
  • Zero or more JDBC Resources representing database connection pools associated with a web application.
  • A Loader representing the web application class loader used by this web application.
  • A Manager representing the session manager used by this web application.
  • An optional Realm used to provide authentication and access control information for this web application.
  • Zero or more Request Filters used to limit access to this web application based on remote host name or IP address.
Default Context

A Default Context represents a subset of the configurable properties of a Context, and is used to set defaults for those properties when web applications are automatically deployed. A Default Context object can be associated with an Engine or a Host. The following configurable properties are supported:

  • cookies - Should be use cookies for session identifier communication? [true]
  • crossContext - Should calls to ServletContext.getServletContext() return the actual context responsible for the specified path? [false]
  • reloadable - Should Tomcat monitor classes in the /WEB-INF/classes directory for changes, and reload the application if they occur? [false]
  • useNaming - Should Tomcat provide a JNDI naming context, containing preconfigured entries and resources, corresponding to the requirements of the Java2 Enterprise Edition specification? [true]

Each Default Context is owned by a parent Engine or Host, and is associated with:

  • Zero or more Environment Entries representing environment entries for the JNDI naming context associated with a web application.
  • Zero or more JDBC Resources representing database connection pools associated with a web application.
  • An optional Loader representing default configuration properties for the Loader component of deployed web applications.
  • An optional Manager representing default configuration properties for the Manager component of deployed web applications.
Default Deployment Descriptor

Default web application characteristics are configured in a special deployment descriptor named $CATALINA_BASE/conf/web.xml. This section describes the configurable components that may be stored there.

FIXME - Complete the description of default servlets, default mappings, default MIME types, and so on.

Engine

An Engine is the representation of the entire Catalina servlet container, and processes all requests for all of the associated virtual hosts and web applications.

The standard component implementing an Engine is org.apache.catalina.core.StandardEngine. It supports the following configurable properties:

  • debug - Debugging detail level. [0]
  • defaultHost - Name of the Host to which requests will be directed if the requested host is unknown. [localhost]
  • name - Logical name of this engine. [Tomcat Stand-Alone]

Each Engine is owned by a parent Service, and is