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

java.lang.Object
  org.apache.directory.shared.ldap.name.DN

All Implemented Interfaces:

Externalizable, Serializable, Cloneable, Comparable<Object>, Name

public class DN
extends Object
implements Name, Externalizable

The DN 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 representation, 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: 921600 $, $Date: 2010-03-10 23:37:30 +0100 (Mer, 10 mar 2010) $

Author:

Apache Directory Project

See Also:

Serialized Form

Field Summary

static DN	EMPTY_DN A null DN
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 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

DN()
Construct an empty DN object

DN(Name name)
Transduces, or copies a Name to an DN.

DN(String... upRdns)
Creates a new instance of DN, using varargs to declare the RDNs.

DN(String upName)
Parse a String and checks that it is a valid DN

Method Summary

Name	add(int pos, RDN newRdn) Adds a single RDN to a specific position.
Name	add(int posn, String comp)
Name	add(RDN newRdn) Adds a single RDN to the (leaf) end of this name.
Name	add(String comp)
Name	addAll(int posn, Name name)
Name	addAll(Name suffix)
Name	addAllNormalized(int posn, Name name) Adds the components of a name -- in order -- at a specified position within this name.
Name	addNormalized(RDN newRdn) Adds a single normalized RDN to the (leaf) end of this name.
Object	clone()
int	compareTo(Object obj)
boolean	endsWith(Name name)
boolean	equals(Object obj)
String	get(int posn)
Enumeration<String>	getAll()
Enumeration<RDN>	getAllRdn() Retrieves the components of this name as an enumeration of strings.
static byte[]	getBytes(DN dn) Get an UTF-8 representation of the normalized form of the DN
String	getName() Get the initial DN
static int	getNbBytes(Name dn) Get the number of bytes necessary to store this DN
String	getNormName() Get the initial DN (without normalization)
Name	getPrefix(int posn)
RDN	getRdn() Retrieves the last (leaf) component of this name.
RDN	getRdn(int posn) Retrieves a component of this name.
List<RDN>	getRdns() Retrieves all the components of this name.
Name	getSuffix(int posn)
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(String dn) Check if a DistinguishedName is syntactically valid.
static DN	normalize(DN dn, Map<String,OidNormalizer> oidsMap) Change the internal DN, using the OID instead of the first name or other aliases.
DN	normalize(Map<String,OidNormalizer> oidsMap) Change the internal DN, using the OID instead of the first name or other aliases.
static Name	normalize(String name, Map<String,OidNormalizer> oidsMap) Static factory which creates a normalized DN from a String and a Map of OIDs.
void	readExternal(ObjectInput in)
Object	remove(int posn)
int	size()
boolean	startsWith(Name name)
String	toNormName() Build the normalized DN as a String,
String	toString() Return the normalized DN as a String.
void	writeExternal(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 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_DN

public static final DN EMPTY_DN

A null DN

Constructor Detail

DN

public DN()

Construct an empty DN object

DN

public DN(Name name)
   throws InvalidNameException

Transduces, or copies a Name to an DN.

Parameters:

name - composed of String name components.

Throws:

InvalidNameException - If the Name is invalid.

DN

public DN(String upName)
   throws 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:

InvalidNameException - if the String does not contain a valid DN.

DN

public DN(String... upRdns)
   throws InvalidNameException

Creates a new instance of DN, using varargs to declare the RDNs. Each String is either a full RDN, or a couple of AttributeType DI and a value. If the String contains a '=' symbol, the the constructor will assume that the String arg contains afull RDN, otherwise, it will consider that the following arg is the value. An example of usage would be :

 String exampleName = "example";
 String baseDn = "dc=apache,dc=org";
 
 DN dn = new DN(
     "cn=Test",
     "ou", exampleName,
     baseDn);
 

Parameters:

upNames -

Throws:

InvalidNameException

Method Detail

normalize

public static Name normalize(String name,
                             Map<String,OidNormalizer> oidsMap)
                      throws InvalidNameException,
                             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:

InvalidNameException - If the DN is invalid.

NamingException - If something went wrong.

toNormName

public String toNormName()

Build the normalized DN as a String,

Returns:

A String representing the normalized DN

toString

public String toString()

Return the normalized DN as a String. It returns the same value as the getNormName method

Overrides:

toString in class Object

Returns:

A String representing the normalized DN

hashCode

public int hashCode()

Gets the hash code of this name.

Overrides:

hashCode in class Object

Returns:

the instance hash code

See Also:

Object.hashCode()

getName

public String getName()

Get the initial DN

Returns:

The DN as a String

getNormName

public String getNormName()

Get the initial DN (without normalization)

Returns:

The DN as a String

size

public int size()

Specified by:

size in interface Name

getNbBytes

public static int getNbBytes(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(DN 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(Name name)

Specified by:

startsWith in interface Name

endsWith

public boolean endsWith(Name name)

Specified by:

endsWith in interface Name

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Name

get

public String get(int posn)

Specified by:

get in interface 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:

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 List<RDN> getRdns()

Retrieves all the components of this name.

Returns:

All the components

getAll

public Enumeration<String> getAll()

Specified by:

getAll in interface Name

getAllRdn

public 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 Name getPrefix(int posn)

Specified by:

getPrefix in interface Name

getSuffix

public Name getSuffix(int posn)

Specified by:

getSuffix in interface Name

addAllNormalized

public Name addAllNormalized(int posn,
                             Name name)
                      throws 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:

ArrayIndexOutOfBoundsException - if posn is outside the specified range

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 Name addAll(Name suffix)
            throws InvalidNameException

Specified by:

addAll in interface Name

Throws:

InvalidNameException

addAll

public Name addAll(int posn,
                   Name name)
            throws InvalidNameException

Specified by:

addAll in interface Name

Throws:

InvalidNameException

add

public Name add(String comp)
         throws InvalidNameException

Specified by:

add in interface Name

Throws:

InvalidNameException

add

public 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 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 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 Name add(int posn,
                String comp)
         throws InvalidNameException

Specified by:

add in interface Name

Throws:

InvalidNameException

remove

public Object remove(int posn)
              throws InvalidNameException

Specified by:

remove in interface Name

Throws:

InvalidNameException

clone

public Object clone()

Specified by:

clone in interface Name

Overrides:

clone in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

Returns:

true if the two instances are equals

See Also:

Object.equals(java.lang.Object)

compareTo

public int compareTo(Object obj)

Specified by:

compareTo in interface Comparable<Object>

Specified by:

compareTo in interface Name

normalize

public static DN normalize(DN dn,
                           Map<String,OidNormalizer> oidsMap)
                    throws 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:

NamingException - If something went wrong.

normalize

public DN normalize(Map<String,OidNormalizer> oidsMap)
             throws 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:

NamingException - If something went wrong.

isValid

public static boolean isValid(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(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Parameters:

out - The stream in which the DN will be serialized

Throws:

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(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Parameters:

in - The stream from which the DN is read

Throws:

IOException - If the stream can't be read

ClassNotFoundException - If the RDN can't be created

See Also:

We read back the data to create a new DN. The structure read is exposed in the {@link DN#writeExternal(ObjectOutput)} method