org.apache.directory.api.ldap.model.name
Class Dn

java.lang.Object
  org.apache.directory.api.ldap.model.name.Dn

All Implemented Interfaces:

Externalizable, Serializable, Iterable<Rdn>

public class Dn
extends Object
implements Iterable<Rdn>, Externalizable

The Dn class contains a Dn (Distinguished Name). This class is immutable.
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 position in a hierarchy, 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 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) For instance,if the Dn is "dc=c, dc=b, dc=a", then the RDNs are stored as : [0] : dc=c [1] : dc=b [2] : dc=a
static Dn	ROOT_DSE The rootDSE

Constructor Summary

Dn()
Construct an empty Dn object

Dn(Rdn... rdns)
Creates a Dn from a list of Rdns.

Dn(Rdn rdn, Dn dn)
Creates a Dn concatenating a Rdn and a Dn.

Dn(SchemaManager schemaManager)
Construct an empty Schema aware Dn object

Dn(SchemaManager schemaManager, Rdn... rdns)
Creates a Schema aware Dn from a list of Rdns.

Dn(SchemaManager schemaManager, String... upRdns)
Creates a new instance of schema aware Dn, using varargs to declare the RDNs.

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

Method Summary

Dn	add(Dn suffix)
Dn	add(Rdn newRdn) Adds a single Rdn to the (leaf) end of this name.
Dn	add(String comp)
Dn	apply(SchemaManager schemaManager) Normalizes the Dn using the given the schema manager, unless the Dn is already normalized
Dn	apply(SchemaManager schemaManager, boolean force) Normalizes the Dn using the given the schema manager.
boolean	equals(Object obj)
Dn	getAncestorOf(Dn descendant) Get the ancestor of a given DN, using the descendant DN.
Dn	getAncestorOf(String descendant) Get the ancestor of a given DN, using the descendant DN.
static byte[]	getBytes(Dn dn) Get an UTF-8 representation of the normalized form of the Dn
Dn	getDescendantOf(Dn ancestor) Get the descendant of a given DN, using the ancestr DN.
Dn	getDescendantOf(String ancestor) Get the descendant of a given DN, using the ancestr DN.
String	getName() Get the user provided Dn
static int	getNbBytes(Dn dn) Get the number of bytes necessary to store this Dn
String	getNormName() Get the normalized Dn.
Dn	getParent() Gets the parent Dn of this Dn.
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.
SchemaManager	getSchemaManager() Get the associated SchemaManager if any.
int	hashCode() Gets the hash code of this Dn.
boolean	isAncestorOf(Dn dn) Tells if the current Dn is a parent of another Dn. For instance, dc=com is a ancestor of dc=example, dc=com
boolean	isAncestorOf(String dn) Tells if the current Dn is a parent of another Dn. For instance, dc=com is a ancestor of dc=example, dc=com
boolean	isDescendantOf(Dn dn) Tells if a Dn is a child of another Dn. For instance, dc=example, dc=apache, dc=com is a descendant of dc=com
boolean	isDescendantOf(String dn) Tells if a Dn is a child of another Dn. For instance, dc=example, dc=com is a descendant of dc=com
boolean	isEmpty() Tells if the Dn contains no Rdn
static boolean	isNullOrEmpty(Dn dn) Check if a DistinguishedName is null or empty.
boolean	isRootDse() Tells if the Dn is the RootDSE Dn (ie, an empty Dn)
boolean	isSchemaAware() Tells if the Dn is schema aware
static boolean	isValid(String name) Check if a DistinguishedName is syntactically valid.
Iterator<Rdn>	iterator() Iterate over the inner Rdn.
void	readExternal(ObjectInput in)
int	size() Get the number of RDNs present in the DN
String	toString() Return the user provided Dn as a String.
void	writeExternal(ObjectOutput out)

Methods inherited from class java.lang.Object

clone, 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)
For instance,if the Dn is "dc=c, dc=b, dc=a", then the RDNs are stored as :

• [0] : dc=c
• [1] : dc=b
• [2] : dc=a

EMPTY_DN

public static final Dn EMPTY_DN

A null Dn

ROOT_DSE

public static final Dn ROOT_DSE

The rootDSE

Constructor Detail

Dn

public Dn()

Construct an empty Dn object

Dn

public Dn(SchemaManager schemaManager)

Construct an empty Schema aware Dn object

Parameters:

schemaManager - The SchemaManager to use

Dn

public Dn(String... upRdns)
   throws LdapInvalidDnException

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.
The created Dn is Schema aware.

An example of usage would be :

 String exampleName = "example";
 String baseDn = "dc=apache,dc=org";

 Dn dn = new Dn( DefaultSchemaManager.INSTANCE,
     "cn=Test",
     "ou", exampleName,
     baseDn);
 

Parameters:

