/*
 * 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/opends/resource/legal-notices/OpenDS.LICENSE
 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
 * 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/opends/resource/legal-notices/OpenDS.LICENSE.  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 2009-2010 Sun Microsystems, Inc.
 */

package org.opends.sdk;



import java.util.Collection;
import java.util.Collections;

import org.opends.sdk.requests.Requests;
import org.opends.sdk.requests.SearchRequest;
import org.opends.sdk.responses.SearchResultEntry;
import org.opends.sdk.schema.CoreSchema;

import com.sun.opends.sdk.util.*;



/**
 * The root DSE is a DSA-specific Entry (DSE) and not part of any naming context
 * (or any subtree), and which is uniquely identified by the empty DN.
 * <p>
 * A Directory Server uses the root DSE to provide information about itself
 * using the following set of attributes:
 * <ul>
 * <li>{@code altServer}: alternative Directory Servers
 * <li>{@code namingContexts}: naming contexts
 * <li>{@code supportedControl}: recognized LDAP controls
 * <li>{@code supportedExtension}: recognized LDAP extended operations
 * <li>{@code supportedFeatures}: recognized LDAP features
 * <li>{@code supportedLDAPVersion}: LDAP versions supported
 * <li>{@code supportedSASLMechanisms}: recognized SASL authentication
 * mechanisms
 * <li>{@code supportedAuthPasswordSchemes}: recognized authentication password
 * schemes
 * <li>{@code subschemaSubentry}: the name of the subschema subentry holding the
 * schema controlling the Root DSE
 * <li>{@code vendorName}: the name of the Directory Server implementer
 * <li>{@code vendorVersion}: the version of the Directory Server
 * implementation.
 * </ul>
 * The values provided for these attributes may depend on session- specific and
 * other factors. For example, a server supporting the SASL EXTERNAL mechanism
 * might only list "EXTERNAL" when the client's identity has been established by
 * a lower level.
 * <p>
 * The root DSE may also include a {@code subschemaSubentry} attribute. If it
 * does, the attribute refers to the subschema (sub)entry holding the schema
 * controlling the root DSE. Clients SHOULD NOT assume that this subschema
 * (sub)entry controls other entries held by the server.
 *
 * @see <a href="http://tools.ietf.org/html/rfc4512">RFC 4512 - Lightweight
 *      Directory Access Protocol (LDAP): Directory Information Models </a>
 * @see <a href="http://tools.ietf.org/html/rfc3045">RFC 3045 - Storing Vendor
 *      Information in the LDAP Root DSE </a>
 * @see <a href="http://tools.ietf.org/html/rfc3112">RFC 3112 - LDAP
 *      Authentication Password Schema </a>
 */
public final class RootDSE
{
  private static final AttributeDescription ATTR_ALT_SERVER =
    AttributeDescription.create(CoreSchema.getAltServerAttributeType());

  private static final AttributeDescription ATTR_NAMING_CONTEXTS =
    AttributeDescription.create(CoreSchema.getNamingContextsAttributeType());

