Class LDAPURL

  • All Implemented Interfaces:
    java.io.Serializable

    @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class LDAPURL
    extends java.lang.Object
    implements java.io.Serializable
    This class provides a data structure for interacting with LDAP URLs. It may be used to encode and decode URLs, as well as access the various elements that they contain. Note that this implementation currently does not support the use of extensions in an LDAP URL.

    The components that may be included in an LDAP URL include:
    • Scheme -- This specifies the protocol to use when communicating with the server. The official LDAP URL specification only allows a scheme of "ldap", but this implementation also supports the use of the "ldaps" scheme to indicate that clients should attempt to perform SSL-based communication with the target server (LDAPS) rather than unencrypted LDAP. It will also accept "ldapi", which is LDAP over UNIX domain sockets, although the LDAP SDK does not directly support that mechanism of communication.
    • Host -- This specifies the address of the directory server to which the URL refers. If no host is provided, then it is expected that the client has some prior knowledge of the host (it often implies the same server from which the URL was retrieved).
    • Port -- This specifies the port of the directory server to which the URL refers. If no host or port is provided, then it is assumed that the client has some prior knowledge of the instance to use (it often implies the same instance from which the URL was retrieved). If a host is provided without a port, then it should be assumed that the standard LDAP port of 389 should be used (or the standard LDAPS port of 636 if the scheme is "ldaps", or a value of 0 if the scheme is "ldapi").
    • Base DN -- This specifies the base DN for the URL. If no base DN is provided, then a default of the null DN should be assumed.
    • Requested attributes -- This specifies the set of requested attributes for the URL. If no attributes are specified, then the behavior should be the same as if no attributes had been provided for a search request (i.e., all user attributes should be included).

      In the string representation of an LDAP URL, the names of the requested attributes (if more than one is provided) should be separated by commas.
    • Scope -- This specifies the scope for the URL. It should be one of the standard scope values as defined in the SearchRequest class. If no scope is provided, then it should be assumed that a scope of SearchScope.BASE should be used.

      In the string representation, the names of the scope values that are allowed include:
    • Filter -- This specifies the filter for the URL. If no filter is provided, then a default of "(objectClass=*)" should be assumed.
    An LDAP URL encapsulates many of the properties of a search request, and in fact the toSearchRequest() method may be used to create a SearchRequest object from an LDAP URL.

    See RFC 4516 for a complete description of the LDAP URL syntax. Some examples of LDAP URLs include:
    • ldap:// -- This is the smallest possible LDAP URL that can be represented. The default values will be used for all components other than the scheme.
    • ldap://server.example.com:1234/dc=example,dc=com?cn,sn?sub?(uid=john) -- This is an example of a URL containing all of the elements. The scheme is "ldap", the host is "server.example.com", the port is "1234", the base DN is "dc=example,dc=com", the requested attributes are "cn" and "sn", the scope is "sub" (which indicates a subtree scope equivalent to SearchScope.SUB), and a filter of "(uid=john)".
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int DEFAULT_LDAP_PORT
      The default port number that will be used for LDAP URLs if none is provided.
      static int DEFAULT_LDAPI_PORT
      The default port number that will be used for LDAPI URLs if none is provided.
      static int DEFAULT_LDAPS_PORT
      The default port number that will be used for LDAPS URLs if none is provided.
    • Constructor Summary

      Constructors 
      Constructor Description
      LDAPURL​(java.lang.String urlString)
      Creates a new LDAP URL from the provided string representation.
      LDAPURL​(java.lang.String scheme, java.lang.String host, java.lang.Integer port, DN baseDN, java.lang.String[] attributes, SearchScope scope, Filter filter)
      Creates a new LDAP URL with the provided information.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean attributesProvided()
      Indicates whether the URL explicitly included an attribute list.
      boolean baseDNProvided()
      Indicates whether the URL explicitly included a base DN.
      boolean equals​(java.lang.Object o)
      Indicates whether the provided object is equal to this LDAP URL.
      boolean filterProvided()
      Indicates whether the URL explicitly included a search filter.
      java.lang.String[] getAttributes()
      Retrieves the attribute list for this LDAP URL.
      DN getBaseDN()
      Retrieves the base DN for this LDAP URL.
      Filter getFilter()
      Retrieves the filter for this LDAP URL.
      java.lang.String getHost()
      Retrieves the host for this LDAP URL.
      int getPort()
      Retrieves the port for this LDAP URL.
      java.lang.String getScheme()
      Retrieves the scheme for this LDAP URL.
      SearchScope getScope()
      Retrieves the scope for this LDAP URL.
      int hashCode()
      Retrieves a hash code for this LDAP URL.
      boolean hostProvided()
      Indicates whether the URL explicitly included a host address.
      static java.lang.String percentDecode​(java.lang.String s)
      Decodes any percent-encoded values that may be contained in the provided string.
      boolean portProvided()
      Indicates whether the URL explicitly included a port number.
      boolean scopeProvided()
      Indicates whether the URL explicitly included a search scope.
      java.lang.String toNormalizedString()
      Retrieves a normalized string representation of this LDAP URL.
      void toNormalizedString​(java.lang.StringBuilder buffer)
      Appends a normalized string representation of this LDAP URL to the provided buffer.
      SearchRequest toSearchRequest()
      Creates a search request containing the base DN, scope, filter, and requested attributes from this LDAP URL.
      java.lang.String toString()
      Retrieves a string representation of this LDAP URL.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • LDAPURL

        public LDAPURL​(@NotNull
                       java.lang.String urlString)
                throws LDAPException
        Creates a new LDAP URL from the provided string representation.
        Parameters:
        urlString - The string representation for this LDAP URL. It must not be null.
        Throws:
        LDAPException - If the provided URL string cannot be parsed as an LDAP URL.
      • LDAPURL

        public LDAPURL​(@NotNull
                       java.lang.String scheme,
                       @Nullable
                       java.lang.String host,
                       @Nullable
                       java.lang.Integer port,
                       @Nullable
                       DN baseDN,
                       @Nullable
                       java.lang.String[] attributes,
                       @Nullable
                       SearchScope scope,
                       @Nullable
                       Filter filter)
                throws LDAPException
        Creates a new LDAP URL with the provided information.
        Parameters:
        scheme - The scheme for this LDAP URL. It must not be null and must be either "ldap", "ldaps", or "ldapi".
        host - The host for this LDAP URL. It may be null if no host is to be included.
        port - The port for this LDAP URL. It may be null if no port is to be included. If it is provided, it must be between 1 and 65535, inclusive.
        baseDN - The base DN for this LDAP URL. It may be null if no base DN is to be included.
        attributes - The set of requested attributes for this LDAP URL. It may be null or empty if no attribute list is to be included.
        scope - The scope for this LDAP URL. It may be null if no scope is to be included. Otherwise, it must be a value between zero and three, inclusive.
        filter - The filter for this LDAP URL. It may be null if no filter is to be included.
        Throws:
        LDAPException - If there is a problem with any of the provided arguments.
    • Method Detail

      • percentDecode

        @NotNull
        public static java.lang.String percentDecode​(@NotNull
                                                     java.lang.String s)
                                              throws LDAPException
        Decodes any percent-encoded values that may be contained in the provided string.
        Parameters:
        s - The string to be decoded.
        Returns:
        The percent-decoded form of the provided string.
        Throws:
        LDAPException - If a problem occurs while attempting to decode the provided string.
      • getScheme

        @NotNull
        public java.lang.String getScheme()
        Retrieves the scheme for this LDAP URL. It will either be "ldap", "ldaps", or "ldapi".
        Returns:
        The scheme for this LDAP URL.
      • getHost

        @Nullable
        public java.lang.String getHost()
        Retrieves the host for this LDAP URL.
        Returns:
        The host for this LDAP URL, or null if the URL does not include a host and the client is supposed to have some external knowledge of what the host should be.
      • hostProvided

        public boolean hostProvided()
        Indicates whether the URL explicitly included a host address.
        Returns:
        true if the URL explicitly included a host address, or false if it did not.
      • getPort

        public int getPort()
        Retrieves the port for this LDAP URL.
        Returns:
        The port for this LDAP URL.
      • portProvided

        public boolean portProvided()
        Indicates whether the URL explicitly included a port number.
        Returns:
        true if the URL explicitly included a port number, or false if it did not and the default should be used.
      • getBaseDN

        @NotNull
        public DN getBaseDN()
        Retrieves the base DN for this LDAP URL.
        Returns:
        The base DN for this LDAP URL.
      • baseDNProvided

        public boolean baseDNProvided()
        Indicates whether the URL explicitly included a base DN.
        Returns:
        true if the URL explicitly included a base DN, or false if it did not and the default should be used.
      • getAttributes

        @NotNull
        public java.lang.String[] getAttributes()
        Retrieves the attribute list for this LDAP URL.
        Returns:
        The attribute list for this LDAP URL.
      • attributesProvided

        public boolean attributesProvided()
        Indicates whether the URL explicitly included an attribute list.
        Returns:
        true if the URL explicitly included an attribute list, or false if it did not and the default should be used.
      • scopeProvided

        public boolean scopeProvided()
        Indicates whether the URL explicitly included a search scope.
        Returns:
        true if the URL explicitly included a search scope, or false if it did not and the default should be used.
      • getFilter

        @NotNull
        public Filter getFilter()
        Retrieves the filter for this LDAP URL.
        Returns:
        The filter for this LDAP URL.
      • filterProvided

        public boolean filterProvided()
        Indicates whether the URL explicitly included a search filter.
        Returns:
        true if the URL explicitly included a search filter, or false if it did not and the default should be used.
      • toSearchRequest

        @NotNull
        public SearchRequest toSearchRequest()
        Creates a search request containing the base DN, scope, filter, and requested attributes from this LDAP URL.
        Returns:
        The search request created from the base DN, scope, filter, and requested attributes from this LDAP URL.
      • hashCode

        public int hashCode()
        Retrieves a hash code for this LDAP URL.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        A hash code for this LDAP URL.
      • equals

        public boolean equals​(@Nullable
                              java.lang.Object o)
        Indicates whether the provided object is equal to this LDAP URL. In order to be considered equal, the provided object must be an LDAP URL with the same normalized string representation.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - The object for which to make the determination.
        Returns:
        true if the provided object is equal to this LDAP URL, or false if not.
      • toString

        @NotNull
        public java.lang.String toString()
        Retrieves a string representation of this LDAP URL.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representation of this LDAP URL.
      • toNormalizedString

        @NotNull
        public java.lang.String toNormalizedString()
        Retrieves a normalized string representation of this LDAP URL.
        Returns:
        A normalized string representation of this LDAP URL.
      • toNormalizedString

        public void toNormalizedString​(@NotNull
                                       java.lang.StringBuilder buffer)
        Appends a normalized string representation of this LDAP URL to the provided buffer.
        Parameters:
        buffer - The buffer to which to append the normalized string representation of this LDAP URL.