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

java.lang.Object
  extended byorg.apache.directory.shared.ldap.name.LdapDN
All Implemented Interfaces:
java.lang.Cloneable, javax.naming.Name, java.io.Serializable

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

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]).

Author:
Apache Directory Project
See Also:
Serialized Form

Field Summary
static LdapDN EMPTY_LDAPDN
          A null LdapDN
static int EQUALS
          Value returned by the compareTo method if values are equals
static int NOT_EQUALS
          Value returned by the compareTo method if values are not equals
 
Constructor Summary
LdapDN()
          Construct an empty LdapDN object
LdapDN(byte[] bytes)
          Parse a buffer and checks that it is a valid DN
LdapDN(java.lang.String upName)
          Parse a String and checks that it is a valid DN
 
Method Summary
 javax.naming.Name add(int posn, java.lang.String comp)
          Adds a single component at a specified position within this name.
 javax.naming.Name add(java.lang.String comp)
          Adds a single component to the end of this name.
 javax.naming.Name addAll(int posn, javax.naming.Name name)
          Adds the components of a name -- in order -- at a specified position within this name.
 javax.naming.Name addAll(javax.naming.Name suffix)
          Adds the components of a name -- in order -- to the end of this name.
 java.lang.Object clone()
          Generates a new copy of this name.
 int compareTo(java.lang.Object obj)
          Compares this name with another name for order.
 boolean endsWith(javax.naming.Name name)
          Determines whether this name ends with a specified suffix.
 boolean equals(java.lang.Object obj)
           
 java.lang.String get(int posn)
          Retrieves a component of this name.
 java.util.Enumeration getAll()
          Retrieves the components of this name as an enumeration of strings.
 java.util.Enumeration getAllRdn()
          Retrieves the components of this name as an enumeration of strings.
static byte[] getBytes(javax.naming.Name dn)
          Get an UTF-8 representation of the normalized form of the DN
 java.lang.String getName()
          Get the initial DN (without normalization)
static int getNbBytes(javax.naming.Name dn)
          Get the number of bytes necessary to store this DN
 javax.naming.Name getPrefix(int posn)
          Creates a name whose components consist of a prefix of the components of this name.
 Rdn getRdn(int posn)
          Retrieves a component of this name.
 java.util.List getRdns()
          Retrieves all the components of this name.
 javax.naming.Name getSuffix(int posn)
          Creates a name whose components consist of a suffix of the components in this name.
 int hashCode()
          Gets the hashcode of the string representation of this name.
 boolean isEmpty()
          Determines whether this name is empty.
static javax.naming.Name normalize(javax.naming.Name dn)
           
static javax.naming.Name normalize(javax.naming.Name dn, java.util.Map oids)
          Change the internal DN, using the first alias instead of oids or other aliases.
static LdapString normalizeAttribute(byte[] data)
          Substitute OIDs and aliases for the simplest alias
 java.lang.Object remove(int posn)
          Removes a component from this name.
 int size()
          Get the number of NameComponent conatained in this LdapDN
 boolean startsWith(javax.naming.Name name)
          Determines whether this name starts with a specified prefix.
 java.lang.String toNormName()
          Build the normalized DN as a String,
 java.lang.String toString()
          Return the normalized DN as a String.
 java.lang.String toUpName()
          Return the User Provided DN as a String,
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

NOT_EQUALS

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

See Also:
Constant Field Values

EQUALS

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

See Also:
Constant Field Values

EMPTY_LDAPDN

public static final LdapDN EMPTY_LDAPDN
A null LdapDN

Constructor Detail

LdapDN

public LdapDN()
Construct an empty LdapDN object


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

Throws:
A - InvalidNameException is thrown if the buffer does not contains a valid DN.
javax.naming.InvalidNameException

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:
A - InvalidNameException is thrown if the buffer does not contains a valid DN.
javax.naming.InvalidNameException
Method Detail

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

Returns:
A String representing the normalized DN

toUpName

public java.lang.String toUpName()
Return the User Provided DN as a String,

Returns:
A String representing the User Provided DN

hashCode

public int hashCode()
Gets the hashcode of the string representation of this name.

See Also:
Object.hashCode()

getName

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

Returns:
The DN as a String

size

public int size()
Get the number of NameComponent conatained in this LdapDN

Specified by:
size in interface javax.naming.Name
Returns:
The number of NameComponent conatained in this LdapDN

getNbBytes

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

Returns:
A integer, which is the size of the UTF-8 byte array

getBytes

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

Returns:
A byte[] representation of the DN

startsWith

public boolean startsWith(javax.naming.Name name)
Determines whether this name starts with a specified prefix. A name name is a prefix if it is equal to getPrefix(name.size()). Be aware that for a specific DN like : cn=xxx, ou=yyy the startsWith method will retourn true with ou=yyy, and false with cn=xxx

Specified by:
startsWith in interface javax.naming.Name
Parameters:
name - the name to check
Returns:
true if name is a prefix of this name, false otherwise

endsWith

public boolean endsWith(javax.naming.Name name)
Determines whether this name ends with a specified suffix. A name name is a suffix if it is equal to getSuffix(size()-name.size()). Be aware that for a specific DN like : cn=xxx, ou=yyy the endsWith method will retourn true with cn=xxx, and false with ou=yyy

Specified by:
endsWith in interface javax.naming.Name
Parameters:
name - the name to check
Returns:
true if name is a suffix of this name, false otherwise

isEmpty

public boolean isEmpty()
Determines whether this name is empty. An empty name is one with zero components.

Specified by:
isEmpty in interface javax.naming.Name
Returns:
true if this name is empty, false otherwise

get

public java.lang.String get(int posn)
Retrieves a component of this name.

