Package org.apache.directory.api.ldap.model.url

Class LdapUrl

  • public class LdapUrl
extends Object
    Decodes a LdapUrl, and checks that it complies with the RFC 4516. The grammar is the following : 
     ldapurl    = scheme "://" [host [ ":" port]] ["/"
                   dn ["?" [attributes] ["?" [scope]
                   ["?" [filter] ["?" extensions]]]]]
 scheme     = "ldap"
 dn         = Dn
 attributes = attrdesc ["," attrdesc]*
 attrdesc   = selector ["," selector]*
 selector   = attributeSelector (from Section 4.5.1 of RFC4511)
 scope      = "base" / "one" / "sub"
 extensions = extension ["," extension]*
 extension  = ["!"] extype ["=" exvalue]
 extype     = oid (from Section 1.4 of RFC4512)
 exvalue    = LDAPString (from Section 4.1.2 of RFC4511)
 host       = host from Section 3.2.2 of RFC3986
 port       = port from Section 3.2.3 of RFC3986
 filter     = filter from Section 3 of RFC 4515
    From Section 3.2.1/2 of RFC3986 
     host        = IP-literal / IPv4address / reg-name
 port        = *DIGIT
 IP-literal  = "[" ( IPv6address / IPvFuture  ) "]"
 IPvFuture   = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
 IPv6address = 6( h16 ":" ) ls32 
               | "::" 5( h16 ":" ) ls32
               | [               h16 ] "::" 4( h16 ":" ) ls32
               | [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
               | [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
               | [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
               | [ *4( h16 ":" ) h16 ] "::"              ls32
               | [ *5( h16 ":" ) h16 ] "::"              h16
               | [ *6( h16 ":" ) h16 ] "::"
 IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
 dec-octet   = DIGIT | [1-9] DIGIT | "1" 2DIGIT | "2" [0-4] DIGIT | "25" [0-5]
 reg-name    = *( unreserved / pct-encoded / sub-delims )
 unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
 pct-encoded = "%" HEXDIG HEXDIG
 sub-delims  = "!" | "$" | "&" | "'" | "(" | ")" | "*" | "+" | "," | ";" | "="
 h16         = 1*4HEXDIG
 ls32        = ( h16 ":" h16 ) / IPv4address
 DIGIT       = 0..9
 ALPHA       = A-Z / a-z
 HEXDIG      = DIGIT / A-F / a-f
    Author:
    Apache Directory Project

    • Field Detail

      • EMPTY_URL

        public static final LdapUrl EMPTY_URL
        A null LdapUrl

      • scheme

        private String scheme
        The scheme

      • host

        private String host
        The host

      • port

        private int port
        The port

      • dn

        private Dn dn
        The Dn

      • attributes

        private List<String> attributes
        The attributes

      • filter

        private String filter
        The filter as a string

      • string

        private String string
        Stores the LdapUrl as a String

      • bytes

        private byte[] bytes
        Stores the LdapUrl as a byte array

      • forceScopeRendering

        private boolean forceScopeRendering
        modal parameter that forces explicit scope rendering in toString

      • hostType

        private HostTypeEnum hostType
        The type of host we use

      • ATTRIBUTE

        private static final Pattern ATTRIBUTE
        A regexp for attributes

    • Constructor Detail

      • LdapUrl

        public LdapUrl()
        Construct an empty LdapUrl

      • LdapUrl

        public LdapUrl​(String string)
        throws LdapURLEncodingException
        Create a new LdapUrl from a String after having parsed it.
        Parameters:
        string - TheString that contains the LdapUrl
        Throws:
        LdapURLEncodingException - If the String does not comply with RFC 2255

    • Method Detail

      • parseHost

        private int parseHost​(char[] chars,
                      int pos)
        Parse this rule : 
         host        = IP-literal / IPv4address / reg-name
 port        = *DIGIT
 <host> ::= <hostname> ':' <hostnumber>
 <hostname> ::= *[ <domainlabel> "." ] <toplabel>
 <domainlabel> ::= <alphadigit> | <alphadigit> *[<alphadigit> | "-" ] <alphadigit>
 <toplabel> ::= <alpha> | <alpha> *[ <alphadigit> | "-" ] <alphadigit>
 <hostnumber> ::= <digits> "." <digits> "." <digits> "." <digits>
        Parameters:
        chars - The buffer to parse
        pos - The current position in the byte buffer
        Returns:
        The new position in the byte buffer, or -1 if the rule does not apply to the byte buffer TODO check that the topLabel is valid (it must start with an alpha)

      • parseIpLiteral

        private int parseIpLiteral​(char[] chars,
                           int pos)
        parse these rules : 
         IP-literal  = "[" ( IPv6address / IPvFuture  ) "]"
 IPvFuture   = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
 IPv6address = 6( h16 ":" ) ls32 
               | "::" 5( h16 ":" ) ls32
               | [               h16 ] "::" 4( h16 ":" ) ls32
               | [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
               | [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
               | [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
               | [ *4( h16 ":" ) h16 ] "::"              ls32
               | [ *5( h16 ":" ) h16 ] "::"              h16
               | [ *6( h16 ":" ) h16 ] "::"
 h16         = 1*4HEXDIG
 ls32        = ( h16 ":" h16 ) / IPv4address
        Parameters:
        chars - The chars to parse
        pos - The position in the chars
        Returns:
        The new position, or -1 if we had an error

      • isValidInet4Address

        public boolean isValidInet4Address​(String inet4Address)
        Validates an IPv4 address. Returns true if valid.
        Parameters:
        inet4Address - the IPv4 address to validate
        Returns:
        true if the argument contains a valid IPv4 address

      • isValidInet6Address

        public boolean isValidInet6Address​(String inet6Address)
        This code source was taken from commons.validator 1.5.0 Validates an IPv6 address. Returns true if valid.
        Parameters:
        inet6Address - the IPv6 address to validate
        Returns:
        true if the argument contains a valid IPv6 address
        Since:
        1.4.1

      • parseIPV6

        private int parseIPV6​(char[] chars,
                      int pos)
        Parse the following rules : 
         IPv6address = 6( h16 ":" ) ls32 
               | "::" 5( h16 ":" ) ls32
               | [               h16 ] "::" 4( h16 ":" ) ls32
               | [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
               | [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
               | [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
               | [ *4( h16 ":" ) h16 ] "::"              ls32
               | [ *5( h16 ":" ) h16 ] "::"              h16
               | [ *6( h16 ":" ) h16 ] "::"
 h16         = 1*4HEXDIG
 ls32        = ( h16 ":" h16 ) / IPv4address
        Parameters:
        chars - The chars to parse
        pos - The position in the chars
        Returns:
        The new position, or -1 if we had an error

      • parseIPvFuture

        private int parseIPvFuture​(char[] chars,
                           int pos)
        Parse these rules : 
         IPvFuture   = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
        (the "v" has already been parsed)
        Parameters:
        chars - The chars to parse
        pos - The position in the chars
        Returns:
        The new position, or -1 if we had an error

      • parseRegName

        private int parseRegName​(char[] chars,
                         int pos)
        parse these rules : 
         reg-name    = *( unreserved / pct-encoded / sub-delims )
 unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
 pct-encoded = "%" HEXDIG HEXDIG
 sub-delims  = "!" | "$" | "&" | "'" | "(" | ")" | "*" | "+" | "," | ";" | "="
 HEXDIG      = DIGIT / A-F / a-f
        Parameters:
        chars - The chars to parse
        pos - The position in the chars
        Returns:
        The new position, or -1 if we had an error

      • parseIPV4

        private int parseIPV4​(char[] chars,
                      int pos)
        Parse these rules : 
         IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
 dec-octet   = DIGIT | [1-9] DIGIT | "1" 2DIGIT | "2" [0-4] DIGIT | "25" [0-5]
        Parameters:
        chars - The buffer to parse
        pos - The current position in the byte buffer
        Returns:
        The new position or -1 if this is not an IPV4 address

      • parseDecOctet

        private int parseDecOctet​(char[] chars,
                          int pos,
                          int[] ipElem,
                          int octetNb)
        Parse this rule : 
         dec-octet   = DIGIT | [1-9] DIGIT | "1" 2DIGIT | "2" [0-4] DIGIT | "25" [0-5]
        Parameters:
        chars - The chars to parse
        pos - The position in the chars
        ipElem - The IP elements to update
        octetNb - The IP octet being processed
        Returns:
        The new position, or -1 if the IP octet is invalid

      • parsePort

        private int parsePort​(char[] chars,
                      int pos)
        Parse this rule : 
         <port> ::= <digit>+
 <digit> ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
        The port must be between 0 and 65535.
        Parameters:
        chars - The buffer to parse
        pos - The current position in the byte buffer
        Returns:
        The new position in the byte buffer, or -1 if the rule does not apply to the byte buffer

      • parseHostPort

        private int parseHostPort​(char[] chars,
                          int pos)
        Parse this rule : 
           <hostport> ::= <host> [':' <port>]
        Parameters:
        chars - The char array to parse
        pos - The current position in the byte buffer
        Returns:
        The new position in the byte buffer, or -1 if the rule does not apply to the byte buffer

      • getAsciiBytes

        private static byte[] getAsciiBytes​(String data)
        Converts the specified string to byte array of ASCII characters.
        Parameters:
        data - the string to be encoded
        Returns:
        The string as a byte array.

      • decodeUrl

        private static byte[] decodeUrl​(byte[] bytes)
                         throws UrlDecoderException
        From commons-codec. Decodes an array of URL safe 7-bit characters into an array of original bytes. Escaped characters are converted back to their original representation.
        Parameters:
        bytes - array of URL safe characters
        Returns:
        array of original bytes
        Throws:
        UrlDecoderException - Thrown if URL decoding is unsuccessful

      • decode

        private static String decode​(String escaped)
                      throws LdapUriException
        From commons-httpclients. Unescape and decode a given string regarded as an escaped string with the default protocol charset.
        Parameters:
        escaped - a string
        Returns:
        the unescaped string
        Throws:
        LdapUriException - if the string cannot be decoded (invalid)

      • parseDN

        private int parseDN​(char[] chars,
                    int pos)
        Parse a string and check that it complies with RFC 2253. Here, we will just call the Dn parser to do the job.
        Parameters:
        chars - The char array to be checked
        pos - the starting position
        Returns:
        -1 if the char array does not contains a Dn

      • validateAttribute

        private void validateAttribute​(String attribute)
                        throws LdapURLEncodingException
        Parse the following rule : 
         oid ::= numericOid | descr
 descr ::= keystring
 keystring ::= leadkeychar *keychar
 leadkeychar ::= [a-zA-Z]
 keychar ::= [a-zA-Z0-0-]
 numericOid ::= number 1*( DOT number )
 number ::= 0 | [1-9][0-9]*
        Parameters:
        attribute - The attribute to validate
        Throws:
        LdapURLEncodingException - If teh attribute is invalid

      • parseAttributes

        private int parseAttributes​(char[] chars,
                            int pos)
        Parse the attributes part
        Parameters:
        chars - The char array to be checked
        pos - the starting position
        Returns:
        -1 if the char array does not contains attributes

      • parseFilter

        private int parseFilter​(char[] chars,
                        int pos)
        Parse the filter part. We will use the FilterParserImpl class
        Parameters:
        chars - The char array to be checked
        pos - the starting position
        Returns:
        -1 if the char array does not contains a filter

      • parseScope

        private int parseScope​(char[] chars,
                       int pos)
        Parse the scope part.
        Parameters:
        chars - The char array to be checked
        pos - the starting position
        Returns:
        -1 if the char array does not contains a scope

      • parseExtensions

        private int parseExtensions​(char[] chars,
                            int pos)
        Parse extensions and critical extensions. The grammar is : extensions ::= extension [ ',' extension ]* extension ::= [ '!' ] ( token | ( 'x-' | 'X-' ) token ) ) [ '=' exvalue ]
        Parameters:
        chars - The char array to be checked
        pos - the starting position
        Returns:
        -1 if the char array does not contains valid extensions or critical extensions

      • urlEncode

        public static String urlEncode​(String url,
                               boolean doubleEncode)
        Encode a String to avoid special characters. 
         RFC 4516, section 2.1. (Percent-Encoding)

 A generated LDAP URL MUST consist only of the restricted set of
 characters included in one of the following three productions defined
 in [RFC3986]:

   <reserved>
   <unreserved>
   <pct-encoded>
 
 Implementations SHOULD accept other valid UTF-8 strings [RFC3629] as
 input.  An octet MUST be encoded using the percent-encoding mechanism
 described in section 2.1 of [RFC3986] in any of these situations:
 
  The octet is not in the reserved set defined in section 2.2 of
  [RFC3986] or in the unreserved set defined in section 2.3 of
  [RFC3986].

  It is the single Reserved character '?' and occurs inside a <dn>,
  <filter>, or other element of an LDAP URL.

  It is a comma character ',' that occurs inside an <exvalue>.

 RFC 3986, section 2.2 (Reserved Characters)
 
 reserved    = gen-delims / sub-delims
 gen-delims  = ":" / "/" / "?" / "#" / "[" / "]" / "@"
 sub-delims  = "!" / "$" / "&" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="

 RFC 3986, section 2.3 (Unreserved Characters)
 
 unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
        Parameters:
        url - The String to encode
        doubleEncode - Set if we need to encode the comma
        Returns:
        An encoded string

      • toString

        public String toString()
        Get a string representation of a LdapUrl.
        Overrides:
        toString in class Object
        Returns:
        A LdapUrl string

      • getAttributes

        public List<String> getAttributes()
        Returns:
        Returns the attributes.

      • getDn

        public Dn getDn()
        Returns:
        Returns the dn.

      • getExtension

        public LdapUrl.Extension getExtension​(String type)
        Gets the extension.
        Parameters:
        type - the extension type, case-insensitive
        Returns:
        Returns the extension, null if this URL does not contain such an extension.

      • getExtensionValue

        public String getExtensionValue​(String type)
        Gets the extension value.
        Parameters:
        type - the extension type, case-insensitive
        Returns:
        Returns the extension value, null if this URL does not contain such an extension or if the extension value is null.

      • getFilter

        public String getFilter()
        Returns:
        Returns the filter.

      • getHost

        public String getHost()
        Returns:
        Returns the host.

      • getPort

        public int getPort()
        Returns:
        Returns the port.

      • getScheme

        public String getScheme()
        Returns:
        Returns the scheme.

      • getNbBytes

        public int getNbBytes()
        Returns:
        the number of bytes for this LdapUrl

      • getBytesReference

        public byte[] getBytesReference()
        Returns:
        a reference on the interned bytes representing this LdapUrl

      • getBytesCopy

        public byte[] getBytesCopy()
        Returns:
        a copy of the bytes representing this LdapUrl

      • getString

        public String getString()
        Returns:
        the LdapUrl as a String

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • setScheme

        public void setScheme​(String scheme)
        Sets the scheme. Must be "ldap://" or "ldaps://", otherwise "ldap://" is assumed as default.
        Parameters:
        scheme - the new scheme

      • setHost

        public void setHost​(String host)
        Sets the host.
        Parameters:
        host - the new host

      • setPort

        public void setPort​(int port)
        Sets the port. Must be between 1 and 65535, otherwise -1 is assumed as default.
        Parameters:
        port - the new port

      • setDn

        public void setDn​(Dn dn)
        Sets the dn.
        Parameters:
        dn - the new dn

      • setAttributes

        public void setAttributes​(List<String> attributes)
        Sets the attributes, null removes all existing attributes.
        Parameters:
        attributes - the new attributes

      • setFilter

        public void setFilter​(String filter)
        Sets the filter.
        Parameters:
        filter - the new filter

      • setForceScopeRendering

        public void setForceScopeRendering​(boolean forceScopeRendering)
        If set to true forces the toString method to render the scope regardless of optional nature. Use this when you want explicit search URL scope rendering.
        Parameters:
        forceScopeRendering - the forceScopeRendering to set