schemaManager - the schema manager

upRdns - The list of String composing the Dn

Throws:

LdapInvalidDnException - If the resulting Dn is invalid

Dn

public Dn(SchemaManager schemaManager,
          String... upRdns)
   throws LdapInvalidDnException

Creates a new instance of schema aware 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.
The created Dn is Schema aware.

An example of usage would be :

 String exampleName = "example";
 String baseDn = "dc=apache,dc=org";

 Dn dn = new Dn( DefaultSchemaManager.INSTANCE,
     "cn=Test",
     "ou", exampleName,
     baseDn);
 

Parameters:

schemaManager - the schema manager

upRdns - The list of String composing the Dn

Throws:

LdapInvalidDnException - If the resulting Dn is invalid

Dn

public Dn(Rdn... rdns)
   throws LdapInvalidDnException

Creates a Dn from a list of Rdns.

Parameters:

rdns - the list of Rdns to be used for the Dn

Throws:

LdapInvalidDnException - If the resulting Dn is invalid

Dn

public Dn(Rdn rdn,
          Dn dn)
   throws LdapInvalidDnException

Creates a Dn concatenating a Rdn and a Dn.

Parameters:

rdn - the Rdn to add to the Dn

dn - the Dn

Throws:

LdapInvalidDnException - If the resulting Dn is invalid

Dn

public Dn(SchemaManager schemaManager,
          Rdn... rdns)
   throws LdapInvalidDnException

Creates a Schema aware Dn from a list of Rdns.

Parameters:

schemaManager - The SchemaManager to use

rdns - the list of Rdns to be used for the Dn

Throws:

LdapInvalidDnException - If the resulting Dn is invalid

Method Detail

getSchemaManager

public SchemaManager getSchemaManager()

Get the associated SchemaManager if any.

Returns:

The SchemaManager

hashCode

public int hashCode()

Gets the hash code of this Dn.

Overrides:

hashCode in class Object

Returns:

the instance hash code

See Also:

Object.hashCode()

getName

public String getName()

Get the user provided Dn

Returns:

The user provided Dn as a String

getNormName

public String getNormName()

Get the normalized Dn. If the Dn is schema aware, the AttributeType will be represented using its OID :

 Dn dn = new Dn( schemaManager, "ou = Example , ou = com" );
 assert( "2.5.4.11=example,2.5.4.11=com".equals( dn.getNormName ) );
 

Otherwise, it will return a Dn with the AttributeType in lower case and the value trimmed :

 Dn dn = new Dn( " CN = A   Test " );
 assertEquals( "cn=A   Test", dn.getNormName() );
 

Returns:

The normalized Dn as a String

size

public int size()

Get the number of RDNs present in the DN

Returns:

The umber of RDNs in the DN

getNbBytes

