Javadoc cleanup
[java-idp.git] / src / edu / internet2 / middleware / shibboleth / idp / authn / LoginContext.java
index 3aef09c..a5081df 100644 (file)
@@ -29,7 +29,7 @@ import org.joda.time.DateTime;
  * 
  * Two properties are tracked by default:
  * 
- * <code>forceAuth</code> - Should user authentiation be forced. <code>passiveAuth</code> - Should user
+ * <code>forceAuth</code> - Should user authentication be forced. <code>passiveAuth</code> - Should user
  * authentication not control the UI.
  * 
  * A Map&lt;String, Object&gt; is provided to store other properties. Alternatively, a profile handler may create a
@@ -38,19 +38,19 @@ import org.joda.time.DateTime;
  * LoginContexts should be created by a profile handler when authentication is needed. Once control has returned to the
  * profile handler, it should remove the LoginContext from the HttpSession.
  * 
- * The {@link AuthenticationManager} or an {@link AuthenticationHandler} should set the
- * {@link LoginContext#setAuthenticationAttempted()}, {@link LoginContext#setAuthnOK(boolean)},
- * {@link LoginContext#setAuthnFailure(String)}, {@link LoginContext#{setAuthenticationDuration(long)}
- * {@link LoginContext#setAuthenticationInstant(DateTime)} appropriately.
- * 
+ * The {@link AuthenticationEngine} or an {@link LoginHandler} should set the
+ * {@link LoginContext#setAuthenticationAttempted()}, {@link LoginContext#setPrincipalAuthenticated(boolean)},
+ * {@link LoginContext#setAuthenticationFailure(AuthenticationException)},
+ * {@link LoginContext#setAuthenticationDuration(long)}, {@link LoginContext#setAuthenticationInstant(DateTime)}
+ * appropriately.
  */
 public class LoginContext implements Serializable {
 
     /** the key in a HttpSession where login contexts are stored. */
     public static final String LOGIN_CONTEXT_KEY = "shib2.logincontext";
-    
+
     /** Serial version UID. */
-    private static final long serialVersionUID = 4268661186941572372L;
+    private static final long serialVersionUID = -8764003758734956911L;
 
     /** Entity ID of the relying party. */
     private String relyingPartyId;
@@ -67,20 +67,20 @@ public class LoginContext implements Serializable {
     /** The ProfileHandler URL. */
     private String profileHandlerURL;
 
-    /** The AuthenticationManager's URL. */
-    private String authnManagerURL;
+    /** The authentication engine's URL. */
+    private String authnEngineURL;
 
     /** has authentication been attempted yet. */
     private boolean authnAttempted;
 
     /** The id of the authenticated user. */
-    private String userID;
+    private String principalName;
 
-    /** Did authentication succceed? */
-    private boolean authenticationOK;
+    /** Did authentication succeed? */
+    private boolean principalAuthenticated;
 
-    /** Optional failure message. */
-    private String authnFailureMessage;
+    /** Exception that occured during authentication. */
+    private AuthenticationException authnException;
 
     /** The instant of authentication. */
     private DateTime authnInstant;
@@ -94,20 +94,24 @@ public class LoginContext implements Serializable {
     /** The session id. */
     private String sessionID;
 
+    /** List of request authentication methods. */
+    private ArrayList<String> requestAuthenticationMethods;
+
     /** Creates a new instance of LoginContext. */
     public LoginContext() {
+        requestAuthenticationMethods = new ArrayList<String>();
     }
 
     /**
      * Creates a new instance of LoginContext.
      * 
-     * @param force if the authentication manager must reauth the user.
+     * @param force if the authentication manager must re-authenticate the user.
      * @param passive if the authentication manager must not interact with the users UI.
      */
     public LoginContext(boolean force, boolean passive) {
-
         forceAuth = force;
         passiveAuth = passive;
+        requestAuthenticationMethods = new ArrayList<String>();
     }
 
     /**
@@ -131,9 +135,9 @@ public class LoginContext implements Serializable {
     /**
      * Returns if authentication must be forced.
      * 
-     * @return <code>true</code> if the authentication manager must reauth the user.
+     * @return <code>true</code> if the authentication manager must re-authenticate the user.
      */
-    public boolean getForceAuth() {
+    public boolean isForceAuthRequired() {
         return forceAuth;
     }
 
@@ -142,32 +146,32 @@ public class LoginContext implements Serializable {
      * 
      * @return <code>true</code> if the authentication manager must not interact with the users UI.
      */
-    public boolean getPassiveAuth() {
+    public boolean isPassiveAuthRequired() {
         return passiveAuth;
     }
 
     /**
      * Sets if authentication must be forced.
      * 
-     * @param forceAuth if the authentication manager must reauth the user.
+     * @param force if the authentication manager must re-authenticate the user.
      */
-    public void setForceAuth(boolean forceAuth) {
-        this.forceAuth = forceAuth;
+    public void setForceAuthRequired(boolean force) {
+        forceAuth = force;
     }
 
     /**
      * Sets if authentication must be passive.
      * 
-     * @param passiveAuth if the authentication manager must not interact with the users UI.
+     * @param passive if the authentication manager must not interact with the users UI.
      */
-    public void setPassiveAuth(boolean passiveAuth) {
-        this.passiveAuth = passiveAuth;
+    public void setPassiveAuthRequired(boolean passive) {
+        passiveAuth = passive;
     }
 
     /**
      * Get an optional property object.
      * 
-     * @param key The key in the properites Map.
+     * @param key The key in the properties Map.
      * 
      * @return The object, or <code>null</code> is no object exists for the key.
      */
@@ -192,8 +196,8 @@ public class LoginContext implements Serializable {
      * 
      * @param authnOK if authentication succeeded;
      */
-    public void setAuthenticationOK(boolean authnOK) {
-        this.authenticationOK = authnOK;
+    public void setPrincipalAuthenticated(boolean authnOK) {
+        this.principalAuthenticated = authnOK;
     }
 
     /**
@@ -201,32 +205,32 @@ public class LoginContext implements Serializable {
      * 
      * @return <code>true</code> is the user was successfully authenticated.
      */
-    public boolean getAuthenticationOK() {
-        return authenticationOK;
+    public boolean isPrincipalAuthenticated() {
+        return principalAuthenticated;
     }
 
     /**
-     * Sets the optional authentication failure message.
+     * Sets the error that occurred during authentication.
      * 
-     * @param failureMessage A description of why authN failed.
+     * @param error error that occurred during authentication
      */
-    public void setAuthenticationFailureMessage(String failureMessage) {
-        authnFailureMessage = failureMessage;
+    public void setAuthenticationFailure(AuthenticationException error) {
+        authnException = error;
     }
 
     /**
-     * Returns the optional authentication failure message.
+     * Gets the error that occurred during authentication.
      * 
-     * @return The failure message, or <code>null</code> is none was set.
+     * @return error that occurred during authentication
      */
-    public String getAuthenticationFailureMessage() {
-        return authnFailureMessage;
+    public AuthenticationException getAuthenticationFailure() {
+        return authnException;
     }
 
     /**
      * Set if authentication has been attempted.
      * 
-     * This method should be called by an {@link AuthenticationHandler} while processing a request.
+     * This method should be called by an {@link LoginHandler} while processing a request.
      */
     public void setAuthenticationAttempted() {
         authnAttempted = true;
@@ -246,8 +250,8 @@ public class LoginContext implements Serializable {
      * 
      * @param id The userid.
      */
-    public void setUserID(String id) {
-        userID = id;
+    public void setPrincipalName(String id) {
+        principalName = id;
     }
 
     /**
@@ -255,8 +259,8 @@ public class LoginContext implements Serializable {
      * 
      * @return the ID of the user, or <code>null</code> if authentication failed.
      */
-    public String getUserID() {
-        return userID;
+    public String getPrincipalName() {
+        return principalName;
     }
 
     /**
@@ -271,28 +275,28 @@ public class LoginContext implements Serializable {
     /**
      * Sets the ProfileHandler URL.
      * 
-     * @param profileHandlerURL The URL of the profile handler that invoked the AuthenticationManager/
+     * @param url The URL of the profile handler that invoked the AuthenticationManager/
      */
-    public void setProfileHandlerURL(String profileHandlerURL) {
-        this.profileHandlerURL = profileHandlerURL;
+    public void setProfileHandlerURL(String url) {
+        profileHandlerURL = url;
     }
 
     /**
-     * Gets the AuthenticationManager URL.
+     * Gets the authentication engine's URL.
      * 
-     * @return the URL of the AuthenticationManager.
+     * @return the URL of the authentication engine
      */
-    public String getAuthenticationManagerURL() {
-        return authnManagerURL;
+    public String getAuthenticationEngineURL() {
+        return authnEngineURL;
     }
 
     /**
-     * Sets the AuthenticationManager's URL.
+     * Sets the authentication engine's URL.
      * 
-     * @param authnManagerURL the URL of the AuthenticationManager.
+     * @param url the URL of the authentication engine
      */
-    public void setAuthenticationManagerURL(String authnManagerURL) {
-        this.authnManagerURL = authnManagerURL;
+    public void setAuthenticationEngineURL(String url) {
+        authnEngineURL = url;
     }
 
     /**
@@ -307,10 +311,10 @@ public class LoginContext implements Serializable {
     /**
      * Sets the authentication instant.
      * 
-     * @param authnInstant The instant of authentication.
+     * @param instant The instant of authentication.
      */
-    public void setAuthenticationInstant(final DateTime authnInstant) {
-        this.authnInstant = authnInstant;
+    public void setAuthenticationInstant(final DateTime instant) {
+        authnInstant = instant;
     }
 
     /**
@@ -325,10 +329,10 @@ public class LoginContext implements Serializable {
     /**
      * Sets the duration of authentication.
      * 
-     * @param authnDuration The duration of authentication.
+     * @param duration The duration of authentication.
      */
-    public void setAuthenticationDuration(long authnDuration) {
-        this.authnDuration = authnDuration;
+    public void setAuthenticationDuration(long duration) {
+        authnDuration = duration;
     }
 
     /**
@@ -343,37 +347,37 @@ public class LoginContext implements Serializable {
     /**
      * Sets the method used to authenticate the user.
      * 
-     * @param authnMethod The method used to authenticate the user.
+     * @param method The method used to authenticate the user.
      */
-    public void setAuthenticationMethod(String authnMethod) {
-        this.authnMethod = authnMethod;
+    public void setAuthenticationMethod(String method) {
+        authnMethod = method;
     }
 
     /**
-     * Gets the {@link Session} ID
+     * Gets the {@link edu.internet2.middleware.shibboleth.idp.session.Session} ID.
      * 
-     * @return the Session id.
+     * @return the Session id
      */
     public String getSessionID() {
         return sessionID;
     }
 
     /**
-     * Sets the {@link Session} ID
+     * Sets the {@link edu.internet2.middleware.shibboleth.idp.session.Session} ID.
      * 
-     * @param sessionID the Session ID
+     * @param id the Session ID
      */
-    public void setSessionID(String sessionID) {
-        this.sessionID = sessionID;
+    public void setSessionID(String id) {
+        sessionID = id;
     }
 
     /**
-     * Return the acceptable authentication handler URIs for authenticating this user. If no authentication methods are
-     * preferred the resultant list will be empty.
+     * Return the acceptable authentication handler URIs, in preference order, for authenticating this user. If no
+     * authentication methods are preferred the resultant list will be empty.
      * 
-     * @return an array of URIs
+     * @return an list of authentication method identifiers
      */
     public List<String> getRequestedAuthenticationMethods() {
-        return new ArrayList<String>();
+        return requestAuthenticationMethods;
     }
-}
+}
\ No newline at end of file