org.apache.directory.shared.ldap.name
Class LdapDN

java.lang.Object
  extended by org.apache.directory.shared.ldap.name.LdapDN
All Implemented Interfaces:
java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<java.lang.Object>, javax.naming.Name

public class LdapDN
extends java.lang.Object
implements javax.naming.Name, java.io.Externalizable

The LdapDN class contains a DN (Distinguished Name). Its specification can be found in RFC 2253, "UTF-8 String Representation of Distinguished Names". We will store two representation of a DN : - a user Provider represeentation, which is the parsed String given by a user - an internal representation. A DN is formed of RDNs, in a specific order : RDN[n], RDN[n-1], ... RDN[1], RDN[0] It represents a tree, in which the root is the last RDN (RDN[0]) and the leaf is the first RDN (RDN[n]).

Version:
$Rev: 686316 $, $Date: 2008-08-15 20:51:12 +0200 (Fr, 15 Aug 2008) $
Author:
Apache Directory Project
See Also:
Serialized Form

Field Summary
static LdapDN EMPTY_LDAPDN
          A null LdapDN
static int EQUAL
          Value returned by the compareTo method if values are equals
protected static org.slf4j.Logger LOG
          The LoggerFactory used by this class
static int NOT_EQUAL
          Value returned by the compareTo method if values are not equals
protected  java.util.List<Rdn> rdns
          The RDNs that are elements of the DN NOTE THAT THESE ARE IN THE OPPOSITE ORDER FROM THAT IMPLIED BY THE JAVADOC! Rdn[0] is rdns.get(n) and Rdn[n] is rdns.get(0)
 
Constructor Summary
LdapDN()
          Construct an empty LdapDN object
LdapDN(byte[] bytes)
          Parse a buffer and checks that it is a valid DN
LdapDN(java.util.Iterator<java.lang.String> nameComponents)
          Creates an ldap name using a list of name components.
LdapDN(java.util.List<java.lang.String> list)
          Creates an ldap name using a list of NameComponents.
LdapDN(javax.naming.Name name)
          Transduces, or copies a Name to an LdapDN.
LdapDN(java.lang.String upName)
          Parse a String and checks that it is a valid DN
 
Method Summary
 javax.naming.Name add(int pos, Rdn newRdn)
          Adds a single RDN to a specific position.
 javax.naming.Name add(int posn, java.lang.String comp)
          
 javax.naming.Name add(Rdn newRdn)
          Adds a single RDN to the (leaf) end of this name.
 javax.naming.Name add(java.lang.String comp)
          
 javax.naming.Name addAll(int posn, javax.naming.Name name)
          
 javax.naming.Name addAll(javax.naming.Name suffix)
          
 javax.naming.Name addAllNormalized(int posn, javax.naming.Name name)
          Adds the components of a name -- in order -- at a specified position within this name.
 javax.naming.Name addNormalized(Rdn newRdn)
          Adds a single normalized RDN to the (leaf) end of this name.
 java.lang.Object clone()
          
 int compareTo(java.lang.Object obj)
          
 boolean endsWith(javax.naming.Name name)
          
 boolean equals(java.lang.Object obj)
           
 java.lang.String get(int posn)
          
 java.util.Enumeration<java.lang.String> getAll()
          
 java.util.Enumeration<Rdn> getAllRdn()
          Retrieves the components of this name as an enumeration of strings.
static byte[] getBytes(LdapDN dn)
          Get an UTF-8 representation of the normalized form of the DN
static int getNbBytes(javax.naming.Name dn)
          Get the number of bytes necessary to store this DN
 java.lang.String getNormName()
          Get the initial DN (without normalization)
 javax.naming.Name getPrefix(int posn)
          
 Rdn getRdn()
          Retrieves the last (leaf) component of this name.
 Rdn getRdn(int posn)
          Retrieves a component of this name.
 java.util.List<Rdn> getRdns()
          Retrieves all the components of this name.
 javax.naming.Name getSuffix(int posn)
          
 java.lang.String getUpName()
          Get the initial DN (without normalization)
 int hashCode()
          Gets the hash code of this name.
 boolean isEmpty()
          
 boolean isNormalized()
          Tells if the DN has already been normalized or not
static boolean isValid(java.lang.String dn)
          Check if a DistinguishedName is syntactically valid.