public static int getNbBytes(Dn 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

isAncestorOf

public boolean isAncestorOf(String dn)

Tells if the current Dn is a parent of another Dn.
For instance, dc=com is a ancestor of dc=example, dc=com

Parameters:

dn - The child

Returns:

true if the current Dn is a parent of the given Dn

isAncestorOf

public boolean isAncestorOf(Dn dn)

Tells if the current Dn is a parent of another Dn.
For instance, dc=com is a ancestor of dc=example, dc=com

Parameters:

dn - The child

Returns:

true if the current Dn is a parent of the given Dn

isDescendantOf

public boolean isDescendantOf(String dn)

Tells if a Dn is a child of another Dn.
For instance, dc=example, dc=com is a descendant of dc=com

Parameters:

dn - The parent

Returns:

true if the current Dn is a child of the given Dn

isDescendantOf

public boolean isDescendantOf(Dn dn)

Tells if a Dn is a child of another Dn.
For instance, dc=example, dc=apache, dc=com is a descendant of dc=com

Parameters:

dn - The parent

Returns:

true if the current Dn is a child of the given Dn

isEmpty

public boolean isEmpty()

Tells if the Dn contains no Rdn

Returns:

true if the Dn is empty

isRootDse

public boolean isRootDse()

Tells if the Dn is the RootDSE Dn (ie, an empty Dn)

Returns:

true if the Dn is the RootDSE's Dn

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

getDescendantOf

public Dn getDescendantOf(String ancestor)
                   throws LdapInvalidDnException

Get the descendant of a given DN, using the ancestr DN. Assuming that a DN has two parts :
DN = [descendant DN][ancestor DN]
To get back the descendant from the full DN, you just pass the ancestor DN as a parameter. Here is a working example :

 Dn dn = new Dn( "cn=test, dc=server, dc=directory, dc=apache, dc=org" );
 
 Dn descendant = dn.getDescendantOf( "dc=apache, dc=org" );
 
 // At this point, the descendant contains cn=test, dc=server, dc=directory"
 

Throws:

LdapInvalidDnException

getDescendantOf

public Dn getDescendantOf(Dn ancestor)
                   throws LdapInvalidDnException

Get the descendant of a given DN, using the ancestr DN. Assuming that a DN has two parts :
DN = [descendant DN][ancestor DN]
To get back the descendant from the full DN, you just pass the ancestor DN as a parameter. Here is a working example :

 Dn dn = new Dn( "cn=test, dc=server, dc=directory, dc=apache, dc=org" );
 
 Dn descendant = dn.getDescendantOf( "dc=apache, dc=org" );
 
 // At this point, the descendant contains cn=test, dc=server, dc=directory"
 

Throws:

LdapInvalidDnException

getAncestorOf

public Dn getAncestorOf(String descendant)
                 throws LdapInvalidDnException

Get the ancestor of a given DN, using the descendant DN. Assuming that a DN has two parts :
DN = [descendant DN][ancestor DN]
To get back the ancestor from the full DN, you just pass the descendant DN as a parameter. Here is a working example :

 Dn dn = new Dn( "cn=test, dc=server, dc=directory, dc=apache, dc=org" );
 
 Dn ancestor = dn.getAncestorOf( "cn=test, dc=server, dc=directory" );
 
 // At this point, the ancestor contains "dc=apache, dc=org"
 

Throws:

LdapInvalidDnException

getAncestorOf

public Dn getAncestorOf(Dn descendant)
                 throws LdapInvalidDnException

Get the ancestor of a given DN, using the descendant DN. Assuming that a DN has two parts :
DN = [descendant DN][ancestor DN]
To get back the ancestor from the full DN, you just pass the descendant DN as a parameter. Here is a working example :

 Dn dn = new Dn( "cn=test, dc=server, dc=directory, dc=apache, dc=org" );
 
 Dn ancestor = dn.getAncestorOf( new Dn( "cn=test, dc=server, dc=directory" ) );
 
 // At this point, the ancestor contains "dc=apache, dc=org"
 

Throws:

LdapInvalidDnException

add

public Dn add(Dn suffix)
       throws LdapInvalidDnException

Throws:

LdapInvalidDnException

add

public Dn add(String comp)
       throws LdapInvalidDnException

Throws:

LdapInvalidDnException

add

public Dn add(Rdn newRdn)
       throws LdapInvalidDnException

Adds a single Rdn to the (leaf) end of this name.

Parameters:

newRdn - the Rdn to add

Returns:

the updated cloned Dn

Throws:

LdapInvalidDnException

getParent

public Dn getParent()

Gets the parent Dn of this Dn. Null if this Dn doesn't have a parent, i.e. because it is the empty Dn.
The Parent is the right part of the Dn, when the Rdn has been removed.

Returns:

the parent Dn of this Dn

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)

apply

public Dn apply(SchemaManager schemaManager,
                boolean force)
         throws LdapInvalidDnException

Normalizes the Dn using the given the schema manager. If the flag is set to true, we will replace the inner SchemaManager by the provided one.

Parameters:

schemaManager - The schemaManagerto use to normalize the Dn

force - Tells if we should replace an existing SchemaManager by a new one

Returns:

The normalized Dn

Throws:

LdapInvalidDnException - If the Dn is invalid.

apply

public Dn apply(SchemaManager schemaManager)
         throws LdapInvalidDnException

Normalizes the Dn using the given the schema manager, unless the Dn is already normalized

Parameters:

schemaManager - The schemaManagerto use to normalize the Dn

Returns:

The normalized Dn

Throws:

LdapInvalidDnException - If the Dn is invalid.

isSchemaAware

public boolean isSchemaAware()

Tells if the Dn is schema aware

Returns:

true if the Dn is schema aware.

iterator

public Iterator<Rdn> iterator()

Iterate over the inner Rdn. The Rdn are returned from the rightmost to the leftmost. For instance, the following code :

 Dn dn = new Dn( "sn=test, dc=apache, dc=org );
 
 for ( Rdn rdn : dn )
 {
     System.out.println( rdn.toString() );
 }
 

will produce this output :

 dc=org
 dc=apache
 sn=test
 

Specified by:

iterator in interface Iterable<Rdn>

isNullOrEmpty

public static boolean isNullOrEmpty(Dn dn)

Check if a DistinguishedName is null or empty.

Parameters:

dn - The Dn to check

Returns:

true> if the Dn is null or empty, false otherwise

isValid

public static boolean isValid(String name)

Check if a DistinguishedName is syntactically valid.

Parameters:

dn - The Dn to validate

Returns:

true> if the Dn is valid, false otherwise

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Throws:

IOException

toString

public String toString()

Return the user provided Dn as a String. It returns the same value as the getName method

Overrides:

toString in class Object

Returns:

A String representing the user provided Dn