directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Emmanuel Lecharny <elecha...@gmail.com>
Subject [Attributes manipulation] How to manipulate attributes inside the server
Date Mon, 19 Mar 2007 22:19:26 GMT
Hi,

We have some serious issues in the server with Attributes manipulation. 
This mail is intended to avoid as much as possible potential breakage 
and bugs, by giving explicit rules of thumb about the way we should 
handle attributes.

First, we will focusing on ADS 1.5, because ADS 1.0.1 is already out.
Second, this mail applies only to in-server attribute manipulations, and 
does not cover clients or tests.

Ok, now, let's get deep into the, well, mud.

1) Introduction, terminology
We have implemented Attribute and Attributes, which are 
javax.naming.directory interfaces 
(http://72.5.124.55/j2se/1.5.0/docs/api/javax/naming/directory/Attribute.html 
and 
http://72.5.124.55/j2se/1.5.0/docs/api/javax/naming/directory/Attributes.html). 
The associated classes in the server are :
org.apache.directory.shared.ldap.message.AttributeImpl
and
org.apache.directory.shared.ldap.message.AttributesImpl

An Attributes can contain many Attribute. Each Attribute contains a key 
(the attribute type) and many values.
As we are in the Ldap World, the Attributes are associated with an Entry.

2) Attribute types
Each Attribute has a key which is unique within an Attributes (Entry). 
This key is *case insensitive*. It means that "cn" is equivalent to "CN" 
or "Cn".
---> First rule : _always use a lowercased attribute name_
This key is not necessarily the best key to identify an attribute. 
Internally, we should *always* use the associated OID (we have a 
relation between an OID and an attribute type : An attributeType 
*always* has a unique OID, when an OID can be associated with more than 
one attributeType)
--> Second rule : _when possible, use the OID instead of any other 
textual name_

What does it mean, in the real world ? Simply, use the OID.

3) Potential problems
The user don't want to receive OIDs when he launch a search. OIDs are 
good for serrvers, not for clients...
Generally, a client ask for a list of attributes as a result of a 
search. This list should be returned as it has been submitted :
let's assume a client has asked for SURNAME, we should not return an 
entry like 2.5.4.4=nerd, but something like SURNAME=nerd

---> Third rule : _return what the client is asking for, not what the 
server is used to manipulate_

Another problem is that we might have to find a specific value of an 
attribute. For instance, we may look for the 'subschema' value in the 
'objectClass' attribute. We have MatchingRules to compare two values. 
Let's suppose we are dealing with the objectClass attributeType : the 
values should be compared case insensitive. PhoneNumber should be 
compared after having remove any inner space. And so on. Each 
attributeType is associated with an Equality Matching Rule which is to 
be used to process comparizons. This leads to CN == cn == cN == Cn, with 
the ObjectClass equality matching rule.

An helper class contains two methods to help dealing with those 
attributeTypes : AttributeUtils.
Three methods has been written :
- containsAnyValues( Attribute, Object[], AttributeType ) : check that 
an attribute contains at least one of the given values
- containsValue( Attribute, Object, AttributeType ) : check that the 
attributes contains the given value
- containsValueCaseIgnore( Attribute, Object ) : special case where we 
check that the value is contained by the attribute, the case sensitivity 
being desabled.

For method 1 and 2, the attributeType is used to call the associated 
comparator.

---> Forth rule : When comparing two attribute values, always use the 
AttributeUtils class, and use the correct method.

Ok, that's all for now, I hope that this little reminder will help to 
build a better server ...

Emmanuel

PS: I think this mail deserves to be put into confluence, but tonite, 
I'm too lazy ...




Mime
View raw message