/*
 * JBoss, Home of Professional Open Source.
 * Copyright 2014 Red Hat, Inc., and individual contributors
 * as indicated by the @author tags.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.wildfly.security.auth.provider;

import java.security.Principal;

/**
 * A representation of a pre-authentication identity.
 *
 * The life of a {@code RealmIdentity} is short and is for a specific authentication attempt. A {@link SecurityRealm} creating a
 * {@code RealmIdentity} does not confirm the existence of the identity.
 *
 *
 * @author <a href="mailto:darran.lofthouse@jboss.com">Darran Lofthouse</a>
 */
public interface RealmIdentity {

    /**
     * Get the {@link Principal} for this identity.
     *
     * This method can return {@code null} if there is no mapping from the identity to a {@link Principal}
     *
     * @return The {@link Principal} for this identity.
     */
    Principal getPrincipal() throws RealmUnavailableException;

    /**
     * Determine whether a given credential is definitely supported, possibly supported, or definitely not supported for this
     * identity.
     *
     * @param credentialType the credential type
     * @return the level of support for this credential type
     */
    CredentialSupport getCredentialSupport(Class<?> credentialType) throws RealmUnavailableException;

    /**
     * Acquire a credential of the given type.
     *
     * @param credentialType the credential type class
     * @param <C> the credential type
     * @return the credential, or {@code null} if the principal has no credential of that type
     */
    <C> C getCredential(Class<C> credentialType) throws RealmUnavailableException;

    /**
     * Verify the given credential.  The result is one of the following:
     * <ul>
     *     <li>{@link VerificationResult#DENIED} - the credential is not valid</li>
     *     <li>{@link VerificationResult#UNVERIFIED} - the credential is not supported or could not be verified; retry with another credential type</li>
     *     <li>{@link VerificationResult#VERIFIED} - the credential is valid and verified</li>
     * </ul>
     *
     * @param credential the credential to verify
     * @return the non-{@code null} verification result
     */
    boolean verifyCredential(Object credential) throws RealmUnavailableException;

    /**
     * Dispose this realm identity after a completed authentication attempt.
     */
    void dispose();

    /**
     * Get an authenticated realm identity for this pre-authenticated identity.
     *
     * @return the authenticated realm identity (may not be {@code null})
     */
    AuthenticatedRealmIdentity getAuthenticatedRealmIdentity();

}

@@ -1395,24 +1395,125 @@
 s identity.%0A
+     * @throws RealmUnavailableException if the realm is not able to handle requests for any reason.%0A
      */%0A    
@@ -1836,24 +1836,125 @@
 ential type%0A
+     * @throws RealmUnavailableException if the realm is not able to handle requests for any reason.%0A
      */%0A    
@@ -2298,24 +2298,125 @@
 f that type%0A
+     * @throws RealmUnavailableException if the realm is not able to handle requests for any reason.%0A
      */%0A    
@@ -2542,65 +2542,23 @@
 ial.
-  The result is one of the following:
 %0A     *
- %3Cul%3E
 %0A     * 
     
@@ -2557,458 +2557,236 @@
   * 
-    %3Cli%3E%7B@link VerificationResult#DENIED%7D - the credential is not valid%3C/li%3E%0A     *     %3Cli%3E%7B@link VerificationResult#UNVERIFIED%7D - the credential is not supported or could not be verified; retry with another credential type%3C/li%3E%0A     *     %3Cli%3E%7B@link VerificationResult#VERIFIED%7D -
+@param credential the credential to verify%0A     * @return %7B@code true%7D if verification was successful, %7B@code false%7D otherwise.%0A     * @throws RealmUnavailableException if
  the 
-c
 re
-denti
 al
+m
  is 
-valid and verified%3C/li%3E%0A     * %3C/ul%3E%0A     *%0A     * @param credential the credential to verify%0A     * @return the non-%7B@code null%7D verification result
+not able to handle requests for any reason.
 %0A   
@@ -3156,16 +3156,117 @@
  null%7D)%0A
+     * @throws RealmUnavailableException if the realm is not able to handle requests for any reason.%0A
      */%0A
@@ -3327,13 +3327,46 @@
 entity()
+ throws RealmUnavailableException
 ;%0A%0A%7D%0A

Update the javadoc to reflect the changes to the verification API and also allow a realm to throw a RealmUnavailableException when obtaining the AuthenticatedRealmIdentity.