001 /*
002 Licensed to the Apache Software Foundation (ASF) under one
003 or more contributor license agreements. See the NOTICE file
004 distributed with this work for additional information
005 regarding copyright ownership. The ASF licenses this file
006 to you under the Apache License, Version 2.0 (the
007 "License"); you may not use this file except in compliance
008 with the License. You may obtain a copy of the License at
009
010 http://www.apache.org/licenses/LICENSE-2.0
011
012 Unless required by applicable law or agreed to in writing,
013 software distributed under the License is distributed on an
014 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 KIND, either express or implied. See the License for the
016 specific language governing permissions and limitations
017 under the License.
018 */
019 package org.apache.wiki.auth.user;
020
021 import java.io.Serializable;
022 import java.util.Date;
023 import java.util.Map;
024
025 /**
026 * Class for representing wiki user information, such as the login name, full
027 * name, wiki name, and e-mail address. Note that since 2.6 the wiki name is
028 * required to be automatically computed from the full name.
029 * As of 2.8, user profiles can store custom key/value String/Serializable attributes, and store
030 * a unique ID. Locks are checked by {@link org.apache.wiki.auth.AuthenticationManager};
031 * if a profile is locked, the user cannot log with that profile.
032 * @since 2.3
033 */
034 public interface UserProfile extends Serializable
035 {
036
037 /**
038 * Returns the attributes associated with this profile as a Map of key/value pairs.
039 * The Map should generally be a "live" Map; changes to the keys or values will be reflected
040 * in the UserProfile.
041 * @return the attributes
042 */
043 Map<String,Serializable> getAttributes();
044
045 /**
046 * Returns the creation date.
047 * @return the creation date
048 */
049 Date getCreated();
050
051 /**
052 * Returns the user's e-mail address.
053 * @return the e-mail address
054 */
055 String getEmail();
056
057 /**
058 * Returns the user's full name.
059 * @return the full name
060 */
061 String getFullname();
062
063 /**
064 * Returns the last-modified date.
065 * @return the date and time of last modification
066 */
067 Date getLastModified();
068
069 /**
070 * Returns the date/time of expiration of the profile's lock, if it has been
071 * previously locked via {@link #setLockExpiry(Date)} and the lock is
072 * still active. If the profile is unlocked, this method returns <code>null</code>.
073 * Note that calling this method after the expiration date, <em>even if had previously
074 * been set explicitly by {@link #setLockExpiry(Date)}</em>, will always return
075 * <code>null</null>.
076 *
077 * @return the lock expiration date
078 */
079 Date getLockExpiry();
080
081 /**
082 * Returns the user's login name.
083 * @return the login name
084 */
085 String getLoginName();
086
087 /**
088 * Returns the user password for use with custom authentication. Note that
089 * the password field is not meaningful for container authentication; the
090 * user's private credentials are generally stored elsewhere. While it
091 * depends on the {@link UserDatabase}implementation, in most cases the
092 * value returned by this method will be a password hash, not the password
093 * itself.
094 * @return the password
095 */
096 String getPassword();
097
098 /**
099 * Returns the unique identifier for the user profile. If not previously
100 * set, the value will be <code>null</code>.
101 * @return the unique ID.
102 */
103 String getUid();
104
105 /**
106 * Returns the user's wiki name, based on the full name with all
107 * whitespace removed.
108 * @return the wiki name.
109 */
110 String getWikiName();
111
112 /**
113 * Returns
114 * <code>true</code> if the profile is currently locked (disabled); <code>false</code> otherwise.
115 * By default, profiles are created unlocked. Strictly speaking, calling this method is equivalent to calling {@link #getLockExpiry()}
116 * and, if it returns a non-<code>null</code> value, checking if the date returned is later than the current time.
117 * @return the result
118 */
119 boolean isLocked();
120
121 /**
122 * Returns <code>true</code> if the profile has never been
123 * saved before. Implementing classes might check the
124 * last modified date, for example, to determine this.
125 * @return whether the profile is new
126 */
127 boolean isNew();
128
129 /**
130 * Sets the created date.
131 * @param date the creation date
132 */
133 void setCreated( Date date );
134
135 /**
136 * Sets the user's e-mail address.
137 * @param email the e-mail address
138 */
139 void setEmail( String email );
140
141 /**
142 * Sets the user's full name. For example, "Janne Jalkanen."
143 * @param arg the full name
144 */
145 void setFullname( String arg );
146
147 /**
148 * Sets the last-modified date
149 * @param date the last-modified date
150 */
151 void setLastModified( Date date );
152
153 /**
154 * Locks the profile until a specified lock expiration date.
155 *
156 * @param expiry the date the lock expires; setting this value to <code>null</code>
157 * will cause the lock to be cleared.
158 */
159 void setLockExpiry( Date expiry );
160
161 /**
162 * Sets the name by which the user logs in. The login name is used as the
163 * username for custom authentication (see
164 * {@link org.apache.wiki.auth.AuthenticationManager#login(WikiSession,HttpServletRequest, String, String)},
165 * {@link org.apache.wiki.auth.login.UserDatabaseLoginModule}). The login
166 * name is typically a short name ("jannej"). In contrast, the wiki name is
167 * typically of type FirstnameLastName ("JanneJalkanen").
168 * @param name the login name
169 */
170 void setLoginName( String name );
171
172 /**
173 * Sets the user's password for use with custom authentication. It is
174 * <em>not</em> the responsibility of implementing classes to hash the
175 * password; that responsibility is borne by the UserDatabase implementation
176 * during save operations (see {@link UserDatabase#save(UserProfile)}).
177 * Note that the password field is not meaningful for container
178 * authentication; the user's private credentials are generally stored
179 * elsewhere.
180 * @param arg the password
181 */
182 void setPassword( String arg );
183
184 /**
185 * Sets the unique identifier for the user profile. Note that UserDatabase implementations
186 * are required <em>not</em> to change the unique identifier after the initial save.
187 * @param uid the unique identifier to set
188 */
189 void setUid( String uid );
190
191 /**
192 * No-op method. In previous versions of JSPWiki, the method
193 * set the user's wiki name directly. Now, the wiki name is automatically
194 * calculated based on the full name.
195 * @param name the wiki name
196 * @deprecated This method will be removed in a future release.
197 */
198 void setWikiName( String name );
199
200 /**
201 * Returns a string representation of this user profile.
202 * @return the string
203 */
204 String toString();
205 }