/*
 * 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 2021 Ping Identity Corporation
 */
package com.unboundid.directory.sdk.scim2.api;

import com.unboundid.directory.sdk.broker.internal.BrokerExtension;
import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
import com.unboundid.directory.sdk.common.internal.Reconfigurable;
import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
import com.unboundid.directory.sdk.scim2.config.SCIMSubResourceTypeHandlerConfig;
import com.unboundid.directory.sdk.scim2.types.SCIMCreateRequest;
import com.unboundid.directory.sdk.scim2.types.SCIMDeleteRequest;
import com.unboundid.directory.sdk.scim2.types.SCIMModifyRequest;
import com.unboundid.directory.sdk.scim2.types.SCIMReplaceRequest;
import com.unboundid.directory.sdk.scim2.types.SCIMRetrieveRequest;
import com.unboundid.directory.sdk.scim2.types.SCIMSearchRequest;
import com.unboundid.directory.sdk.scim2.types.SCIMServerContext;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.scim2.common.ScimResource;
import com.unboundid.scim2.common.exceptions.NotImplementedException;
import com.unboundid.scim2.common.exceptions.ScimException;
import com.unboundid.scim2.common.types.SchemaResource;
import com.unboundid.util.Extensible;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.ArgumentParser;

import java.util.Collections;
import java.util.List;
import java.util.Map;

/**
 * This class defines an API that may be implemented by PingAuthorize Server
 * extensions that need to extend the server's standard SCIM 2 capabilities.
 * <p>
 * A SCIM sub-resource type is a child type of a SCIM resource type. Where a
 * SCIM resource type strictly provides a view of a data store record (such
 * as an LDAP directory server entry), a SCIM sub-resource type may expose
 * arbitrary capabilities or data associated with a parent SCIM resource type.
 * <p>
 * A SCIM sub-resource type REST API endpoint is accessed as a child path of
 * the parent SCIM resource. For example, a SCIM Sub-Resource Type Handler that
 * provides an account state management API for a "User" SCIM resource type
 * might be accessed via the path <i>/scim/v2/Users/{resourceId}/account</i>.
 *
 * <h2>One-to-one vs. one-to-many relationships</h2>
 *
 * A SCIM sub-resource type may have a <i>one-to-one</i> relationship with its
 * parent resource type, meaning that only one sub-resource exists per parent
 * SCIM resource, or it may have a <i>one-to-many</i> relationship, meaning
 * that multiple sub-resources may exist parent SCIM resource.
 *
 * Each resource belonging to a one-to-many SCIM sub-resource type should have
 * a unique identifier, just as each resource of a SCIM resource type has a
 * unique identifier. For example, a SCIM sub-resource representing a user's
 * pet cat might have the path
 * <i>/scim/v2/Users/{resourceId}/Cats/{subresourceId}</i>, where
 * "<i>{subresourceId}</i>" is the cat resource's unique identifier.
 *
 * <h2>Configuring SCIM Sub-Resource Type Handlers</h2>
 *
 * In order to configure a SCIM Sub-Resource Type Handler created using this
 * API, use a command like:
 * <pre>
 *      dsconfig create-scim-sub-resource-type-handler \
 *           --type-name "<i>{parent-resource-type}</i> \
 *           ---handler-name "<i>{name}</i>" \
 *           --type third-party \
 *           --set enabled:true \
 *           --set "endpoint:<i>{endpoint}</i>" \
 *           --set "extension-class:<i>{class-name}</i>" \
 *           --set "extension-argument:<i>{name=value}</i>"
 * </pre>
 * where "<i>{parent-resource-type}</i>" is the name of the parent SCIM
 * Resource Type (such as "Users"), "<i>{name}</i>" is the name to use for the
 * SCIM Sub-Resource Type Handler instance, "<i>{endpoint}</i>" is the HTTP
 * addressable endpoint of the SCIM sub-resource type relative to the base
 * resource URL, "<i>{class-name}</i>" is the fully-qualified name of the Java
 * class that extends
 * {@code com.unboundid.directory.sdk.scim2.api.SCIMSubResourceTypeHandler},
 * and "<i>{name=value}</i>" represents name-value pairs for any arguments to
 * provide to the SCIM Sub-Resource Type Handler. If multiple arguments should
 * be provided to the extension, then the
 * "<code>--set extension-argument:<i>{name=value}</i></code>" option should be
 * provided multiple times.
 */
