UserDAO


1   /*
2    * Copyright (c) 2003, Rafael Steil
3    * All rights reserved.
4    * 
5    * Redistribution and use in source and binary forms, 
6    * with or without modification, are permitted provided 
7    * that the following conditions are met:
8    * 
9    * 1) Redistributions of source code must retain the above 
10   * copyright notice, this list of conditions and the 
11   * following  disclaimer.
12   * 2)  Redistributions in binary form must reproduce the 
13   * above copyright notice, this list of conditions and 
14   * the following disclaimer in the documentation and/or 
15   * other materials provided with the distribution.
16   * 3) Neither the name of "Rafael Steil" nor 
17   * the names of its contributors may be used to endorse 
18   * or promote products derived from this software without 
19   * specific prior written permission.
20   * 
21   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT 
22   * HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 
23   * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, 
24   * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
25   * MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
26   * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 
27   * THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 
28   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
29   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
30   * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
31   * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
32   * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
33   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 
34   * IN CONTRACT, STRICT LIABILITY, OR TORT 
35   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
36   * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 
37   * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
38   * 
39   * This file creating date: Feb 19, 2003 / 8:56:56 PM
40   * The JForum Project
41   * http://www.jforum.net 
42   */
43  package net.jforum.dao;
44  
45  import java.security.NoSuchAlgorithmException  ;
46  import java.util.List  ;
47  
48  import net.jforum.entities.User;
49  
50  /**
51    * Model interface for {@link net.jforum.User}.
52   * This interface defines methods which are expected to be
53   * implementd by a specific data access driver. The intention is
54   * to provide all functionality needed to update, insert, delete and
55   * select some specific data.
56   * 
57   * @author Rafael Steil
58   * @version $Id: UserDAO.java,v 1.5 2005/07/26 03:04:28 rafaelsteil Exp $
59   */
60  public interface UserDAO 
61  {
62      /**
63       * Gets a specific <code>User</code>.
64       * 
65       * @param userId The User ID to search
66       * @return <code>User</code>object containing all the information
67       * @throws Exception
68       * @see #selectAll
69       */
70      public User selectById(int userId) throws Exception  ;
71      
72      /**
73       * Gets a specific <code>User</code>.
74       * 
75       * @param username The User name to search
76       * @return <code>User</code> object containing all the information
77       * or <code>null</code> if no data was found. 
78       * @throws Exception
79       * @see #selectAll
80       */
81      public User selectByName(String   username) throws Exception  ;
82      
83      /**
84       * Gets all users
85       * 
86       * @return <code>ArrayList</code> with the users. Each entry is an <code>User</code> object
87       * @throws Exception
88       */
89      public List   selectAll() throws Exception  ;
90      
91      /**
92       * Gets all users with your Karma.
93       * 
94       * @return <code>List</code> with the users. Each entry is an <code>User</code> object
95       * (with the KarmaStatus populated).
96       * @throws Exception
97       */
98      public List   selectAllWithKarma() throws Exception  ;
99      
100     /**
101      * Gets all users from a specific group.
102      * 
103      * @param groupId The group id
104      * @param start The index position to start fetching
105      * @param count The total number of records to fetch
106      * @return <code>List</code> with the users. Each entry is an <code>User</code> object
107      * @throws Exception
108      */
109     public List   selectAllByGroup(int groupId, int start, int count) throws Exception  ; 
110     
111     /**
112      * Gets all users
113      *
114      * @param startFrom Index to start fetching from
115      * @param count Number of records to retrieve
116      * @return <code>ArrayList</code> with the users. Each entry is an <code>User</code> object
117      * (with the KarmaStatus populated).
118      * @throws Exception
119      */
120     public List   selectAllWithKarma(int startFrom, int count) throws Exception  ;
121     
122     /**
123      * Finds an user by matching an input string. 
124      * 
125      * @param input The username to search. May be part of the username. 
126      * The method will match all users who have the input string as 
127      * part of their usernames.
128      * @param exactMath Set to <code>true</code> to get the user data related to 
129      * the username passed as argument, and set it to <code>false</code> to 
130      * search all users who match the criteria. 
131      * @return <code>List</code> with the found users. Each entry is an 
132      * <code>User</code> object, where only the <i>id</i> and <i>username</i>
133      * members are filled.
134      * @throws Exception exact
135      */
136     public List   findByName(String   input, boolean exactMath) throws Exception  ;
137     
138     /**
139      * Gets all users
140      *
141      * @param startFrom Index to start fetching from
142      * @param count Number of records to retrieve
143      * @return <code>ArrayList</code> with the users. Each entry is an <code>User</code> object
144      * @throws Exception
145      */
146     public List   selectAll(int startFrom, int count) throws Exception  ;
147     
148 
149     /**
150      * Deletes an user.
151      * 
152      * @param userId The user ID to delete
153      * @throws Exception
154      * @see #undelete(int)
155      */
156     public void delete(int userId) throws Exception  ;
157     
158     /**
159      * Undeletes an user.
160      * The system allows user undeletation because when you 
161      * call {@link #delete(int)} the user isn't fisically deleted of the
162      * database, but just marked as deleted. This is done to ensure
163      * data integrity.
164      * 
165      * @param userId The user ID to undelete
166      * @throws Exception
167      * @see #delete(int)
168      */
169     public void undelete(int userId) throws Exception  ;
170     
171     /**
172      * Updates a user.
173      * 
174      * @param user Reference to a <code>User</code> object to update
175      * @throws Exception
176      * @see #update(int)
177      */
178     public void update(User user) throws Exception  ;
179     
180     /**
181      * Adds a new User.
182      * After successfuly persisting the data, this method
183      * <b>shoud</b> call <code>user.setId(theNewId);</code>, as well
184      * return the new user id. 
185      * @param user Reference to a valid and configured <code>User</code> object
186      * @return The new user id
187      * @throws Exception
188      */
189     public int addNew(User user) throws Exception  ;
190 
191     /**
192      * Adds a new user with a predefined user id
193      * 
194      * (added by Pieter for external login support)
195      * @param user Reference to a valid and configured <code>User</code> object, with the user id already set
196      * @throws Exception
197      */
198     public void addNewWithId(User user) throws Exception   ;
199     
200     /**
201      * Set the active status.
202      * An user with the active status equals to false cannot be considered
203      * a "oficial", "fully registered" user until its status is set to true. This is
204      * interesting when you want to request user confirmation about registrations,
205      * for example
206      * 
207      * @param userId The user ID to change the status
208      * @param active <code>true</code> or <code>false</code>
209      * @throws Exception
210      */
211     public void setActive(int userId, boolean active) throws Exception  ;
212     
213     /**
214      * Sets the ranking.
215      * 
216      * @param userId The user ID
217      * @throws Exception
218      */
219     public void setRanking(int userId, int rankingId) throws Exception  ;
220     
221     /**
222      * Increments the number of posts of the user.
223      * 
224      * @param userId The user ID to increment the number of posts
225      * @throws Exception
226      */
227     public void incrementPosts(int userId) throws Exception  ;
228     
229     /**
230      * Decrement the number of posts of some user.
231      * 
232      * @param userId The user ID do decrement the number of posts.
233      * @throws Exception
234      */
235     public void decrementPosts(int userId) throws Exception  ;
236     
237     /**
238      * Gest some piece of information of the last user registered
239      * 
240      * @return <code>HashMap</code> containing the information. The map
241      * has two keys:<br>
242      * <li><b>userName</b>: The username
243      * <li><b>userId</b>: The user's ID 
244      * @throws Exception
245      */
246     public User getLastUserInfo() throws Exception  ;
247     
248     /**
249      * Gets the total number of users
250      * 
251      * @return The total number of users
252      * @throws Exception
253      */
254     public int getTotalUsers() throws Exception  ;
255     
256     /**
257      * Gets the total number of users of some group.
258      * 
259      * @param groupId The group id
260      * @return The total number of users
261      * @throws Exception
262      */
263     public int getTotalUsersByGroup(int groupId) throws Exception  ;
264     
265     /**
266      * whether the user is locked or not.
267      * 
268      * @return boolean
269      * @throws Exception
270      */ 
271     public boolean isDeleted(int user_id) throws Exception  ;
272     
273     /***
274      * Checks the existence of some username.
275      * This method is used to ensure that will not be two equal usernames in the database.
276      * 
277      * @param username The username to verify
278      * @return <code>true</code> or <code>false</code>, if the user was found or not, respectively
279      * @throws Exception
280      */
281     public boolean isUsernameRegistered(String   username) throws Exception  ;
282     
283     /**
284      * Validates the user login.
285      * 
286      * @param username The username
287      * @param password The password
288      * @return The user object if the provided information was corret, <code>null</code> if the information was invalid 
289      * @throws Exception
290      */
291     public User validateLogin(String   username, String   password) throws NoSuchAlgorithmException  , Exception  ;
292     
293     /**
294      * Associate the user to the group
295      * 
296      * @param userId The user id 
297      * @param groupId The group id to associate to
298      * @throws Exception
299      */
300     public void addToGroup(int userId, int[] groupId) throws Exception  ;
301     
302     /**
303      * Remove the user from the group
304      * 
305      * @param userId The user id
306      * @param groupId The group id to remove the user from
307      */
308     public void removeFromGroup(int userId, int[] groupId) throws Exception  ;
309     
310     /**
311      * Stores the "lost password" security hash, that was generated
312      * when the user asked the system to get a reminder of his password. 
313      * This hash is used to ensure the information supplied.  
314      * 
315      * @param email The user email
316      * @param hash The hash to store.
317      * @throws Exception
318      */
319     public void writeLostPasswordHash(String   email, String   hash) throws Exception  ;
320     
321     /**
322      * Validate the provided security hash against the data stored in our system.
323      * 
324      * @param email The user email
325      * @param hash The supplied security hash
326      * @return <code>true</code> if the data matches ok, of <code>false</code> if it is invalid
327      * @throws Exception
328      */
329     public boolean validateLostPasswordHash(String   email, String   hash) throws Exception  ;
330     
331     /**
332      * Writes a new password for the user. 
333      * 
334      * @param password The new password
335      * @param email The user email
336      * @throws Exception
337      */
338     public void saveNewPassword(String   password, String   email) throws Exception  ;
339     
340     /**
341      * Gets the username related to the email
342      * 
343      * @param email The email to search for the username
344      * @return The username, if found, or an empty <code>String</code>
345      * @throws Exception
346      */
347     public String   getUsernameByEmail(String   email) throws Exception  ;
348     
349     /**
350      * Validate if the activated key matches the one in the database
351      * 
352      * @param userId Which user to validate the activation key?
353      * @param hash The activation key
354      * @return <code>true</code> if the data matches ok, of <code>false</code> if it is invalid
355      * @throws Exception
356      */
357     public boolean validateActivationKeyHash(int userId , String   hash) throws Exception  ;
358 
359     /**
360      * Set user account to active
361      * 
362      * @param userId Which user account to set active?
363      * @throws Exception
364      */ 
365     public void writeUserActive(int userId) throws Exception  ;
366     
367     /**
368      * Updates only the username. 
369      * This method generally will be used in implementations
370      * of <code>net.jforum.drivers.external.LoginAuthenticator</code> to 
371      * update usernames which changed in the external source and therefore
372      * should be updated in jforum's users table. 
373      * 
374      * @param userId The user's id related to the username to update
375      * @param username The new username to write
376      * @throws Exception
377      */
378     public void updateUsername(int userId, String   username) throws Exception  ;
379     
380     /**
381      * Check if the username passed as argument is different of
382      * the username existent in the database. 
383      * 
384      * @param userId The user's id to work with
385      * @param usernameToCheck The username to compare with the existing
386      * one in <i>jforum_users</i>
387      * @return <code>true</code> if the usernames are different.
388      * @throws Exception
389      */
390     public boolean hasUsernameChanged(int userId, String   usernameToCheck) throws Exception  ;
391     
392 }
393
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags