Clarify handling of multiple authentication mechanisms.

Signed-off-by: Arjan Tijms <arjan.tijms@omnifish.ee>

api/src/main/java/jakarta/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanism.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright (c) 2024 Contributors to Eclipse Foundation.
  * Copyright (c) 2015, 2020 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -30,66 +31,72 @@
 /**
  * <code>HttpAuthenticationMechanism</code> is a mechanism for obtaining a caller's
  * credentials in some way, using the HTTP protocol where necessary.
- * 
+ *
  * <p>
  * This is used to help in securing Jakarta Servlet endpoints, including
- * endpoints that may be build on top of Jakarta Servlets like Jakarta RESTful Web Services endpoints and 
+ * endpoints that may be build on top of Jakarta Servlets like Jakarta RESTful Web Services endpoints and
  * Jakarta Faces views. It specifically <b>is not</b> used for endpoints such as remote Jakarta Enterprise Beans
  * or (Jakarta Messaging) message driven beans.
- * 
+ *
  * <p>
- * A <code>HttpAuthenticationMechanism</code> is essentially a Jakarta Servlet specific and CDI enabled version of
- * the {@link ServerAuthModule} that adheres to the Servlet Container Profile. See the Jakarta Authentication spec for 
+ * An <code>HttpAuthenticationMechanism</code> is essentially a Jakarta Servlet specific and CDI enabled version of
+ * the {@link ServerAuthModule} that adheres to the Servlet Container Profile. See the Jakarta Authentication spec for
  * further details on this.
- * 
+ *
  * <p>
  * Implementations of this class can notify the Jakarta Servlet container about a successful authentication by using the
  * {@link HttpMessageContext#notifyContainerAboutLogin(java.security.Principal, java.util.Set)} method.
- * 
+ *
  * <p>
  * Implementations are expected and encouraged to delegate the actual credential validation and/or retrieval of the
  * caller name with optional groups to an {@link IdentityStore}. This is however <b>not</b> required and implementations
  * can either do the validation checks for authentication completely autonomously, or delegate only certain aspects of
  * the process to the store (e.g. use the store only for retrieving the groups an authenticated user is in).
+ *
+ * <p>
+ * By default only one <code>HttpAuthenticationMechanism</code> can be active. This is enforced by the default implementation
+ * of the {@link HttpAuthenticationMechanismHandler}. If an application wants to use multiple <code>HttpAuthenticationMechanism</code>s,
+ * e.g. a Form mechanism for the UI section and Basic HTTP for a REST endpoint, a custom {@link HttpAuthenticationMechanismHandler} has
+ * to be provided. A future version of this specification may provide default behavior in this area.
  */
 public interface HttpAuthenticationMechanism {
 
     /**
      * Authenticate an HTTP request.
-     * 
+     *
      * <p>
-     * This method is called in response to an HTTP client request for a resource, and is always invoked 
+     * This method is called in response to an HTTP client request for a resource, and is always invoked
      * <strong>before</strong> any {@link Filter} or {@link HttpServlet}. Additionally this method is called
      * in response to {@link HttpServletRequest#authenticate(HttpServletResponse)}
-     * 
+     *
      * <p>
      * Note that by default this method is <strong>always</strong> called for every request, independent of whether
      * the request is to a protected or non-protected resource, or whether a caller was successfully authenticated
      * before within the same HTTP session or not.
-     * 
+     *
      * <p>
-     * A CDI/Interceptor spec interceptor can be used to prevent calls to this method if needed. 
+     * A CDI/Interceptor spec interceptor can be used to prevent calls to this method if needed.
      * See {@link AutoApplySession} and {@link RememberMe} for two examples.
-     * 
+     *
      * @param request contains the request the client has made
      * @param response contains the response that will be send to the client
      * @param httpMessageContext context for interacting with the container
      * @return the completion status of the processing performed by this method
      * @throws AuthenticationException when the processing failed
      */
     AuthenticationStatus validateRequest(HttpServletRequest request, HttpServletResponse response, HttpMessageContext httpMessageContext) throws AuthenticationException;
-   
+
     /**
      * Secure the response, optionally.
-     * 
+     *
      * <p>
-     * This method is called to allow for any post processing to be done on the request, and is always invoked 
-     * <strong>after</strong> any {@link Filter} or {@link HttpServlet}. 
-     * 
+     * This method is called to allow for any post processing to be done on the request, and is always invoked
+     * <strong>after</strong> any {@link Filter} or {@link HttpServlet}.
+     *
      * <p>
      * Note that this method is only called when a (Servlet) resource has indeed been invoked, i.e. if a previous call
      * to <code>validateRequest</code> that was invoked before any {@link Filter} or {@link HttpServlet} returned SUCCESS.
-     *  
+     *
      * @param request contains the request the client has made
      * @param response contains the response that will be send to the client
      * @param httpMessageContext context for interacting with the container
@@ -99,16 +106,16 @@ public interface HttpAuthenticationMechanism {
     default AuthenticationStatus secureResponse(HttpServletRequest request, HttpServletResponse response, HttpMessageContext httpMessageContext) throws AuthenticationException {
         return SUCCESS;
     }
-    
+
     /**
      * Remove mechanism specific principals and credentials from the subject and any other state the mechanism
      * might have used.
-     * 
+     *
      * <p>
      * This method is called in response to {@link HttpServletRequest#logout()} and gives the authentication mechanism
      * the option to remove any state associated with an earlier established authenticated identity. For example, an
      * authentication mechanism that stores state within a cookie can send remove that cookie here.
-     * 
+     *
      * @param request contains the request the client has made
      * @param response contains the response that will be send to the client
      * @param httpMessageContext context for interacting with the container