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

Class Rdn

java.lang.Object

org.apache.directory.api.ldap.model.name.Rdn

All Implemented Interfaces:

Externalizable, Serializable, Cloneable, Comparable<Rdn>, Iterable<Ava>

public class Rdn
extends Object
implements Cloneable, Externalizable, Iterable<Ava>, Comparable<Rdn>

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 Ava. Those Avas are ordered in the alphabetical natural order : a < b < c ... < z As the type are not case sensitive, we can say that a = A
This class is immutable.

Author:

Apache Directory Project

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected Ava	ava A simple Ava is used to store the Rdn for the simple case where we only have a single type=value.
private List<Ava>	avas Stores all couple type = value.
private String	avaType We keep the type for a single valued Rdn, to avoid the creation of an HashMap
private org.apache.commons.collections.MultiMap	avaTypes We also keep a set of types, in order to use manipulations.
static Rdn	EMPTY_RDN An empty Rdn
static int	EQUAL Constant used in comparisons
private int	h The computed hashcode
static int	INFERIOR Constant used in comparisons
protected static org.slf4j.Logger	LOG The LoggerFactory used by this class
private int	nbAvas The number of Avas.
private boolean	normalized A flag used to tell if the Rdn has been normalized
private String	normName The normalized Rdn
private SchemaManager	schemaManager the schema manager
private static long	serialVersionUID Declares the Serial Version Uid.
static int	SUPERIOR Constant used in comparisons
static int	UNDEFINED CompareTo() results
private String	upName The User Provided Rdn

Constructor Summary

Constructors

Constructor and Description
Rdn() A empty constructor.
Rdn(Ava... avas) A constructor that constructs a Rdn from some values.
Rdn(Rdn rdn) Constructs an Rdn from the given rdn.
Rdn(SchemaManager schemaManager) Creates a new schema aware instance of Rdn.
Rdn(SchemaManager schemaManager, Ava... avas) A constructor that constructs a Schema aware Rdn from some values.
Rdn(SchemaManager schemaManager, String rdn) A constructor that parse a String representing a schema aware Rdn.
Rdn(SchemaManager schemaManager, String upType, String upValue) A constructor that constructs a schema aware Rdn from a type and a value.
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.

Method Summary

Modifier and Type	Method and Description
(package private) void	addAVA(SchemaManager schemaManager, Ava value) Add an Ava to the current schema aware Rdn
private void	addAVA(SchemaManager schemaManager, String upType, String type, Value<?> value) Add an Ava to the current Rdn
Rdn	apply(SchemaManager schemaManager) Transform a Rdn by changing the value to its OID counterpart and normalizing the value accordingly to its type.
(package private) void	clear() Clear the Rdn, removing all the Avas.
Rdn	clone() Clone the Rdn
int	compareTo(Rdn arg0)
int	deserialize(byte[] buffer, int pos) Deserialize a RDN from a byte[], starting at a given position
boolean	equals(Object that) 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	getAva() Return the unique Ava, or the first one of we have more than one
Ava	getAva(String type) Get the Ava which type is given as an argument.
String	getName()
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, as a String
Object	getNormValue(String type) Get the normalized value of the Ava which type is given as an argument.
String	getType() Return the user provided type, or the first one of we have more than one (the lowest)
String	getValue() Return the User Provided value, as a String
Object	getValue(String type) Get the value of the Ava which type is given as an argument.
int	hashCode() Gets the hashcode of this rdn.
boolean	isSchemaAware() Tells if the Rdn is schema aware.
static boolean	isValid(String dn) Validate a NameComponent :
Iterator<Ava>	iterator() Retrieves the components of this Rdn as an iterator of Avas.
(package private) void	normalize() Transform the external representation of the current Rdn to an internal normalized form where : - types are trimmed and lower cased - values are trimmed and lower cased
private static void	parse(String dn, Rdn rdn) Parse a NameComponent :
void	readExternal(ObjectInput in) We read back the data to create a new RDB.
(package private) void	replaceAva(Ava value, int pos) Replace an Ava into a Rdn at a given position
int	serialize(byte[] buffer, int pos) Serialize a RDN into a byte[]
(package private) void	setUpName(String upName) Set the User Provided Name.
int	size() Get the number of Avas of this Rdn
String	toString()
static Object	unescapeValue(String value) Unescape the given string according to RFC 2253 If in <string> form, a LDAP string representation asserted value can be obtained by replacing (left-to-right, non-recursively) each <pair> appearing in the <string> as follows: replace <ESC><ESC> with <ESC> replace <ESC><special> with <special> replace <ESC><hexpair> with the octet indicated by the <hexpair> If in <hexstring> form, a BER representation can be obtained from converting each <hexpair> of the <hexstring> to the octet indicated by the <hexpair>
void	writeExternal(ObjectOutput out) A Rdn is composed of on to many Avas (AttributeType And Value).

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

