http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-admin-opers.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-admin-opers.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-admin-opers.html new file mode 100644 index 0000000..d39daff --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-admin-opers.html @@ -0,0 +1,269 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications - Administrative Apps - Supported Operations</title><meta content="Craig McClanahan" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + Catalina Functional Specifications + " align="right" src="../images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Functional Specs</a></li></ul><p><strong>Administrative Apps</strong></p><ul><li><a href="fs-admin-apps.html">Overall Requirements</a></li><li><a href="mbean-names.html">Tomcat MBean Names</a></li><li><a href="fs-admin-objects.html">Administered Objects</a></li><li><a href="fs-admin-opers.html">Supported Operations</a></li></ul><p><strong>Internal Servlets</strong></p><ul><li><a href="fs-default. html">Default Servlet</a></li><li><a href="fs-invoker.html">Invoker Servlet</a></li></ul><p><strong>Realm Implementations</strong></p><ul><li><a href="fs-jdbc-realm.html">JDBC Realm</a></li><li><a href="fs-jndi-realm.html">JNDI Realm</a></li><li><a href="fs-memory-realm.html">Memory Realm</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Catalina Functional Specifications</h1><h2>Administrative Apps - Supported Operations</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Supported_Operations_Overview">Supported Operations Overview</a></li><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> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Supported Operations Overview"><!--()--></a><a name="Supported_Operations_Overview"><strong>Supported Operations Overview</strong></a></font></td></tr><tr><td><blockquote> + +<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 6 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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Access Logger"><!--()--></a><a name="Access_Logger"><strong>Access Logger</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Connector"><strong>Connector</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Context"><strong>Context</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Default Context"><!--()--></a><a name="Default_Context"><strong>Default Context</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Engine"><strong>Engine</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Environment Entry"><!--()--></a><a name="Environment_Entry"><strong>Environment Entry</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Host"><strong>Host</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="JDBC Resource"><!--()--></a><a name="JDBC_Resource"><strong>JDBC Resource</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Loader"><strong>Loader</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Manager"><strong>Manager</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Realm"><strong>Realm</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Request Filter"><!--()--></a><a name="Request_Filter"><strong>Request Filter</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Server"><strong>Server</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Service"><strong>Service</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-default.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-default.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-default.html new file mode 100644 index 0000000..0dc7c92 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-default.html @@ -0,0 +1,230 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications - Default Servlet</title><meta content="Craig McClanahan" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + Catalina Functional Specifications + " align="right" src="../images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Functional Specs</a></li></ul><p><strong>Administrative Apps</strong></p><ul><li><a href="fs-admin-apps.html">Overall Requirements</a></li><li><a href="mbean-names.html">Tomcat MBean Names</a></li><li><a href="fs-admin-objects.html">Administered Objects</a></li><li><a href="fs-admin-opers.html">Supported Operations</a></li></ul><p><strong>Internal Servlets</strong></p><ul><li><a href="fs-default. html">Default Servlet</a></li><li><a href="fs-invoker.html">Invoker Servlet</a></li></ul><p><strong>Realm Implementations</strong></p><ul><li><a href="fs-jdbc-realm.html">JDBC Realm</a></li><li><a href="fs-jndi-realm.html">JNDI Realm</a></li><li><a href="fs-memory-realm.html">Memory Realm</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Catalina Functional Specifications</h1><h2>Default Servlet</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Overview">Overview</a><ol><li><a href="#Introduction">Introduction</a></li><li><a href="#External_Specifications">External Specifications</a></li><li><a href="#Implementation_Requirements">Implementation Requirements</a></li></ol></li><li><a href="#Dependencies">Dependencies</a><ol><li><a href="#Environmental_Dependencies">Environmental Dependencies</a></li><li><a href="#Container_Dependencies">Container Dependencies</a></li></ol></li><li><a href="#Functionality">Functionality</a><ol><li><a href="#Initialization_Functionality">Initialization Functionality</a></li><li><a href="#Per-Request_Functionality">Per-Request Functionality</a></li><li><a href="#Finalization_Functionality">Finalization Functionality</a></li></ol></li><li><a href="#Testable_Assertions">Testable Assertions</a></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> + + <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> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="External Specifications"><!--()--></a><a name="External_Specifications"><strong>External Specifications</strong></a></font></td></tr><tr><td><blockquote> + + <p>The following external specifications have provisions which + partially define the correct behavior of the default servlet:</p> + <ul> + <li><a href="http://java.sun.com/products/servlet/download.html";> + Servlet Specification</a> (Version 2.3 PFD2)</li> + <li><a href="http://www.rfc-editor.org/rfc/rfc2046.txt";>Multipurpose + Internet Mail Extensions (MIME) Part Two: Media Types</a></li> + <li><a href="http://www.rfc-editor.org/rfc/rfc2616.txt";>Hypertext + Transfer Protocol -- HTTP/1.1</a></li> + </ul> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Implementation Requirements"><!--()--></a><a name="Implementation_Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote> + + <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> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Environmental Dependencies"><!--()--></a><a name="Environmental_Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote> + + <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> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Container Dependencies"><!--()--></a><a name="Container_Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote> + + <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> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Initialization Functionality"><!--()--></a><a name="Initialization_Functionality"><strong>Initialization Functionality</strong></a></font></td></tr><tr><td><blockquote> + + <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> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Per-Request Functionality"><!--()--></a><a name="Per-Request_Functionality"><strong>Per-Request Functionality</strong></a></font></td></tr><tr><td><blockquote> + + + <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> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Finalization Functionality"><!--()--></a><a name="Finalization_Functionality"><strong>Finalization Functionality</strong></a></font></td></tr><tr><td><blockquote> + + <p>No specific processing is required when the <code>destroy()</code> + method is called:</p> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Testable Assertions"><!--()--></a><a name="Testable_Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote> + + <p>In addition the 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> + +</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-invoker.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-invoker.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-invoker.html new file mode 100644 index 0000000..539e512 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-invoker.html @@ -0,0 +1,225 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications - Invoker Servlet</title><meta content="Craig McClanahan" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + Catalina Functional Specifications + " align="right" src="../images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Functional Specs</a></li></ul><p><strong>Administrative Apps</strong></p><ul><li><a href="fs-admin-apps.html">Overall Requirements</a></li><li><a href="mbean-names.html">Tomcat MBean Names</a></li><li><a href="fs-admin-objects.html">Administered Objects</a></li><li><a href="fs-admin-opers.html">Supported Operations</a></li></ul><p><strong>Internal Servlets</strong></p><ul><li><a href="fs-default. html">Default Servlet</a></li><li><a href="fs-invoker.html">Invoker Servlet</a></li></ul><p><strong>Realm Implementations</strong></p><ul><li><a href="fs-jdbc-realm.html">JDBC Realm</a></li><li><a href="fs-jndi-realm.html">JNDI Realm</a></li><li><a href="fs-memory-realm.html">Memory Realm</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Catalina Functional Specifications</h1><h2>Invoker Servlet</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Overview">Overview</a><ol><li><a href="#Introduction">Introduction</a></li><li><a href="#External_Specifications">External Specifications</a></li><li><a href="#Implementation_Requirements">Implementation Requirements</a></li></ol></li><li><a href="#Dependencies">Dependencies</a><ol><li><a href="#Environmental_Dependencies">Environmental Dependencies</a></li><li><a href="#Container_Dependencies">Container Dependencies</a></li></ol></li><li><a href="#Functionality">Functionality</a><ol><li><a href="#Initialization_Functionality">Initialization Functionality</a></li><li><a href="#Per-Request_Functionality">Per-Request Functionality</a></li><li><a href="#Finalization_Functionality">Finalization Functionality</a></li></ol></li><li><a href="#Testable_Assertions">Testable Assertions</a></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> + + <p>The purpose of the <strong>Invoker Servlet</strong> is to allow a + web application to dynamically register new <em>servlet definitions</em> + that correspond with a <code><servlet></code> element in the + <code>/WEB-INF/web.xml</code> deployment descriptor, and execute + requests utilizing the new servlet definitions. From the perspective + of the newly registered servlets, all servlet lifecycle requirements + of the Servlet Specification (such as calling <code>init()</code> and + <code>destroy()</code> at the correct times) will be respected.</p> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="External Specifications"><!--()--></a><a name="External_Specifications"><strong>External Specifications</strong></a></font></td></tr><tr><td><blockquote> + + <p>I do not know of any formal specification of the behavior of an + invoker servlet that is publicly available. Anyone know of one?</p> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Implementation Requirements"><!--()--></a><a name="Implementation_Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote> + + <p>The implementation of this functionality shall conform to the + following requirements:</p> + <ul> + <li>Implemented as a servlet.</li> + <li>Exist in the <code>org.apache.catalina.servlets</code> package + so that it can be loaded by the Catalina class loader.</li> + <li>Implement the <code>org.apache.catalina.ContainerServlet</code> + interface, so that it gains knowledge of the <code>Wrapper</code> + that is responsible for itself and, therefore, access to other + internal Catalina components.</li> + <li>Support a configurable debugging detail level.</li> + <li>Log debugging and operational messages (suitably internationalized) + via the <code>getServletContext().log()</code> method.</li> + </ul> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Environmental Dependencies"><!--()--></a><a name="Environmental_Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote> + + <p>The following environmental dependencies must be met in order for + the Invoker servlet to operate correctly:</p> + <ul> + <li>The invoker 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 "path mapped" + servlet mapping. The historical default mapping is to URL pattern + "<code>/servlet/*</code>", although the invoker servlet must operate + correctly with an arbitrary mapping.</li> + </ul> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Container Dependencies"><!--()--></a><a name="Container_Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote> + + <p>Correct operation of the invoker servlet depends on the following + specific features of the surrounding container:</p> + <ul> + <li>Correct support for the <code>ContainerServlet</code> interface, + including calling <code>setWrapper()</code> <strong>before</strong> + the <code>init()</code> method of the invoker servlet is called.</li> + <li>The web application class loader must be stored as the context + class loader of the request processing thread.</li> + </ul> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Initialization Functionality"><!--()--></a><a name="Initialization_Functionality"><strong>Initialization Functionality</strong></a></font></td></tr><tr><td><blockquote> + + <p>The following processing must be performed when the <code>init()</code> + method of the invoker servlet is called:</p> + <ul> + <li>Ensure that the container has called <code>setWrapper()</code>. If + not, throw a permanent <code>UnavailableException</code>.</li> + <li>Look up and cache the <code>Context</code> that corresponds to our + <code>Wrapper</code>. This is the component with which new servlet + definitions and mappings will be registered.</li> + </ul> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Per-Request Functionality"><!--()--></a><a name="Per-Request_Functionality"><strong>Per-Request Functionality</strong></a></font></td></tr><tr><td><blockquote> + + <p>On each request, the following processing shall be performed:</p> + <ol> + <li>Calculate the <code>{ServletPath}</code> for this request, either from + request attribute <code>javax.servlet.include.servlet_path</code> or + by calling <code>request.getServletPath()</code>.</li> + <li>Calculate the <code>{PathInfo}</code> for this request, either from + request attribute <code>javax.servlet.include.path_info</code> or + by calling <code>request.getPathInfo()</code>. If the calculated + <code>{PathInfo}</code> is null, return HTTP status 400 + (bad request).</li> + <li>Parse the calculated <code>{PathInfo}</code> value as follows: + <ol> + <li>Ignore the leading slash character.</li> + <li>Accumulate characters up to the next '/' (if any) as the + <code>{ServletSelector}</code>.</li> + <li>If a '/' was encountered, accumulate all characters from that + slash (inclusive) to the end of the string as + <code>{PathRemainder}</code>. If no slash was encountered, + set <code>{PathRemainder}</code> to a zero-length string.</li> + </ol></li> + <li>Determine whether <code>{ServletSelector}</code> is the name of an + existing servlet definition, and process it as follows: + <ol> + <li>Ask our associated <code>Context</code> to find and return a + child <code>Wrapper</code> named <code>{ServletSelector}</code>. + </li> + <li>If there is no such child, skip to the next major step.</li> + <li>Register a new servlet mapping for this <code>Wrapper</code>, + using a URL pattern calculated as follows: + <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code> + + "/*"</li> + <li>Create a request dispatcher using a path calculated as follows: + <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code> + + <code>{PathRemainder}</code></li> + <li>Forward this request to the created request dispatcher, and + exit from this request.</li> + </ol></li> + <li>Assume that <code>{ServletSelector}</code> is the fully qualified + name of a Java class that implements <code>javax.servlet.Servlet</code> + and process it as follows: + <ol> + <li>Synthesize a new <code>{ServletName}</code> for the servlet + definition that will be created.</li> + <li>If there is already a child <code>Wrapper</code> associated with + this name, return HTTP status 500 (internal server error), because + a mapping should have already been created for this servlet.</li> + <li>Attempt to load a class named <code>{ServletSelector}</code> from + the web application class loader (i.e. the context class loader + for our current thread). If this fails, return HTTP status 404 + (not found).</li> + <li>Instantiate an instance of this class. If an error occurs, + return HTTP status 404 (not found).</li> + <li>If this class does not implement the + <code>javax.servlet.Servlet</code> interface, return HTTP status + 404 (not found).</li> + <li>Create and register a new <code>Wrapper</code> child with our + <code>Context</code>, under name <code>{ServletName}</code>.</li> + <li>Register a new servlet mapping for this <code>Wrapper</code>, + using a URL pattern calculated as follows: + <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code> + + "/*"</li> + <li>Create a request dispatcher using a path calculated as follows: + <code>{ServletPath}</code> + "/" + <code>{ServletSelector}</code> + + <code>{PathRemainder}</code></li> + <li>Forward this request to the created request dispatcher, and + exit from this request.</li> + </ol></li> + </ol> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Finalization Functionality"><!--()--></a><a name="Finalization_Functionality"><strong>Finalization Functionality</strong></a></font></td></tr><tr><td><blockquote> + + <p>No specific processing is required when the <code>destroy()</code> + method is called:</p> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Testable Assertions"><!--()--></a><a name="Testable_Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote> + + <p>In addition the the assertions implied by the functionality requirements + listed above, the following additional assertions shall be tested to + validate the behavior of the invoker servlet:</p> + <ul> + <li>It is possible to access an existing servlet definition by name + through the invoker. The existing servlet definition can include + either a <code><servlet-class></code> or + <code><jsp-file></code> subelement.</li> + <li>When an existing servlet definition is accessed by name, the request + will be ultimately processed by the same servlet instance that would + have processed it had a mapping to that servlet definition been used + on the request directly.</li> + <li>It is possible to access an anonymous servlet by class name + through the invoker.</li> + <li>When an anonymous servlet is accessed, the servlet instance is processed + according to the lifecycle requirements of the Servlet Specification. + </li> + <li>When an anonymous servlet is accessed, the servlet instance receives + a <code>ServletConfig</code> instance with no servlet initialization + parameters.</li> + <li>It is possible to utilize the invoker servlet via a direct request.</li> + <li>It is possible to utilize the invoker servlet via a call to + <code>RequestDispatcher.forward()</code>, or the corresponding + <code><jsp:forward></code> tag in a JSP page.</li> + <li>It is possible to utilize the invoker servlet via a call to + <code>RequestDispatcher.include()</code>, or the corresponding + <code><jsp:include></code> tag in a JSP page.</li> + <li>It is possible to use any HTTP method (including GET and POST) that + is supported by the Servlet class that is ultimately executed.</li> + <li>The invoker servlet should never be asked to process a second or + subsequent request for the same <code>{ServletSelector}</code> (because + it will have registered an appropriate servlet mapping.</li> + </ul> + +</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-jdbc-realm.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-jdbc-realm.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-jdbc-realm.html new file mode 100644 index 0000000..cfd7b60 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/funcspecs/fs-jdbc-realm.html @@ -0,0 +1,226 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications - JDBCRealm</title><meta content="Craig McClanahan" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + Catalina Functional Specifications + " align="right" src="../images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Functional Specs</a></li></ul><p><strong>Administrative Apps</strong></p><ul><li><a href="fs-admin-apps.html">Overall Requirements</a></li><li><a href="mbean-names.html">Tomcat MBean Names</a></li><li><a href="fs-admin-objects.html">Administered Objects</a></li><li><a href="fs-admin-opers.html">Supported Operations</a></li></ul><p><strong>Internal Servlets</strong></p><ul><li><a href="fs-default. html">Default Servlet</a></li><li><a href="fs-invoker.html">Invoker Servlet</a></li></ul><p><strong>Realm Implementations</strong></p><ul><li><a href="fs-jdbc-realm.html">JDBC Realm</a></li><li><a href="fs-jndi-realm.html">JNDI Realm</a></li><li><a href="fs-memory-realm.html">Memory Realm</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Catalina Functional Specifications</h1><h2>JDBCRealm</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Overview">Overview</a><ol><li><a href="#Introduction">Introduction</a></li><li><a href="#External_Specifications">External Specifications</a></li><li><a href="#Implementation_Requirements">Implementation Requirements</a></li></ol></li><li><a href="#Dependencies">Dependencies</a><ol><li><a href="#Environmental_Dependencies">Environmental Dependencies</a></li><li><a href="#Container_Dependencies">Container Dependencies</a></li></ol></li><li><a href="#Functionality">Functionality</a><ol><li><a href="#Overview_of_Operation">Overview of Operation</a></li><li><a href="#Detailed_Functional_Requirements">Detailed Functional Requirements</a></li></ol></li><li><a href="#Testable_Assertions">Testable Assertions</a></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> + + <p>The purpose of the <strong>JDBCRealm</strong> implementation is to + provide a mechanism by which Tomcat 6 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> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="External Specifications"><!--()--></a><a name="External_Specifications"><strong>External Specifications</strong></a></font></td></tr><tr><td><blockquote> + + <p>The implementation of this functionality depends on the following + external specifications:</p> + <ul> + <li><a href="http://java.sun.com/products/jdbc/";>Java Database + Connectivity</a> (version 2.0 or later)</li> + <li><a href="http://java.sun.com/products/jdbc/";>Java Database + Connectivity Optional Package</a> (version 2.0 or later)</li> + </ul> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Implementation Requirements"><!--()--></a><a name="Implementation_Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote> + + <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> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Environmental Dependencies"><!--()--></a><a name="Environmental_Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote> + + <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><Realm></code> element that is nested inside a + corresponding <code><Engine></code>, <code><Host></code>, + or <code><Context></code> element.</li> + </ul> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Container Dependencies"><!--()--></a><a name="Container_Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote> + + <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> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview of Operation"><!--()--></a><a name="Overview_of_Operation"><strong>Overview of Operation</strong></a></font></td></tr><tr><td><blockquote> + + <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> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Detailed Functional Requirements"><!--()--></a><a name="Detailed_Functional_Requirements"><strong>Detailed Functional Requirements</strong></a></font></td></tr><tr><td><blockquote> + + + <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> + + </blockquote></td></tr></table> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Testable Assertions"><!--()--></a><a name="Testable_Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote> + + <p>In addition the 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> + +</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file
