001: /*
002: * Copyright (c) JForum Team
003: * All rights reserved.
004: *
005: * Redistribution and use in source and binary forms,
006: * with or without modification, are permitted provided
007: * that the following conditions are met:
008: *
009: * 1) Redistributions of source code must retain the above
010: * copyright notice, this list of conditions and the
011: * following disclaimer.
012: * 2) Redistributions in binary form must reproduce the
013: * above copyright notice, this list of conditions and
014: * the following disclaimer in the documentation and/or
015: * other materials provided with the distribution.
016: * 3) Neither the name of "Rafael Steil" nor
017: * the names of its contributors may be used to endorse
018: * or promote products derived from this software without
019: * specific prior written permission.
020: *
021: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT
022: * HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
023: * EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
024: * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
025: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR
026: * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
027: * THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
028: * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
029: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES
030: * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
031: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
032: * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
033: * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
034: * IN CONTRACT, STRICT LIABILITY, OR TORT
035: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
036: * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
037: * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
038: *
039: * This file creating date: Feb 19, 2003 / 8:56:56 PM
040: * The JForum Project
041: * http://www.jforum.net
042: */
043: package net.jforum.dao;
044:
045: import java.util.List;
046:
047: import net.jforum.entities.User;
048:
049: /**
050: * Model interface for {@link net.jforum.entities.User}.
051: * This interface defines methods which are expected to be
052: * implementd by a specific data access driver. The intention is
053: * to provide all functionality needed to update, insert, delete and
054: * select some specific data.
055: *
056: * @author Rafael Steil
057: * @version $Id: UserDAO.java,v 1.10 2007/09/21 17:26:08 rafaelsteil Exp $
058: */
059: public interface UserDAO {
060: /**
061: * Gets a specific <code>User</code>.
062: *
063: * @param userId The User ID to search
064: * @return <code>User</code>object containing all the information
065: * @see #selectAll
066: */
067: public User selectById(int userId);
068:
069: /**
070: * Gets a specific <code>User</code>.
071: *
072: * @param username The User name to search
073: * @return <code>User</code> object containing all the information
074: * or <code>null</code> if no data was found.
075: * @see #selectAll
076: */
077: public User selectByName(String username);
078:
079: /**
080: * Gets all users
081: *
082: * @return <code>ArrayList</code> with the users. Each entry is an <code>User</code> object
083: */
084: public List selectAll();
085:
086: /**
087: * Gets all users with your Karma.
088: *
089: * @return <code>List</code> with the users. Each entry is an <code>User</code> object
090: * (with the KarmaStatus populated).
091: */
092: public List selectAllWithKarma();
093:
094: /**
095: * Gets all users from a specific group.
096: *
097: * @param groupId The group id
098: * @param start The index position to start fetching
099: * @param count The total number of records to fetch
100: * @return <code>List</code> with the users. Each entry is an <code>User</code> object
101: */
102: public List selectAllByGroup(int groupId, int start, int count);
103:
104: /**
105: * Gets all users
106: *
107: * @param startFrom Index to start fetching from
108: * @param count Number of records to retrieve
109: * @return <code>ArrayList</code> with the users. Each entry is an <code>User</code> object
110: * (with the KarmaStatus populated).
111: */
112: public List selectAllWithKarma(int startFrom, int count);
113:
114: /**
115: * Finds an user by matching an input string.
116: *
117: * @param input The username to search. May be part of the username.
118: * The method will match all users who have the input string as
119: * part of their usernames.
120: * @param exactMath Set to <code>true</code> to get the user data related to
121: * the username passed as argument, and set it to <code>false</code> to
122: * search all users who match the criteria.
123: * @return <code>List</code> with the found users. Each entry is an
124: * <code>User</code> object, where only the <i>id</i> and <i>username</i>
125: * members are filled.
126: */
127: public List findByName(String input, boolean exactMath);
128:
129: /**
130: * Gets all users
131: *
132: * @param startFrom Index to start fetching from
133: * @param count Number of records to retrieve
134: * @return <code>ArrayList</code> with the users. Each entry is an <code>User</code> object
135: */
136: public List selectAll(int startFrom, int count);
137:
138: /**
139: * Deletes an user.
140: *
141: * @param userId The user ID to delete
142: * @see #undelete(int)
143: */
144: public void delete(int userId);
145:
146: /**
147: * Undeletes an user.
148: * The system allows user undeletation because when you
149: * call {@link #delete(int)} the user isn't fisically deleted of the
150: * database, but just marked as deleted. This is done to ensure
151: * data integrity.
152: *
153: * @param userId The user ID to undelete
154: * @see #delete(int)
155: */
156: public void undelete(int userId);
157:
158: /**
159: * Updates a user.
160: *
161: * @param user Reference to a <code>User</code> object to update
162: */
163: public void update(User user);
164:
165: /**
166: * Adds a new User.
167: * After successfuly persisting the data, this method
168: * <b>shoud</b> call <code>user.setId(theNewId);</code>, as well
169: * return the new user id.
170: * @param user Reference to a valid and configured <code>User</code> object
171: * @return The new user id
172: */
173: public int addNew(User user);
174:
175: /**
176: * Adds a new user with a predefined user id
177: *
178: * (added by Pieter for external login support)
179: * @param user Reference to a valid and configured <code>User</code> object, with the user id already set
180: */
181: public void addNewWithId(User user);
182:
183: /**
184: * Set the active status.
185: * An user with the active status equals to false cannot be considered
186: * a "oficial", "fully registered" user until its status is set to true. This is
187: * interesting when you want to request user confirmation about registrations,
188: * for example
189: *
190: * @param userId The user ID to change the status
191: * @param active <code>true</code> or <code>false</code>
192: */
193: public void setActive(int userId, boolean active);
194:
195: /**
196: * Sets the ranking.
197: *
198: * @param userId The user ID
199: * @param rankingId int
200: */
201: public void setRanking(int userId, int rankingId);
202:
203: /**
204: * Increments the number of posts of the user.
205: *
206: * @param userId The user ID to increment the number of posts
207: */
208: public void incrementPosts(int userId);
209:
210: /**
211: * Decrement the number of posts of some user.
212: *
213: * @param userId The user ID do decrement the number of posts.
214: */
215: public void decrementPosts(int userId);
216:
217: /**
218: * Gest some piece of information of the last user registered
219: *
220: * @return <code>HashMap</code> containing the information. The map
221: * has two keys:<br>
222: * <li><b>userName</b>: The username
223: * <li><b>userId</b>: The user's ID
224: */
225: public User getLastUserInfo();
226:
227: /**
228: * Gets the total number of users
229: *
230: * @return The total number of users
231: */
232: public int getTotalUsers();
233:
234: /**
235: * Gets the total number of users of some group.
236: *
237: * @param groupId The group id
238: * @return The total number of users
239: */
240: public int getTotalUsersByGroup(int groupId);
241:
242: /**
243: * whether the user is locked or not.
244: *
245: * @param user_id int
246: * @return boolean
247: */
248: public boolean isDeleted(int user_id);
249:
250: /***
251: * Checks the existence of some username.
252: * This method is used to ensure that will not be two equal usernames in the database.
253: *
254: * @param username The username to verify
255: * @return <code>true</code> or <code>false</code>, if the user was found or not, respectively
256: */
257: public boolean isUsernameRegistered(String username);
258:
259: /**
260: * Validates the user login.
261: *
262: * @param username The username
263: * @param password The password
264: * @return The user object if the provided information was corret, <code>null</code> if the information was invalid
265: */
266: public User validateLogin(String username, String password);
267:
268: /**
269: * Associate the user to the group
270: *
271: * @param userId The user id
272: * @param groupId The group id to associate to
273: */
274: public void addToGroup(int userId, int[] groupId);
275:
276: /**
277: * Remove the user from the group
278: *
279: * @param userId The user id
280: * @param groupId The group id to remove the user from
281: */
282: public void removeFromGroup(int userId, int[] groupId);
283:
284: /**
285: * Stores the "lost password" security hash, that was generated
286: * when the user asked the system to get a reminder of his password.
287: * This hash is used to ensure the information supplied.
288: *
289: * @param email The user email
290: * @param hash The hash to store.
291: */
292: public void writeLostPasswordHash(String email, String hash);
293:
294: /**
295: * Validate the provided security hash against the data stored in our system.
296: *
297: * @param email The user email
298: * @param hash The supplied security hash
299: * @return <code>true</code> if the data matches ok, of <code>false</code> if it is invalid
300: */
301: public boolean validateLostPasswordHash(String email, String hash);
302:
303: /**
304: * Writes a new password for the user.
305: *
306: * @param password The new password
307: * @param email The user email
308: */
309: public void saveNewPassword(String password, String email);
310:
311: /**
312: * Gets the username related to the email
313: *
314: * @param email The email to search for the username
315: * @return The username, if found, or an empty <code>String</code>
316: */
317: public String getUsernameByEmail(String email);
318:
319: /**
320: * Validate if the activated key matches the one in the database
321: *
322: * @param userId Which user to validate the activation key?
323: * @param hash The activation key
324: * @return <code>true</code> if the data matches ok, of <code>false</code> if it is invalid
325: */
326: public boolean validateActivationKeyHash(int userId, String hash);
327:
328: /**
329: * Set user account to active
330: *
331: * @param userId Which user account to set active?
332: */
333: public void writeUserActive(int userId);
334:
335: /**
336: * Updates only the username.
337: * This method generally will be used in implementations
338: * of <code>net.jforum.drivers.external.LoginAuthenticator</code> to
339: * update usernames which changed in the external source and therefore
340: * should be updated in jforum's users table.
341: *
342: * @param userId The user's id related to the username to update
343: * @param username The new username to write
344: */
345: public void updateUsername(int userId, String username);
346:
347: /**
348: * Check if the username passed as argument is different of
349: * the username existent in the database.
350: *
351: * @param userId The user's id to work with
352: * @param usernameToCheck The username to compare with the existing
353: * one in <i>jforum_users</i>
354: * @return <code>true</code> if the usernames are different.
355: */
356: public boolean hasUsernameChanged(int userId, String usernameToCheck);
357:
358: /**
359: * Saves the user-specific security hash to the database
360: * @param userId the user id to save
361: * @param hash the security hash
362: */
363: public void saveUserAuthHash(int userId, String hash);
364:
365: /**
366: * Retrieves the auth hash from the database
367: * @param userId intt
368: * @return String
369: */
370: public String getUserAuthHash(int userId);
371:
372: /**
373: * Returns a list of users that haven't yet activated their accounts
374: * @return
375: */
376: public List pendingActivations();
377:
378: /**
379: * Finds a user by its email address
380: * @param email the email address to search
381: * @return the user instance if a match is found, or null otherwise
382: */
383: public User findByEmail(String email);
384: }
|