Package org.forgerock.opendj.ldap

Class RootDse

  • public final class RootDse
extends Object
    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.

    A Directory Server uses the root DSE to provide information about itself using the following set of attributes:

    • altServer: alternative Directory Servers
    • namingContexts: naming contexts
    • supportedControl: recognized LDAP controls
    • supportedExtension: recognized LDAP extended operations
    • supportedFeatures: recognized LDAP features
    • supportedLDAPVersion: LDAP versions supported
    • supportedSASLMechanisms: recognized SASL authentication mechanisms
    • supportedAuthPasswordSchemes: recognized authentication password schemes
    • subschemaSubentry: the name of the subschema subentry holding the schema controlling the Root DSE
    • vendorName: the name of the Directory Server implementer
    • vendorVersion: the version of the Directory Server implementation.
    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.

    The root DSE may also include a 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 Also:
    RFC 4512 - Lightweight Directory Access Protocol (LDAP): Directory Information Models , RFC 3045 - Storing Vendor Information in the LDAP Root DSE , RFC 3112 - LDAP Authentication Password Schema

    • Method Detail

      • readRootDseAsync

        public static LdapPromise<RootDse> readRootDseAsync​(Connection connection)
        Asynchronously reads the Root DSE from the Directory Server using the provided connection.

        If the Root DSE is not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, the returned promise will never return null.

        Parameters:
        connection - A connection to the Directory Server whose Root DSE is to be read.
        Returns:
        A promise representing the result of the operation.
        Throws:
        UnsupportedOperationException - If the connection does not support search operations.
        IllegalStateException - If the connection has already been closed, i.e. if isClosed() == true.
        NullPointerException - If the connection was null.

      • readRootDse

        public static RootDse readRootDse​(Connection connection)
                           throws LdapException
        Reads the Root DSE from the Directory Server using the provided connection.

        If the Root DSE is not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, this method will never return null.

        Parameters:
        connection - A connection to the Directory Server whose Root DSE is to be read.
        Returns:
        The Directory Server's Root DSE.
        Throws:
        LdapException - If the result code indicates that the request failed for some reason.
        UnsupportedOperationException - If the connection does not support search operations.
        IllegalStateException - If the connection has already been closed, i.e. if isClosed() == true.
        NullPointerException - If the connection was null.

      • readRootDse

        public static Single<RootDse> readRootDse​(LdapClientSocket socket)
        Reads the Root DSE from the Directory Server using the provided socket.

        If the Root DSE is not returned by the Directory Server then the request will fail with an EntryNotFoundException.

        Note that the request will only be sent when the returned Single has been subscribed.

        Parameters:
        socket - A socket connected to the Directory Server whose Root DSE is to be read.
        Returns:
        The Directory Server's Root DSE.
        Throws:
        UnsupportedOperationException - If the connection does not support search operations.
        IllegalStateException - If the socket has already been closed, i.e. if isClosed() == true.
        NullPointerException - If the socket was null.

      • valueOf

        public static RootDse valueOf​(Entry entry)
        Creates a new Root DSE instance backed by the provided entry. Modifications made to 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 UnsupportedOperationException.
        Parameters:
        entry - The Root DSE entry.
        Returns:
        A Root DSE instance backed by the provided entry.
        Throws:
        NullPointerException - If entry was null .

      • getAlternativeServers

        public Collection<String> getAlternativeServers()
        Returns an unmodifiable list of URIs referring to alternative Directory Servers that may be contacted when the Directory Server becomes unavailable.

        URIs for Directory Servers implementing the LDAP protocol are written according to RFC 4516. Other kinds of URIs may be provided.

        If the Directory Server does not know of any other Directory Servers that could be used, the returned list will be empty.

        Returns:
        An unmodifiable list of URIs referring to alternative Directory Servers, which may be empty.
        See Also:
        RFC 4516 - Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator

      • getEntry

        public Entry getEntry()
        Returns the entry which backs this Root DSE instance. Modifications made to the returned entry will be reflected in this Root DSE.
        Returns:
        The underlying Root DSE entry.

      • getNamingContexts

        public Collection<Dn> getNamingContexts()
        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).

        If the Directory Server does not master or shadow any naming contexts, the returned list will be empty.

        Returns:
        An unmodifiable list of DNs identifying the context prefixes of the naming contexts, which may be empty.

      • getSubschemaSubentry

        public Dn getSubschemaSubentry()
        Returns a string which represents the DN of the subschema subentry holding the schema controlling the Root DSE.

        Clients SHOULD NOT assume that this subschema (sub)entry controls other entries held by the Directory Server.

        Returns:
        The DN of the subschema subentry holding the schema controlling the Root DSE, or null if the DN is not provided.

      • getSupportedAuthenticationPasswordSchemes

        public Collection<String> getSupportedAuthenticationPasswordSchemes()
        Returns an unmodifiable list of supported authentication password schemes which the Directory Server supports.

        If the Directory Server does not support any authentication password schemes, the returned list will be empty.

        Returns:
        An unmodifiable list of supported authentication password schemes, which may be empty.
        See Also:
        RFC 3112 - LDAP Authentication Password Schema

      • getSupportedControls

        public Collection<String> getSupportedControls()
        Returns an unmodifiable list of object identifiers identifying the request controls that the Directory Server supports.

        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.

        Returns:
        An unmodifiable list of object identifiers identifying the request controls, which may be empty.

      • getSupportedExtendedOperations

        public Collection<String> getSupportedExtendedOperations()
        Returns an unmodifiable list of object identifiers identifying the extended operations that the Directory Server supports.

        If the Directory Server does not support any extended operations, the returned list will be empty.

        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.

        Returns:
        An unmodifiable list of object identifiers identifying the extended operations, which may be empty.

      • getSupportedFeatures

        public Collection<String> getSupportedFeatures()
        Returns an unmodifiable list of object identifiers identifying elective features that the Directory Server supports.

        If the server does not support any discoverable elective features, the returned list will be empty.

        Returns:
        An unmodifiable list of object identifiers identifying the elective features, which may be empty.

      • getSupportedLdapVersions

        public Collection<Integer> getSupportedLdapVersions()
        Returns an unmodifiable list of the versions of LDAP that the Directory Server supports.
        Returns:
        An unmodifiable list of the versions.

      • getVendorVersion

        public String getVendorVersion()
        Returns a string which represents the version of the Directory Server implementation.

        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.

        Returns:
        The version of the Directory Server implementation, or null if the vendor version is not provided.
        See Also:
        RFC 3045 - Storing Vendor Information in the LDAP Root DSE

      • getFullVendorVersion

        public String getFullVendorVersion()
        Returns a string which represents the full version of the Directory Server implementation.
        Returns:
        The full version of the Directory Server implementation, or null if the vendor version is not provided.