directory-api mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matthew Swift <Matthew.Sw...@Sun.COM>
Subject Re: [DN] Existing API review
Date Thu, 14 Jan 2010 21:46:40 GMT


On 14/01/10 00:43, Emmanuel LŽcharny wrote:
> [...]
> Well, I don't really think that it's anything but implementation 
> dependent, so from the API POV, it's irrelevant. As soon as we add the 
> valueof() methods, those who want to add a cache can do it.
>

It's very relevant from an API POV. Being future proof is an essential 
part of any API. Client applications will need to be modified if a 
valueOf constructor is added at a later date in order to take advantage 
of any potential perf improvements. By including the valueOf initially 
applications can choose to use the constructor knowing that they will 
inherit any future improvements such as caching.

If for learnability reasons we decide that a DN(String) constructor is 
required then so be it, but it should include Javadoc recommending that 
users use the valueOf constructor in preference.



> I don't know why I raised this point...
>>
>>> The base constructor we can have are probably something like:
>>> DN()
>>> DN(String dnStr)
>>> DN( RDN... rdns)
>>> DN( RDN rdn, DN parent)
>>>
>>
>>
>> I like the DN( RDN rdn, DN parent) constructor - we support this via 
>> an instance method called DN.child(RDN). I think I prefer the 
>> constructor approach since it is not clear from our "child" method 
>> whether or not it modifies this DN or creates a new DN.  A 
>> constructor is more obvious. You may want to have a concatenation 
>> constructor DN(DN child, DN parent) for constructing DNs of entries 
>> within a subtree using a relative DN (or "local name").
> Why not a DN(DN child, DN parent) constructor two. It does not hurt 
> and can help.

OK.

>>
>> One thing that is a bit tricky is whether or not the API should order 
>> RDN parameters in little-endian (LDAP World) order or big-endian 
>> (everyone else outside of LDAP) order. I think first time users may 
>> be surprised by LDAP's unnatural little endian ordering.
> I think we should keep the LDAP order when using DN( RDN...) 
> constructor. For instance, if we want to create "dc=example, dc=org", 
> that would be :
> DN( "dc=example", "dc=org") (here, I use the String, but you should 
> read RDN)


Ok, fair enough.


>>
>> Also, I strongly believe that DNs and RDNs and AVAs should be 
>> immutable objects (as well as any other low level API type). What do 
>> you think?
> DN and RDN should be immutable, sure. AVA, I have some doubt.

If AVA is mutable then it is impossible for DN and RDN to be immutable 
unless they do defensive copies which will be a bit annoying.


>>
>> Also, on the subject of AVAs - we have the AVA type as an inner class 
>> in RDN. I'm not particularly happy with this this, but less happy 
>> with it being a standalone class since AVAs are only used in RDNs and 
>> may introduce confusion elsewhere. For example, filters also use 
>> attribute value assertions but these are not the same type of object 
>> as an AVA even if they have the same name. For example, AVAs (in 
>> RDNs) do not allow attribute options or matching rules to be specified.
> I don't really like inner classes in this case for two reasons :
> - It will be a big class, and the RN class while be hundreds of line 
> long. Not cool
> - If we just use an Inner class just because we want to hide it from 
> the other classes, then I think it's probably better to have it 
> package protected (ie, no qualifier for this class).
>

If it's package protected then the class will not be part of the public 
API. I'm not sure that I understand?

I agree about inner classes. They look even uglier in the API Javadoc...

Matt


Mime
View raw message