View Javadoc

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