Mailing-List: contact api-help@directory.apache.org; run by ezmlm
Precedence: bulk
Reply-To: api@directory.apache.org
Received-SPF: pass (nike.apache.org: domain of elecharny@gmail.com designates
 209.85.219.217 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=message-id:date:from:user-agent:mime-version:to:subject:references
         :in-reply-to:content-type:content-transfer-encoding;
        b=wb9ia6K6zBN8uj/26NshnMRySDL3JwgsHk13khQSqxgsn9moLgdzH5CZ9T7FDGJlDc
         Qjrp2wW5gFeMqpjymDMvSQA1IMoxisCt+Nku24Q0w4z7d3JdREOR1jMIXoVnJNA9T+2A
         pwiklTgN9/pS5m5EwVBVJRbRnDmWKrC7PmcYM=
Message-ID: <4B4F9A97.40800@gmail.com>
Date: Thu, 14 Jan 2010 23:28:39 +0100
From: =?UTF-8?B?RW1tYW51ZWwgTMKOY2hhcm55?= <elecharny@gmail.com>
User-Agent: Thunderbird 2.0.0.23 (Macintosh/20090812)
MIME-Version: 1.0
To: api@directory.apache.org
Subject: Re: [DN] Existing API review
References: <4B4C7948.3000503@gmail.com> <4B4DAD6E.4040204@sun.com>
 <4B4E5AA6.7060907@gmail.com> <4B4F90C0.8050809@sun.com>
In-Reply-To: <4B4F90C0.8050809@sun.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit

Matthew Swift a écrit :
>
>
> 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. 
Sorry, you don't caught what I wanted to express, or I wasn't able to 
express what I had in mind.

I meant that discussing this point is irrelevant, just because having 
both the constructor *and* the valueof makes sense to me now.

> 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.
On the same page.
>
> 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.
Well, here, I disagree. Users are smat enough to understand the 
difference between both methods to create objects, and i don't thik we 
have to stress it out, otherwise people will keep asking 'why are you 
keeping those two guys in the API ?'
>
>>>
>>> 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.
I'm probably confusing the creation of AVA and the presence of setters. 
Anyway, if AVAs is not visible, it' s a non issue.
>
>
>>>
>>> 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?
Well, it's to protect the class from being used (then no need to make it 
immutable ;)