LOG

protected static final org.slf4j.Logger LOG

The LoggerFactory used by this class

EMPTY_RDN

public static final Rdn EMPTY_RDN

An empty Rdn

serialVersionUID

private static final long serialVersionUID

Declares the Serial Version Uid.

See Also:

Always Declare Serial Version Uid, Constant Field Values

upName

private String upName

The User Provided Rdn

normName

private String normName

The normalized Rdn

avas

private List<Ava> avas

Stores all couple type = value. We may have more than one type, if the '+' character appears in the Ava. This is a TreeSet, because we want the Avas to be sorted. An Ava may contain more than one value. In this case, the values are String stored in a List.

avaTypes

private org.apache.commons.collections.MultiMap avaTypes

We also keep a set of types, in order to use manipulations. A type is connected with the Ava it represents. Note : there is no Generic available classes in commons-collection...

avaType

private String avaType

We keep the type for a single valued Rdn, to avoid the creation of an HashMap

ava

protected Ava ava

A simple Ava 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.

nbAvas

private int nbAvas

The number of Avas. We store this number here to avoid complex manipulation of Ava and Avas

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

normalized

private boolean normalized

A flag used to tell if the Rdn has been normalized

schemaManager

private SchemaManager schemaManager

the schema manager

h

private volatile int h

The computed hashcode

Constructor Detail

Rdn

public Rdn()

A empty constructor.

Rdn

public Rdn(SchemaManager schemaManager)

Creates a new schema aware instance of Rdn.

Parameters:

schemaManager - the schema manager

Rdn

public Rdn(SchemaManager schemaManager,
           String rdn)
    throws LdapInvalidDnException

A constructor that parse a String representing a schema aware Rdn.

Parameters:

schemaManager - the schema manager

rdn - the String containing the Rdn to parse

Throws:

LdapInvalidDnException - if the Rdn is invalid

Rdn

public Rdn(String rdn)
    throws LdapInvalidDnException

A constructor that parse a String representing a Rdn.

Parameters:

rdn - the String containing the Rdn to parse

Throws:

LdapInvalidDnException - if the Rdn is invalid

Rdn

public Rdn(SchemaManager schemaManager,
           String upType,
           String upValue)
    throws LdapInvalidDnException

A constructor that constructs a schema aware Rdn from a type and a value.

The string attribute values are not interpreted as RFC 414 formatted Rdn strings. That is, the values are used literally (not parsed) and assumed to be un-escaped.

Parameters:

schemaManager - the schema manager

upType - the user provided type of the Rdn

upValue - the user provided value of the Rdn

Throws:

LdapInvalidDnException - if the Rdn is invalid

Rdn

public Rdn(String upType,
           String upValue)
    throws LdapInvalidDnException

A constructor that constructs a Rdn from a type and a value.

Parameters:

upType - the user provided type of the Rdn

upValue - the user provided value of the Rdn

Throws:

LdapInvalidDnException - if the Rdn is invalid

See Also:

Rdn( SchemaManager, String, String )

Rdn

public Rdn(SchemaManager schemaManager,
           Ava... avas)
    throws LdapInvalidDnException

A constructor that constructs a Schema aware Rdn from some values.

Parameters:

schemaManager - The schemaManager to use

avas - The list of values

Throws:

LdapInvalidDnException - If the Rdn is invalid

Rdn

public Rdn(Ava... avas)
    throws LdapInvalidDnException

A constructor that constructs a Rdn from some values.

Parameters:

avas - The list of values

Throws:

LdapInvalidDnException - If the Rdn is invalid

Rdn

public Rdn(Rdn rdn)

Constructs an Rdn from the given rdn. The content of the rdn is simply copied into the newly created Rdn.

Parameters:

rdn - The non-null Rdn to be copied.

Method Detail

normalize

void normalize()

Transform the external representation of the current Rdn to an internal normalized form where : - types are trimmed and lower cased - values are trimmed and lower cased

apply

public Rdn apply(SchemaManager schemaManager)
          throws LdapInvalidDnException

Transform a Rdn by changing the value to its OID counterpart and normalizing the value accordingly to its type. The modified Rdn is a new instance, as the Rdn class is immutable.

Parameters:

schemaManager - the SchemaManager

Returns:

this Rdn, normalized

Throws:

LdapInvalidDnException - if the Rdn is invalid

addAVA

private void addAVA(SchemaManager schemaManager,
                    String upType,
                    String type,
                    Value<?> value)
             throws LdapInvalidDnException

Add an Ava to the current Rdn

Parameters:

upType - The user provided type of the added Rdn.

type - The normalized provided type of the added Rdn.

upValue - The user provided value of the added Rdn

value - The normalized provided value of the added Rdn

Throws:

LdapInvalidDnException - If the Rdn is invalid

replaceAva

void replaceAva(Ava value,
                int pos)
         throws LdapInvalidDnException

