/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * docs/licenses/cddl.txt
 * or http://www.opensource.org/licenses/cddl1.php.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * docs/licenses/cddl.txt.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Copyright 2016-2018 Ping Identity Corporation
 */

package com.unboundid.directory.sdk.broker.types;

import com.unboundid.util.NotExtensible;



/**
 * The result of a single step through the authentication flow of an Identity
 * Authenticator. Use AuthenticationResult.Builder to create instances of
 * this class.
 */
@NotExtensible()
public final class AuthenticationResult
{
  /**
   * Whether the authentication event is successful.
   */
  private final boolean successful;

  /**
   * The error code if an error occurred while processing the authentication
   * request.
   */
  private final String error;

  /**
   * The message describing the error that occurred while processing the
   * authentication request.
   */
  private final String errorDetail;

  /**
   * The authenticated user, or {@code null} if additional steps are required.
   */
  private final ScimResourcePrincipal principal;

  /**
   * Parameters to return that may be used to continue the authentication
   * process. May be {@code null}.
   */
  private final String responseParams;

  /**
   * State parameters to be preserved and resubmitted to the authenticator
   * to continue a multi-step authentication flow. May be {@code null}.
   */
  private final String flowStateParams;

  /**
   * The message that will be only be included in the trace log for diagnostic
   * purposes.
   */
  private final String diagnosticMessage;



  /**
   * Builder class to build an instance of AuthenticationResult.
   */
  public static class Builder
  {
    private boolean successful;
    private String error;
    private String errorDetail;
    private ScimResourcePrincipal principal;
    private String responseParams;
    private String flowStateParams;
    private String diagnosticMessage;



    /**
     * Specifies the JSON object specifying the parameters to return that may be
     * used to continue the authentication process.
     * <p>
     * Since this response is visible to the client in a potentially
     * unauthenticated context, the authenticator should not expose any
     * sensitive user or server information in the response.
     * @param responseParams  The parameters to return.
     * @return  this builder.
     */
    public Builder setResponseParams(final String responseParams)
    {
      this.responseParams = responseParams;
      return this;
    }



    /**
     * Specifies the JSON object specifying the state parameters to be preserved
     * and resubmitted to the authenticator to continue a multi-step
     * authentication flow. If no state parameters are set for this result,
     * any existing state parameters will be resubmitted to the authenticator.
     * @param flowStateParams  The state parameters to be preserved.
     * @return  this builder.
     */
    public Builder setFlowStateParams(final String flowStateParams)
    {
      this.flowStateParams = flowStateParams;
      return this;
    }



    /**
     * Specifies the message that will be only be included in the trace log
     * for diagnostic purposes.
     * @param diagnosticMessage  The diagnostic message
     * @return  this builder.
     */
    public Builder setDiagnosticMessage(final String diagnosticMessage)
    {
      this.diagnosticMessage = diagnosticMessage;
      return this;
    }



    /**
     * Builds a new AuthenticationResult.
     *
     * @return  A new AuthenticationResult.
     */
    public AuthenticationResult build()
    {
      return new AuthenticationResult(
          successful,
          error,
          errorDetail,
          principal,
          responseParams,
          flowStateParams,
          diagnosticMessage);
    }
  }

  /**
   * Create a new builder for a successful response. An authenticator
   * should only return success if the client provided the correct
   * credentials.
   *
   * @param principal The authenticated user.
   *
   * @return  A new builder for a successful response.
   */
  public static Builder success(final ScimResourcePrincipal principal)
  {
    final Builder b = new Builder();
    b.successful = true;
    b.principal = principal;
    return b;
  }



  /**
   * Create a new builder for an unsuccessful response. An authenticator
   * should return an unsuccessful response if additional info is needed.
   *
   * @return  A new builder for an unsuccessful response.
   */
  public static Builder failure()
  {
    final Builder b = new Builder();
    b.successful = false;
    return b;
  }



  /**
   * Create a new builder for an unsuccessful error response. An authenticator
   * should return an error response if the provided credentials are incorrect
   * or an error occurred while processing the authentication request.
   * <p>
   * Since this response is visible to the client in a potentially
   * unauthenticated context, the authenticator should not expose any sensitive
   * user or server information in the error response.
   *
   * @param error The error code.
   * @param errorDetail The details about the error.
   * @return  A new builder for an unsuccessful response.
   */
  public static Builder failure(final String error, final String errorDetail)
  {
    final Builder b = new Builder();
    b.successful = false;
    b.error = error;
    b.errorDetail = errorDetail;
    return b;
  }



