Catalina Functional Specifications

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 Access Methods to the supported administrative functionality shall be supported, to meet varying requirements:

• As A Scriptable Web Application - The existing Manager 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.
• As An HTML-Based Web Application - Use an HTML presentation to provide a GUI-like user interface for humans to interact with the administrative capabilities.
• As SOAP-Based Web Services - The operational commands to administer Tomcat are made available as web services that utilize SOAP message formats.
• As Java Management Extensions (JMX) Commands - The operational commands to administer Tomcat are made available through JMX APIs, for integration into management consoles that utilize them.
• Other Remote Access APIs - Other remote access APIs, such as JINI, RMI, and CORBA can also be utilized to access administrative capabilities.

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 Deployer.deploy() 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.

The current status of this functional specification is PROPOSED. It has not yet been discussed and agreed to on the TOMCAT-DEV mailing list.

The implementation of this functionality depends on the following external specifications:

• Java IDL (for CORBA, included in the JDK)
• Java Management Extensions
• Remote Method Invocation (Included in the JDK)

The implementation of this functionality shall conform to the following requirements:

• 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.
• 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.
• 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.
• The common business logic components shall be implemented in package org.apache.catalina.admin.
• The common business logic components shall be built as part of the standard Catalina build process, and made visible in the Catalina class loader.
• The Java components required for each access method shall be implemented in subpackages of org.apache.catalina.admin.
• 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.
• 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.
• Administrative commands to start up and shut down the overall Tomcat container are out of scope for the purposes of these applications. It is assumed that other (usually platform-specific) mechanisms will be used for container startup and shutdown.

The following environmental dependencies must be met in order for administrative applications to operate correctly:

• For access methods that require creation of server sockets, the appropriate ports must be configured and available.

Correct operation of administrative applications depends on the following specific features of the surrounding container:

• 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.

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:
FIXME - This list below is totally outdated, but nobody cares about the administrative app anymore. It is removed and unsupported since Tomcat 6.0.

• Java Standard Edition (Version 1.2 or later)
• Servlet 2.4 (supported natively by Tomcat 5)
• JavaServer Pages 2.0 (supported natively by Tomcat 5)
• JavaServer Pages Standard Tag Library 1.0 (Jakarta Taglibs-Standard 1.0.3)
• Struts Framework (Version 1.0) - MVC Framework for Web Applications
• TO BE DETERMINED - Application for hosting SOAP based web services

Functional requirements for administrative applications are specified in terms of Administered Objects, whose definitions and detailed properties are listed here. In general, Administered Objects correspond to components in the Catalina architecture, but these objects are defined separately here for the following reasons:

• It is possible that the administrative applications do not expose every possible configurable facet of the underlying components.
• 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.
• 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).
• It is necessary to represent configuration information (such as a Default Context) when there is no corresponding component instance.
• 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.

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 Administered Objects and Components, different font presentations are utilized. Default values for many properties are listed in [square brackets].

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 here.

Scriptable Web Application

An appropriate subset of the administrative operations described above shall be implemented as commands that can be performed by the "Manager" web application. FIXME - Enumerate them.

In addition, this web application shall conform to the following requirements:

• All request URIs shall be protected by security constraints that require a security role to be assigned for processing.
• The default user database shall not contain any user that has been assigned a security role.

HTML-Based Web Application

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:

• Must be implemented using servlet, JSP, and MVC framework technologies described under "External Technologies", above.
• Prompts and error messages must be internationalizable to multiple languages.
• Rendered HTML must be compatible with Netscape Navigator (version 4.7 or later) and Internet Explorer (version 5.0 or later).