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 Map<String,List<Ava>>	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) Creates a new RDN from a list of AVA
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) Creates a new schema aware RDN from a list of AVA
Rdn(SchemaManager schemaManager, Rdn rdn) Constructs an Rdn from the given rdn.
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 addedAva) Add an Ava to the current schema aware Rdn
private void	addAVA(SchemaManager schemaManager, String type, Value value) Add an Ava to the current Rdn
private List<Ava>	addOrdered(List<Ava> avaList, Ava newAva) Add an AVA in a List of Ava, at the right place (ordered)
private void	buildNormRdn(StringBuilder sb, Ava ava)
(package private) void	clear() Clear the Rdn, removing all the Avas.
Rdn	clone() Clone the Rdn
int	compareTo(Rdn otherRdn) Compare the current RDN with the provided one.
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(int pos) Return the Nth Ava
Ava	getAva(String type) Get the Ava which type is given as an argument.
String	getEscaped()
String	getName()
String	getNormName()
String	getNormType() Return the normalized type, or the first one of we have more than one (the lowest)
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(SchemaManager schemaManager, String dn) Validate a NameComponent :
static boolean	isValid(String dn) Validate a NameComponent :
Iterator<Ava>	iterator() Retrieves the components of this Rdn as an iterator of Avas.
private static void	parse(SchemaManager schemaManager, String dn, Rdn rdn) Parse a NameComponent :
void	readExternal(ObjectInput in) We read back the data to create a new RDB.
int	serialize(byte[] buffer, int pos) Serialize a RDN into a byte[]
(package private) void	setNormName(String normName) Set the normalized Name.
(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 transient 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 transient Map<String,List<Ava>> avaTypes

We also keep a set of types, in order to use manipulations. A type is connected with the Ava it represents.

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 transient 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,
           LdapInvalidAttributeValueException

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

LdapInvalidAttributeValueException - If the given AttributeType or value are invalid

Rdn

public Rdn(String upType,
           String upValue)
    throws LdapInvalidDnException,
           LdapInvalidAttributeValueException

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

LdapInvalidAttributeValueException - If the given AttributeType or Value are incorrect

See Also:

Rdn( SchemaManager, String, String )

Rdn

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

Creates a new schema aware RDN from a list of AVA

Parameters:

schemaManager - The schemaManager to use

avas - The AVA that will be used

Throws:

LdapInvalidDnException - If the RDN is invalid

Rdn

public Rdn(Ava... avas)
    throws LdapInvalidDnException

Creates a new RDN from a list of AVA

Parameters:

avas - The AVA that will be used

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.

Rdn

public Rdn(SchemaManager schemaManager,
           Rdn rdn)
    throws LdapInvalidDnException

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

Parameters:

schemaManager - The SchemaManager

rdn - The non-null Rdn to be copied.

Throws:

LdapInvalidDnException - If the given Rdn is invalid

Method Detail

addOrdered

private List<Ava> addOrdered(List<Ava> avaList,
                             Ava newAva)

Add an AVA in a List of Ava, at the right place (ordered)

Parameters:

avaList - The list of Ava

newAva - The Ava to add

Returns:

The list of Ava with the new Ava at the right position

addAVA

private void addAVA(SchemaManager schemaManager,
                    String type,
                    Value value)
             throws LdapInvalidDnException

Add an Ava to the current Rdn

Parameters:

schemaManager - The SchemaManager

type - The user provided type of the added Rdn.

value - The user provided provided value of the added Rdn

Throws:

LdapInvalidDnException - If the Rdn is invalid

addAVA

void addAVA(SchemaManager schemaManager,
            Ava addedAva)
     throws LdapInvalidDnException

Add an Ava to the current schema aware Rdn

Parameters:

schemaManager - The SchemaManager

addedAva - The added Ava

Throws:

LdapInvalidDnException - If the Ava is invalid

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

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

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

getNormName

public String getNormName()

Returns:

the normalized name

setNormName

void setNormName(String normName)

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

Parameters:

normName - the Normalized 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

getAva

public Ava getAva(int pos)

Return the Nth Ava

Parameters:

pos - The Ava we are looking for

Returns:

The Ava at the given position in 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

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.

getEscaped

public String getEscaped()

Returns:

The RDN as an escaped String

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

isValid

public static boolean isValid(SchemaManager schemaManager,
                              String dn)

Validate a NameComponent :

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

Parameters:

schemaManager - The Schemamanager to use

dn - The string to parse

Returns:

true if the Rdn is valid

parse

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

Parse a NameComponent :

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

Parameters:

schemaManager - The SchemaManager

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 the serialization failed

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

buildNormRdn

private void buildNormRdn(StringBuilder sb,
                          Ava ava)

compareTo

public int compareTo(Rdn otherRdn)

Compare the current RDN with the provided one.

Specified by:

compareTo in interface Comparable<Rdn>

Parameters:

otherRdn - The RDN we want to compare to

Returns:

a negative value if the current RDN is below the provided one, a positive value if it's above and 0 if they are equal.

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