/*
 * 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
 * trunk/ds/resource/legal-notices/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
 * trunk/ds/resource/legal-notices/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 2013-2015 UnboundID Corp.
 */
package com.unboundid.directory.sdk.broker.api;

import com.unboundid.directory.sdk.broker.config.StoreAdapterConfig;
import com.unboundid.directory.sdk.broker.internal.IdentityBrokerExtension;
import com.unboundid.directory.sdk.http.types.AuthenticationException;
import com.unboundid.directory.sdk.http.types.AuthenticationRequest;
import com.unboundid.directory.sdk.broker.types.IdentityBrokerContext;
import com.unboundid.directory.sdk.broker.types.MetaDataMods;
import com.unboundid.directory.sdk.broker.types.StoreCreateRequest;
import com.unboundid.directory.sdk.broker.types.StoreDeleteRequest;
import com.unboundid.directory.sdk.broker.types.StoreSearchRequest;
import com.unboundid.directory.sdk.broker.types.StoreUpdateRequest;
import com.unboundid.directory.sdk.common.internal.Configurable;
import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
import com.unboundid.scim.data.BaseResource;
import com.unboundid.scim.schema.ResourceDescriptor;
import com.unboundid.scim.sdk.Resources;
import com.unboundid.scim.sdk.SCIMException;
import com.unboundid.scim.sdk.SCIMFilterType;
import com.unboundid.scim.sdk.SCIMQueryAttributes;
import com.unboundid.util.ByteString;
import com.unboundid.util.Extensible;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.ArgumentParser;

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


/**
 * This class defines an API that must be implemented by extensions that need
 * to store user data in some non-LDAP data store. This adapter API is generic
 * and can support a wide range of repositories. When using multiple Identity
 * Broker instances in a deployment, the data store should be accessible from
 * all instances.
 * <p>
 * A Store Adapter can optionally support authentication by implementing the
 * {@code supportsAuthentication()} and
 * {@code authenticate(StoreAuthenticationRequest)} methods.
 * <p>
 * A Store Adapter can also opt to store the Identity Broker user metadata
 * attributes, which contain the consents, OAuth tokens, and consent history,
 * among other things. This metadata is separated into two categories: small
 * and large. Both types are multi-valued and store raw binary values. The
 * main difference is that the "small" metadata will typically contain small
 * binary values and be accessed more frequently, whereas the "large" metadata
 * will contain more sizable values (or a larger number of values) and be
 * accessed less frequently. Implementers should take this into consideration
 * when deciding where to store these metadata attributes.
 * <p>
 * After the StoreAdapter is initialized (via the initializeStoreAdapter()
 * method), all methods will be guarded by a call to {@link #isAvailable()} to
 * make sure that the adapter is currently connected and ready to service
 * requests. If this returns {@code false}, the DataView will return an
 * appropriate 503 response code to clients until the adapter becomes available
 * again.
 * <H2>Configuring Store Adapters</H2>
 * In order to configure a store adapter created using this API, use
 * a command like:
 * <PRE>
 *      dsconfig create-store-adapter \
 *           ---adapter-name "<I>{name}</I>" \
 *           --type third-party \
 *           --set "extension-class:<I>{class-name}</I>" \
 *           --set "extension-argument:<I>{name=value}</I>"
 * </PRE>
 * where "<I>{name}</I>" is the name to use for the token store
 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Java class
 * that extends
 * {@code com.unboundid.directory.sdk.broker.api.StoreAdapter},
 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to
 * provide to the store adapter. If multiple arguments should be
 * provided to extension, then the
 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
 * provided multiple times.
 */