static LdapDN normalize(LdapDN dn, java.util.Map<java.lang.String,OidNormalizer> oidsMap)
          Change the internal DN, using the OID instead of the first name or other aliases.
 LdapDN normalize(java.util.Map<java.lang.String,OidNormalizer> oidsMap)
          Change the internal DN, using the OID instead of the first name or other aliases.
static javax.naming.Name normalize(java.lang.String name, java.util.Map<java.lang.String,OidNormalizer> oidsMap)
          Static factory which creates a normalized DN from a String and a Map of OIDs.
 void readExternal(java.io.ObjectInput in)
           
 java.lang.Object remove(int posn)
          
 int size()
          
 boolean startsWith(javax.naming.Name name)
          
 java.lang.String toNormName()
          Build the normalized DN as a String,
 java.lang.String toString()
          Return the normalized DN as a String.
 void writeExternal(java.io.ObjectOutput out)
           
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

LOG

protected static final org.slf4j.Logger LOG
The LoggerFactory used by this class


NOT_EQUAL

public static final int NOT_EQUAL
Value returned by the compareTo method if values are not equals

See Also:
Constant Field Values

EQUAL

public static final int EQUAL
Value returned by the compareTo method if values are equals

See Also:
Constant Field Values

rdns

protected java.util.List<Rdn> rdns
The RDNs that are elements of the DN NOTE THAT THESE ARE IN THE OPPOSITE ORDER FROM THAT IMPLIED BY THE JAVADOC! Rdn[0] is rdns.get(n) and Rdn[n] is rdns.get(0)


EMPTY_LDAPDN

public static final LdapDN EMPTY_LDAPDN
A null LdapDN

Constructor Detail

LdapDN

public LdapDN()
Construct an empty LdapDN object


LdapDN

public LdapDN(javax.naming.Name name)
       throws javax.naming.InvalidNameException
Transduces, or copies a Name to an LdapDN.

Parameters:
name - composed of String name components.
Throws:
javax.naming.InvalidNameException - If the Name is invalid.

LdapDN

public LdapDN(java.util.List<java.lang.String> list)
       throws javax.naming.InvalidNameException
Creates an ldap name using a list of NameComponents. Each NameComponent is a String

Parameters:
list - of String name components.
Throws:
javax.naming.InvalidNameException - If the nameComponent is incorrect

LdapDN

public LdapDN(java.util.Iterator<java.lang.String> nameComponents)
       throws javax.naming.InvalidNameException
Creates an ldap name using a list of name components.

Parameters:
nameComponents - List of String name components.
Throws:
javax.naming.InvalidNameException - If the nameComponent is incorrect

LdapDN

public LdapDN(java.lang.String upName)
       throws javax.naming.InvalidNameException
Parse a String and checks that it is a valid DN

<distinguishedName> ::= <name> | e
<name> ::= <name-component> <name-components>
<name-components> ::= <spaces> <separator> <spaces> <name-component> <name-components> | e

Parameters:
upName - The String that contains the DN.
Throws:
javax.naming.InvalidNameException - if the String does not contain a valid DN.

LdapDN

public LdapDN(byte[] bytes)
       throws javax.naming.InvalidNameException
Parse a buffer and checks that it is a valid DN

<distinguishedName> ::= <name> | e
<name> ::= <name-component> <name-components>
<name-components> ::= <spaces> <separator> <spaces> <name-component> <name-components> | e

Parameters:
bytes - The byte buffer that contains the DN.
Throws:
javax.naming.InvalidNameException - if the buffer does not contains a valid DN.
Method Detail

normalize

public static javax.naming.Name normalize(java.lang.String name,
                                          java.util.Map<java.lang.String,OidNormalizer> oidsMap)
                                   throws javax.naming.InvalidNameException,
                                          javax.naming.NamingException
Static factory which creates a normalized DN from a String and a Map of OIDs.

Parameters:
name - The DN as a String
oidsMap - The OID mapping
Returns:
A valid DN
Throws:
javax.naming.InvalidNameException - If the DN is invalid.
javax.naming.NamingException - If something went wrong.

toNormName

public java.lang.String toNormName()
Build the normalized DN as a String,

Returns:
A String representing the normalized DN

toString

public java.lang.String toString()
Return the normalized DN as a String. It returns the same value as the getNormName method

Overrides:
toString in class java.lang.Object
Returns:
A String representing the normalized DN

