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

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

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