com.ca.commons.naming
Class DN

java.lang.Object
  |
  +--com.ca.commons.naming.DN

All Implemented Interfaces:

java.lang.Cloneable, javax.naming.Name, java.io.Serializable

public class DN

extends java.lang.Object

implements javax.naming.Name

A Data class that encapsulated the idea of an ldap Distinguished Name of the form: ou=frog farmers,o=frogcorp,c=au - and provides a bunch of utility methods for modifying and reading these values, especially the various bits of each rdn in various ways.

implements javax.naming.Name.

Why don't we just use CompoundName or CompositeName?
- basically because we're not supporting multiple naming systems - we're *only* supporting ldap. So Name is implemented for support with existing jndi ftns, but also a lot of other stuff is needed for rdns, and multi-value rdns. This could be architected as, say, compound name with another helper class, but that seems clumsy.

See Also:

Serialized Form

Field Summary

static java.lang.String

BLANKBASEDN Default constructor creates a DN with no value set.

Constructor Summary

DN()

DN(DN copyMe)
Copy constructor creates a new DN with an item by item copy of the parameter DN.

DN(javax.naming.Name name)
This Constructor takes an existing jndi Name, And initialises itself by taking that Name's rdn elements an element at a time, and converting them to RDN objects.

DN(java.lang.String ldapDN)
Main Constructor takes an ldap Distinguished Name string (e.g.

Method Summary

javax.naming.Name	add(int posn, RDN rdn) The core method for adding RDN objects to the name.
javax.naming.Name	add(int posn, java.lang.String rdn)
javax.naming.Name	add(RDN rdn) Add an RDN to the end of the DN.
javax.naming.Name	add(java.lang.String rdn)
javax.naming.Name	addAll(int posn, javax.naming.Name n)
javax.naming.Name	addAll(javax.naming.Name suffix)
void	addChildRDN(RDN rdn) Adds a new 'deepest level' RDN to a DN
void	addChildRDN(java.lang.String rdn) Adds a new 'deepest level' RDN to a DN
void	addParentRDN(java.lang.String rdn) Adds an RDN to an existing DN at the highest level - mainly used internally while parsing a DN.
static void	checkRDN(java.lang.String RDN) roughly checks if an RDN is syntactically and schematically correct.
void	clear() Empties the DN of all RDNs.
java.lang.Object	clone()
int	compareTo(java.lang.Object obj)
void	debugPrint() dumps the dn in a structured form, demonstrating parsing.
boolean	endsWith(javax.naming.Name n)
boolean	equals(DN testDN) Check whether this DN is equal to another DN...
boolean	equals(java.lang.Object o) implement the object.equals(object) method for genericity and unit testing.
boolean	error() Whether there was an error using this DN (i.e. when creating it).
protected java.lang.String	exchangeRDNelementValue(java.lang.String rdn, java.lang.String value) Exchanges the value of an rdn att=val element, and returns
java.lang.String	get(int posn)
java.util.Enumeration	getAll()
java.lang.String	getDN() a synonym for 'toString()' this returns the full ldap DN.
java.lang.String	getError() Gets the error message (if any) associated with this DN.
RDN	getLowestRDN() gets the value of the lowest ldap RDN, i.e. the furthest-from-the-root class value of the DN.
javax.naming.Name	getPrefix(int posn)
RDN	getRDN(int i) gets the full RDN (e.g.
java.lang.String	getRDNAttribute(int i) gets the ldap 'class' (e.g.
java.lang.String	getRDNValue(int i) gets the ldap value (e.g.
RDN	getRootRDN() Returns the root RDN as a string (e.g.
javax.naming.Name	getSuffix(int posn)
boolean	isEmpty() returns true if this is an 'empty', or root DN (i.e. \"\")
DN	parentDN() Returns the full DN of this DN's immediate parent (i.e. returns this DN after removing the lowest RDN)
java.lang.Object	remove(int posn)
void	reverse() reverse the order of elements in a DN...
void	setError(java.lang.String e) Overload this method for app specific error handling.
void	setLowestRDNRawValue(java.lang.String value) sets (or more often resets) the lowest (furthest-from-root) value of the DN
void	setRDN(RDN rdn, int i) gets the full RDN (e.g.
boolean	sharesParent(DN testDN) Tests if the DNs are identical except for the lowest RDN (e.g. they are leaves on the same branch)
int	size()
boolean	startsWith(DN testDN) Checks whether the testDN is a subset of the current DN, starting from the root.
boolean	startsWith(javax.naming.Name n)
java.lang.String	toFormattedString() Spits back the DN as a tree-level formatted string (mainly for debugging)
java.lang.String	toString() Spits back the DN as an escaped ldap DN string

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

BLANKBASEDN

public static java.lang.String BLANKBASEDN

Default constructor creates a DN with no value set.

Constructor Detail

DN

public DN()

DN

public DN(DN copyMe)

Copy constructor creates a new DN with an item by item copy of the parameter DN.

DN

public DN(java.lang.String ldapDN)

Main Constructor takes an ldap Distinguished Name string (e.g. 'ou=wombat botherers,o=nutters inc,c=au') and breaks it up into a vector of RDNs

Parameters:

ldapDN - the ldap distinguished name to be parsed.

DN

public DN(javax.naming.Name name)

This Constructor takes an existing jndi Name, And initialises itself by taking that Name's rdn elements an element at a time, and converting them to RDN objects.

Method Detail

toString

public java.lang.String toString()

Spits back the DN as an escaped ldap DN string

Overrides:

toString in class java.lang.Object

toFormattedString

public java.lang.String toFormattedString()

Spits back the DN as a tree-level formatted string (mainly for debugging)

getDN

public java.lang.String getDN()

a synonym for 'toString()' this returns the full ldap DN.

getRDNAttribute

public java.lang.String getRDNAttribute(int i)

gets the ldap 'class' (e.g. 'c' or 'cn') for a particular RDN. If there are multiple attributes (for a multi-valued rdn) only the first is returned (XXX).

Parameters:

i - the index of the RDN class to return.

getRDNValue

public java.lang.String getRDNValue(int i)

gets the ldap value (e.g. 'au' or 'Silverstone, Alicia') for a particular RDN. If there are multiple values, only the first is returned (XXX).

Parameters:

i - the index of the RDN value to return.

debugPrint

public void debugPrint()

dumps the dn in a structured form, demonstrating parsing.

setRDN

public void setRDN(RDN rdn,
                   int i)

gets the full RDN (e.g. 'c=au' or 'cn=Englebert Humperdink') for a particular indexed RDN.

Parameters:

i - the index of the RDN to return.

getRDN

public RDN getRDN(int i)

gets the full RDN (e.g. 'c=au' or 'cn=Englebert Humperdink') for a particular indexed RDN.

Parameters:

i - the index of the RDN to return.

getRootRDN

public RDN getRootRDN()

Returns the root RDN as a string (e.g. 'c=au')

getLowestRDN

public RDN getLowestRDN()

gets the value of the lowest ldap RDN, i.e. the furthest-from-the-root class value of the DN. (i.e. 'ou=frog fanciers' in 'ou=frog fanciers,o=nutters,c=uk'

checkRDN

public static void checkRDN(java.lang.String RDN)
                     throws javax.naming.InvalidNameException

roughly checks if an RDN is syntactically and schematically correct.

Parameters:

RDN - the RDN string to check for correctness

javax.naming.InvalidNameException

addParentRDN

public void addParentRDN(java.lang.String rdn)

Adds an RDN to an existing DN at the highest level - mainly used internally while parsing a DN.

addChildRDN

public void addChildRDN(java.lang.String rdn)
                 throws javax.naming.InvalidNameException

Adds a new 'deepest level' RDN to a DN

javax.naming.InvalidNameException

addChildRDN

public void addChildRDN(RDN rdn)
                 throws javax.naming.InvalidNameException

Adds a new 'deepest level' RDN to a DN

javax.naming.InvalidNameException

setLowestRDNRawValue

public void setLowestRDNRawValue(java.lang.String value)

sets (or more often resets) the lowest (furthest-from-root) value of the DN

Parameters:

value - the (raw, unescaped) new lowest RDN value to overwrite the existing lowest RDN value with

exchangeRDNelementValue

protected java.lang.String exchangeRDNelementValue(java.lang.String rdn,
                                                   java.lang.String value)

Exchanges the value of an rdn att=val element, and returns

equals

public boolean equals(DN testDN)

Check whether this DN is equal to another DN...

Parameters:

testDN - the DN to compare against this DN

equals

public boolean equals(java.lang.Object o)

implement the object.equals(object) method for genericity and unit testing. Note that this is slower than DN.equals(DN), since it requires instanceof checks.

Overrides:

equals in class java.lang.Object

Parameters:

o - a DN or Name object to test against

startsWith

public boolean startsWith(DN testDN)

Checks whether the testDN is a subset of the current DN, starting from the root. Currently case insensitive.

Parameters:

testDN - the subset DN to test against

sharesParent

public boolean sharesParent(DN testDN)

Tests if the DNs are identical except for the lowest RDN (e.g. they are leaves on the same branch)

Parameters:

testDN - the putatitive sibling DN

parentDN

public DN parentDN()

Returns the full DN of this DN's immediate parent (i.e. returns this DN after removing the lowest RDN)

reverse

public void reverse()

reverse the order of elements in a DN...

clear

public void clear()

Empties the DN of all RDNs.

setError

public void setError(java.lang.String e)

Overload this method for app specific error handling.

error

public boolean error()

Whether there was an error using this DN (i.e. when creating it).

getError

public java.lang.String getError()

Gets the error message (if any) associated with this DN.

add

public javax.naming.Name add(RDN rdn)

Add an RDN to the end of the DN.

add

public javax.naming.Name add(int posn,
                             RDN rdn)

The core method for adding RDN objects to the name. Called by all add methods.

Parameters:

posn - the position in the DN to add the RDN at (0 = root)

rdn - the RDN to add (may be multi-valued).

add

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

Specified by:

add in interface javax.naming.Name

javax.naming.InvalidNameException

add

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

Specified by:

add in interface javax.naming.Name

javax.naming.InvalidNameException

addAll

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

Specified by:

addAll in interface javax.naming.Name

javax.naming.InvalidNameException

addAll

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

Specified by:

addAll in interface javax.naming.Name

javax.naming.InvalidNameException

clone

public java.lang.Object clone()

Specified by:

clone in interface javax.naming.Name

Overrides:

clone in class java.lang.Object

compareTo

public int compareTo(java.lang.Object obj)

Specified by:

compareTo in interface javax.naming.Name

endsWith

public boolean endsWith(javax.naming.Name n)

Specified by:

endsWith in interface javax.naming.Name

get

public java.lang.String get(int posn)

Specified by:

get in interface javax.naming.Name

getAll

public java.util.Enumeration getAll()

Specified by:

getAll in interface javax.naming.Name

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

isEmpty

public boolean isEmpty()

returns true if this is an 'empty', or root DN (i.e. \"\")

Specified by:

isEmpty in interface javax.naming.Name

remove

public java.lang.Object remove(int posn)

Specified by:

remove in interface javax.naming.Name

size

public int size()

Specified by:

size in interface javax.naming.Name

startsWith

public boolean startsWith(javax.naming.Name n)

Specified by:

startsWith in interface javax.naming.Name