PageRenderTime 84ms CodeModel.GetById 17ms RepoModel.GetById 0ms app.codeStats 0ms

/projects/jspwiki-2.8.4/src/com/ecyrd/jspwiki/auth/user/UserDatabase.java

https://gitlab.com/essere.lab.public/qualitas.class-corpus
Java | 232 lines | 25 code | 19 blank | 188 comment | 0 complexity | 9b9b40d5d4af146b292f29f1c07e4ee3 MD5 | raw file
  1. /*
  2. JSPWiki - a JSP-based WikiWiki clone.
  3. Licensed to the Apache Software Foundation (ASF) under one
  4. or more contributor license agreements. See the NOTICE file
  5. distributed with this work for additional information
  6. regarding copyright ownership. The ASF licenses this file
  7. to you under the Apache License, Version 2.0 (the
  8. "License"); you may not use this file except in compliance
  9. with the License. You may obtain a copy of the License at
  10. http://www.apache.org/licenses/LICENSE-2.0
  11. Unless required by applicable law or agreed to in writing,
  12. software distributed under the License is distributed on an
  13. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  14. KIND, either express or implied. See the License for the
  15. specific language governing permissions and limitations
  16. under the License.
  17. */
  18. package com.ecyrd.jspwiki.auth.user;
  19. import java.security.Principal;
  20. import java.util.Properties;
  21. import com.ecyrd.jspwiki.NoRequiredPropertyException;
  22. import com.ecyrd.jspwiki.WikiEngine;
  23. import com.ecyrd.jspwiki.auth.NoSuchPrincipalException;
  24. import com.ecyrd.jspwiki.auth.WikiSecurityException;
  25. /**
  26. * Defines an interface for loading, persisting and storing users.
  27. * @author Janne Jalkanen
  28. * @author Andrew Jaquith
  29. * @since 2.3
  30. */
  31. public interface UserDatabase
  32. {
  33. /**
  34. * No-op method that in previous versions of JSPWiki was intended to
  35. * atomically commit changes to the user database. Now, the {@link #rename(String, String)},
  36. * {@link #save(UserProfile)} and {@link #deleteByLoginName(String)} methods
  37. * are atomic themselves.
  38. * @throws WikiSecurityException
  39. * @deprecated there is no need to call this method because the save, rename and
  40. * delete methods contain their own commit logic
  41. */
  42. public void commit() throws WikiSecurityException;
  43. /**
  44. * Looks up and deletes the first {@link UserProfile} in the user database
  45. * that matches a profile having a given login name. If the user database
  46. * does not contain a user with a matching attribute, throws a
  47. * {@link NoSuchPrincipalException}. This method is intended to be atomic;
  48. * results cannot be partially committed. If the commit fails, it should
  49. * roll back its state appropriately. Implementing classes that persist
  50. * to the file system may wish to make this method <code>synchronized</code>.
  51. * @param loginName the login name of the user profile that shall be deleted
  52. */
  53. public void deleteByLoginName( String loginName ) throws NoSuchPrincipalException, WikiSecurityException;
  54. /**
  55. * <p>
  56. * Looks up the Principals representing a user from the user database. These
  57. * are defined as a set of Principals manufactured from the login name, full
  58. * name, and wiki name. The order of the Principals returned is not
  59. * significant. If the user database does not contain a user with the
  60. * supplied identifier, throws a {@link NoSuchPrincipalException}.
  61. * </p>
  62. * <p>
  63. * Note that if an implememtation wishes to mark one of the returned
  64. * Principals as representing the user's common name, it should instantiate
  65. * this Principal using
  66. * {@link com.ecyrd.jspwiki.auth.WikiPrincipal#WikiPrincipal(String, String)}
  67. * with the <code>type</code> parameter set to
  68. * {@link com.ecyrd.jspwiki.auth.WikiPrincipal#WIKI_NAME}. The method
  69. * {@link com.ecyrd.jspwiki.WikiSession#getUserPrincipal()} will return this
  70. * principal as the "primary" principal. Note that this method can also be
  71. * used to mark a WikiPrincipal as a login name or a wiki name.
  72. * </p>
  73. * @param identifier the name of the user to retrieve; this corresponds to
  74. * value returned by the user profile's
  75. * {@link UserProfile#getLoginName()} method.
  76. * @return the array of Principals representing the user's identities
  77. */
  78. public Principal[] getPrincipals( String identifier ) throws NoSuchPrincipalException;
  79. /**
  80. * Returns all WikiNames that are stored in the UserDatabase
  81. * as an array of Principal objects. If the database does not
  82. * contain any profiles, this method will return a zero-length
  83. * array.
  84. * @return the WikiNames
  85. */
  86. public Principal[] getWikiNames() throws WikiSecurityException;
  87. /**
  88. * Looks up and returns the first {@link UserProfile} in the user database
  89. * that whose login name, full name, or wiki name matches the supplied
  90. * string. This method provides a "forgiving" search algorithm for resolving
  91. * Principal names when the exact profile attribute that supplied the name
  92. * is unknown.
  93. * @param index the login name, full name, or wiki name
  94. */
  95. public UserProfile find( String index ) throws NoSuchPrincipalException;
  96. /**
  97. * Looks up and returns the first {@link UserProfile} in the user database
  98. * that matches a profile having a given e-mail address. If the user
  99. * database does not contain a user with a matching attribute, throws a
  100. * {@link NoSuchPrincipalException}.
  101. * @param index the e-mail address of the desired user profile
  102. * @return the user profile
  103. */
  104. public UserProfile findByEmail( String index ) throws NoSuchPrincipalException;
  105. /**
  106. * Looks up and returns the first {@link UserProfile} in the user database
  107. * that matches a profile having a given login name. If the user database
  108. * does not contain a user with a matching attribute, throws a
  109. * {@link NoSuchPrincipalException}.
  110. * @param index the login name of the desired user profile
  111. * @return the user profile
  112. */
  113. public UserProfile findByLoginName( String index ) throws NoSuchPrincipalException;
  114. /**
  115. * Looks up and returns the first {@link UserProfile} in the user database
  116. * that matches a profile having a given unique ID (uid). If the user database
  117. * does not contain a user with a unique ID, it throws a
  118. * {@link NoSuchPrincipalException}.
  119. * @param uid the unique identifier of the desired user profile
  120. * @return the user profile
  121. * @since 2.8
  122. */
  123. public UserProfile findByUid( String uid ) throws NoSuchPrincipalException;
  124. /**
  125. * Looks up and returns the first {@link UserProfile} in the user database
  126. * that matches a profile having a given wiki name. If the user database
  127. * does not contain a user with a matching attribute, throws a
  128. * {@link NoSuchPrincipalException}.
  129. * @param index the wiki name of the desired user profile
  130. * @return the user profile
  131. */
  132. public UserProfile findByWikiName( String index ) throws NoSuchPrincipalException;
  133. /**
  134. * Looks up and returns the first {@link UserProfile} in the user database
  135. * that matches a profile having a given full name. If the user database
  136. * does not contain a user with a matching attribute, throws a
  137. * {@link NoSuchPrincipalException}.
  138. * @param index the fill name of the desired user profile
  139. * @return the user profile
  140. */
  141. public UserProfile findByFullName( String index ) throws NoSuchPrincipalException;
  142. /**
  143. * Initializes the user database based on values from a Properties object.
  144. */
  145. public void initialize( WikiEngine engine, Properties props ) throws NoRequiredPropertyException;
  146. /**
  147. * Factory method that instantiates a new user profile.
  148. * The {@link UserProfile#isNew()} method of profiles created using
  149. * this method should return <code>true</code>.
  150. */
  151. public UserProfile newProfile();
  152. /**
  153. * <p>Renames a {@link UserProfile} in the user database by changing
  154. * the profile's login name. Because the login name is the profile's unique
  155. * identifier, implementations should verify that the identifier is
  156. * "safe" to change before actually changing it. Specifically: the profile
  157. * with the supplied login name must already exist, and the proposed new
  158. * name must not be in use by another profile.</p>
  159. * <p>This method is intended to be atomic; results cannot be partially committed.
  160. * If the commit fails, it should roll back its state appropriately.
  161. * Implementing classes that persist to the file system may wish to make
  162. * this method <code>synchronized</code>.</p>
  163. * @param loginName the existing login name for the profile
  164. * @param newName the proposed new login name
  165. * @throws NoSuchPrincipalException if the user profile identified by
  166. * <code>loginName</code> does not exist
  167. * @throws DuplicateUserException if another user profile with the
  168. * proposed new login name already exists
  169. * @throws WikiSecurityException if the profile cannot be renamed for
  170. * any reason, such as an I/O error, database connection failure
  171. * or lack of support for renames.
  172. */
  173. public void rename( String loginName, String newName ) throws NoSuchPrincipalException, DuplicateUserException, WikiSecurityException;
  174. /**
  175. * <p>
  176. * Saves a {@link UserProfile}to the user database, overwriting the
  177. * existing profile if it exists. The user name under which the profile
  178. * should be saved is returned by the supplied profile's
  179. * {@link UserProfile#getLoginName()} method.
  180. * </p>
  181. * <p>
  182. * The database implementation is responsible for detecting potential
  183. * duplicate user profiles; specifically, the login name, wiki name, and
  184. * full name must be unique. The implementation is not required to check for
  185. * validity of passwords or e-mail addresses. Special case: if the profile
  186. * already exists and the password is null, it should retain its previous
  187. * value, rather than being set to null.
  188. * </p>
  189. * <p>Implementations are <em>required</em> to time-stamp the creation
  190. * or modification fields of the UserProfile./p>
  191. * <p>This method is intended to be atomic; results cannot be partially committed.
  192. * If the commit fails, it should roll back its state appropriately.
  193. * Implementing classes that persist to the file system may wish to make
  194. * this method <code>synchronized</code>.</p>
  195. * @param profile the user profile to save
  196. * @throws WikiSecurityException if the profile cannot be saved
  197. */
  198. public void save( UserProfile profile ) throws WikiSecurityException;
  199. /**
  200. * Determines whether a supplied user password is valid, given a login name
  201. * and password. It is up to the implementing class to determine how the
  202. * comparison should be made. For example, the password might be hashed
  203. * before comparing it to the value persisted in the back-end data store.
  204. * @param loginName the login name
  205. * @param password the password
  206. * @return <code>true</code> if the password is valid, <code>false</code>
  207. * otherwise
  208. */
  209. public boolean validatePassword( String loginName, String password );
  210. }