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

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

All Implemented Interfaces:

Externalizable, Serializable, Cloneable, Comparable, Iterable<AVA>

public class RDN
extends Object
implements Cloneable, Comparable, Externalizable, Iterable<AVA>

This class store the name-component part or the following BNF grammar (as of RFC2253, par. 3, and RFC1779, fig. 1) :
- <name-component> ::= <attributeType> <spaces> '=' <spaces> <attributeValue> <attributeTypeAndValues>
- <attributeTypeAndValues> ::= <spaces> '+' <spaces> <attributeType> <spaces> '=' <spaces> <attributeValue> <attributeTypeAndValues> | e
- <attributeType> ::= [a-zA-Z] <keychars> | <oidPrefix> [0-9] <digits> <oids> | [0-9] <digits> <oids>
- <keychars> ::= [a-zA-Z] <keychars> | [0-9] <keychars> | '-' <keychars> | e
- <oidPrefix> ::= 'OID.' | 'oid.' | e
- <oids> ::= '.' [0-9] <digits> <oids> | e
- <attributeValue> ::= <pairs-or-strings> | '#' <hexstring> |'"' <quotechar-or-pairs> '"'
- <pairs-or-strings> ::= '\' <pairchar> <pairs-or-strings> | <stringchar> <pairs-or-strings> | e
- <quotechar-or-pairs> ::= <quotechar> <quotechar-or-pairs> | '\' <pairchar> <quotechar-or-pairs> | e
- <pairchar> ::= ',' | '=' | '+' | '<' | '>' | '#' | ';' | '\' | '"' | [0-9a-fA-F] [0-9a-fA-F]
- <hexstring> ::= [0-9a-fA-F] [0-9a-fA-F] <hexpairs>
- <hexpairs> ::= [0-9a-fA-F] [0-9a-fA-F] <hexpairs> | e
- <digits> ::= [0-9] <digits> | e
- <stringchar> ::= [0x00-0xFF] - [,=+<>#;\"\n\r]
- <quotechar> ::= [0x00-0xFF] - [\"]
- <separator> ::= ',' | ';'
- <spaces> ::= ' ' <spaces> | e

A RDN is a part of a DN. It can be composed of many types, as in the RDN following RDN :
ou=value + cn=other value

or
ou=value + ou=another value

In this case, we have to store an 'ou' and a 'cn' in the RDN.

The types are case insensitive.
Spaces before and after types and values are not stored.
Spaces before and after '+' are not stored.

Thus, we can consider that the following RDNs are equals :

'ou=test 1'
' ou=test 1'
'ou =test 1'
'ou= test 1'
'ou=test 1 '
' ou = test 1 '

So are the following :

'ou=test 1+cn=test 2'
'ou = test 1 + cn = test 2'
' ou =test 1+ cn =test 2 '
'cn = test 2 +ou = test 1'

but the following are not equal :
'ou=test 1'
'ou=test 1'
because we have more than one spaces inside the value.

The Rdn is composed of one or more AttributeTypeAndValue (atav) Those atavs are ordered in the alphabetical natural order : a < b < c ... < z As the type are not case sensitive, we can say that a = A

Version:

$Rev: 918756 $, $Date: 2010-03-04 00:05:29 +0100 (Jeu, 04 mar 2010) $

Author:

Apache Directory Project

See Also:

Serialized Form

Field Summary

protected AVA	atav A simple AttributeTypeAndValue is used to store the Rdn for the simple case where we only have a single type=value.
static int	EQUAL Constant used in comparisons
static int	INFERIOR Constant used in comparisons
protected static org.slf4j.Logger	LOG The LoggerFactory used by this class
static int	SUPERIOR Constant used in comparisons
static int	UNDEFINED CompareTo() results

Constructor Summary

RDN()
A empty constructor.

RDN(RDN rdn)
Constructs an Rdn from the given rdn.

RDN(String rdn)
A constructor that parse a String representing a RDN.

RDN(String upType, String upValue)
A constructor that constructs a RDN from a type and a value.

RDN(String upType, String normType, String upValue, String normValue)
A constructor that constructs a RDN from a type and a value.

Method Summary

void	clear() Clear the RDN, removing all the AttributeTypeAndValues.
Object	clone() Clone the Rdn
int	compareTo(Object object) Compares two RDNs.
boolean	equals(Object rdn) Compares the specified Object with this Rdn for equality.
static String	escapeValue(byte[] attrValue) Transform a value in a String, accordingly to RFC 2253
static String	escapeValue(String value) Transform a value in a String, accordingly to RFC 2253
AVA	getAtav() Return the unique AttributeTypeAndValue, or the first one of we have more than one
AVA	getAttributeTypeAndValue(String type) Get the AttributeTypeAndValue which type is given as an argument.
int	getLength() Get the Rdn length
int	getNbAtavs()
String	getNormName()
String	getNormType() Return the normalized type, or the first one of we have more than one (the lowest)
String	getNormValue() Return the normalized value, or the first one of we have more than one (the lowest)
int	getStart() Get the start position
String	getUpName()
String	getUpType() Return the user provided type, or the first one of we have more than one (the lowest)
String	getUpValue() Return the User Provided value
Object	getValue(String type) Get the Value of the AttributeTypeAndValue which type is given as an argument.
int	hashCode() Gets the hashcode of this rdn.
Iterator<AVA>	iterator() Retrieves the components of this RDN as an iterator of AttributeTypeAndValue.
RDN	normalize(Map<String,OidNormalizer> oidsMap) Transform a RDN by changing the value to its OID counterpart and normalizing the value accordingly to its type.
void	readExternal(ObjectInput in)
void	setUpName(String upName) Set the User Provided Name
int	size() Get the number of Attribute type and value of this Rdn
String	toString()
static Object	unescapeValue(String value) Unescape the given string according to RFC 2253 If in form, a LDAP string representation asserted value can be obtained by replacing (left-to-right, non-recursively) each appearing in the as follows: replace with ; replace with ; replace with the octet indicated by the If in form, a BER representation can be obtained from converting each of the to the octet indicated by the
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

atav

protected AVA atav

A simple AttributeTypeAndValue is used to store the Rdn for the simple case where we only have a single type=value. This will be 99.99% the case. This avoids the creation of a HashMap.

UNDEFINED

public static final int UNDEFINED

CompareTo() results

See Also:

Constant Field Values

SUPERIOR

public static final int SUPERIOR

Constant used in comparisons

See Also:

Constant Field Values

INFERIOR

public static final int INFERIOR

Constant used in comparisons

See Also:

Constant Field Values

EQUAL

public static final int EQUAL

Constant used in comparisons

See Also:

Constant Field Values

Constructor Detail

RDN

public RDN()

A empty constructor.

RDN

public RDN(String rdn)
    throws InvalidNameException

A constructor that parse a String representing a RDN.

Parameters:

rdn - The String containing the RDN to parse

Throws:

InvalidNameException - If the RDN is invalid

RDN

public RDN(String upType,
           String normType,
           String upValue,
           String normValue)
    throws InvalidNameException

A constructor that constructs a RDN from a type and a value. Constructs an Rdn from the given attribute type and value. The string attribute values are not interpreted as RFC 2253 formatted RDN strings. That is, the values are used literally (not parsed) and assumed to be un-escaped.

Parameters:

upType - The user provided type of the RDN

upValue - The user provided value of the RDN

normType - The normalized provided type of the RDN

normValue - The normalized provided value of the RDN

Throws:

InvalidNameException - If the RDN is invalid

RDN

public RDN(String upType,
           String upValue)
    throws InvalidNameException

A constructor that constructs a RDN from a type and a value. Constructs an Rdn from the given attribute type and value. The string attribute values are not interpreted as RFC 2253 formatted RDN strings. That is, the values are used literally (not parsed) and assumed to be un-escaped.

Parameters:

upType - The user provided type of the RDN

upValue - The user provided value of the RDN

Throws:

InvalidNameException - If the RDN is invalid

RDN

public RDN(RDN rdn)

Constructs an Rdn from the given rdn. The contents of the rdn are simply copied into the newly created

Parameters:

rdn - The non-null Rdn to be copied.

Method Detail

normalize

public RDN normalize(Map<String,OidNormalizer> oidsMap)
              throws InvalidNameException,
                     NamingException

Transform a RDN by changing the value to its OID counterpart and normalizing the value accordingly to its type.

Parameters:

rdn - The RDN to modify.

oidsMap - The map of all existing oids and normalizer.

Throws:

InvalidNameException - If the RDN is invalid.

NamingException - If something went wrong.

clear

public void clear()

Clear the RDN, removing all the AttributeTypeAndValues.

getValue

public Object getValue(String type)
                throws InvalidNameException

Get the Value of the AttributeTypeAndValue which type is given as an argument.

Parameters:

type - The type of the NameArgument

Returns:

The Value to be returned, or null if none found.

Throws:

InvalidNameException

getStart

public int getStart()

Get the start position

Returns:

The start position in the DN

getLength

public int getLength()

Get the Rdn length

Returns:

The Rdn length

getAttributeTypeAndValue

public AVA getAttributeTypeAndValue(String type)

Get the AttributeTypeAndValue which type is given as an argument. If we have more than one value associated with the type, we will return only the first one.

Parameters:

type - The type of the NameArgument to be returned

Returns:

The AttributeTypeAndValue, of null if none is found.

iterator

public Iterator<AVA> iterator()

Retrieves the components of this RDN as an iterator of AttributeTypeAndValue. The effect on the iterator of updates to this RDN is undefined. If the RDN has zero components, an empty (non-null) iterator is returned.

Specified by:

iterator in interface Iterable<AVA>

Returns:

an iterator of the components of this RDN, each an AttributeTypeAndValue

clone

public Object clone()

Clone the Rdn

Overrides:

clone in class Object

Returns:

A clone of the current RDN

compareTo

public int compareTo(Object object)

Compares two RDNs. They are equals if :

their have the same number of NC (AttributeTypeAndValue)

each ATAVs are equals

comparison of type are done case insensitive

each value is equal, case sensitive

Order of ATAV is not important If the RDNs are not equals, a positive number is returned if the first RDN is greater, negative otherwise

Specified by:

compareTo in interface Comparable

Parameters:

object -

Returns:

0 if both rdn are equals. -1 if the current RDN is inferior, 1 if the current Rdn is superior, UNDEFINED otherwise.

toString

public String toString()

Overrides:

toString in class Object

Returns:

a String representation of the RDN

getUpName

public String getUpName()

Returns:

the user provided name

getNormName

public String getNormName()

Returns:

The normalized name

setUpName

public void setUpName(String upName)

Set the User Provided Name

Parameters:

upName - the User Provided dame

getNbAtavs

public int getNbAtavs()

Returns:

Returns the nbAtavs.

getAtav

public AVA getAtav()

Return the unique AttributeTypeAndValue, or the first one of we have more than one

Returns:

The first AttributeTypeAndValue of this RDN

getUpType

public String getUpType()

Return the user provided type, or the first one of we have more than one (the lowest)

Returns:

The first user provided type of this RDN

getNormType

public String getNormType()

Return the normalized type, or the first one of we have more than one (the lowest)

Returns:

The first normalized type of this RDN

getUpValue

public String getUpValue()

Return the User Provided value

Returns:

The first User provided value of this RDN

getNormValue

public String getNormValue()

Return the normalized value, or the first one of we have more than one (the lowest)

Returns:

The first normalized value of this RDN

equals

public boolean equals(Object rdn)

Compares the specified Object with this Rdn for equality. Returns true if the given object is also a Rdn and the two Rdns represent the same attribute type and value mappings. The order of components in multi-valued Rdns is not significant.

Overrides:

equals in class Object

Parameters:

rdn - Rdn to be compared for equality with this Rdn

Returns:

true if the specified object is equal to this Rdn

size

public int size()

Get the number of Attribute type and value of this Rdn

Returns:

The number of ATAVs in this Rdn

unescapeValue

public static Object unescapeValue(String value)

Unescape the given string according to RFC 2253 If in form, a LDAP string representation asserted value can be obtained by replacing (left-to-right, non-recursively) each appearing in the as follows: replace with ; replace with ; replace with the octet indicated by the If in form, a BER representation can be obtained from converting each of the to the octet indicated by the

Parameters:

value - The value to be unescaped

Returns:

Returns a string value as a String, and a binary value as a byte array.

Throws:

IllegalArgumentException - - When an Illegal value is provided.

escapeValue

public static String escapeValue(String value)

Transform a value in a String, accordingly to RFC 2253

Parameters:

value - The attribute value to be escaped

Returns:

The escaped string value.

escapeValue

public static String escapeValue(byte[] attrValue)

Transform a value in a String, accordingly to RFC 2253

Parameters:

attrValue - The attribute value to be escaped

Returns:

The escaped string value.

hashCode

public int hashCode()

Gets the hashcode of this rdn.

Overrides:

hashCode in class Object

Returns:

the instance's hash code

See Also:

Object.hashCode()

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Parameters:

out - The stream into which the serialized RDN will be put

Throws:

IOException - If the stream can't be written

See Also:

A RDN is composed of on to many ATAVs (AttributeType And Value). We should write all those ATAVs sequencially, following the structure :

nbAtavs

The number of ATAVs to write. Can't be 0.

upName

The User provided RDN

normName

The normalized RDN. It can be empty if the normalized name equals the upName.

atavs

For each ATAV :

start

The position of this ATAV in the upName string

length

The ATAV user provided length

Call the ATAV write method

The ATAV itself

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Parameters:

in - The input stream from which the RDN will be read

Throws:

IOException - If we can't read from the input stream

ClassNotFoundException - If we can't create a new RDN

See Also:

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