KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > net > jforum > dao > 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 JavaDoc;
46 import java.util.List JavaDoc;
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 JavaDoc;
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 JavaDoc username) throws Exception JavaDoc;
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 JavaDoc selectAll() throws Exception JavaDoc;
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 JavaDoc selectAllWithKarma() throws Exception JavaDoc;
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 JavaDoc selectAllByGroup(int groupId, int start, int count) throws Exception JavaDoc;
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 JavaDoc selectAllWithKarma(int startFrom, int count) throws Exception JavaDoc;
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 JavaDoc findByName(String JavaDoc input, boolean exactMath) throws Exception JavaDoc;
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 JavaDoc selectAll(int startFrom, int count) throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc ;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc username) throws Exception JavaDoc;
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 JavaDoc username, String JavaDoc password) throws NoSuchAlgorithmException JavaDoc, Exception JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc email, String JavaDoc hash) throws Exception JavaDoc;
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 JavaDoc email, String JavaDoc hash) throws Exception JavaDoc;
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 JavaDoc password, String JavaDoc email) throws Exception JavaDoc;
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 JavaDoc getUsernameByEmail(String JavaDoc email) throws Exception JavaDoc;
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 JavaDoc hash) throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc username) throws Exception JavaDoc;
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 JavaDoc usernameToCheck) throws Exception JavaDoc;
391     
392 }
393
Popular Tags