The ProfileForm
class has a set of submit handler methods for working with profiles. Each of these methods performs a specific form handling task, such as logging in a user. When a handler performs its task, it can perform several additional actions, including preprocessing and post-processing steps, and redirecting the user to the appropriate page depending on whether or not it encountered errors.
The following table summarizes the main handler methods of the ProfileForm
class. Each of these methods is then explained in greater detail.
Method | Function |
---|---|
| Creates a new permanent profile and sets the profile attributes to the values entered in the form. |
| Modifies the attributes of the current profile. |
| Uses the |
| Changes the password attribute of the profile to the new value entered by the user. |
| Resets the profile to a new anonymous profile and optionally expires the current session. |
handleCreate
The handleCreate
method calls three other methods that you can override to add to or modify the default functionality. The preCreateUser
and postCreateUser
methods are protected methods with no functionality. They exist as stubs for subclasses to insert application logic before and after a persistent user is registered in the profile repository. After the preCreateUser
method is called, the handler invokes the checkFormError
method. This checks for errors in the form and stops processing if it finds any. The createUser
method takes all the form values submitted by the user and attempts to register the user.
The first step in registering a user is verifying that the user has supplied all the required form parameters. By default, the only required form parameter is the confirmation password parameter. The checkForRequiredParameters
method is invoked if the ProfileForm
component’s checkForRequiredParameters
property is set to true
. In addition, if the ProfileForm
component’s confirmPassword
property is set to true
, the handler requires the user to submit the form with an additional parameter that is not part of the profile definition. This parameter is the confirmation password parameter, which is used to verify the password profile attribute value supplied.
After this first pass for verification, the system checks to see if a user already exists with the given login name, and then uses the createProfileItem
method to construct a MutableRepositoryItem
that represents the new user. At this point, the user’s profile exists as an object, but is not yet stored in the database.
After the MutableRepositoryItem
is created, it is updated to contain all the attributes the user supplies. Next, if the ProfileForm
component’s checkForRequiredProperties
property is set to true
, the form calls the checkForRequiredProperties
method to see if any of the profile attributes are required. If any profile attributes are required, it checks whether the value of any of the required profile attributes is null.
Finally, the createUser
method transforms the RAM-based profile into a persistent profile stored in the profile database by invoking the addUser
method. After the createUser
method is finished, the handleCreate
method takes the new persistent MutableRepositoryItem
and updates the form handler to use that as the current profile. At this point, the session-scoped Profile
object’s dataSource
property is updated so that it also references the new persistent user data structure. As a final step, the postCreateUser
method is called, by which time the user will be a fully registered member. As noted above, the postCreateUser
does not do anything; it exists as a stub that you can override if you subclass ProfileForm
.
handleLogin
The handleLogin
method is similar to the handleCreate
method. It, too, provides three significant methods that you can override: preLoginUser
, findUser
and postLoginUser
. For each of the handleX
methods, the preprocessing and post-processing methods have no implementation. They are stubs that you can override in subclasses. The findUser
method is called after the preLoginUser
method. It attempts to locate the correct user based on the login and password information that the user supplies, invoking the /atg/dynamo/security/IdentityManager
to perform the verification of the login. If a user is not found with a matching login name and password, the method then attempts to find a user based on only the login name. If this process finds a user, then it is evident that the password supplied was invalid and the form indicates that in an appropriate form exception. If no user is found with a matching login, then the form indicates that the login name supplied was incorrect.
You can specify that certain properties should be copied upon login from the anonymous profile to the registered user’s account. This is useful if anonymous site visitors accumulate profile information that you do not want to lose when they log in. The method copyPropertiesOnLogin
implements this functionality. Specify which profile attributes you want copied to the persistent profile with the propertiesToCopyOnLogin
property of the ProfileForm
component.
After the user has been identified by login and password and any desired properties are copied, the data structures for the form handler and session-scoped Profile
object are updated to reference the registered user’s RepositoryItem
.
For more information on login verification, see Managing User Logins.
handleLogout
The handleLogout
method allows users to log out of their authenticated sessions. Like the other handleX
methods, you can subclass ProfileForm
to use the preLogoutUser
and postLogoutUser
methods. The ProfileForm
property expireSessionOnLogout
defines the default behavior of the handleLogout
operation. The user’s session is invalidated when the handleLogout
method is called if the expiresSessionOnLogout
property is set to true, which is the default value. After logout, a subsequent request from the same user creates a new anonymous RAM profile.
If you do not wish to expire the session when you perform the logout, set the expireSessionOnLogout
property to false
. With this setting, the form handler and session-scoped Profile
objects are reset to use a new anonymous RAM profile, but maintain the same session. When the user is redirected after a successful logout operation, the Personalization module adds an extra query argument labeled DPSLogout
to the session ID information The default value of DPSLogout
is true
. The parameter name is defined by the constant atg.userprofiling.ProfileRequestServlet.LOGOUT_PARAM
. The ProfileRequestServlet
recognizes this query parameter and disables auto-login for the life of the session by setting a parameter AutoLogin
in the user’s session to Boolean.FALSE
. Otherwise, if you have configured the Personalization module to use auto-login, the persistent cookie or Basic Authentication information automatically attempts to reload the user profile even though the user logged out. See the Tracking Users section of this chapter for more information.
handleDelete
The handleDelete
method permanently removes a user from the profile repository. The preDeleteUser
and postDeleteUser
methods are available for performing actions before and after the process of actually removing the user profile. The removeUser
method performs the function of deleting the user profile. This method uses the current value of the repositoryId
property of ProfileForm
when invoking the MutableRepository.removeItem
method.
handleUpdate
The handleUpdate
method takes values entered into a profile form and explicitly updates the user’s profile with new attribute settings. Processing can occur before and after the update procedure by overriding the preUpdateUser
and postUpdateUser
methods. The updateUser
method modifies the user’s profile with the values submitted in the form. This method checks for required parameters in a process similar to the handleCreate
method.
The updateUser
method calls the updateProfileAttributes
method before committing the changes by calling the MutableRepository.updateItem
method. All the parameters that are managed by the form handler are stored in a Dictionary through the ProfileForm
component’s value
property. These values are stored in the Dictionary for all form submissions, including operations for handling the registration and login of users. The updateProfileAttributes
method iterates through all the submitted parameters and looks for an associated attribute in the user profile.
Once the updateProfileAttributes
method finds a profile attribute, the same method checks the value of the profile attribute’s RepositoryPropertyDescriptor
writable
property to determine whether the attribute can be updated. If this value is true
, then the value stored in the Dictionary is parsed into the correct data type for the profile attribute. Additional transformations may occur, depending on the property to be updated. For example, for the password
property, in the default configuration, the plain-text password value is turned into a hash representation and updated in the profile.
By default, the login
and email
attributes are trimmed to remove trailing and leading spaces. The list of properties to trim is defined by the trimProperties
property. The protected method isTrimProperty
is used to test if the specific property should be trimmed. The current implementation iterates over the list of properties specified by the trimProperties
property and returns true
if a match is found.
The MutableRepositoryItem
for the profile is updated with all the form changes. After the update, the same verification for required profile attributes occurs as in the handleCreate
process. If there are no errors, all updates are committed in one transaction. If there are any errors, no changes are made.
handleChangePassword
The handleChangePassword
method allows users to update their password profile attribute. This specific handler is available because it allows the form to check that the user changing the password knows the original password value. Optionally, you can ask for a confirmation password value to verify that the user did not mistype the new password entry. This handler also contains the standard preprocessing and post-processing methods. The changePassword
method compares the old password value with the confirm password value. The generatePassword
method of the PropertyManager
is used to transform the user’s password value (using a one-way hash) into the value that is stored in the database.