On 3/19/07, Emmanuel Lecharny <elecharny@gmail.com> wrote:

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.

Snip ... 

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)

I think this is why we created the AttributeUtils.getAttribute() method which
uses all alias names and the OID to extract the attribute.  However we do not
use it religiously since this method appeared after we noticed issues appearing
for certain corner cases.

--> 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.

Hmm not sure I understand the context here.

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, but something like SURNAME=nerd

Yep I agree completely.

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

Right this way values are compared correctly.

---> 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 ...


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

+1 to being put into confluence :).