eTextReader.authentication
Interface Authenticator

All Known Implementing Classes:

DBAuthenticator

public interface Authenticator

A set of methods that can be used to authenticate a user given an identity and some "secret& to verify that identity. For instance, a user name and a password are commonly used for this purpose.

In addition to verifying a user's identity, a mechanism is also provided to update a user's secret

Author:

mcfall

Nested Class Summary

static class

Authenticator.AUTHENTICATION_RESULT This enum provides the set of possible return values for the authenticate and updateSecret methods.

Method Summary

Authenticator.AUTHENTICATION_RESULT	authenticate(java.lang.Object identity, java.lang.Object secret) Attempts to verify the user identified by identity using the supplied secret.
java.lang.String	getOperationalErrorDescription() Provides feedback when an Authenticator specific operational error occurs.
java.lang.String	getOtherErrorDescription() Provides feedback when a Authenticator specific error condition arises.
Authenticator.AUTHENTICATION_RESULT	updateSecret(java.lang.Object identity, java.lang.Object oldSecret, java.lang.Object newSecret) Provides a mechanism for a user's secret to be updated.

Method Detail

authenticate

Authenticator.AUTHENTICATION_RESULT authenticate(java.lang.Object identity,
                                                 java.lang.Object secret)

Attempts to verify the user identified by identity using the supplied secret.

If the supplied secret matches that known to this Authenticator, then the enum value SUCCESS should be returned. If authentication fails, the Authenticator can choose to provide specific feedback, such as the fact that an unknown identity was presented, at the Authenticator implementor's discretion. If specified feedback is not desired, the enum value FAILED should be returned. Implementors can indicate custom return values through the use of the OTHER_ERROR enum value. If OTHER_ERROR is returned, then the result the method getOtherErrorDescription should return a description of the error so that the user can be provided with feedback.

If an implementation specific error occurs, such as a failure to contact a specific database, then the enum value OPERATIONAL_ERROR should be returned, and the method getOperationalErrorDescription should return a description of the error so that the user can be provided with feedback.

Parameters:

identity - an object used to identify a given individual

secret - an object known/possessed by only the individual identified by identity

Returns:

an AUTHENTICATION_RESULT object indicating the results of authenticating the given entity

updateSecret

Authenticator.AUTHENTICATION_RESULT updateSecret(java.lang.Object identity,
                                                 java.lang.Object oldSecret,
                                                 java.lang.Object newSecret)

Provides a mechanism for a user's secret to be updated. The user's identity is first verified by calling authenticate using the supplied identity and oldSecret. If this succeeds, the secret is updated.

Parameters:

identity - an object used to identify a given user

oldSecret - the user's current secret

newSecret - the new secret to be used for the given user

Returns:

an AUTHENTICATION_RESULT, which should correspond to the description given in the authenticate method.

getOtherErrorDescription

java.lang.String getOtherErrorDescription()

Provides feedback when a Authenticator specific error condition arises. If a previous call to either authenticate or updateSecret has not result in a return value of OTHER_ERROR, then this method may return invalid information.

Returns:

a String describing the error that occurred

getOperationalErrorDescription

java.lang.String getOperationalErrorDescription()

Provides feedback when an Authenticator specific operational error occurs. If a previous call to either authenticate or updateSecret has not result in a return value of OTHER_ERROR, then this method may return invalid information.

Returns:

a String describing the error that occurred