KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > Yasna > forum > User


1 /**
2  * Copyright (C) 2001 Yasna.com. All rights reserved.
3  *
4  * ===================================================================
5  * The Apache Software License, Version 1.1
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  *
14  * 2. Redistributions in binary form must reproduce the above copyright
15  * notice, this list of conditions and the following disclaimer in
16  * the documentation and/or other materials provided with the
17  * distribution.
18  *
19  * 3. The end-user documentation included with the redistribution,
20  * if any, must include the following acknowledgment:
21  * "This product includes software developed by
22  * Yasna.com (http://www.yasna.com)."
23  * Alternately, this acknowledgment may appear in the software itself,
24  * if and wherever such third-party acknowledgments normally appear.
25  *
26  * 4. The names "Yazd" and "Yasna.com" must not be used to
27  * endorse or promote products derived from this software without
28  * prior written permission. For written permission, please
29  * contact yazd@yasna.com.
30  *
31  * 5. Products derived from this software may not be called "Yazd",
32  * nor may "Yazd" appear in their name, without prior written
33  * permission of Yasna.com.
34  *
35  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38  * DISCLAIMED. IN NO EVENT SHALL YASNA.COM OR
39  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46  * SUCH DAMAGE.
47  * ====================================================================
48  *
49  * This software consists of voluntary contributions made by many
50  * individuals on behalf of Yasna.com. For more information
51  * on Yasna.com, please see <http://www.yasna.com>.
52  */

53
54 /**
55  * Copyright (C) 2000 CoolServlets.com. All rights reserved.
56  *
57  * ===================================================================
58  * The Apache Software License, Version 1.1
59  *
60  * Redistribution and use in source and binary forms, with or without
61  * modification, are permitted provided that the following conditions
62  * are met:
63  *
64  * 1. Redistributions of source code must retain the above copyright
65  * notice, this list of conditions and the following disclaimer.
66  *
67  * 2. Redistributions in binary form must reproduce the above copyright
68  * notice, this list of conditions and the following disclaimer in
69  * the documentation and/or other materials provided with the
70  * distribution.
71  *
72  * 3. The end-user documentation included with the redistribution,
73  * if any, must include the following acknowledgment:
74  * "This product includes software developed by
75  * CoolServlets.com (http://www.coolservlets.com)."
76  * Alternately, this acknowledgment may appear in the software itself,
77  * if and wherever such third-party acknowledgments normally appear.
78  *
79  * 4. The names "Jive" and "CoolServlets.com" must not be used to
80  * endorse or promote products derived from this software without
81  * prior written permission. For written permission, please
82  * contact webmaster@coolservlets.com.
83  *
84  * 5. Products derived from this software may not be called "Jive",
85  * nor may "Jive" appear in their name, without prior written
86  * permission of CoolServlets.com.
87  *
88  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
89  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
90  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
91  * DISCLAIMED. IN NO EVENT SHALL COOLSERVLETS.COM OR
92  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
93  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
94  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
95  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
96  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
97  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
98  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
99  * SUCH DAMAGE.
100  * ====================================================================
101  *
102  * This software consists of voluntary contributions made by many
103  * individuals on behalf of CoolServlets.com. For more information
104  * on CoolServlets.com, please see <http://www.coolservlets.com>.
105  */

106
107 package com.Yasna.forum;
108
109 import java.util.*;
110
111 /**
112  * The User interface provides information about and services for users
113  * of the forum system. Users can be identified by a unique id or username.
114  * Users can also be organized into Groups for easier management of
115  * permissions at the forum level.
116  * <p>
117  * The name and email field will normally be required fields when creating
118  * user accounts for most implementations of forums. However, some users may
119  * wish to keep that information private. Therefore, there are two flags to
120  * set if the name and email fields should be made visible to other users. If
121  * the flags are set to deny access, getName() and getEmail() will throw
122  * UnauthorizedExceptions to users that don't have ADMIN permissions.
123  * <p>
124  * Security for User objects is provide by UserProxy protection proxy objects.
125  *
126  * @see Group
127  */

