com.ca.commons.naming
Class RDN

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

public class RDN

extends java.lang.Object

An RDN element. May be multi-valued (but most aren't)

Some quick definitions:

• 'raw' means an rdn with unescaped special characters in it, suitable for display to a user - cn=fred+nurk.
• 'escaped' means with special characters escaped in a form suitable for jndi transmission (leading '\' characters, and quad slashes '\\\\' for an escaped slash.
• 'jndireturn' means an incorrectly escaped string from a jndi query which requires special handling due to bugs (?) in jndi (as of java 1.3)

Values are entered and stored in the RDN unescaped. Utility ftns are provided to translate rdns between these different forms, and functions creating/changing rdns should make sure always to pass the final (no escape character) form when using RDNs.

While parts of an rdn (particular attributes and values) may be manipulated as raw, unescaped strings, entire rdns are always escaped when represented as strings (e.g. by the 'toString()' method).

An added complication is unicode. While strings may be entered as escaped utf8, they are always converted to unicode asap, and never returned as utf8. (they are automatically translated to utf8 by jndi when transmitted to the server, or manually by JXplorer when saving ldif files as a final step).

The class is optimised for single valued RDNs, as this represents the majority of examples seen by the author...

This class uses delayed evaluation of RDN strings. Hence invalid RDNs can be instantiated, and will only throw exceptions when used.

Constructor Summary

RDN()
Empty constructor - creates an RDN with no values.

RDN(RDN copyMe)
clones an RDN.

RDN(java.lang.String rdn)
Standard constructor - creates an RDN using an ldap escaped utf8 rdn string, which may be multi-valued.

Method Summary

void	addEscaped(java.lang.String rdnfragment) adds an ldap escaped utf8 Name element (i.e. the portion of an rdn separated by a '+' sign)
void	addRaw(java.lang.String rdnfragment) adds an unescaped unicode Name element (i.e. one of the parts seperated by a '+' sign).
boolean	contains(java.lang.String attributeType) Utility function - returns true if the passed attribute value is contained within the RDN.
void	dump() Debug prints the raw, unescaped form of the elements.
boolean	equals(java.lang.Object o) Generic equality test allows for test against non-RDN objects via their 'toString()' and a case-insensitive match.
boolean	equals(RDN test) test two RDNs for equivalence.
java.lang.String	getAtt() Gets the first attribute name.
java.lang.String	getAtt(int i) gets the attribute name from a particular indexed rdn element.
java.lang.String[]	getAtts() gets the attribute type names as a String array.
java.lang.String	getElement(int i) Returns the Ith att-val pair in escaped ldap form.
java.lang.String[]	getElements() Returns all elements as a string array, in escaped ldap form.
java.lang.String	getRawVal() Gets the first raw, unescaped, attribute value.
java.lang.String	getRawVal(int i) gets the raw, unescaped, attribute value from a particular indexed rdn element.
java.lang.String	getRawVal(java.lang.String attributeType) Utility function - returns a raw attribute value looked up by name.
java.lang.String[]	getRawVals() gets the attribute type names as a String array.
boolean	isEmpty() Whether the rdn is empty (i.e. is an empty string)
boolean	isMultiValued()
void	setElement(int i, java.lang.String ldapEscapedElement) Sets the Ith att-val pair in escaped ldap form.
void	setRawVal(java.lang.String v) Sets the raw, unescaped value of uni-valued rdn.
void	setRawVal(java.lang.String v, int i) sets a raw, unescaped, value at a particular index position.
int	size() returns the number of sub-elements in this rdn.
java.lang.String	toString() Returns the RDN as an ldap escaped ldap utf8 string.
boolean	validate() Checks whether the RDN is valid (i.e. has non null, correctly escaped elements).

Methods inherited from class java.lang.Object

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

Constructor Detail

RDN

public RDN()

Empty constructor - creates an RDN with no values.

RDN

public RDN(java.lang.String rdn)

Standard constructor - creates an RDN using an ldap escaped utf8 rdn string, which may be multi-valued.

Parameters:

rdn - the string rdn to be parsed

RDN

public RDN(RDN copyMe)

clones an RDN.

Parameters:

copyMe - the RDN to copy.

Method Detail

isEmpty

public boolean isEmpty()

Whether the rdn is empty (i.e. is an empty string)

addEscaped

public void addEscaped(java.lang.String rdnfragment)
                throws javax.naming.InvalidNameException

adds an ldap escaped utf8 Name element (i.e. the portion of an rdn separated by a '+' sign)

Parameters:

rdnfragment - an attribute = value pair.

javax.naming.InvalidNameException

addRaw

public void addRaw(java.lang.String rdnfragment)
            throws javax.naming.InvalidNameException

adds an unescaped unicode Name element (i.e. one of the parts seperated by a '+' sign).

Parameters:

rdnfragment - an attribute = value pair.

javax.naming.InvalidNameException

toString

public java.lang.String toString()

Returns the RDN as an ldap escaped ldap utf8 string. (This is a very inexpensive operation - it simply returns the pre-existing string.)

Overrides:

toString in class java.lang.Object

Returns:

the internal representation of the RDN as an ldap escaped string.

dump

public void dump()

Debug prints the raw, unescaped form of the elements.

getElement

public java.lang.String getElement(int i)

Returns the Ith att-val pair in escaped ldap form.

Parameters:

i - the element index to get (counting from 0)

Returns:

the attribute value pair.

getElements

public java.lang.String[] getElements()

Returns all elements as a string array, in escaped ldap form.

setElement

public void setElement(int i,
                       java.lang.String ldapEscapedElement)
                throws javax.naming.InvalidNameException

Sets the Ith att-val pair in escaped ldap form.

Parameters:

i - the element index to get (counting from 0)

ldapEscapedElement - the element to replace (if the rdn is single valued, this would be the whole rdn.)

javax.naming.InvalidNameException

getAtt

public java.lang.String getAtt()

Gets the first attribute name.

getAtt

public java.lang.String getAtt(int i)

gets the attribute name from a particular indexed rdn element.

getAtts

public java.lang.String[] getAtts()

gets the attribute type names as a String array.

Returns:

an array of attribute types as a string; e.g. {'cn', 'uid'}

contains

public boolean contains(java.lang.String attributeType)

Utility function - returns true if the passed attribute value is contained within the RDN. This is case insensitive.

Returns:

true if it exists in the RDN, false if not.

getRawVal

public java.lang.String getRawVal(java.lang.String attributeType)

Utility function - returns a raw attribute value looked up by name. This search is case insensitive. Note that this class is not optimized for this function .

Parameters:

attributeType - the attribute type to find the corresponding value for (e.g. "cn").

Returns:

String the corresponding value (e.g. "Fred"), or null if there is no such value.

getRawVal

public java.lang.String getRawVal()

Gets the first raw, unescaped, attribute value.

getRawVal

public java.lang.String getRawVal(int i)

gets the raw, unescaped, attribute value from a particular indexed rdn element.

getRawVals

public java.lang.String[] getRawVals()

gets the attribute type names as a String array.

Returns:

an array of attribute types as a string; e.g. {'cn', 'uid'}

setRawVal

public void setRawVal(java.lang.String v)
               throws javax.naming.InvalidNameException

Sets the raw, unescaped value of uni-valued rdn.

javax.naming.InvalidNameException

setRawVal

public void setRawVal(java.lang.String v,
                      int i)
               throws javax.naming.InvalidNameException

sets a raw, unescaped, value at a particular index position.

javax.naming.InvalidNameException

size

public int size()

returns the number of sub-elements in this rdn. (usually one!)

isMultiValued

public boolean isMultiValued()

equals

public boolean equals(RDN test)

test two RDNs for equivalence. Takes a bit of a shortcut - checks for case insensitive equivalence, doesn't check schema to see whether the value is case sensitive or not...

equals

public boolean equals(java.lang.Object o)

Generic equality test allows for test against non-RDN objects via their 'toString()' and a case-insensitive match.

Overrides:

equals in class java.lang.Object

validate

public boolean validate()

Checks whether the RDN is valid (i.e. has non null, correctly escaped elements). A (relatively) expensive operation.