  /**
   * Create a new AuthenticationResult from the provided information.
   * @param successful      Whether the authentication event is successful.
   * @param error           The error code.
   * @param errorDetail     The error detail.
   * @param principal       The authenticated user.
   * @param responseParams  The response parameters.
   * @param flowStateParams The flow state parameters.
   * @param diagnosticMessage  The diagnostic message.
   */
  private AuthenticationResult(
      final boolean successful,
      final String error,
      final String errorDetail,
      final ScimResourcePrincipal principal,
      final String responseParams,
      final String flowStateParams,
      final String diagnosticMessage)
  {
    this.successful = successful;
    this.error = error;
    this.errorDetail = errorDetail;
    this.principal = principal;
    this.responseParams = responseParams;
    this.flowStateParams = flowStateParams;
    this.diagnosticMessage = diagnosticMessage;
  }



  /**
   * Indicates whether the authentication event is successful.
   *
   * @return {@code true} if the authentication event is successful, or
   *         {@code false} otherwise.
   */
  public boolean isSuccessful()
  {
    return successful;
  }



  /**
   * Retrieve the error code to return if an error occurred while processing the
   * authentication request or {@code null} if an error did not occur.
   *
   * @return The error code.
   */
  public String getError()
  {
    return error;
  }



  /**
   * Retrieve the message to return if an error occurred while processing
   * the authentication request describing the details of the error
   * or {@code null} if an error did not occur.
   *
   * @return The error details.
   */
  public String getErrorDetail()
  {
    return errorDetail;
  }



  /**
   * Retrieve the authenticated user, or {@code null} if additional steps
   * are required. An authenticator should set the principal in the result
   * if it can identify a user with the provided credentials. Otherwise,
   * it should return the principal that was provided in the authentication
   * request.
   *
   * @return  The authenticated user, or {@code null} if additional steps
   *          are required.
   */
  public ScimResourcePrincipal getPrincipal()
  {
    return principal;
  }



  /**
   * Retrieve the JSON object specifying the parameters to return that may be
   * used to continue the authentication process. This string can be parsed
   * using any JSON library. For example, Jackson's ObjectMapper.readTree() or
   * the UnboundID LDAP SDK's JSONObject constructor.
   * @return  The parameters to return, may be {@code null}.
   */
  public String getResponseParams()
  {
    return responseParams;
  }



  /**
   * Retrieve the state parameters to be preserved and resubmitted to the
   * authenticator to continue a multi-step authentication flow.
   * @return  The state parameters to be preserved, may be {@code null}.
   */
  public String getFlowStateParams()
  {
    return flowStateParams;
  }

  /**
   * Gets the message that will be only be included in the trace log
   * for diagnostic purposes.
   *
   * @return The message that will be only be included in the trace log
   */
  public String getDiagnosticMessage()
  {
    return diagnosticMessage;
  }



  /**
   * {@inheritDoc}
   */
  @Override
  public boolean equals(final Object o)
  {
    if (this == o)
    {
      return true;
    }
    if (o == null || getClass() != o.getClass())
    {
      return false;
    }

    final AuthenticationResult that = (AuthenticationResult) o;

    if (successful != that.successful)
    {
      return false;
    }
    if (!error.equals(that.error))
    {
      return false;
    }
    if (!errorDetail.equals(that.errorDetail))
    {
      return false;
    }
    if (principal != null ?
        !principal.equals(that.principal) : that.principal != null)
    {
      return false;
    }
    if (responseParams != null ?
        !responseParams.equals(that.responseParams) :
        that.responseParams != null)
    {
      return false;
    }
    return flowStateParams != null ?
           flowStateParams.equals(that.flowStateParams) :
           that.flowStateParams == null;
  }



  /**
   * {@inheritDoc}
   */
  @Override
  public int hashCode()
  {
    int result = (successful ? 1 : 0);
    result = 31 * result +
             (error != null ? error.hashCode() : 0);
    result = 31 * result +
             (errorDetail != null ? errorDetail.hashCode() : 0);
    result = 31 * result +
             (principal != null ? principal.hashCode() : 0);
    result = 31 * result +
             (responseParams != null ? responseParams.hashCode() : 0);
    result = 31 * result +
             (flowStateParams != null ? flowStateParams.hashCode() : 0);
    return result;
  }



  /**
   * {@inheritDoc}
   */
  @Override
  public String toString()
  {
    final StringBuilder sb = new StringBuilder("AuthenticationResult{");
    sb.append("successful=").append(successful);
    sb.append(", error='").append(error).append('\'');
    sb.append(", errorDetail='").append(errorDetail).append('\'');
    sb.append(", principal='").append(principal).append('\'');
    sb.append(", responseParams='").append(responseParams).append('\'');
    sb.append(", flowStateParams='").append(flowStateParams).append('\'');
    sb.append('}');
    return sb.toString();
  }
}