128 public interface User {
129
130     /**
131      * Returns the user's id. All ids must be unique in the system.
132      *
133      * @return the user's id.
134      */

135     public int getID();
136
137     /**
138      * Returns true if the User object is an anonymous user object.
139      *
140      * @return true if the user is anonymous.
141      */

142     public boolean isAnonymous();
143
144     /**
145      * Returns the user's username. All usernames must be unique in the system.
146      *
147      * @return the username of the user.
148      */

149     public String JavaDoc getUsername();
150
151     /**
152      * Returns the user's name. The user's name does not have to be to be
153      * unique in the system. Some users may opt to not let others see their
154      * name for privacy reasons. In that case, the user can set nameVisible to
155      * false. In that case, a call to this method will return null.
156      *
157      * @return the name of the user.
158      */

159     public String JavaDoc getName();
160
161     /**
162      * Sets the user's name. The user's name does not have to be to be
163      * unique in the system.
164      *
165      * @param name new name for the user.
166      * @throws UnauthorizedException if does not have ADMIN permissions.
167      */

168     public void setName(String JavaDoc name) throws UnauthorizedException;
169
170     /**
171      * Returns true if the user has chosen to make her name visible to other
172      * users. If the name is not visible, calling getName() will throw an
173      * UnauthorizedException.
174      *
175      * @return true if the name is visible to other users.
176      */

177     public boolean isNameVisible();
178
179     /**
180      * Sets whether a user's name is visible to other users. If the field
181      * is set to not be visible, calling getName() will throw an
182      * UnauthorizedException.
183      *
184      * @param visible boolean value to determin if the name should be visible.
185      * @throws UnauthorizedException if does not have ADMIN permissions.
186      */

187     public void setNameVisible(boolean visible) throws UnauthorizedException;
188
189     /**
190      * Sets the users's password. The password should be passed in as
191      * plain text. The way the password is stored is implementation dependent.
192      * However, it is recommended to at least hash passwords with an
193      * algorithm such as MD5.
194      *
195      * @param password new password for the user.
196      * @throws UnauthorizedException if does not have ADMIN permissions.
197      */

198     public void setPassword(String JavaDoc password) throws UnauthorizedException;
199
200     /**
201      * Returns the user's password in hashed form. This method is only intended
202      * for system administration functions and can be ignored by skin writers.
203      *
204      * @return the hashed password.
205      * @throws UnauthorizedException if does not have ADMIN permissions.
206      */

207     public String JavaDoc getPasswordHash() throws UnauthorizedException;
208
209     /**
210      * Sets the user's password in hashed form. This method is only intended
211      * for system administration functions and can be ignored by skin writers.
212      *
213      * @param passwordHash the hashedPassword for the user.
214      * @throws UnauthorizedException if does not have ADMIN permissions.
215      */

216     public void setPasswordHash(String JavaDoc passwordHash) throws UnauthorizedException;
217
218     /**
219      * Reset's a user's password. This is useful if a user forgets their
220      * password since many implementations will not be able retrieve a
221      * hashed password. The normal side effect of calling this method is
222      * that the new password is emailed to the user using the email address
223      * listed in the account. However, this method could be abused by another
224      * user if they were able to continually reset another users's password.
225      * <p>
226      * A recommendation for implementation of a password resetting system:
227      * provide a form where users can request a password reset because they've
228      * forgotten their password. Making this request sends an email to the
229      * email account listed for the user. That email should include a web
230      * address with a random string for security. If the user visits that
231      * address within 24 hours, the password is reset with a random string
232      * and emailed to the user. If the web page is never visited, the password
233      * is not reset. This method provides good security and prevents abuse
234      * of the password resetting system. This functionality would probably
235      * be incorporated into a forum skin.
236      */

237     //NOTE: This feature will be delayed until after Yazd 1.0
238
//public void resetPassword();
239

240     /**
241      * Returns the user's email address. Email should be considered to be
242      * a required field of a user account since it is critical to many
243      * user operations performing. If the user sets emailVisible to false,
244      * this method will always return null.
245      *
246      * @return the email address of the user.
247      */

248     public String JavaDoc getEmail();
249     /**
250      * Returns the user's last login date. This date is updated in the DbAuthorizationFactory
251      * after the user successfully is validated.
252      *
253      * @return the last date that user successfully logged in
254      */

255     public Calendar getLastLogin();
256     /**
257      * Returns the date that the user posted his last message.
258      *
259      * @return the last date that user posted his last message
260      */

261     public Calendar getLastPost();
262    /**
263     * Returns the user's preferred locale. This would drive how the Yazd forum would display the buttons
264     * and in which language.
265     * @return
266     */

267     public Locale getUserLocale();
268     /**
269      * This would set the user's perferred locale.
270      * @param locale
271      * @throws UnauthorizedException
272      */

273     public void setUserLocale(Locale locale) throws UnauthorizedException;
274
275     /**
276     * Returns the user's Time Zone. This would drive how the Yazd forum would display the dates
277     * and in which language. If there is no time zone set by the user, it returns
278     * the default time zone.
279     * @return TimeZone
280     */

281
282     public TimeZone getUserTimeZone();
283
284     /**
285      * This would set the user's perferred Time Zone.
286      * @param timezoneid
287      * @throws UnauthorizedException
288      */

289     public void setUserTimeZone(String JavaDoc timezoneid) throws UnauthorizedException;
290     /**
291      * Sets the user's email address. Email should be considered to be
292      * a required field of a user account since it is critical to many
293      * user operations performing.
294      *
295      * @param email new email address for the user.
296      * @throws UnauthorizedException if does not have ADMIN permissions.
297      */

298     public void setEmail(String JavaDoc email) throws UnauthorizedException;
299
300
301     /**
302      * Shows if user wants to subscribe to the threads he posts messages in.
303      *
304      * @return true if user wants to receive mail on reply.
305      */

306     public boolean getThreadSubscribe();
307
308     /**
309      * Boolean value to determin if user wants to
310      * subscribe to the threads that he posts messages in.
311      *
312      * @param emailReply boolean value to determin if user wants to
313      * receive email when a reply on his/her message occur.
314      * @throws UnauthorizedException if does not have ADMIN permissions.
315      */

316     public void setThreadSubscribe(boolean emailReply) throws UnauthorizedException;
317
318     /**
319      * Returns true if the user has chosen to make her email visible to other
320      * users. If the email field is not visible, calling getEmail() will throw
321      * an UnauthorizedException.
322      *
323      * @return true if the name is visible to other users.
324      */

325     public boolean isEmailVisible();
326
327     /**
328      * Sets whether a user's email is visible to other users. If the field
329      * is set to not be visible, calling getEmail() will throw an
330      * UnauthorizedException.
331      *
332      * @param visible boolean value to determin if the name should be visible.
333      * @throws UnauthorizedException if does not have ADMIN permissions.
334      */

335     public void setEmailVisible(boolean visible) throws UnauthorizedException;
336
337     /**
338      * Returns an extended property of the user. Each user can have an
339      * arbitrary number of extended properties. This lets particular skins
340      * or filters provide enhanced functionality that is not part of the base
341      * interface.
342      *
343      * @param name the name of the property to get.
344      * @return the value of the property
345      */

346     public String JavaDoc getProperty(String JavaDoc name);
347
348     /**
349      * Returns an Enumeration of all the names of the extended user properties.
350      *
351      * @return an Enumeration of the property names.
352      */

353     public Enumeration propertyNames();
354
355     /**
356      * Sets an extended property of the user. Each user can have an
357      * arbitrary number of extended properties. This lets particular skins
358      * or filters provide enhanced functionality that is not part of the base
359      * interface.
360      *
361      * @param name the name of the property to set.
362      * @param value the new value for the property.
363      */

364     public void setProperty(String JavaDoc name, String JavaDoc value);
365
366     /**
367      * Returns the permissions for the user that correspond to the
368      * passed-in Authorization.
369      *
370      * @param authorization the auth token to look up permissions with.
371      */

372     public abstract ForumPermissions getPermissions(Authorization authorization);
373
374     /**
375      * Returns true if the handle on the object has the permission specified.
376      * A list of possible permissions can be found in the ForumPermissions
377      * class. Certain methods of this class are restricted to certain
378      * permissions as specified in the method comments.
379      *
380      * @see ForumPermissions
381      */

382     public boolean hasPermission(int type);
383 }
384
Popular Tags