Author: jalkanen
Date: Sat Jan 16 11:45:34 2010
New Revision: 899922
URL: http://svn.apache.org/viewvc?rev=899922&view=rev
Log:
Cleaned Javadocs (and resolved a number of Checkstyle issues).
Modified:
incubator/jspwiki/trunk/src/java/org/apache/wiki/auth/user/UserDatabase.java
Modified:
incubator/jspwiki/trunk/src/java/org/apache/wiki/auth/user/UserDatabase.java
URL:
http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/java/org/apache/wiki/auth/user/UserDatabase.java?rev=899922&r1=899921&r2=899922&view=diff
==============================================================================
---
incubator/jspwiki/trunk/src/java/org/apache/wiki/auth/user/UserDatabase.java
(original)
+++
incubator/jspwiki/trunk/src/java/org/apache/wiki/auth/user/UserDatabase.java
Sat Jan 16 11:45:34 2010
@@ -37,194 +37,226 @@
{
/**
- * No-op method that in previous versions of JSPWiki was intended to
- * atomically commit changes to the user database. Now, the {...@link
#rename(String, String)},
- * {...@link #save(UserProfile)} and {...@link #deleteByLoginName(String)}
methods
- * are atomic themselves.
- * @throws WikiSecurityException
- * @deprecated there is no need to call this method because the save,
rename and
- * delete methods contain their own commit logic
+ * No-op method that in previous versions of JSPWiki was intended to
+ * atomically commit changes to the user database. Now, the {...@link
#rename(String, String)},
+ * {...@link #save(UserProfile)} and {...@link
#deleteByLoginName(String)} methods
+ * are atomic themselves.
+ *
+ * @throws WikiSecurityException Never throws one.
+ * @deprecated there is no need to call this method because the save,
rename and
+ * delete methods contain their own commit logic
*/
public void commit() throws WikiSecurityException;
/**
- * Looks up and deletes the first {...@link UserProfile} in the user
database
- * that matches a profile having a given login name. If the user database
- * does not contain a user with a matching attribute, throws a
- * {...@link NoSuchPrincipalException}. This method is intended to be
atomic;
- * results cannot be partially committed. If the commit fails, it should
- * roll back its state appropriately. Implementing classes that persist
- * to the file system may wish to make this method
<code>synchronized</code>.
- * @param loginName the login name of the user profile that shall be
deleted
+ * Looks up and deletes the first {...@link UserProfile} in the user
database
+ * that matches a profile having a given login name. If the user database
+ * does not contain a user with a matching attribute, throws a
+ * {...@link NoSuchPrincipalException}. This method is intended to be
atomic;
+ * results cannot be partially committed. If the commit fails, it should
+ * roll back its state appropriately. Implementing classes that persist
+ * to the file system may wish to make this method
<code>synchronized</code>.
+ *
+ * @param loginName the login name of the user profile that shall be
deleted
+ * @throws NoSuchPrincipalException If no such login name exists.
+ * @throws WikiSecurityException If the user cannot be deleted.
*/
public void deleteByLoginName( String loginName ) throws
NoSuchPrincipalException, WikiSecurityException;
/**
- * <p>
- * Looks up the Principals representing a user from the user database.
These
- * are defined as a set of Principals manufactured from the login name,
full
- * name, and wiki name. The order of the Principals returned is not
- * significant. If the user database does not contain a user with the
- * supplied identifier, throws a {...@link NoSuchPrincipalException}.
- * </p>
- * <p>
- * Note that if an implememtation wishes to mark one of the returned
- * Principals as representing the user's common name, it should instantiate
- * this Principal using
- * {...@link org.apache.wiki.auth.WikiPrincipal#WikiPrincipal(String,
String)}
- * with the <code>type</code> parameter set to
- * {...@link org.apache.wiki.auth.WikiPrincipal#FULL_NAME}. The method
- * {...@link org.apache.wiki.WikiSession#getUserPrincipal()} will return
this
- * principal as the "primary" principal. Note that this method can also be
- * used to mark a WikiPrincipal as a login name or a wiki name.
- * </p>
- * @param identifier the name of the user to retrieve; this corresponds to
- * value returned by the user profile's
- * {...@link UserProfile#getLoginName()} method.
- * @return the array of Principals representing the user's identities
+ * <p>
+ * Looks up the Principals representing a user from the user database.
These
+ * are defined as a set of Principals manufactured from the login name,
full
+ * name, and wiki name. The order of the Principals returned is not
+ * significant. If the user database does not contain a user with the
+ * supplied identifier, throws a {...@link NoSuchPrincipalException}.
+ * </p>
+ * <p>
+ * Note that if an implememtation wishes to mark one of the returned
+ * Principals as representing the user's common name, it should
instantiate
+ * this Principal using
+ * {...@link org.apache.wiki.auth.WikiPrincipal#WikiPrincipal(String,
String)}
+ * with the <code>type</code> parameter set to
+ * {...@link org.apache.wiki.auth.WikiPrincipal#FULL_NAME}. The method
+ * {...@link org.apache.wiki.WikiSession#getUserPrincipal()} will return
this
+ * principal as the "primary" principal. Note that this method can also be
+ * used to mark a WikiPrincipal as a login name or a wiki name.
+ * </p>
+ *
+ * @param identifier the name of the user to retrieve; this corresponds to
+ * value returned by the user profile's
+ * {...@link UserProfile#getLoginName()} method.
+ * @return the array of Principals representing the user's identities
+ * @throws NoSuchPrincipalException If there's no such identifier in the
database.
*/
public Principal[] getPrincipals( String identifier ) throws
NoSuchPrincipalException;
/**
- * Returns all WikiNames that are stored in the UserDatabase
- * as an array of Principal objects. If the database does not
- * contain any profiles, this method will return a zero-length
- * array.
- * @return the WikiNames
+ * Returns all WikiNames that are stored in the UserDatabase
+ * as an array of Principal objects. If the database does not
+ * contain any profiles, this method will return a zero-length
+ * array.
+ *
+ * @return the WikiNames
+ * @throws WikiSecurityException If there's a problem in getting the
names,
*/
public Principal[] getWikiNames() throws WikiSecurityException;
/**
- * Looks up and returns the first {...@link UserProfile} in the user
database
- * that whose login name, full name, or wiki name matches the supplied
- * string. This method provides a "forgiving" search algorithm for
resolving
- * Principal names when the exact profile attribute that supplied the name
- * is unknown.
- * @param index the login name, full name, or wiki name
+ * Looks up and returns the first {...@link UserProfile} in the user
database
+ * that whose login name, full name, or wiki name matches the supplied
+ * string. This method provides a "forgiving" search algorithm for
resolving
+ * Principal names when the exact profile attribute that supplied the name
+ * is unknown.
+ *
+ * @param index the login name, full name, or wiki name
+ * @throws NoSuchPrincipalException If there was no matching identity.
+ * @return A valid UserProfile
*/
public UserProfile find( String index ) throws NoSuchPrincipalException;
/**
- * Looks up and returns the first {...@link UserProfile} in the user
database
- * that matches a profile having a given e-mail address. If the user
- * database does not contain a user with a matching attribute, throws a
- * {...@link NoSuchPrincipalException}.
- * @param index the e-mail address of the desired user profile
- * @return the user profile
+ * Looks up and returns the first {...@link UserProfile} in the user
database
+ * that matches a profile having a given e-mail address. If the user
+ * database does not contain a user with a matching attribute, throws a
+ * {...@link NoSuchPrincipalException}.
+ *
+ * @param index the e-mail address of the desired user profile
+ * @return the user profile
+ * @throws NoSuchPrincipalException If there was no such email.
*/
public UserProfile findByEmail( String index ) throws
NoSuchPrincipalException;
/**
- * Looks up and returns the first {...@link UserProfile} in the user
database
- * that matches a profile having a given login name. If the user database
- * does not contain a user with a matching attribute, throws a
- * {...@link NoSuchPrincipalException}.
- * @param index the login name of the desired user profile
- * @return the user profile
+ * Looks up and returns the first {...@link UserProfile} in the user
database
+ * that matches a profile having a given login name. If the user database
+ * does not contain a user with a matching attribute, throws a
+ * {...@link NoSuchPrincipalException}.
+ *
+ * @param index the login name of the desired user profile
+ * @return the user profile
+ * @throws NoSuchPrincipalException If there's no such login name.
*/
public UserProfile findByLoginName( String index ) throws
NoSuchPrincipalException;
/**
- * Looks up and returns the first {...@link UserProfile} in the user
database
- * that matches a profile having a given unique ID (uid). If the user
database
- * does not contain a user with a unique ID, it throws a
- * {...@link NoSuchPrincipalException}.
- * @param uid the unique identifier of the desired user profile
- * @return the user profile
- * @since 2.8
+ * Looks up and returns the first {...@link UserProfile} in the user
database
+ * that matches a profile having a given unique ID (uid). If the user
database
+ * does not contain a user with a unique ID, it throws a
+ * {...@link NoSuchPrincipalException}.
+ *
+ * @param uid the unique identifier of the desired user profile
+ * @return the user profile
+ * @since 2.8
+ * @throws NoSuchPrincipalException If no UID exists.
*/
public UserProfile findByUid( String uid ) throws NoSuchPrincipalException;
/**
- * Looks up and returns the first {...@link UserProfile} in the user
database
- * that matches a profile having a given wiki name. If the user database
- * does not contain a user with a matching attribute, throws a
- * {...@link NoSuchPrincipalException}.
- * @param index the wiki name of the desired user profile
- * @return the user profile
+ * Looks up and returns the first {...@link UserProfile} in the user
database
+ * that matches a profile having a given wiki name. If the user database
+ * does not contain a user with a matching attribute, throws a
+ * {...@link NoSuchPrincipalException}.
+ *
+ * @param index the wiki name of the desired user profile
+ * @return the user profile
+ * @throws NoSuchPrincipalException If there was no such wikiname.
*/
public UserProfile findByWikiName( String index ) throws
NoSuchPrincipalException;
/**
- * Looks up and returns the first {...@link UserProfile} in the user
database
- * that matches a profile having a given full name. If the user database
- * does not contain a user with a matching attribute, throws a
- * {...@link NoSuchPrincipalException}.
- * @param index the fill name of the desired user profile
- * @return the user profile
+ * Looks up and returns the first {...@link UserProfile} in the user
database
+ * that matches a profile having a given full name. If the user database
+ * does not contain a user with a matching attribute, throws a
+ * {...@link NoSuchPrincipalException}.
+ *
+ * @param index the fill name of the desired user profile
+ * @return the user profile
+ *
+ * @throws NoSuchPrincipalException If there's no such user.
*/
public UserProfile findByFullName( String index ) throws
NoSuchPrincipalException;
/**
- * Initializes the user database based on values from a Properties object.
+ * Initializes the user database based on values from a Properties object.
+ *
+ * @param engine WikiEngine.
+ * @param props Properties used to initialize the engine.
+ * @throws NoRequiredPropertyException If the Database could not find a
property it absolutely requires. The database
+ * SHOULD include the name of the property which was not found in
the Exception description.
*/
public void initialize( WikiEngine engine, Properties props ) throws
NoRequiredPropertyException;
/**
- * Factory method that instantiates a new user profile.
- * The {...@link UserProfile#isNew()} method of profiles created using
- * this method should return <code>true</code>.
+ * Factory method that instantiates a new user profile.
+ * The {...@link UserProfile#isNew()} method of profiles created using
+ * this method should return <code>true</code>.
+ *
+ * @return A new user profile.
*/
public UserProfile newProfile();
/**
- * <p>Renames a {...@link UserProfile} in the user database by changing
- * the profile's login name. Because the login name is the profile's unique
- * identifier, implementations should verify that the identifier is
- * "safe" to change before actually changing it. Specifically: the profile
- * with the supplied login name must already exist, and the proposed new
- * name must not be in use by another profile.</p>
- * <p>This method is intended to be atomic; results cannot be partially
committed.
- * If the commit fails, it should roll back its state appropriately.
- * Implementing classes that persist to the file system may wish to make
- * this method <code>synchronized</code>.</p>
- * @param loginName the existing login name for the profile
- * @param newName the proposed new login name
- * @throws NoSuchPrincipalException if the user profile identified by
- * <code>loginName</code> does not exist
- * @throws DuplicateUserException if another user profile with the
- * proposed new login name already exists
- * @throws WikiSecurityException if the profile cannot be renamed for
- * any reason, such as an I/O error, database connection failure
- * or lack of support for renames.
+ * <p>Renames a {...@link UserProfile} in the user database by changing
+ * the profile's login name. Because the login name is the profile's
unique
+ * identifier, implementations should verify that the identifier is
+ * "safe" to change before actually changing it. Specifically: the profile
+ * with the supplied login name must already exist, and the proposed new
+ * name must not be in use by another profile.</p>
+ * <p>This method is intended to be atomic; results cannot be partially
committed.
+ * If the commit fails, it should roll back its state appropriately.
+ * Implementing classes that persist to the file system may wish to make
+ * this method <code>synchronized</code>.</p>
+ *
+ * @param loginName the existing login name for the profile
+ * @param newName the proposed new login name
+ * @throws NoSuchPrincipalException if the user profile identified by
+ * <code>loginName</code> does not exist
+ * @throws DuplicateUserException if another user profile with the
+ * proposed new login name already exists
+ * @throws WikiSecurityException if the profile cannot be renamed for
+ * any reason, such as an I/O error, database connection failure
+ * or lack of support for renames.
*/
public void rename( String loginName, String newName ) throws
NoSuchPrincipalException, DuplicateUserException, WikiSecurityException;
/**
- * <p>
- * Saves a {...@link UserProfile}to the user database, overwriting the
- * existing profile if it exists. The user name under which the profile
- * should be saved is returned by the supplied profile's
- * {...@link UserProfile#getLoginName()} method.
- * </p>
- * <p>
- * The database implementation is responsible for detecting potential
- * duplicate user profiles; specifically, the login name, wiki name, and
- * full name must be unique. The implementation is not required to check
for
- * validity of passwords or e-mail addresses. Special case: if the profile
- * already exists and the password is null, it should retain its previous
- * value, rather than being set to null.
- * </p>
- * <p>Implementations are <em>required</em> to time-stamp the creation
- * or modification fields of the UserProfile./p>
- * <p>This method is intended to be atomic; results cannot be partially
committed.
- * If the commit fails, it should roll back its state appropriately.
- * Implementing classes that persist to the file system may wish to make
- * this method <code>synchronized</code>.</p>
- * @param profile the user profile to save
- * @throws WikiSecurityException if the profile cannot be saved
+ * <p>
+ * Saves a {...@link UserProfile}to the user database, overwriting the
+ * existing profile if it exists. The user name under which the profile
+ * should be saved is returned by the supplied profile's
+ * {...@link UserProfile#getLoginName()} method.
+ * </p>
+ * <p>
+ * The database implementation is responsible for detecting potential
+ * duplicate user profiles; specifically, the login name, wiki name, and
+ * full name must be unique. The implementation is not required to check
for
+ * validity of passwords or e-mail addresses. Special case: if the profile
+ * already exists and the password is null, it should retain its previous
+ * value, rather than being set to null.
+ * </p>
+ * <p>Implementations are <em>required</em> to time-stamp the creation
+ * or modification fields of the UserProfile./p>
+ * <p>This method is intended to be atomic; results cannot be partially
committed.
+ * If the commit fails, it should roll back its state appropriately.
+ * Implementing classes that persist to the file system may wish to make
+ * this method <code>synchronized</code>.</p>
+ *
+ * @param profile the user profile to save
+ * @throws WikiSecurityException if the profile cannot be saved
*/
public void save( UserProfile profile ) throws WikiSecurityException;
/**
- * Determines whether a supplied user password is valid, given a login name
- * and password. It is up to the implementing class to determine how the
- * comparison should be made. For example, the password might be hashed
- * before comparing it to the value persisted in the back-end data store.
- * @param loginName the login name
- * @param password the password
- * @return <code>true</code> if the password is valid, <code>false</code>
- * otherwise
+ * Determines whether a supplied user password is valid, given a login
name
+ * and password. It is up to the implementing class to determine how the
+ * comparison should be made. For example, the password might be hashed
+ * before comparing it to the value persisted in the back-end data store.
+ *
+ * @param loginName the login name
+ * @param password the password
+ * @return <code>true</code> if the password is valid, <code>false</code>
+ * otherwise
*/
public boolean validatePassword( String loginName, String password );