hashCode

public int hashCode()
Gets the hash code of this name.

Overrides:
hashCode in class java.lang.Object
Returns:
the instance hash code
See Also:
Object.hashCode()

getUpName

public java.lang.String getUpName()
Get the initial DN (without normalization)

Returns:
The DN as a String

getNormName

public java.lang.String getNormName()
Get the initial DN (without normalization)

Returns:
The DN as a String

size

public int size()

Specified by:
size in interface javax.naming.Name

getNbBytes

public static int getNbBytes(javax.naming.Name dn)
Get the number of bytes necessary to store this DN

Parameters:
dn - The DN.
Returns:
A integer, which is the size of the UTF-8 byte array

getBytes

public static byte[] getBytes(LdapDN dn)
Get an UTF-8 representation of the normalized form of the DN

Parameters:
dn - The DN.
Returns:
A byte[] representation of the DN

startsWith

public boolean startsWith(javax.naming.Name name)

Specified by:
startsWith in interface javax.naming.Name

endsWith

public boolean endsWith(javax.naming.Name name)

Specified by:
endsWith in interface javax.naming.Name

isEmpty

public boolean isEmpty()

Specified by:
isEmpty in interface javax.naming.Name

get

public java.lang.String get(int posn)

Specified by:
get in interface javax.naming.Name

getRdn

public Rdn getRdn(int posn)
Retrieves a component of this name.

Parameters:
posn - the 0-based index of the component to retrieve. Must be in the range [0,size()).
Returns:
the component at index posn
Throws:
java.lang.ArrayIndexOutOfBoundsException - if posn is outside the specified range

getRdn

public Rdn getRdn()
Retrieves the last (leaf) component of this name.

Returns:
the last component of this DN

getRdns

public java.util.List<Rdn> getRdns()
Retrieves all the components of this name.

Returns:
All the components

getAll

public java.util.Enumeration<java.lang.String> getAll()

Specified by:
getAll in interface javax.naming.Name

getAllRdn

public java.util.Enumeration<Rdn> getAllRdn()
Retrieves the components of this name as an enumeration of strings. The effect on the enumeration of updates to this name is undefined. If the name has zero components, an empty (non-null) enumeration is returned. This starts at the root (rightmost) rdn.

Returns:
an enumeration of the components of this name, as Rdn

getPrefix

public javax.naming.Name getPrefix(int posn)

Specified by:
getPrefix in interface javax.naming.Name

getSuffix

public javax.naming.Name getSuffix(int posn)

Specified by:
getSuffix in interface javax.naming.Name

addAllNormalized

public javax.naming.Name addAllNormalized(int posn,
                                          javax.naming.Name name)
                                   throws javax.naming.InvalidNameException
Adds the components of a name -- in order -- at a specified position within this name. Components of this name at or after the index of the first new component are shifted up (away from 0) to accommodate the new components. Compoenents are supposed to be normalized.

Parameters:
posn - the index in this name at which to add the new components. Must be in the range [0,size()]. Note this is from the opposite end as rnds.get(posn)
name - the components to add
Returns:
the updated name (not a new one)
Throws:
java.lang.ArrayIndexOutOfBoundsException - if posn is outside the specified range
javax.naming.InvalidNameException - if n is not a valid name, or if the addition of the components would violate the syntax rules of this name

addAll

public javax.naming.Name addAll(javax.naming.Name suffix)
                         throws javax.naming.InvalidNameException

Specified by:
addAll in interface javax.naming.Name
Throws:
javax.naming.InvalidNameException

addAll

public javax.naming.Name addAll(int posn,
                                javax.naming.Name name)
                         throws javax.naming.InvalidNameException

Specified by:
addAll in interface javax.naming.Name
Throws:
javax.naming.InvalidNameException

add

public javax.naming.Name add(java.lang.String comp)
                      throws javax.naming.InvalidNameException

Specified by:
add in interface javax.naming.Name
Throws:
javax.naming.InvalidNameException

add

public javax.naming.Name add(Rdn newRdn)
Adds a single RDN to the (leaf) end of this name.

Parameters:
newRdn - the RDN to add
Returns:
the updated name (not a new one)

add

public javax.naming.Name add(int pos,
                             Rdn newRdn)
Adds a single RDN to a specific position.

Parameters:
newRdn - the RDN to add
pos - The position where we want to add the Rdn
Returns:
the updated name (not a new one)

