View Javadoc

1   package org.apache.turbine.om.security;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.io.Serializable;
20  
21  import java.util.Hashtable;
22  
23  import javax.servlet.http.HttpSessionBindingListener;
24  
25  /***
26   * This interface represents functionality that all users of the
27   * Turbine system require.
28   *
29   * @author <a href="mailto:frank.kim@clearink.com">Frank Y. Kim</a>
30   * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
31   * @author <a href="mailto:jon@collab.net">Jon S. Stevens</a>
32   * @author <a href="mailto:cberry@gluecode.com">Craig D. Berry</a>
33   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
34   * @version $Id: User.java 264148 2005-08-29 14:21:04Z henning $
35   */
36  public interface User
37      extends HttpSessionBindingListener, Serializable, SecurityEntity
38  {
39      /*** The 'perm storage' key name for the first name. */
40      String FIRST_NAME = "FIRST_NAME";
41  
42      /*** The 'perm storage' key name for the last name. */
43      String LAST_NAME = "LAST_NAME";
44  
45      /*** The 'perm storage' key name for the last_login field. */
46      String LAST_LOGIN = "LAST_LOGIN";
47  
48      /*** The 'perm storage' key name for the password field. */
49      String PASSWORD = "PASSWORD_VALUE";
50  
51      /*** The 'perm storage' key name for the username field. */
52      String USERNAME = "LOGIN_NAME";
53  
54      /*** The 'perm storage' key for the confirm_value field. */
55      String CONFIRM_VALUE = "CONFIRM_VALUE";
56  
57      /*** The 'perm storage' key for the email field. */
58      String EMAIL = "EMAIL";
59  
60      /*** This is the value that is stored in the database for confirmed users */
61      String CONFIRM_DATA = "CONFIRMED";
62  
63      /*** The 'perm storage' key name for the access counter. */
64      String ACCESS_COUNTER = "_access_counter";
65  
66      /*** The 'temp storage' key name for the session access counter */
67      String SESSION_ACCESS_COUNTER = "_session_access_counter";
68  
69      /*** The 'temp storage' key name for the 'has logged in' flag */
70      String HAS_LOGGED_IN = "_has_logged_in";
71  
72      /*** The session key for the User object. */
73      String SESSION_KEY = "turbine.user";
74  
75      /***
76       * Gets the access counter for a user from perm storage.
77       *
78       * @return The access counter for the user.
79       */
80      int getAccessCounter();
81  
82      /***
83       * Gets the access counter for a user during a session.
84       *
85       * @return The access counter for the user for the session.
86       */
87      int getAccessCounterForSession();
88  
89      /***
90       * Gets the last access date for this User. This is the last time
91       * that the user object was referenced.
92       *
93       * @return A Java Date with the last access date for the user.
94       */
95      java.util.Date getLastAccessDate();
96  
97      /***
98       * Gets the create date for this User.  This is the time at which
99       * the user object was created.
100      *
101      * @return A Java Date with the date of creation for the user.
102      */
103     java.util.Date getCreateDate();
104 
105     /***
106      * Returns the user's last login date.
107      *
108      * @return A Java Date with the last login date for the user.
109      */
110     java.util.Date getLastLogin();
111 
112     /***
113      * Returns the user's password. This method should not be used by
114      * the application directly, because it's meaning depends upon
115      * the implementation of UserManager that manages this particular
116      * user object. Some implementations will use this attribute for
117      * storing a password encrypted in some way, other will not use
118      * it at all, when user entered password is presented to some external
119      * authority (like NT domain controller) to validate it.
120      * See also {@link org.apache.turbine.services.security.UserManager#authenticate(User,String)}.
121      *
122      * @return A String with the password for the user.
123      */
124     String getPassword();
125 
126     /***
127      * Get an object from permanent storage.
128      *
129      * @param name The object's name.
130      * @return An Object with the given name.
131      */
132     Object getPerm(String name);
133 
134     /***
135      * Get an object from permanent storage; return default if value
136      * is null.
137      *
138      * @param name The object's name.
139      * @param def A default value to return.
140      * @return An Object with the given name.
141      */
142     Object getPerm(String name, Object def);
143 
144     /***
145      * This should only be used in the case where we want to save the
146      * data to the database.
147      *
148      * @return A Hashtable.
149      */
150     Hashtable getPermStorage();
151 
152     /***
153      * This should only be used in the case where we want to save the
154      * data to the database.
155      *
156      * @return A Hashtable.
157      */
158     Hashtable getTempStorage();
159 
160     /***
161      * Get an object from temporary storage.
162      *
163      * @param name The object's name.
164      * @return An Object with the given name.
165      */
166     Object getTemp(String name);
167 
168     /***
169      * Get an object from temporary storage; return default if value
170      * is null.
171      *
172      * @param name The object's name.
173      * @param def A default value to return.
174      * @return An Object with the given name.
175      */
176     Object getTemp(String name, Object def);
177 
178     /***
179      * Returns the username for this user.
180      *
181      * @return A String with the username.
182      *
183      * @deprecated This is the same as getName(), so use this.
184      */
185     String getUserName();
186 
187     /***
188      * Returns the first name for this user.
189      *
190      * @return A String with the user's first name.
191      */
192 
193     String getFirstName();
194 
195     /***
196      * Returns the last name for this user.
197      *
198      * @return A String with the user's last name.
199      */
200     String getLastName();
201 
202     /***
203      * Returns the email address for this user.
204      *
205      * @return A String with the user's email address.
206      */
207     String getEmail();
208 
209     /***
210      * This sets whether or not someone has logged in.  hasLoggedIn()
211      * returns this value.
212      *
213      * @param value Whether someone has logged in or not.
214      */
215     void setHasLoggedIn(Boolean value);
216 
217     /***
218      * The user is considered logged in if they have not timed out.
219      *
220      * @return True if the user has logged in.
221      */
222     boolean hasLoggedIn();
223 
224     /***
225      * Increments the permanent hit counter for the user.
226      */
227     void incrementAccessCounter();
228 
229     /***
230      * Increments the session hit counter for the user.
231      */
232     void incrementAccessCounterForSession();
233 
234     /***
235      * Remove an object from temporary storage and return the object.
236      *
237      * @param name The name of the object to remove.
238      * @return An Object.
239      */
240     Object removeTemp(String name);
241 
242     /***
243      * Sets the access counter for a user, saved in perm storage.
244      *
245      * @param cnt The new count.
246      */
247     void setAccessCounter(int cnt);
248 
249     /***
250      * Sets the session access counter for a user, saved in temp
251      * storage.
252      *
253      * @param cnt The new count.
254      */
255     void setAccessCounterForSession(int cnt);
256 
257     /***
258      * Sets the last access date for this User. This is the last time
259      * that the user object was referenced.
260      */
261     void setLastAccessDate();
262 
263     /***
264      * Set last login date/time.
265      *
266      * @param lastLogin The last login date.
267      */
268     void setLastLogin(java.util.Date lastLogin);
269 
270     /***
271      * Set password. Application should not use this method
272      * directly, see {@link #getPassword()}.
273      * See also {@link org.apache.turbine.services.security.UserManager#changePassword(User,String,String)}.
274      *
275      * @param password The new password.
276      */
277 
278     void setPassword(String password);
279 
280     /***
281      * Put an object into permanent storage.
282      *
283      * @param name The object's name.
284      * @param value The object.
285      */
286     void setPerm(String name,
287                  Object value);
288 
289     /***
290      * This should only be used in the case where we want to save the
291      * data to the database.
292      *
293      * @param storage A Hashtable.
294      */
295     void setPermStorage(Hashtable storage);
296 
297     /***
298      * This should only be used in the case where we want to save the
299      * data to the database.
300      *
301      * @param storage A Hashtable.
302      */
303     void setTempStorage(Hashtable storage);
304 
305     /***
306      * Put an object into temporary storage.
307      *
308      * @param name The object's name.
309      * @param value The object.
310      */
311     void setTemp(String name, Object value);
312 
313     /***
314      * Sets the username for this user.
315      *
316      * @param username The user's username.
317      *
318      * @deprecated This is the same as setName(), so use this.
319      */
320     void setUserName(String username);
321 
322     /***
323      * Sets the first name for this user.
324      *
325      * @param firstName User's first name.
326      */
327     void setFirstName(String firstName);
328 
329     /***
330      * Sets the last name for this user.
331      *
332      * @param lastName User's last name.
333      */
334     void setLastName(String lastName);
335 
336     /***
337      * Sets the creation date for this user.
338      *
339      * @param date Creation date
340      */
341     void setCreateDate(java.util.Date date);
342 
343     /***
344      * Sets the email address.
345      *
346      * @param address The email address.
347      */
348     void setEmail(String address);
349 
350     /***
351      * This method reports whether or not the user has been confirmed
352      * in the system by checking the TurbineUserPeer.CONFIRM_VALUE
353      * column to see if it is equal to CONFIRM_DATA.
354      *
355      * @return True if the user has been confirmed.
356      */
357     boolean isConfirmed();
358 
359     /***
360      * Sets the confirmation value.
361      *
362      * @param value The confirmation key value.
363      */
364     void setConfirmed(String value);
365 
366     /***
367      * Gets the confirmation value.
368      *
369      * @return The confirmed value
370      */
371     String getConfirmed();
372 
373     /***
374      * Updates the last login date in the database.
375      *
376      * @exception Exception A generic exception.
377      */
378     void updateLastLogin()
379         throws Exception;
380 }