source: nutchez-0.1/tomcat/webapps/docs/funcspecs/fs-jdbc-realm.html @ 160

Last change on this file since 160 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 13.7 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications - JDBCRealm</title><meta value="Craig McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"></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="
2      Catalina Functional Specifications
3    " align="right" src="../images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></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 nowrap="true" 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 align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Catalina Functional Specifications</h1><h2>JDBCRealm</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/fs-jdbc-realm.html"><img alt="Printer Friendly Version" border="0" src="../images/printer.gif"><br>print-friendly<br>version
4                    </a></small></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>
5
6
7  <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>
8
9    <p>The purpose of the <strong>JDBCRealm</strong> implementation is to
10    provide a mechanism by which Tomcat 6 can acquire information needed
11    to authenticate web application users, and define their security roles,
12    from a relational database accessed via JDBC APIs.  For integration
13    with Catalina, the resulting class(es) must implement the
14    <code>org.apache.catalina.Realm</code> interface.</p>
15
16    <p>This specification reflects a combination of functionality that is
17    already present in the <code>org.apache.catalina.realm.JDBCRealm</code>
18    class, as well as requirements for enhancements that have been
19    discussed.  Where appropriate, requirements statements are marked
20    <em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>
21
22    <p>The current status of this functional specification is
23    <strong>PROPOSED</strong>.  It has not yet been discussed and
24    agreed to on the TOMCAT-DEV mailing list.</p>
25
26  </blockquote></td></tr></table>
27
28
29  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="External Specifications"><strong>External Specifications</strong></a></font></td></tr><tr><td><blockquote>
30
31    <p>The implementation of this functionality depends on the following
32    external specifications:</p>
33    <ul>
34    <li><a href="http://java.sun.com/products/jdbc/">Java Database
35        Connectivity</a> (version 2.0 or later)</li>
36    <li><a href="http://java.sun.com/products/jdbc/">Java Database
37        Connectivity Optional Package</a> (version 2.0 or later)</li>
38    </ul>
39
40  </blockquote></td></tr></table>
41
42
43  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Implementation Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote>
44
45    <p>The implementation of this functionality shall conform to the
46    following requirements:</p>
47    <ul>
48    <li>Be realized in one or more implementation classes.</li>
49    <li>Implement the <code>org.apache.catalina.Realm</code> interface.
50        [Current]</li>
51    <li>Implement the <code>org.apache.catalina.Lifecycle</code>
52        interface.  [Current]</li>
53    <li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
54        base class.</li>
55    <li>Live in the <code>org.apache.catalina.realm</code> package.
56        [Current]</li>
57    <li>Support a configurable debugging detail level. [Current]</li>
58    <li>Log debugging and operational messages (suitably internationalized)
59        via the <code>getContainer().log()</code> method. [Current]</li>
60    </ul>
61
62  </blockquote></td></tr></table>
63
64
65</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>
66
67
68  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Environmental Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote>
69
70    <p>The following environmental dependencies must be met in order for
71    JDBCRealm to operate correctly:</p>
72    <ul>
73    <li>The desire to utilize JDBCRealm must be registered in
74        <code>$CATALINA_BASE/conf/server.xml</code>, in a
75        <code>&lt;Realm&gt;</code> element that is nested inside a
76        corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
77        or <code>&lt;Context&gt;</code> element.</li>
78    </ul>
79
80  </blockquote></td></tr></table>
81
82
83  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Container Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>
84
85    <p>Correct operation of JDBCRealm depends on the following
86    specific features of the surrounding container:</p>
87    <ul>
88    <li>Interactions with <code>JDBCRealm</code> will be initiated by
89        the appropriate <code>Authenticator</code> implementation, based
90        on the login method that is selected.</li>
91    <li><code>JDBCRealm</code> must have the JDBC standard API classes
92        available to it.  For a JDK 1.2 or later container, these APIs
93        are included in the standard platform.</li>
94    <li>When connection pooling is implemented, <code>JDBCRealm</code>
95        must have the JDBC Optional Package (version 2.0 or later) APIs
96        available to it.  This library is available as a separate
97        download (and will be included in Tomcat binary distributions).</li>
98    </ul>
99
100  </blockquote></td></tr></table>
101
102
103</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>
104
105
106  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview of Operation"><strong>Overview of Operation</strong></a></font></td></tr><tr><td><blockquote>
107
108    <p>The main purpose of <code>JDBCRealm</code> is to allow Catalina to
109    authenticate users, and look up the corresponding security roles, from
110    the information found in a relational database accessed via JDBC APIs.
111    For maximum flexibility, the details of how this is done (for example,
112    the names of the required tables and columns) should be configurable.</p>
113
114    <p>Each time that Catalina needs to authenticate a user, it will call
115    the <code>authenticate()</code> method of this Realm implementation,
116    passing the username and password that were specified by the user.  If
117    we find the user in the database (and match on the password), we accumulate
118    all of the security roles that are defined for this user, and create a
119    new <code>GenericPrincipal</code> object to be returned.  If the user
120    is not authenticated, we return <code>null</code> instead.  The
121    <code>GenericUser</code> object caches the set of security roles that
122    were owned by this user at the time of authentication, so that calls to
123    <code>isUserInRole()</code> can be answered without going back to the
124    database every time.</p>
125
126  </blockquote></td></tr></table>
127
128
129  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Detailed Functional Requirements"><strong>Detailed Functional Requirements</strong></a></font></td></tr><tr><td><blockquote>
130
131
132    <h3>Configurable Properties</h3>
133
134    <p>The implementation shall support the following properties
135    that can be configured with JavaBeans property setters:</p>
136    <ul>
137    <li>Configuration parameters defining the JDBC driver to use, the
138        database connection URL to be accessed, and the username/password
139        to use for logging in. [Current]</li>
140    <li>Configuration parameters describing the connection pool to be
141        created to support simultaneous authentications. [Requested]</li>
142    <li>Name of the tables to be searched for users and roles. [Current]</li>
143    <li>Name of the columns to be used for usernames, passwords, and
144        role names.  [Current]</li>
145    </ul>
146
147    <h3>Lifecycle Functionality</h3>
148
149    <p>The following processing must be performed when the <code>start()</code>
150    method is called:</p>
151    <ul>
152    <li>Establish a connection to the configured database, using the
153        configured username and password.  [Current]</li>
154    <li>Configure and establish a connection pool of connections to the
155        database.  [Requested]</li>
156    </ul>
157
158    <p>The following processing must be performed when the <code>stop()</code>
159    method is called:</p>
160    <ul>
161    <li>Close any opened connections to the database.</li>
162    </ul>
163
164
165    <h3>Method authenticate() Functionality</h3>
166
167    <p>When <code>authenticate()</code> is called, the following processing
168    is required:</p>
169    <ul>
170    <li>Acquire the one and only connection [Current] or acquire a connection
171        from the connection pool [Requested].</li>
172    <li>Select the one and only row from the user's table for this user,
173        and retrieve the corresponding password column.  If zero rows (or
174        more than one row) are found, return <code>null</code>.</li>
175    <li>Authenticate the user by comparing the (possibly encrypted) password
176        value that was received against the password presented by the user.
177        If there is no match, return <code>null</code>.</li>
178    <li>Acquire a <code>List</code> of the security roles assigned to the
179        authenticated user by selecting from the roles table.</li>
180    <li>Construct a new instance of class
181        <code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
182        constructor arguments:  this realm instance, the authenticated
183        username, and a <code>List</code> of the security roles associated
184        with this user.</li>
185    <li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
186        <code>GenericPrincipal</code> objects for a particular user, because
187        the information in the directory server might have changed since the
188        last time this user was authenticated.</li>
189    <li>Return the newly constructed <code>GenericPrincipal</code>.</li>
190    </ul>
191
192
193    <h3>Method hasRole() Functionality</h3>
194
195    <p>When <code>hasRole()</code> is called, the following processing
196    is required:</p>
197    <ul>
198    <li>The <code>principal</code> that is passed as an argument SHOULD
199        be one that we returned (instanceof class
200        <code>org.apache.catalina.realm.GenericPrincipal</code>, with a
201        <code>realm</code> property that is equal to our instance.</li>
202    <li>If the passed <code>principal</code> meets these criteria, check
203        the specified role against the list returned by
204        <code>getRoles()</code>, and return <code>true</code> if the
205        specified role is included; otherwise, return <code>false</code>.</li>
206    <li>If the passed <code>principal</code> does not meet these criteria,
207        return <code>false</code>.</li>
208    </ul>
209
210  </blockquote></td></tr></table>
211
212</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"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote>
213
214  <p>In addition the the assertions implied by the functionality requirements
215  listed above, the following additional assertions shall be tested to
216  validate the behavior of <code>JDBCRealm</code>:</p>
217  <ul>
218  </ul>
219
220</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>
221        Copyright &copy; 1999-2008, Apache Software Foundation
222        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.