  private static final AttributeDescription ATTR_SUBSCHEMA_SUBENTRY =
    AttributeDescription.create(CoreSchema.getSubschemaSubentryAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_AUTH_PASSWORD_SCHEMES =
    AttributeDescription.create(
        CoreSchema.getSupportedAuthPasswordSchemesAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_CONTROL =
    AttributeDescription.create(CoreSchema.getSupportedControlAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_EXTENSION =
    AttributeDescription.create(
        CoreSchema.getSupportedExtensionAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_FEATURE =
    AttributeDescription.create(CoreSchema.getSupportedFeaturesAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_LDAP_VERSION =
    AttributeDescription.create(
        CoreSchema.getSupportedLDAPVersionAttributeType());

  private static final AttributeDescription ATTR_SUPPORTED_SASL_MECHANISMS =
    AttributeDescription.create(
        CoreSchema.getSupportedSASLMechanismsAttributeType());

  private static final AttributeDescription ATTR_VENDOR_NAME =
    AttributeDescription.create(CoreSchema.getVendorNameAttributeType());

  private static final AttributeDescription ATTR_VENDOR_VERSION =
    AttributeDescription.create(CoreSchema.getVendorNameAttributeType());

  private static final SearchRequest SEARCH_REQUEST = Requests
      .newSearchRequest(DN.rootDN(), SearchScope.BASE_OBJECT, Filter
          .getObjectClassPresentFilter(), ATTR_ALT_SERVER.toString(),
          ATTR_NAMING_CONTEXTS.toString(), ATTR_SUPPORTED_CONTROL.toString(),
          ATTR_SUPPORTED_EXTENSION.toString(), ATTR_SUPPORTED_FEATURE
              .toString(), ATTR_SUPPORTED_LDAP_VERSION.toString(),
          ATTR_SUPPORTED_SASL_MECHANISMS.toString(), ATTR_VENDOR_NAME
              .toString(), ATTR_VENDOR_VERSION.toString(),
          ATTR_SUPPORTED_AUTH_PASSWORD_SCHEMES.toString(),
          ATTR_SUBSCHEMA_SUBENTRY.toString(), "*");



  /**
   * Reads the Root DSE from the Directory Server using the provided connection.
   * <p>
   * If the Root DSE is not returned by the Directory Server then the request
   * will fail with an {@link EntryNotFoundException}. More specifically, the
   * returned future will never return {@code null}.
   *
   * @param connection
   *          A connection to the Directory Server whose Root DSE is to be read.
   * @param handler
   *          A result handler which can be used to asynchronously process the
   *          operation result when it is received, may be {@code null}.
   * @return A future representing the result of the operation.
   * @throws UnsupportedOperationException
   *           If the connection does not support search operations.
   * @throws IllegalStateException
   *           If the connection has already been closed, i.e. if {@code
   *           isClosed() == true}.
   * @throws NullPointerException
   *           If the {@code connection} was {@code null}.
   */
  public static FutureResult<RootDSE> readRootDSE(
      final AsynchronousConnection connection,
      final ResultHandler<? super RootDSE> handler)
      throws UnsupportedOperationException, IllegalStateException,
      NullPointerException
  {
    final FutureResultTransformer<SearchResultEntry, RootDSE> future =
      new FutureResultTransformer<SearchResultEntry, RootDSE>(handler)
    {

      @Override
      protected RootDSE transformResult(final SearchResultEntry result)
          throws ErrorResultException
      {
        return new RootDSE(result);
      }

    };

    final FutureResult<SearchResultEntry> innerFuture = connection
        .searchSingleEntry(SEARCH_REQUEST, future);
    future.setFutureResult(innerFuture);
    return future;
  }



  /**
   * Reads the Root DSE from the Directory Server using the provided connection.
   * <p>
   * If the Root DSE is not returned by the Directory Server then the request
   * will fail with an {@link EntryNotFoundException}. More specifically, this
   * method will never return {@code null}.
   *
   * @param connection
   *          A connection to the Directory Server whose Root DSE is to be read.
   * @return The Directory Server's Root DSE.
   * @throws ErrorResultException
   *           If the result code indicates that the request failed for some
   *           reason.
   * @throws InterruptedException
   *           If the current thread was interrupted while waiting.
   * @throws UnsupportedOperationException
   *           If the connection does not support search operations.
   * @throws IllegalStateException
   *           If the connection has already been closed, i.e. if {@code
   *           isClosed() == true}.
   * @throws NullPointerException
   *           If the {@code connection} was {@code null}.
   */
  public static RootDSE readRootDSE(final Connection connection)
      throws ErrorResultException, InterruptedException,
      UnsupportedOperationException, IllegalStateException,
      NullPointerException
  {
    final Entry entry = connection.searchSingleEntry(SEARCH_REQUEST);
    return new RootDSE(entry);
  }



  private final Entry entry;



  /**
   * Creates a new Root DSE instance backed by the provided entry. Modifications
   * made to {@code entry} will be reflected in the returned Root DSE. The
   * returned Root DSE instance is unmodifiable and attempts to use modify any
   * of the returned collections will result in a {@code
   * UnsupportedOperationException}.
   *
   * @param entry
   *          The Root DSE entry.
   * @throws NullPointerException
   *           If {@code entry} was {@code null} .
   */
  public RootDSE(final Entry entry) throws NullPointerException
  {
    Validator.ensureNotNull(entry);
    this.entry = entry;
  }



  /**
   * Returns an unmodifiable list of URIs referring to alternative Directory
   * Servers that may be contacted when the Directory Server becomes
   * unavailable.
   * <p>
   * URIs for Directory Servers implementing the LDAP protocol are written
   * according to RFC 4516. Other kinds of URIs may be provided.
   * <p>
   * If the Directory Server does not know of any other Directory Servers that
   * could be used, the returned list will be empty.
   *
   * @return An unmodifiable list of URIs referring to alternative Directory
   *         Servers, which may be empty.
   * @see <a href="http://tools.ietf.org/html/rfc4516">RFC 4516 - Lightweight
   *      Directory Access Protocol (LDAP): Uniform Resource Locator </a>
   */
  public Collection<String> getAlternativeServers()
  {
    return getMultiValuedAttribute(ATTR_ALT_SERVER, Functions.valueToString());
  }



  /**
   * Returns the entry which backs this Root DSE instance. Modifications made to
   * the returned entry will be reflected in this Root DSE.
   *
   * @return The underlying Root DSE entry.
   */
  public Entry getEntry()
  {
    return entry;
  }



  /**
   * Returns an unmodifiable list of DNs identifying the context prefixes of the
   * naming contexts that the Directory Server masters or shadows (in part or in
   * whole).
   * <p>
   * If the Directory Server does not master or shadow any naming contexts, the
   * returned list will be empty.
   *
   * @return An unmodifiable list of DNs identifying the context prefixes of the
   *         naming contexts, which may be empty.
   */
  public Collection<DN> getNamingContexts()
  {
    return getMultiValuedAttribute(ATTR_NAMING_CONTEXTS, Functions.valueToDN());
  }



  /**
   * Returns a string which represents the DN of the subschema subentry holding
   * the schema controlling the Root DSE.
   * <p>
   * Clients SHOULD NOT assume that this subschema (sub)entry controls other
   * entries held by the Directory Server.
   *
   * @return The DN of the subschema subentry holding the schema controlling the
   *         Root DSE, or {@code null} if the DN is not provided.
   */
  public DN getSubschemaSubentry()
  {
    return getSingleValuedAttribute(ATTR_SUBSCHEMA_SUBENTRY, Functions
        .valueToDN());
  }



  /**
   * Returns an unmodifiable list of supported authentication password schemes
   * which the Directory Server supports.
   * <p>
   * If the Directory Server does not support any authentication password
   * schemes, the returned list will be empty.
   *
   * @return An unmodifiable list of supported authentication password schemes,
   *         which may be empty.
   * @see <a href="http://tools.ietf.org/html/rfc3112">RFC 3112 - LDAP
   *      Authentication Password Schema </a>
   */
  public Collection<String> getSupportedAuthenticationPasswordSchemes()
  {
    return getMultiValuedAttribute(ATTR_SUPPORTED_AUTH_PASSWORD_SCHEMES,
        Functions.valueToString());
  }



  /**
   * Returns an unmodifiable list of object identifiers identifying the request
   * controls that the Directory Server supports.
   * <p>
   * If the Directory Server does not support any request controls, the returned
   * list will be empty. Object identifiers identifying response controls may
   * not be listed.
   *
   * @return An unmodifiable list of object identifiers identifying the request
   *         controls, which may be empty.
   */
  public Collection<String> getSupportedControls()
  {
    return getMultiValuedAttribute(ATTR_SUPPORTED_CONTROL, Functions
        .valueToString());
  }



  /**
   * Returns an unmodifiable list of object identifiers identifying the extended
   * operations that the Directory Server supports.
   * <p>
   * If the Directory Server does not support any extended operations, the
   * returned list will be empty.
   * <p>
   * An extended operation generally consists of an extended request and an
   * extended response but may also include other protocol data units (such as
   * intermediate responses). The object identifier assigned to the extended
   * request is used to identify the extended operation. Other object
   * identifiers used in the extended operation may not be listed as values of
   * this attribute.
   *
   * @return An unmodifiable list of object identifiers identifying the extended
   *         operations, which may be empty.
   */
  public Collection<String> getSupportedExtendedOperations()
  {
    return getMultiValuedAttribute(ATTR_SUPPORTED_EXTENSION, Functions
        .valueToString());
  }



  /**
   * Returns an unmodifiable list of object identifiers identifying elective
   * features that the Directory Server supports.
   * <p>
   * If the server does not support any discoverable elective features, the
   * returned list will be empty.
   *
   * @return An unmodifiable list of object identifiers identifying the elective
   *         features, which may be empty.
   */
  public Collection<String> getSupportedFeatures()
  {
    return getMultiValuedAttribute(ATTR_SUPPORTED_FEATURE, Functions
        .valueToString());
  }



  /**
   * Returns an unmodifiable list of the versions of LDAP that the Directory
   * Server supports.
   *
   * @return An unmodifiable list of the versions.
   */
  public Collection<Integer> getSupportedLDAPVersions()
  {
    return getMultiValuedAttribute(ATTR_SUPPORTED_LDAP_VERSION, Functions
        .valueToInteger());
  }



  /**
   * Returns an unmodifiable list of the SASL mechanisms that the Directory
   * Server recognizes and/or supports.
   * <p>
   * The contents of the returned list may depend on the current session state
   * and may be empty if the Directory Server does not support any SASL
   * mechanisms.
   *
   * @return An unmodifiable list of the SASL mechanisms, which may be empty.
   * @see <a href="http://tools.ietf.org/html/rfc4513">RFC 4513 - Lightweight
   *      Directory Access Protocol (LDAP): Authentication Methods and Security
   *      Mechanisms </a>
   * @see <a href="http://tools.ietf.org/html/rfc4422">RFC 4422 - Simple
   *      Authentication and Security Layer (SASL) </a>
   */
  public Collection<String> getSupportedSASLMechanisms()
  {
    return getMultiValuedAttribute(ATTR_SUPPORTED_SASL_MECHANISMS, Functions
        .valueToString());
  }



  /**
   * Returns a string which represents the name of the Directory Server
   * implementer.
   *
   * @return The name of the Directory Server implementer, or {@code null} if
   *         the vendor name is not provided.
   * @see <a href="http://tools.ietf.org/html/rfc3045">RFC 3045 - Storing Vendor
   *      Information in the LDAP Root DSE </a>
   */
  public String getVendorName()
  {
    return getSingleValuedAttribute(ATTR_VENDOR_NAME, Functions.valueToString());
  }



  /**
   * Returns a string which represents the version of the Directory Server
   * implementation.
   * <p>
   * Note that this value is typically a release value comprised of a string
   * and/or a string of numbers used by the developer of the LDAP server
   * product. The returned string will be unique between two versions of the
   * Directory Server, but there are no other syntactic restrictions on the
   * value or the way it is formatted.
   *
   * @return The version of the Directory Server implementation, or {@code null}
   *         if the vendor version is not provided.
   * @see <a href="http://tools.ietf.org/html/rfc3045">RFC 3045 - Storing Vendor
   *      Information in the LDAP Root DSE </a>
   */
  public String getVendorVersion()
  {
    return getSingleValuedAttribute(ATTR_VENDOR_VERSION, Functions
        .valueToString());
  }



  private <N> Collection<N> getMultiValuedAttribute(
      final AttributeDescription attributeDescription,
      final Function<ByteString, N, Void> function)
  {
    // The returned collection is unmodifiable because we may need to
    // return an empty collection if the attribute does not exist in the
    // underlying entry. If a value is then added to the returned empty
    // collection it would require that an attribute is created in the
    // underlying entry in order to maintain consistency.
    final Attribute attr = entry.getAttribute(attributeDescription);
    if (attr != null)
    {
      return Collections.unmodifiableCollection(Collections2.transformedCollection(attr,
          function, Functions.objectToByteString()));
    }
    else
    {
      return Collections.emptySet();
    }
  }



  private <N> N getSingleValuedAttribute(
      final AttributeDescription attributeDescription,
      final Function<ByteString, N, Void> function)
  {
    final Attribute attr = entry.getAttribute(attributeDescription);
    if (attr == null || attr.isEmpty())
    {
      return null;
    }
    else
    {
      return function.apply(attr.firstValue(), null);
    }
  }

}