Specified by:
get in interface javax.naming.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(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

getRdns

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

Returns:
All the components

getAll

public java.util.Enumeration getAll()
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.

Specified by:
getAll in interface javax.naming.Name
Returns:
an enumeration of the components of this name, each as string

getAllRdn

public java.util.Enumeration 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.

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

getPrefix

public javax.naming.Name getPrefix(int posn)
Creates a name whose components consist of a prefix of the components of this name. Subsequent changes to this name will not affect the name that is returned and vice versa.

Specified by:
getPrefix in interface javax.naming.Name
Parameters:
posn - the 0-based index of the component at which to stop. Must be in the range [0,size()].
Returns:
a name consisting of the components at indexes in the range [0,posn].
Throws:
java.lang.ArrayIndexOutOfBoundsException - if posn is outside the specified range

getSuffix

public javax.naming.Name getSuffix(int posn)
Creates a name whose components consist of a suffix of the components in this name. Subsequent changes to this name do not affect the name that is returned and vice versa.

Specified by:
getSuffix in interface javax.naming.Name
Parameters:
posn - the 0-based index of the component at which to start. Must be in the range [0,size()].
Returns:
a name consisting of the components at indexes in the range [posn,size()]. If posn is equal to size(), an empty name is returned.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if posn is outside the specified range

addAll

public javax.naming.Name addAll(javax.naming.Name suffix)
                         throws javax.naming.InvalidNameException
Adds the components of a name -- in order -- to the end of this name.

Specified by:
addAll in interface javax.naming.Name
Parameters:
suffix - the components to add
Returns:
the updated name (not a new one)
Throws:
javax.naming.InvalidNameException - if suffix 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(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.

Specified by:
addAll in interface javax.naming.Name
Parameters:
name - the components to add
posn - the index in this name at which to add the new components. Must be in the range [0,size()].
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

add

public javax.naming.Name add(java.lang.String comp)
                      throws javax.naming.InvalidNameException
Adds a single component to the end of this name.

Specified by:
add in interface javax.naming.Name
Parameters:
comp - the component to add
Returns:
the updated name (not a new one)
Throws:
javax.naming.InvalidNameException - if adding comp would violate the syntax rules of this name

add

public javax.naming.Name add(int posn,
                             java.lang.String comp)
                      throws javax.naming.InvalidNameException
Adds a single component at a specified position within this name. Components of this name at or after the index of the new component are shifted up by one (away from index 0) to accommodate the new component.

Specified by:
add in interface javax.naming.Name
Parameters:
comp - the component to add
posn - the index at which to add the new component. Must be in the range [0,size()].
Returns:
the updated name (not a new one)
Throws:
java.lang.ArrayIndexOutOfBoundsException - if posn is outside the specified range
javax.naming.InvalidNameException - if adding comp would violate the syntax rules of this name

remove

public java.lang.Object remove(int posn)
                        throws javax.naming.InvalidNameException
Removes a component from this name. The component of this name at the specified position is removed. Components with indexes greater than this position are shifted down (toward index 0) by one.

Specified by:
remove in interface javax.naming.Name
Parameters:
posn - the index of the component to remove. Must be in the range [0,size()).
Returns:
the component removed (a String)
Throws:
java.lang.ArrayIndexOutOfBoundsException - if posn is outside the specified range
javax.naming.InvalidNameException - if deleting the component would violate the syntax rules of the name

clone

public java.lang.Object clone()
Generates a new copy of this name. Subsequent changes to the components of this name will not affect the new copy, and vice versa.

Specified by:
clone in interface javax.naming.Name
Returns:
a copy of this name
See Also:
Object.clone()

equals

public boolean equals(java.lang.Object obj)
See Also:
Object.equals(java.lang.Object)

compareTo

public int compareTo(java.lang.Object obj)
Compares this name with another name for order. Returns a negative integer, zero, or a positive integer as this name is less than, equal to, or greater than the given name.

As with Object.equals(), the notion of ordering for names depends on the class that implements this interface. For example, the ordering may be based on lexicographical ordering of the name components. Specific attributes of the name, such as how it treats case, may affect the ordering. In general, two names of different classes may not be compared.

Specified by:
compareTo in interface javax.naming.Name
Parameters:
obj - the non-null object to compare against.
Returns:
a negative integer, zero, or a positive integer as this name is less than, equal to, or greater than the given name
Throws:
java.lang.ClassCastException - if obj is not a Name of a type that may be compared with this name
See Also:
Comparable.compareTo(Object)

normalize

public static javax.naming.Name normalize(javax.naming.Name dn,
                                          java.util.Map oids)
                                   throws javax.naming.InvalidNameException,
                                          javax.naming.NamingException
Change the internal DN, using the first alias instead of oids 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 : cn=People, dc=example, dc=com because 2.5.4.3 is the OID for cn and dc is the first alias of the couple of aliases (dc, domaincomponent). This is really important do have such a representation, as 'cn' and 'commonname' share the same OID.

Parameters:
dn - The DN to transform
oids - The mapping between names and oids.
Returns:
A normalized form of the DN
Throws:
javax.naming.InvalidNameException - If the DN is invalid
javax.naming.NamingException

normalize

public static javax.naming.Name normalize(javax.naming.Name dn)
                                   throws javax.naming.InvalidNameException,
                                          javax.naming.NamingException
Throws:
javax.naming.InvalidNameException
javax.naming.NamingException

normalizeAttribute

public static LdapString normalizeAttribute(byte[] data)
                                     throws LdapStringEncodingException
Substitute OIDs and aliases for the simplest alias

Returns:
A simple attribute
Throws:
LdapStringEncodingException - If the attribute is not valid


Copyright © 2003-2006 . All Rights Reserved.