@Extensible()
@BrokerExtension()
public abstract class SCIMSubResourceTypeHandler
    implements UnboundIDExtension,
    Reconfigurable<SCIMSubResourceTypeHandlerConfig>, ExampleUsageProvider
{
  /**
   * {@inheritDoc}
   */
  @Override
  public abstract String getExtensionName();

  /**
   * {@inheritDoc}
   */
  @Override
  public abstract String[] getExtensionDescription();

  /**
   * {@inheritDoc}
   */
  @Override
  public void defineConfigArguments(final ArgumentParser parser)
      throws ArgumentException
  {
    // No arguments will be allowed by default.
  }

  /**
   * {@inheritDoc}
   */
  @Override
  public Map<List<String>, String> getExamplesArgumentSets()
  {
    // No example arguments will be provided by default.
    return null;
  }

  /**
   * {@inheritDoc}
   */
  @Override
  public boolean isConfigurationAcceptable(
      final SCIMSubResourceTypeHandlerConfig config,
      final ArgumentParser parser,

      final List<String> unacceptableReasons)
  {
    // No extended validation will be performed by default.
    return true;
  }

  /**
   * {@inheritDoc}
   */
  @Override
  public ResultCode applyConfiguration(
      final SCIMSubResourceTypeHandlerConfig config,
      final ArgumentParser parser,
      final List<String> adminActionsRequired,
      final List<String> messages)
  {
    // By default, no configuration changes will be applied. If there are any
    // arguments, then add an admin action message indicating that the extension
    // needs to be restarted for any changes to take effect.
    if (!parser.getNamedArguments().isEmpty())
    {
      adminActionsRequired.add(
          "No configuration change has actually been applied. The new " +
              "configuration will not take effect until this SCIM " +
              "Sub-Resource Type Handler is disabled and re-enabled or until " +
              "the server is restarted.");
    }

    return ResultCode.SUCCESS;
  }

  /**
   * Initializes this SCIM Sub-Resource Type Handler.
   *
   * @param serverContext  A handle to the server context for the server in
   *                       which this extension is running.
   * @param config         The configuration for this SCIM Sub-Resource Type
   *                       Handler.
   * @param parser         The argument parser which has been initialized from
   *                       the configuration for this SCIM Sub-Resource Type
   *                       Handler.
   * @throws Exception     If a problem occurs while initializing this SCIM
   *                       Sub-Resource Type Handler.
   */
  public abstract void initializeHandler(
      final SCIMServerContext serverContext,
      final SCIMSubResourceTypeHandlerConfig config,
      final ArgumentParser parser) throws Exception;

  /**
   * Performs any cleanup that might be necessary when this SCIM Sub-Resource
   * Type Handler is taken out of service.
   */
  public void finalizeHandler()
  {
    // Do nothing by default.
  }

  /**
   * Gets the SCIM Sub-Resource Type's core schema.
   *
   * @return The core schema for the SCIM Sub-Resource Type.
   *         This must not return {@code null}.
   */
  public abstract SchemaResource getCoreSchema();

  /**
   * Gets the SCIM Sub-Resource Type's schema extensions, if any.
   * <p>
   * By default, this method will return an empty map, indicating that no
   * schema extensions are supported.
   *
   * @return A map of schema extensions, where each key is a SchemaResource and
   *         the value is a boolean indicating whether the schema extension is
   *         required.
   */
  public Map<SchemaResource, Boolean> getSchemaExtensions()
  {
    return Collections.emptyMap();
  }

  /**
   * Indicates whether the SCIM Sub-Resource Type implemented by this handler
   * is supports one and only one sub-resource per parent resource or supports
   * multiple sub-resources per parent resource.
   *
   * @return True if this SCIM Sub-Resource Type Handler supports multiple
   *         sub-resources per parent resource, or false if it supports a
   *         single sub-resource per parent resource.
   */
  public abstract boolean supportsOneToMany();

  /**
   * Handles SCIM create requests.
   * <p>
   * By default, this method will throw a {@link NotImplementedException} if
   * it is not overridden.
   *
   * @param request         A SCIM create request.
   * @return                The created sub-resource.
   * @throws ScimException  If an error occurs.
   */
  public ScimResource create(final SCIMCreateRequest request)
      throws ScimException
  {
    throw new NotImplementedException(notImplementedMessage("Create"));
  }

  /**
   * Handles SCIM retrieve requests.
   * <p>
   * By default, this method will throw a {@link NotImplementedException} if
   * it is not overridden.
   *
   * @param request         A SCIM retrieve request.
   * @return                The retrieved sub-resource.
   * @throws ScimException  If an error occurs.
   */
  public ScimResource retrieve(final SCIMRetrieveRequest request)
      throws ScimException
  {
    throw new NotImplementedException(notImplementedMessage("Retrieve"));
  }

  /**
   * Handles SCIM modify requests.
   * <p>
   * By default, this method will throw a {@link NotImplementedException} if
   * it is not overridden.
   *
   * @param request         A SCIM modify request.
   * @return                The modified sub-resource.
   * @throws ScimException  If an error occurs.
   */
  public ScimResource modify(final SCIMModifyRequest request)
      throws ScimException
  {
    throw new NotImplementedException(notImplementedMessage("Modify"));
  }

  /**
   * Handles SCIM replace requests.
   * <p>
   * By default, this method will throw a {@link NotImplementedException} if
   * it is not overridden.
   *
   * @param request         A SCIM replace request.
   * @return                The replaced sub-resource.
   * @throws ScimException  If an error occurs.
   */
  public ScimResource replace(final SCIMReplaceRequest request)
      throws ScimException
  {
    throw new NotImplementedException(notImplementedMessage("Replace"));
  }

  /**
   * Handles SCIM delete requests.
   * <p>
   * By default, this method will throw a {@link NotImplementedException} if
   * it is not overridden.
   *
   * @param request         A SCIM delete request.
   * @throws ScimException  If an error occurs.
   */
  public void delete(final SCIMDeleteRequest request)
      throws ScimException
  {
    throw new NotImplementedException(notImplementedMessage("Delete"));
  }

  /**
   * Handles SCIM search requests.
   * <p>
   * By default, this method will throw a {@link NotImplementedException} if
   * it is not overridden.
   *
   * @param request         A SCIM search request.
   * @throws ScimException  If an error occurs.
   */
  public void search(final SCIMSearchRequest request)
      throws ScimException
  {
    throw new NotImplementedException(notImplementedMessage("Search"));
  }

  /**
   * Returns a human-readable message to be used when throwing a
   * {@link NotImplementedException}.
   *
   * @param operationType  The SCIM operation type, such as "Retrieve".
   *
   * @return               A human-readable message to be used when throwing a
   *                       {@link NotImplementedException}.
   */
  private String notImplementedMessage(final String operationType)
  {
    return String.format("%s operations are not supported by the '%s' " +
            "sub-resource", operationType, getExtensionName());
  }
}