tomcat-uidm/webapps/docs/funcspecs/fs-memory-realm.html - UniIdentify/tomcat - Gitiles

 <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications (6.0.39) - MemoryRealm</title><meta name="author" content="Craig McClanahan"><style type="text/css" media="print">
 			.noPrint {display: none;}
 			td#mainBody {width: 100%;}
 		</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
       Catalina Functional Specifications
     " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.39, Jan 27 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><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 width="80%" valign="top" align="left" id="mainBody"><h1>Catalina Functional Specifications</h1><h2>MemoryRealm</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>


   <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>

     <p>The purpose of the <strong>MemoryRealm</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 simple text-based configuration file in XML format.  This is
     intended to simplify the initial installation and operation of Tomcat 6,
     without the complexity of configuring a database or directory server
     based Realm.  It is not intended for production use.</p>

     <p>This specification reflects a combination of functionality that is
     already present in the <code>org.apache.catalina.realm.MemoryRealm</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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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>None</li>
     </ul>

   </blockquote></td></tr></table>


   <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote>


   <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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
     MemoryRealm to operate correctly:</p>
     <ul>
     <li>The desire to utilize MemoryRealm must be registered in
         <code>$CATALINA_BASE/conf/server.xml</code>, in a
         <code>&lt;Realm&gt;</code> element that is nested inside a
         corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
         or <code>&lt;Context&gt;</code> element.  (This is already
         included in the default <code>server.xml</code> file.)</li>
     </ul>

   </blockquote></td></tr></table>


   <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Container Dependencies"><!--()--></a><a name="Container_Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>

     <p>Correct operation of MemoryRealm depends on the following
     specific features of the surrounding container:</p>
     <ul>
     <li>Interactions with <code>MemoryRealm</code> will be initiated by
         the appropriate <code>Authenticator</code> implementation, based
         on the login method that is selected.</li>
     <li><code>MemoryRealm</code> must have an XML parser compatible with
         the JAXP/1.1 APIs available to it.  This is normally accomplished
         by placing the corresponding JAR files in directory
         <code>$CATALINA_HOME/lib</code>.</li>
     </ul>

   </blockquote></td></tr></table>


 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote>


   <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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>MemoryRealm</code> is to allow Catalina to
     authenticate users, and look up the corresponding security roles, from
     the information found in an XML-format configuration file.  The format
     of this file is described below.  When a <code>MemoryRealm</code>
     instance is started, it will read the contents of this XML file and create
     an "in memory database" of all the valid users and their associated
     security roles.</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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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>Configurable debugging detail level.</li>
     <li>Configurable file pathname (absolute or relative to
         <code>$CATALINA_BASE</code> of the XML file containing our
         defined users.  [<code>conf/tomcat-users.xml</code>].</li>
     </ul>

     <h3>Lifecycle Functionality</h3>

     <p>The following processing must be performed when the <code>start()</code>
     method is called:</p>
     <ul>
     <li>Open and parse the specified XML file.</li>
     <li>Create an in-memory database representation of the XML file
         contents.</li>
     <li><strong>NOTE</strong> - There is no requirement to recognize
         subsequent changes to the contents of the XML file.</li>
     </ul>

     <p>The following processing must be performed when the <code>stop()</code>
     method is called:</p>
     <ul>
     <li>Release object references to the in-memory database representation.</li>
     </ul>


     <h3>Method authenticate() Functionality</h3>

     <p>When <code>authenticate()</code> is called, the following processing
     is required:</p>
     <ul>
     <li>Select the one and only "user" instance from the in-memory database,
         based on matching the specified username.  If there is no such
         instance, 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>Construct a new instance of class
         <code>org.apache.catalina.realm.GenericPrincipal</code> (if not
         already using this as the internal database representation) that
         contains the authenticated username and a <code>List</code> of the
         security roles associated with this user.</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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><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>MemoryRealm</code>:</p>
   <ul>
   </ul>

 </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
         Copyright &copy; 1999-2014, Apache Software Foundation
         </em></font></div></td></tr></table></body></html>
	<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications (6.0.39) - MemoryRealm</title><meta name="author" content="Craig McClanahan"><style type="text/css" media="print">
	.noPrint {display: none;}
	td#mainBody {width: 100%;}
	</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
	Catalina Functional Specifications
	" border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.39, Jan 27 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><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 width="80%" valign="top" align="left" id="mainBody"><h1>Catalina Functional Specifications</h1><h2>MemoryRealm</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>


	<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>

	<p>The purpose of the <strong>MemoryRealm</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 simple text-based configuration file in XML format. This is
	intended to simplify the initial installation and operation of Tomcat 6,
	without the complexity of configuring a database or directory server
	based Realm. It is not intended for production use.</p>

	<p>This specification reflects a combination of functionality that is
	already present in the <code>org.apache.catalina.realm.MemoryRealm</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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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>None</li>
	</ul>

	</blockquote></td></tr></table>


	<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote>


	<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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
	MemoryRealm to operate correctly:</p>
	<ul>
	<li>The desire to utilize MemoryRealm 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. (This is already
	included in the default <code>server.xml</code> file.)</li>
	</ul>

	</blockquote></td></tr></table>


	<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Container Dependencies"><!--()--></a><a name="Container_Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>

	<p>Correct operation of MemoryRealm depends on the following
	specific features of the surrounding container:</p>
	<ul>
	<li>Interactions with <code>MemoryRealm</code> will be initiated by
	the appropriate <code>Authenticator</code> implementation, based
	on the login method that is selected.</li>
	<li><code>MemoryRealm</code> must have an XML parser compatible with
	the JAXP/1.1 APIs available to it. This is normally accomplished
	by placing the corresponding JAR files in directory
	<code>$CATALINA_HOME/lib</code>.</li>
	</ul>

	</blockquote></td></tr></table>


	</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote>


	<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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>MemoryRealm</code> is to allow Catalina to
	authenticate users, and look up the corresponding security roles, from
	the information found in an XML-format configuration file. The format
	of this file is described below. When a <code>MemoryRealm</code>
	instance is started, it will read the contents of this XML file and create
	an "in memory database" of all the valid users and their associated
	security roles.</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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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>Configurable debugging detail level.</li>
	<li>Configurable file pathname (absolute or relative to
	<code>$CATALINA_BASE</code> of the XML file containing our
	defined users. [<code>conf/tomcat-users.xml</code>].</li>
	</ul>

	<h3>Lifecycle Functionality</h3>

	<p>The following processing must be performed when the <code>start()</code>
	method is called:</p>
	<ul>
	<li>Open and parse the specified XML file.</li>
	<li>Create an in-memory database representation of the XML file
	contents.</li>
	<li><strong>NOTE</strong> - There is no requirement to recognize
	subsequent changes to the contents of the XML file.</li>
	</ul>

	<p>The following processing must be performed when the <code>stop()</code>
	method is called:</p>
	<ul>
	<li>Release object references to the in-memory database representation.</li>
	</ul>


	<h3>Method authenticate() Functionality</h3>

	<p>When <code>authenticate()</code> is called, the following processing
	is required:</p>
	<ul>
	<li>Select the one and only "user" instance from the in-memory database,
	based on matching the specified username. If there is no such
	instance, 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>Construct a new instance of class
	<code>org.apache.catalina.realm.GenericPrincipal</code> (if not
	already using this as the internal database representation) that
	contains the authenticated username and a <code>List</code> of the
	security roles associated with this user.</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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><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>MemoryRealm</code>:</p>
	<ul>
	</ul>

	</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
	Copyright © 1999-2014, Apache Software Foundation
	</em></font></div></td></tr></table></body></html>