addNormalized

public javax.naming.Name addNormalized(Rdn newRdn)
Adds a single normalized RDN to the (leaf) end of this name.

Parameters:
newRdn - the RDN to add
Returns:
the updated name (not a new one)

add

public javax.naming.Name add(int posn,
                             java.lang.String comp)
                      throws javax.naming.InvalidNameException

Specified by:
add in interface javax.naming.Name
Throws:
javax.naming.InvalidNameException

remove

public java.lang.Object remove(int posn)
                        throws javax.naming.InvalidNameException

Specified by:
remove in interface javax.naming.Name
Throws:
javax.naming.InvalidNameException

clone

public java.lang.Object clone()

Specified by:
clone in interface javax.naming.Name
Overrides:
clone in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)
Overrides:
equals in class java.lang.Object
Returns:
true if the two instances are equals
See Also:
Object.equals(java.lang.Object)

compareTo

public int compareTo(java.lang.Object obj)

Specified by:
compareTo in interface java.lang.Comparable<java.lang.Object>
Specified by:
compareTo in interface javax.naming.Name

normalize

public static LdapDN normalize(LdapDN dn,
                               java.util.Map<java.lang.String,OidNormalizer> oidsMap)
                        throws javax.naming.NamingException
Change the internal DN, using the OID instead of the first name or other aliases. As we still have the UP name of each RDN, we will be able to provide both representation of the DN. example : dn: 2.5.4.3=People, dc=example, domainComponent=com will be transformed to : 2.5.4.3=People, 0.9.2342.19200300.100.1.25=example, 0.9.2342.19200300.100.1.25=com because 2.5.4.3 is the OID for cn and dc is the first alias of the couple of aliases (dc, domaincomponent), which OID is 0.9.2342.19200300.100.1.25. This is really important do have such a representation, as 'cn' and 'commonname' share the same OID.

Parameters:
dn - The DN to transform.
oidsMap - The mapping between names and oids.
Returns:
A normalized form of the DN.
Throws:
javax.naming.NamingException - If something went wrong.

normalize

public LdapDN normalize(java.util.Map<java.lang.String,OidNormalizer> oidsMap)
                 throws javax.naming.NamingException
Change the internal DN, using the OID instead of the first name or other aliases. As we still have the UP name of each RDN, we will be able to provide both representation of the DN. example : dn: 2.5.4.3=People, dc=example, domainComponent=com will be transformed to : 2.5.4.3=People, 0.9.2342.19200300.100.1.25=example, 0.9.2342.19200300.100.1.25=com because 2.5.4.3 is the OID for cn and dc is the first alias of the couple of aliases (dc, domaincomponent), which OID is 0.9.2342.19200300.100.1.25. This is really important do have such a representation, as 'cn' and 'commonname' share the same OID.

Parameters:
oidsMap - The mapping between names and oids.
Returns:
The normalized DN
Throws:
javax.naming.NamingException - If something went wrong.

isValid

public static boolean isValid(java.lang.String dn)
Check if a DistinguishedName is syntactically valid.

Parameters:
dn - The DN to validate
Returns:
true> if the DN is valid, false otherwise

isNormalized

public boolean isNormalized()
Tells if the DN has already been normalized or not

Returns:
true if the DN is already normalized.

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException
Specified by:
writeExternal in interface java.io.Externalizable
Parameters:
out - The stream in which the DN will be serialized
Throws:
java.io.IOException - If the serialization fail
See Also:
We have to store a DN data efficiently. Here is the structure :
  • upName
  • The User provided DN

  • normName
  • May be null if the normName is equaivalent to the upName

  • rdns
  • The rdn's List.

    for each rdn :

  • call the RDN write method

  • readExternal

    public void readExternal(java.io.ObjectInput in)
                      throws java.io.IOException,
                             java.lang.ClassNotFoundException
    Specified by:
    readExternal in interface java.io.Externalizable
    Parameters:
    in - The stream from which the DN is read
    Throws:
    java.io.IOException - If the stream can't be read
    java.lang.ClassNotFoundException - If the RDN can't be created
    See Also:
    We read back the data to create a new LdapDN. The structure read is exposed in the {@link LdapDN#writeExternal(ObjectOutput)} method



    Copyright © 2003-2011 Apache Software Foundation. All Rights Reserved.