Mailing-List: contact api-help@directory.apache.org; run by ezmlm
Precedence: bulk
Reply-To: api@directory.apache.org
Received-SPF: pass (athena.apache.org: domain of elecharny@gmail.com
 designates 74.125.78.25 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=message-id:date:from:reply-to:user-agent:mime-version:to:subject
         :references:in-reply-to:content-type:content-transfer-encoding;
        b=hkg1dnTmLia4JGj/ab7ERBBFfNNrE/FzQw4OyvnZNlY+O6jIU3JIINBVa17Rk2bhl8
         bDNYpoDEcgwF4TDT/6Zhq8NAGZmc/4PvTWBK54mcVJsFKsRGF3n+x4PyUN6qnfRDMMTU
         xyMUlKyqWH0ucVrLKmuPjOmgrLtbZuocZxSu0=
Message-ID: <4B6D4E91.3000209@gmail.com>
Date: Sat, 06 Feb 2010 12:12:17 +0100
From: Emmanuel Lecharny <elecharny@gmail.com>
Reply-To: elecharny@apache.org
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US;
 rv:1.9.1.7) Gecko/20100111 Thunderbird/3.0.1
MIME-Version: 1.0
To: api@directory.apache.org
Subject: Re: Entry API
References: <4B6B143C.40205@gmail.com>
 <a32f6b021002041154l28975ebav6674005137ef81ac@mail.gmail.com>
 <4B6CAB11.8060805@sun.com>
In-Reply-To: <4B6CAB11.8060805@sun.com>
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Transfer-Encoding: 8bit

On 2/6/10 12:34 AM, Matthew Swift wrote:
> I totally agree with Alex. Entry MUST be an interface - I feel very 
> strongly about this :-)
this is probably why ODS and ADS Entry are both interface :)

Alex is right here : having it an interface does not obliterate the future.
>
> In ODS we take the Collections API approach by having Entry defined as 
> an interface and then providing several sub-implementations based on 
> the storage/retrieval model the implementation provides. We only have 
> one implementation so far which is a TreeMap based Entry called 
> SortedEntry (it may have been better to call it TreeMapEntry). This 
> gives nice user-friendly behavior in GUIs for example since our 
> AttributeDescription (the keys in the TreeMap) have a sort order: 
> objectClass first, then user attributes, then operational attributes, 
> each group sorted alphabetically. 
IMHO, I find this a bit dubious that any user will need to get 
attributes sorted. In most cases, you simply pull a specific attribute 
from an entry, and rarely use an iterator on attributes which needs them 
to be ordered. Anyway, I see no reason either not to propose such an 
implementation. I just think it should not be the base implementation 
for the API users.
> However, this is not so good in other use cases:
>
>    * other tools would be better using a LinkedHashMap instead in order
>      to preserve the original ordering
>
>    * proxy like apps are unlikely to need to query the entry, just
>      reserialize it, so they need an implementation which is tuned for
>      decode/encode
>
>    * entry caches need an implementation tuned for memory footprint and
>      which is read-only
>
>    * a tool such as searchrate would need a "null" entry implementation
>      - it throws away any attributes you attempt to store in the entry
>      (typically you don't want a searchrate tool to decode every
>      SearchResultEntry into a TreeMap/LinkHashMap based Entry).
>
>
> That's just a few example use cases and I can think of a few others too.
Yeah, and this is why Entry *must* be an interface, I now agree. 
Sometime you have to be the devil advocate...
>
> I also agree with the requirement to have an EntryFactory interface. 
> This can be passed to search operations in order to determine which 
> implementation is used.
Question is : should we use this factory to define a default 
implementation which should not be visible to the users, and use a 
specific object (like SortedEntry) for specific needs ?
>
> I recently raised these RFEs to the ODS SDK which proves that I am not 
> making this up as I go along: ;-)
>
>    https://opends.dev.java.net/issues/show_bug.cgi?id=4425
>    https://opends.dev.java.net/issues/show_bug.cgi?id=4426
I would make those proposal a part of an extended API. KISS...
>
> As for naming, I am a bit against having a "default implementation" 
> called something like EntryImpl since the name does not communicate 
> anything about how it works (is it sorted, original order, etc?).
In my mind, it does not have to convoy any information about the entry 
but the DN and the Attributes. Every other behavior should be delivered 
though subclasses. If we use a factory to create an Entry, then it may 
even be not visible.
>
> Regarding schema, I have implemented the following policy in our SDK:
>
>    * DNs need a schema for decoding
>
>    * Attribute descriptions need a schema for decoding
>
>    * Filters need a schema during compilation (out of scope here as
>      this is a server side thing)
Well, you can control the filter before sending the request to the 
server. It can save CPU on the server at a small price on the client...
>
>    * Entries need a schema for schema validation
>
>    * IIRC all other objects in the SDK either do not need schema (e.g.
>      SearchScope) or are containers of some sort containing DNs,
>      attributes, etc (e.g. entries, requests, etc). Containers:
>
>          o provide methods which accept pre-decoded objects (DN,
>            AttributeDescription, Attribute, etc) which are already
>            associated with a schema
>
>          o provide ease-of-use String based methods (e.g.
>            Entry.setDN(String))
>
>          o have no intrinsic Schema associated with them. Otherwise,
>            consider what it means if an Entry did have an intrinsic
>            Schema - what would happen if I call Entry.setDN(DN) using a
>            DN decoded using a different schema? Should an exception be
>            thrown?
>
>          o attempts to use String based methods which require some form
>            of decoding (e.g. Entry.setDN(String)) always use the global
>            default schema.
Not sure if you consider Entry as a container (ie "have no intrinsic 
Schema") or if "Entries need a schema for schema validation".

In your third point about containers, if an entry has an associated 
schema which is different from the schema used to create the DN, then I 
think we should throw an exception All in all, schemas are associated 
with a subtree, clearly defined by the DN, so the entry's schema must be 
the DN schema.
>
> I don't know if it makes much sense to you guys - I understand that 
> there is no right or wrong way here. I took this approach after 
> spending many hours (days?) pondering and playing around with 
> alternatives and simply settled on the one above. I figured that if 
> applications are using String based methods then they are probably 
> only using a single default schema. I think that this is a reasonable 
> assumption and avoids potentially confusing APIs and unexpected 
> behaviors. E.g:
>
>    Schema schema1 = ...;
>    Schema schema2 = ...;
>
>    DN dn = DN.valueOf(schema1, "dc=example,dc=com");
>
>    // Two different schema - what happens here?
>    Entry entry = new LinkedHashMapEntry(schema2, dn);
Bang ! You have to punish people doing mistakes ;) Seriously, if we can 
detect such errors early in the process, and likely on the client, it 
will help the server.

Another point too : how many users will deal with more than one schema ? 
(I mean, if we exclude those writing a VD).

Last question : what if someone writes :
DN dn = DN.valueOf( "dc=example, dc=com" )

Should we automatically use a default schema under the hood?

-- 
Regards,
Cordialement,
Emmanuel L�charny
www.nextury.com