/*
 * 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 2013-2015 UnboundID Corp.
 */

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

import com.unboundid.directory.sdk.broker.internal.IdentityBrokerExtension;
import com.unboundid.directory.sdk.broker.types.IdentityBrokerContext;
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.broker.config.
    PolicyInformationProviderConfig;
import com.unboundid.directory.sdk.broker.types.RequestAttribute;
import com.unboundid.directory.sdk.broker.types.RequestContext;
import com.unboundid.ldap.sdk.ResultCode;
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.Collections;
import java.util.List;
import java.util.Map;


/**
 * This class defines an API that must be implemented by Identity Broker
 * extensions that retrieve XACML attributes as part of the Policy Information
 * Point (PIP).
 *
 * <H2>Configuring Policy Information Providers</H2>
 * In order to configure a policy information provider created using this API,
 * use a command like:
 *
 * <PRE>
 *      dsconfig create-policy-information-provider \
 *           --provider-name "<I>{name}</I>" \
 *           --type third-party \
 *           --set enabled:true \
 *           --set "extension-class:<I>{class-name}</I>" \
 *           --set "extension-argument:<I>{name=value}</I>" \
 *           --set "xacml-attribute-id:<I>{attributeId}</I> \
 *           --set "evaluation-order-index:<I>{index}</I>
 * </PRE>
 * where "<I>{name}</I>" is the name to use for the policy information provider
 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Java
 * class that extends
 * {@code com.unboundid.directory.sdk.broker.api.PolicyInformationProvider},
 * "<I>{index}</I>" is an integer from 1 to 9999 that is used to determine the
 * position of this Policy Information Provider in the order of evaluation
 * among all Policy Information Providers, "<I>{attributeId}</I>" identifies
 * the XACML attribute(s) that this provider knows how to retrieve, and
 * "<I>{name=value}</I>" represents name-value pairs for any additional
 * arguments to provide to the Policy Information Provider. 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.  If the Policy Information Provider can retrieve
 * more than one attribute type, then the
 * "<CODE>--set xacml-attribute-id:<I>{attributeId}</I></CODE>" option can also
 * be provided multiple times.
 */
@Extensible()
@IdentityBrokerExtension()
@ThreadSafety(level= ThreadSafetyLevel.INTERFACE_THREADSAFE)
public abstract class PolicyInformationProvider
    implements UnboundIDExtension,
       Reconfigurable<PolicyInformationProviderConfig>,
       ExampleUsageProvider
{

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

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


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


  /**
   * Initializes this policy information provider.
   *
   * @param  serverContext  A handle to the server context for the server in
   *                        which this extension is running.
   * @param  config         The general configuration for this policy
   *                        information provider.
   * @param  parser         The argument parser which has been initialized from
   *                        the configuration for this policy information
   *                        provider.
   *
   * @throws Exception      If a problem occurs while initializing this
   *                        policy information provider.
   */
  public void initializePolicyInformationProvider(
      final IdentityBrokerContext serverContext,
      final PolicyInformationProviderConfig config,
      final ArgumentParser parser)
      throws Exception
  {
    // No initialization will be performed by default.
  }


  /**
   * {@inheritDoc}
   */
  public boolean isConfigurationAcceptable(
      final PolicyInformationProviderConfig config,
      final ArgumentParser parser,
      final List<String> unacceptableReasons)
  {

    // No extended validation will be performed by default.
    return true;
  }


  /**
   * {@inheritDoc}
   */
  public ResultCode applyConfiguration(
      final PolicyInformationProviderConfig 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 policy " +
              "information provider is disabled and re-enabled or until " +
              "the server is restarted.");
    }
    return ResultCode.SUCCESS;

  }


  /**
   * Performs any cleanup which may be necessary when this policy information
   * provider is to be taken out of service.
   */
  public void finalizePolicyInformationProvider()
  {
    // no implementation is required
  }


  /**
   * Retrieve an attribute that has been requested by the policy engine.
   * @param categoryId XACML category identifier.  This is the category Id
   *                   specified by the AttributeDesignator element in the
   *                   policy that is requesting this attribute.
   * @param attributeId XACML attribute identifier.  This will be one of the
   *                   identifiers specified by the xacml-attribute-id
   *                   property of the configuration for this Policy
   *                   Information Provider.
   * @param context request context, can be used to retrieve other
   *                attributes from the request that may be needed
   *                in order to evaluate the requested attribute
   * @return RequestAttribute object containing the requested attribute,
   *                never null.
   * @throws Exception if an error occurs retrieving the attribute
   */
  public abstract RequestAttribute getAttribute(
      final String categoryId,
      final String attributeId,
      RequestContext context) throws Exception;


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