@Extensible()
@IdentityBrokerExtension
@ThreadSafety(level= ThreadSafetyLevel.INTERFACE_THREADSAFE)
public abstract class StoreAdapter implements UnboundIDExtension,
        Configurable, ExampleUsageProvider
{
  /**
   * Creates a new instance of this store adapter.  All
   * implementations must include a default constructor, but any
   * initialization should generally be done in the
   * {@link #initializeStoreAdapter} method.
   */
  public StoreAdapter()
  {
    // No implementation is required.
  }

  /**
   * {@inheritDoc}
   */
  @Override
  public abstract String getExtensionName();

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

  /**
   * {@inheritDoc}
   */
  @Override
  public Map<List<String>,String> getExamplesArgumentSets()
  {
    return Collections.emptyMap();
  }

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

  /**
   * Initializes this store adapter. Any initialization should be performed
   * here. This method should generally store the
   * {@link com.unboundid.directory.sdk.broker.types.IdentityBrokerContext} in
   * a class member so that it can be used elsewhere in the implementation.
   * <p>
   * The default implementation is empty.
   *
   * @param  serverContext  A handle to the server context for the server in
   *                        which this extension is running. Extensions should
   *                        typically store this in a class member.
   * @param  config         The general configuration for this object.
   * @param  parser         The argument parser which has been initialized from
   *                        the configuration for this store adapter.
   * @throws Exception      If a problem occurs while initializing this store
   *                        adapter.
   */
  public void initializeStoreAdapter(final IdentityBrokerContext serverContext,
                                     final StoreAdapterConfig config,
                                     final ArgumentParser parser)
      throws Exception
  {
    // No initialization will be performed by default.
  }

  /**
   * This hook is called when the DataView is disabled or the Identity Broker
   * shuts down. Any clean-up of this store adapter should be performed here.
   * <p>
   * The default implementation is empty.
   */
  public void finalizeStoreAdapter()
  {
    // No implementation is performed by default.
  }

  /**
   * Determines whether this StoreAdapter can handle the provided
   * authentication request. The default implementation returns {@code false},
   * but subclasses may override this if they do support authentication.
   *
   * @param request the class of the authentication request.
   * @return true if the StoreAdapter supports the provided authentication
   *         request, false otherwise.
   */
  public boolean supportsAuthentication(
      final Class<? extends AuthenticationRequest> request)
  {
    return false;
  }

  /**
   * Determines whether this StoreAdapter supports reading and writing the user
   * metadata attributes. The default implementation returns {@code false}, but
   * subclasses may override this if they do support storing the metadata
   * attributes.
   *
   * @return true if the StoreAdapter supports the Broker metadata, false
   *         otherwise.
   */
  public boolean supportsUserMetaData()
  {
    return false;
  }

  /**
   * Authenticate the specified user against the backend data store. The default
   * implementation throws UnsupportedOperationException; subclasses that
   * support authentication should override this.
   *
   * @param scimId the id of the user to authenticate.
   * @param request the authentication request.
   * @return <code>true</code> if authentication succeeds or <code>false</code>
   *         if this StoreAdaptor is unable to support the authentication
   *         request. In this case, other StoreAdaptors that supports the
   *         authentication request will be tried.
   * @throws SCIMException if there is a problem authenticating the user
   * @throws AuthenticationException if authentication fails
   */
  public boolean authenticate(final String scimId,
                              final AuthenticationRequest request)
          throws SCIMException, AuthenticationException
  {
    throw new com.unboundid.scim.sdk.UnsupportedOperationException(
            "This StoreAdapter (" + getExtensionName() + ") is not " +
            "configured to support authentication.");
  }

  /**
   * Determines whether this StoreAdapter is currently available and
   * in-service. This may return {@code false} in the case that all
   * backend servers are down, for example; during this time the DataView
   * will return an appropriate 503 response code to clients.
   *
   * @return {@code true} if the StoreAdapter initialized and connected;
   *         {@code false} otherwise.
   */
  public abstract boolean isAvailable();

  /**
   * Gets a ResourceDescriptor that describes the schema for the objects that
   * will be returned by this StoreAdapter. The StoreAdapter will always be
   * initialized before this method is called, and the {@link #isAvailable()}
   * method will be checked as well.
   *
   * @return a SCIM ResourceDescriptor object. This may not be {@code null}.
   */
  public abstract ResourceDescriptor getNativeSchema();

  /**
   * Fetches the entries that match the specified criteria.
   *
   * @param request the search request
   * @return a collection of SCIM resources that are in the native schema. This
   *         may be empty, but it may not be {@code null}.
   * @throws SCIMException if there is a problem fulfilling the search request
   */
  public abstract Resources<? extends BaseResource> search(
          final StoreSearchRequest request) throws SCIMException;

  /**
   * Create the specified entry in the native data store.
   *
   * @param request the create request
   * @return the resource that was just created, scoped according to the
   *         SCIMQueryAttributes contained in the request
   * @throws SCIMException if there is a problem creating the entry
   */
  public abstract BaseResource create(final StoreCreateRequest request)
          throws SCIMException;

  /**
   * Update the specified entry in the native data store.
   *
   * @param request the update request
   * @return the updated resource, scoped according to the SCIMQueryAttributes
   *         contained in the request
   * @throws SCIMException if there is a problem modifying the entry
   */
  public abstract BaseResource update(final StoreUpdateRequest request)
          throws SCIMException;

  /**
   * Delete the specified entry from the native data store.
   *
   * @param request the delete request
   * @throws SCIMException if there is a problem deleting the entry
   */
  public abstract void delete(final StoreDeleteRequest request)
          throws SCIMException;

  /**
   * Update the user metadata and/or user indexed metadata for the specified
   * user with the specified modifications. At least one of the MetaDataMods
   * parameters will be non-null. The default implementation throws
   * UnsupportedOperationException; subclasses should override this if they
   * support the user metadata attributes.
   *
   * @param scimId       the id of the user whose metadata is to be updated
   * @param metaDataMods the set of modifications to the user metadata
   *                     (may be {@code null})
   * @param indexedMetaDataMods the set of modifications to the indexed metadata
   *                            (may be {@code null})
   * @param largeMetaDataMods the set of modifications to the large metadata
   *                            (may be {@code null})
   * @throws SCIMException if there is a problem updating the metadata
   */
  public void updateUserMetaData(final String scimId,
                                 final MetaDataMods metaDataMods,
                                 final MetaDataMods indexedMetaDataMods,
                                 final MetaDataMods largeMetaDataMods)
          throws SCIMException
  {
    throw new com.unboundid.scim.sdk.UnsupportedOperationException(
            "This StoreAdapter (" + getExtensionName() + ") is not " +
            "configured to store the user metadata attributes.");
  }

  /**
   * Retrieve the user metadata for the specified user. The default
   * implementation throws UnsupportedOperationException; subclasses should
   * override this if they support the user metadata attributes.
   *
   * @param scimId the id of the user
   * @return the set of values for the metadata attribute
   * @throws SCIMException if there is a problem retrieving the metadata
   */
  public Collection<ByteString> getUserMetaData(final String scimId)
          throws SCIMException
  {
    throw new com.unboundid.scim.sdk.UnsupportedOperationException(
            "This StoreAdapter (" + getExtensionName() + ") is not " +
            "configured to store the user metadata attributes.");
  }

  /**
   * Retrieve the user indexed metadata for the specified user. The default
   * implementation throws UnsupportedOperationException; subclasses should
   * override this if they support the user metadata attributes.
   *
   * @param scimId the id of the user
   * @return the set of values for the indexed metadata attribute
   * @throws SCIMException if there is a problem retrieving the large metadata
   */
  public Collection<ByteString> getUserIndexedMetaData(final String scimId)
          throws SCIMException
  {
    throw new com.unboundid.scim.sdk.UnsupportedOperationException(
            "This StoreAdapter (" + getExtensionName() + ") is not " +
            "configured to store the user metadata attributes.");
  }

  /**
   * Retrieve the user large metadata for the specified user. The default
   * implementation throws UnsupportedOperationException; subclasses should
   * override this if they support the user metadata attributes.
   *
   * @param scimId the id of the user
   * @return the set of values for the large metadata attribute
   * @throws SCIMException if there is a problem retrieving the large metadata
   */
  public Collection<ByteString> getUserLargeMetaData(final String scimId)
          throws SCIMException
  {
    throw new com.unboundid.scim.sdk.UnsupportedOperationException(
            "This StoreAdapter (" + getExtensionName() + ") is not " +
            "configured to store the user metadata attributes.");
  }

  /**
   * Retrieve resources that contain the specified user indexed metadata value.
   *
   * @param filterType    The filter type to use.
   * @param value         The user indexed metadata value to search on.
   * @param requestAttrs  The attributes to return.
   *
   * @return  The resources that contain the specified user indexed metadata
   *          value. Guaranteed not to be {@code null}, but could be empty.
   *
   * @throws SCIMException if there is a problem fulfilling the search request
   */
  public Resources<? extends BaseResource> searchIndexedMetaData(
      final SCIMFilterType filterType, final ByteString value,
      final SCIMQueryAttributes requestAttrs)
      throws SCIMException
  {
    throw new com.unboundid.scim.sdk.UnsupportedOperationException(
            "This StoreAdapter (" + getExtensionName() + ") is not " +
            "configured to store the user metadata attributes.");
  }
}