Javadoc cleanup
[java-idp.git] / src / edu / internet2 / middleware / shibboleth / idp / authn / LoginContext.java
index 54ff474..a5081df 100644 (file)
 
 package edu.internet2.middleware.shibboleth.idp.authn;
 
-
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Map;
-import javolution.util.FastMap;
+import java.util.concurrent.ConcurrentHashMap;
 
 import org.joda.time.DateTime;
 
-
 /**
- * Login context created by a profile handler and interpreted
- * by the authentication package.
+ * Login context created by a profile handler and interpreted by the authentication package.
  * 
  * Two properties are tracked by default:
  * 
- * <code>forceAuth</code> - Should user authentiation be forced.
- * <code>passiveAuth</code> - Should user authentication not control the UI.
+ * <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 subclass of LoginContext with
- * extra fields.
- *
- * 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)} appropriately.
- *
+ * A Map&lt;String, Object&gt; is provided to store other properties. Alternatively, a profile handler may create a
+ * subclass of LoginContext with extra fields.
+ * 
+ * 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 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 {
-    
-    /** the key in a HttpSession where login contexts are stored */
+public class LoginContext implements Serializable {
+
+    /** the key in a HttpSession where login contexts are stored. */
     public static final String LOGIN_CONTEXT_KEY = "shib2.logincontext";
-    
-    
-    /** Should user authentication be forced */
-    private boolean forceAuth = false;
-    
-    /** Must authentication not interact with the UI */
-    private boolean passiveAuth = false;
-    
-    /** a catch-all map for other properties */
-    private Map<String, Object> propsMap = new FastMap<String, Object>();
-    
-    /** The ProfileHandler URL */
+
+    /** Serial version UID. */
+    private static final long serialVersionUID = -8764003758734956911L;
+
+    /** Entity ID of the relying party. */
+    private String relyingPartyId;
+
+    /** Should user authentication be forced. */
+    private boolean forceAuth;
+
+    /** Must authentication not interact with the UI. */
+    private boolean passiveAuth;
+
+    /** a catch-all map for other properties. */
+    private Map<String, Serializable> propsMap = new ConcurrentHashMap<String, Serializable>();
+
+    /** The ProfileHandler URL. */
     private String profileHandlerURL;
-    
-    /** The AuthenticationManager's URL */
-    private String authnManagerURL;
-    
-    /** has authentication been attempted yet */
-    private boolean authnAttempted = false;
-    
-    /** The id of the authenticated user */ 
-    private String userID;
-
-    /** Did authentication succceed? */
-    private boolean authenticationOK;
-    
-    /** Optional failure message  */
-    private String authnFailureMessage;
-
-    /** The instant of authentication */
+
+    /** The authentication engine's URL. */
+    private String authnEngineURL;
+
+    /** has authentication been attempted yet. */
+    private boolean authnAttempted;
+
+    /** The id of the authenticated user. */
+    private String principalName;
+
+    /** Did authentication succeed? */
+    private boolean principalAuthenticated;
+
+    /** Exception that occured during authentication. */
+    private AuthenticationException authnException;
+
+    /** The instant of authentication. */
     private DateTime authnInstant;
-    
-    /** The duration of authentication */
+
+    /** The duration of authentication. */
     private long authnDuration;
-    
-    /** The method used to authenticate the user */
-    private String authnMethod;        
-    
-    /** The session id */
+
+    /** The method used to authenticate the user. */
+    private String authnMethod;
+
+    /** The session id. */
     private String sessionID;
-    
-    
-    /** Creates a new instance of LoginContext */
+
+    /** 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 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>();
+    }
+
+    /**
+     * Gets the entity ID of the relying party.
+     * 
+     * @return entity ID of the relying party
+     */
+    public String getRelyingPartyId() {
+        return relyingPartyId;
     }
-    
-    
+
     /**
-     * Creates a new instance of LoginContext
-     *
-     * @param forceAuth if the authentication manager must reauth the user.
-     * @param passiveAuth if the authentication manager must not interact with the users UI. 
+     * Gets the entity ID of the relying party.
+     * 
+     * @param id entity ID of the relying party
      */
-    public LoginContext(boolean forceAuth, boolean passiveAuth) {
-        
-        this.forceAuth = forceAuth;
-        this.passiveAuth = passiveAuth;
-    }    
-    
-    
+    public void setRelyingParty(String id) {
+        relyingPartyId = id;
+    }
+
     /**
      * 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() {
-        return this.forceAuth;
+    public boolean isForceAuthRequired() {
+        return forceAuth;
     }
-    
-    
+
     /**
      * Returns if authentication must be passive.
      * 
      * @return <code>true</code> if the authentication manager must not interact with the users UI.
      */
-    public boolean getPassiveAuth() {
-        return this.passiveAuth;
+    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.
      */
     public Object getProperty(String key) {
-        return this.propsMap.get(key);
+        return propsMap.get(key);
     }
-    
-    
+
     /**
      * Sets an optional property object.
      * 
@@ -169,205 +187,197 @@ public class LoginContext {
      * @param key The key to set.
      * @param obj The object to associate with key.
      */
-    public void setProperty(String key, final Object obj) {
-        this.propsMap.put(key, obj);
+    public void setProperty(String key, final Serializable obj) {
+        propsMap.put(key, obj);
     }
-    
+
     /**
      * Sets if authentication succeeded.
      * 
      * @param authnOK if authentication succeeded;
      */
-    public void setAuthnOK(boolean authnOK) {
-        this.authenticationOK = authnOK;
+    public void setPrincipalAuthenticated(boolean authnOK) {
+        this.principalAuthenticated = authnOK;
     }
-    
-    
+
     /**
      * Returns if authentication succeeded.
      * 
      * @return <code>true</code> is the user was successfully authenticated.
      */
-    public boolean getAuthnOK() {
-        return this.authenticationOK;
+    public boolean isPrincipalAuthenticated() {
+        return principalAuthenticated;
     }
-    
-    
-    /** Sets the optional authentication failure message.
-     * 
-     * @param failureMessage A description of why authN failed.
-     */ 
-    public void setAuthnFailureMessage(String failureMessage) {
-        this.authnFailureMessage = failureMessage;
+
+    /**
+     * Sets the error that occurred during authentication.
+     * 
+     * @param error error that occurred during authentication
+     */
+    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 getAuthnFailureMessage() {
-        return this.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() {
-       this.authnAttempted = true;
+        authnAttempted = true;
     }
-    
-    
+
     /**
      * Returns if authentication has been attempted for this user.
+     * 
+     * @return if authentication has been attempted for this user
      */
     public boolean getAuthenticationAttempted() {
-       return this.authnAttempted;
+        return authnAttempted;
     }
-    
-    
+
     /**
      * Sets the ID of the authenticated user.
      * 
-     * @param userID The userid.
+     * @param id The userid.
      */
-    public void setUserID(String userID) {
-        this.userID = userID;
+    public void setPrincipalName(String id) {
+        principalName = id;
     }
-    
-    
+
     /**
      * Returns the ID of the authenticated user.
      * 
      * @return the ID of the user, or <code>null</code> if authentication failed.
      */
-    public String getUserID() {
-        return this.userID;
+    public String getPrincipalName() {
+        return principalName;
     }
-    
-    
+
     /**
      * Gets the ProfileHandler URL.
-     *
+     * 
      * @return the URL of the profile handler that is invoking the Authentication Manager.
      */
     public String getProfileHandlerURL() {
-       return this.profileHandlerURL;
+        return profileHandlerURL;
     }
-    
-    
+
     /**
      * 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.
-     *
-     * @return the URL of the AuthenticationManager.
+     * Gets the authentication engine's URL.
+     * 
+     * @return the URL of the authentication engine
      */
-    public String getAuthnManagerURL() {
-       return this.authnManagerURL;
+    public String getAuthenticationEngineURL() {
+        return authnEngineURL;
     }
-    
-    
+
     /**
-     * Sets the AuthenticationManager's URL.
-     *
-     * @param authnManagerURL the URL of the AuthenticationManager.
+     * Sets the authentication engine's URL.
+     * 
+     * @param url the URL of the authentication engine
      */
-    public void setAuthnManagerURL(String authnManagerURL) {
-       this.authnManagerURL = authnManagerURL;
+    public void setAuthenticationEngineURL(String url) {
+        authnEngineURL = url;
     }
-    
-    
+
     /**
      * Gets the authentication instant.
-     *
+     * 
      * @return The instant of authentication, or <code>null</code> if none was set.
      */
     public DateTime getAuthenticationInstant() {
-           return this.authnInstant;
+        return authnInstant;
     }
-    
-    
+
     /**
      * 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;
     }
-    
-    
+
     /**
      * Gets the duration of authentication.
-     *
+     * 
      * @return The duration of authentication, or zero if none was set.
      */
     public long getAuthenticationDuration() {
-       return this.authnDuration;
+        return authnDuration;
     }
-    
-    
+
     /**
      * 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;
     }
-    
-    
+
     /**
      * Gets the method used to authenticate the user.
-     *
+     * 
      * @return The method used to authenticate the user.
      */
     public String getAuthenticationMethod() {
-       return this.authnMethod;
+        return authnMethod;
     }
-    
-    
+
     /**
      * 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
-     *
-     * @return the Session id.
+     * Gets the {@link edu.internet2.middleware.shibboleth.idp.session.Session} ID.
+     * 
+     * @return the Session id
      */
     public String getSessionID() {
-       return this.sessionID;
+        return sessionID;
     }
-    
-    
+
     /**
-     * Sets the {@link Session} ID
-     *
-     * @param sessionID the Session ID
+     * Sets the {@link edu.internet2.middleware.shibboleth.idp.session.Session} ID.
+     * 
+     * @param id the Session ID
+     */
+    public void setSessionID(String id) {
+        sessionID = id;
+    }
+
+    /**
+     * 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 list of authentication method identifiers
      */
-    public void setSessionID(String sessionID) {
-       this.sessionID = sessionID;
+    public List<String> getRequestedAuthenticationMethods() {
+        return requestAuthenticationMethods;
     }
-}
+}
\ No newline at end of file