Re: LDAPDN (WG last call on the Java API)

[Rob Weltman <robw@coscend.com>]

"Kurt D. Zeilenga" wrote:
> 
> >4.11 public class LDAPDN
> >   A utility class representing a distinguished name (DN).
> >
> >4.11.1 equals
> >   public static boolean equals(String dn1, String dn2)
> >
> >   Returns true if the two strings correspond to the same DN, after
> >   appropriate normalization.
> 
> How are the DNs compared?  Per distinguished name matching
> rule or by some other means.  In either case, be explicit.

  Each RDN is compared using the matching rules for the attribute of the RDN, which means that some components may be compared case-sensitively and others not.

 
> What are the normalization requirements?  Depending on what
> this normalization function, it might be useful to expose an
> normalizer method so that callers might make use of it.

  As in RFC 2253:

   "Implementations MUST allow for space (' ' ASCII 32) characters to be
   present between name-component and ',', between attributeTypeAndValue
   and '+', between attributeType and '=', and between '=' and
   attributeValue.  These space characters are ignored when parsing."

  Normalization removes any such spade characters.


> What if either DN is invalid?

  IllegalArgumentException is thrown.


> What if the comparison is Undefined?

  What does that mean?


> >4.11.2 escapeRDN
> >
> >   public static String escapeRDN(String rdn)
> >
> >   Returns the RDN after escaping the characters requiring escaping [4].
> >   For example, for the rdn ôcn=Acme, Incö, ôcn=Acme\, Incö is returned.
> 
> How are multi-valued RDNs handled?

  Each of the values is compared separately, with the order not significant.


> What happens if the unescaped RDN cannot be parsed?

  IllegalArgumentException is thrown.


> No byte[] support?

  RFC 2253 states:

   "If the AttributeValue is of a type which does not have a string
   representation defined for it, then it is simply encoded as an
   octothorpe character ('#' ASCII 35) followed by the hexadecimal
   representation of each of the bytes of the BER encoding of the X.500
   AttributeValue."


> >4.11.3 unescapeRDN
> >   public static String unescapeRDN(String rdn)
> >
> >   Returns the RDN after unescaping the characters requiring escaping
> >   [4]. For example, for the rdn ôcn=Acme\, Incö, ôcn=Acme, Incö is
> >   returned.
> 
> What happens if the escaped RDN cannot be parsed?

  IllegalArgumentException is thrown.


> How are multi-valued RDNs handled?

  Each component is unescaped before returning the value.


> What if the value is hex-encoded BER?

  If it meets the requirements of RFC 2253, it is unescaped and returned. Otherwise an IllegalArgumentException is thrown.


> No byte[] support?

  RFC 2253 states:

   "If the AttributeValue is of a type which does not have a string
   representation defined for it, then it is simply encoded as an
   octothorpe character ('#' ASCII 35) followed by the hexadecimal
   representation of each of the bytes of the BER encoding of the X.500
   AttributeValue."


> >4.11.4 explodeDN
> >
> >   public static String[] explodeDN(String dn,
> >                                    boolean noTypes)
> >
> >   Returns the individual components of a distinguished name (DN).
> >
> >   Parameters are:
> >
> >      dn             Distinguished name, e.g. "cn=Babs
> >                      Jensen,ou=Accounting,o=Acme,c=us"
> >
> >      noTypes        If true, returns only the values of the
> >                      components, and not the names, e.g. "Babs
> >                      Jensen", "Accounting", "Acme", "us" - instead of
> >                      "cn=Babs Jensen", "ou=Accounting", "o=Acme", and
> >                      "c=us".
> 
> What happens if the DN cannot be exploded?

  IllegalArgumentException is thrown.


> What if the value is escaped or hex-encoded BER?

  If it meets the requirements of RFC 2253, it is parsed into components and returned. Otherwise an IllegalArgumentException is thrown.


> How are multi-valued RDNs handled with and without noTypes?

  As per RFC 2253, they are returned separated by the "+" character (for each RDN containing multiple values). If noTypes, the attribute name and the "=" character are omitted.

 
> >4.11.5 explodeRDN
> >   public static String[] explodeRDN(String rdn,
> >                                     boolean noTypes)
> >
> >   Returns the individual components of a relative distinguished name
> >   (RDN).
> >
> >   Parameters are:
> >      rdn            Relative distinguished name, i.e. the left-most
> >                      component of a distinguished name.
> >      noTypes        If true, returns only the values of the
> >                      components, and not the names.
> 
> Example, please?  Does this explode "CN=bar+SN=foo"?

  Yes.

  If noTypes, it returns {"bar", "foo"}
  If !noTypes, it returns {"CN=bar", "SN=foo"}


Rob