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: Entry API
Date Fri, 05 Feb 2010 23:34:41 GMT
I totally agree with Alex. Entry MUST be an interface - I feel very 
strongly about this :-)

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

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.

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

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

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)

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

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


Matt


On 04/02/10 20:54, Alex Karasulu wrote:
> On Thu, Feb 4, 2010 at 8:38 PM, Emmanuel Lecharny<elecharny@gmail.com>wrote:
>
>    
>> Hi,
>>
>> here are some preliminary thoughts about the Entry class.
>>
>> The Entry class
>> ---------------
>>
>> It's the base data structure representing an element stored into a LDAP
>> server. It has a name (a DN) and some attributes.
>>
>> All the existing API use the same name, Entry (or LDAPEntry), except JNDI
>> which has no such class (it uses Attributes but without a DN) and this class
>> contains at least those two inner elements :
>> - a DN
>> - a set of Attribute
>>
>> There is some difference though as this element is either an Interface
>> (ADS, ODS) or a Class (UID, jLdap)
>>
>> ODS define an implementing class named SortedEntry, which does not make a
>> lot of sense, IMO. ADS class hierarchy is even more complex, as there are
>> two lower interfaces (ClientEntry and ServerEntry) with two implementing
>> classes (DefaultClientEntry and DefaultServerEntry). Overkilling … (and will
>> be rewritten soon)
>>
>>
>>      
> I'd be careful to remove interfaces.  As an API you have to allow the
> broadest range of implementation possibilities. Interfaces are good to have.
>   When in doubt keep the interface.
>
> All in all, I'm wondering if it's a good idea to have an interface instead
>    
>> of a class, as it does not make a lot of sense to implement some different
>> version of such an object.
>>
>>
>>      
> It's hard to foresee the future here.  You've got to watch out when you're
> trying to prognosticate the future while designing an API.
>
> Just my two cents.
>
> Alex
>
>    

Mime
View raw message