Replace an Ava into a Rdn at a given position

Parameters:

value - The modified Ava

pos - The position of the Ava in the Rdn

Throws:

LdapInvalidDnException - If the position is not valid

addAVA

void addAVA(SchemaManager schemaManager,
            Ava value)
     throws LdapInvalidDnException

Add an Ava to the current schema aware Rdn

Parameters:

value - The added Ava

Throws:

LdapInvalidDnException

clear

void clear()

Clear the Rdn, removing all the Avas.

getValue

public Object getValue(String type)
                throws LdapInvalidDnException

Get the value of the Ava 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:

LdapInvalidDnException - if the Rdn is invalid

getNormValue

public Object getNormValue(String type)
                    throws LdapInvalidDnException

Get the normalized value of the Ava which type is given as an argument.

Parameters:

type - the type of the NameArgument

Returns:

the normalized value to be returned, or null if none found.

Throws:

LdapInvalidDnException - if the Rdn is invalid

getAva

public Ava getAva(String type)

Get the Ava 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 Ava, of null if none is found.

iterator

public Iterator<Ava> iterator()

Retrieves the components of this Rdn as an iterator of Avas. 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 Ava

clone

public Rdn clone()

Clone the Rdn

Overrides:

clone in class Object

Returns:

A clone of the current Rdn

getName

public String getName()

Returns:

the user provided name

getNormName

public String getNormName()

Returns:

The normalized name

setUpName

void setUpName(String upName)

Set the User Provided Name. Package private because Rdn is immutable, only used by the Dn parser.

Parameters:

upName - the User Provided dame

getAva

public Ava getAva()

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

Returns:

The first Ava of this Rdn

getType

public String getType()

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

getValue

public String getValue()

Return the User Provided value, as a String

Returns:

The first User provided value of this Rdn

getNormValue

public String getNormValue()

Return the Normalized value, as a String

Returns:

The first Normalized value of this Rdn

equals

public boolean equals(Object that)

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:

that - 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 Avas of this Rdn

Returns:

The number of Avas in this Rdn

unescapeValue

public static Object unescapeValue(String value)

Unescape the given string according to RFC 2253 If in <string> form, a LDAP string representation asserted value can be obtained by replacing (left-to-right, non-recursively) each <pair> appearing in the <string> as follows:

• replace <ESC><ESC> with <ESC>
• replace <ESC><special> with <special>
• replace <ESC><hexpair> with the octet indicated by the <hexpair>

If in <hexstring> form, a BER representation can be obtained from converting each <hexpair> of the <hexstring> to the octet indicated by the <hexpair>

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.

isSchemaAware

public boolean isSchemaAware()

Tells if the Rdn is schema aware.

Returns:

true if the Rdn is schema aware

isValid

public static boolean isValid(String dn)

Validate a NameComponent :

<name-component> ::= <attributeType> <spaces> '=' <spaces> <attributeValue> <nameComponents>

Parameters:

dn - The string to parse

Returns:

true if the Rdn is valid

parse

private static void parse(String dn,
                          Rdn rdn)
                   throws LdapInvalidDnException

Parse a NameComponent :

<name-component> ::= <attributeType> <spaces> '=' <spaces> <attributeValue> <nameComponents>

Parameters:

dn - The String to parse

rdn - The Rdn to fill. Beware that if the Rdn is not empty, the new AttributeTypeAndValue will be added.

Throws:

LdapInvalidDnException - If the NameComponent is invalid

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()

serialize

public int serialize(byte[] buffer,
                     int pos)
              throws IOException

Serialize a RDN into a byte[]

Parameters:

buffer - The buffer which will contain the serilaized form of this RDN

pos - The position in the buffer where to store the RDN

Returns:

The new position in the byte[]

Throws:

IOException - If we had an error while serilaizing the RDN

deserialize

public int deserialize(byte[] buffer,
                       int pos)
                throws IOException,
                       LdapInvalidAttributeValueException

Deserialize a RDN from a byte[], starting at a given position

Parameters:

buffer - The buffer containing the RDN

pos - The position in the buffer

Returns:

The new position

Throws:

IOException - If the serialized value is not a RDN

LdapInvalidAttributeValueException - If the serialized RDN is invalid

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

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

• parentId The parent entry's Id
• nbAvas The number of Avas 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.
• Avas

For each Ava :

• start The position of this Ava in the upName string
• length The Ava user provided length
• Call the Ava write method The Ava itself

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:

Externalizable.readExternal(ObjectInput)

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

We read back the data to create a new RDB. The structure read is exposed in the writeExternal(ObjectOutput) method

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:

Externalizable.readExternal(ObjectInput)

compareTo

public int compareTo(Rdn arg0)

Specified by:

compareTo in interface Comparable<Rdn>

toString

public String toString()

Overrides:

toString in class Object

Returns:

a String representation of the Rdn. The caller will get back the user provided Rdn