Package org.forgerock.opendj.ldap

Class LdapUrl

  • public final class LdapUrl
extends Object
    An LDAP URL as defined in RFC 4516. In addition, the secure ldap (ldaps://) is also supported. LDAP URLs have the following format: 
     "ldap[s]://" [ hostName [":" portNumber] ]
          "/" distinguishedName
          ["?" attributeList
              ["?" scope "?" filterString ] ]
    Where:
    • all text within double-quotes are literal
    • hostName and portNumber identify the location of the LDAP server.
    • distinguishedName is the name of an entry within the given directory (the entry represents the starting point of the search).
    • attributeList contains a list of attributes to retrieve (if null, fetch all attributes). This is a comma-delimited list of attribute names.
    • scope is one of the following:
      • base indicates that this is a search only for the specified entry
      • one indicates that this is a search for matching entries one level under the specified entry (and not including the entry itself)
      • sub indicates that this is a search for matching entries at all levels under the specified entry (including the entry itself)
      • subordinates indicates that this is a search for matching entries all levels under the specified entry (excluding the entry itself)
      If not specified, scope is base by default.
    • filterString is a human-readable representation of the search criteria. If no filter is provided, then a default of " (objectClass=*)" should be assumed.
    The same encoding rules for other URLs (e.g. HTTP) apply for LDAP URLs. Specifically, any "illegal" characters are escaped with %HH, where HH represent the two hex digits which correspond to the ASCII value of the character. This encoding is only legal (or necessary) on the DN and filter portions of the URL.

    Note that this class does not implement extensions.

    See Also:
    RFC 4516 - Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator

    • Constructor Detail

      • LdapUrl

        public LdapUrl​(boolean isSecured,
               String host,
               Integer port,
               Dn name)
        Creates a new LDAP URL referring to a single entry on the specified server. The LDAP URL with have base object scope and the filter (objectClass=*).
        Parameters:
        isSecured - true if this LDAP URL should use LDAPS or false if it should use LDAP.
        host - The name or IP address in dotted format of the LDAP server. For example, ldap.server1.com or 192.202.185.90. Use null for the local host.
        port - The port number of the LDAP server, or null to use the default port (389 for LDAP and 636 for LDAPS).
        name - The distinguished name of the base entry relative to which the search is to be performed, or null to specify the root DSE.
        Throws:
        LocalizedIllegalArgumentException - If port was less than 1 or greater than 65535.

      • LdapUrl

        public LdapUrl​(boolean isSecured,
               String host,
               Integer port,
               Dn name,
               SearchScope scope,
               Filter filter,
               String... attributes)
        Creates a new LDAP URL including the full set of parameters for a search request.
        Parameters:
        isSecured - true if this LDAP URL should use LDAPS or false if it should use LDAP.
        host - The name or IP address in dotted format of the LDAP server. For example, ldap.server1.com or 192.202.185.90. Use null for the local host.
        port - The port number of the LDAP server, or null to use the default port (389 for LDAP and 636 for LDAPS).
        name - The distinguished name of the base entry relative to which the search is to be performed, or null to specify the root DSE.
        scope - The search scope, or null to specify base scope.
        filter - The search filter, or null to specify the filter (objectClass=*).
        attributes - The list of attributes to be included in the search results.
        Throws:
        LocalizedIllegalArgumentException - If port was less than 1 or greater than 65535.

    • Method Detail

      • valueOf

        public static LdapUrl valueOf​(String url)
        Parses the provided LDAP string representation of an LDAP URL using the default schema.
        Parameters:
        url - The LDAP string representation of an LDAP URL.
        Returns:
        The parsed LDAP URL.
        Throws:
        LocalizedIllegalArgumentException - If url is not a valid LDAP string representation of an LDAP URL.
        NullPointerException - If url was null.

      • valueOf

        public static LdapUrl valueOf​(String url,
                              Schema schema)
        Parses the provided LDAP string representation of an LDAP URL using the provided schema.
        Parameters:
        url - The LDAP string representation of an LDAP URL.
        schema - The schema to use when parsing the LDAP URL.
        Returns:
        The parsed LDAP URL.
        Throws:
        LocalizedIllegalArgumentException - If url is not a valid LDAP string representation of an LDAP URL.
        NullPointerException - If url or schema was null.

      • asSearchRequest

        public SearchRequest asSearchRequest()
        Creates a new search request containing the parameters of this LDAP URL.
        Returns:
        A new search request containing the parameters of this LDAP URL.

      • getAttributes

        public List<String> getAttributes()
        Returns an unmodifiable list containing the attributes to be included with each entry that matches the search criteria. Attributes that are sub-types of listed attributes are implicitly included. If the returned list is empty then all user attributes will be included by default.
        Returns:
        An unmodifiable list containing the attributes to be included with each entry that matches the search criteria.

      • getFilter

        public Filter getFilter()
        Returns the search filter associated with this LDAP URL.
        Returns:
        The search filter associated with this LDAP URL.

      • getHost

        public String getHost()
        Returns the name or IP address in dotted format of the LDAP server referenced by this LDAP URL. For example, ldap.server1.com or 192.202.185.90. Use null for the local host.
        Returns:
        A name or IP address in dotted format of the LDAP server referenced by this LDAP URL.

      • getName

        public Dn getName()
        Returns the distinguished name of the base entry relative to which the search is to be performed.
        Returns:
        The distinguished name of the base entry relative to which the search is to be performed.

      • getPort

        public int getPort()
        Returns the port number of the LDAP server referenced by this LDAP URL.
        Returns:
        The port number of the LDAP server referenced by this LDAP URL.

      • getScope

        public SearchScope getScope()
        Returns the search scope associated with this LDAP URL.
        Returns:
        The search scope associated with this LDAP URL.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • isSecure

        public boolean isSecure()
        Returns true if this LDAP URL should use LDAPS or false if it should use LDAP.
        Returns:
        true if this LDAP URL should use LDAPS or false if it should use LDAP.