You are viewing a plain text version of this content. The canonical link for it is here.
Posted to api@directory.apache.org by Emmanuel Lecharny <el...@gmail.com> on 2010/02/04 19:38:52 UTC
Entry API
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)
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.
Constructors
------------
Here are the current implementations :
ADS :
DefaultClientEntry()
DefaultClientEntry(LdapDN)
DefaultClientEntry(LdapDN, EntryAttribute...)
DefaultClientEntry(LdapDN, String...)
DefaultServerEntry(SchemaManager)
DefaultServerEntry(SchemaManager, Entry)
DefaultServerEntry(SchemaManager, LdapDN)
DefaultServerEntry(SchemaManager, LdapDN, AttributeType, String)
DefaultServerEntry(SchemaManager, LdapDN, AttributeType...)
DefaultServerEntry(SchemaManager, LdapDN, ServerAttribute...)
DefaultServerEntry(SchemaManager, LdapDN, String...)
jLdap :
LDAPEntry()
LDAPEntry(String)
LDAPEntry(String, LDAPAttributeSet)
JNDI :
N/A
OpenDS :
SortedEntry()
SortedEntry(DN)
SortedEntry(Entry)
SortedEntry(String)
SortedEntry(String...)
UID :
Entry(DN)
Entry(DN, Attribute...)
Entry(DN, Collection<Attribute>)
Entry(String)
Entry(String, Attribute...)
Entry(String, Collection<Attribute>)
Entry(String...)
Quite complex :/ The problem here is that we would like those entries to
be schema aware. The question is : how to make it simple for the user to
create a schema aware entry? Either the entry comes from the server he
is connected to, or he creates new entries on the client before sending
them to the server. In both cases, the entry has to know about the schema.
Let's first assume that it's the case. The minimal list of constructors is :
Entry() : an empty constructor
Entry(DN)
Entry(String) : The DN is a string
Entry(DN, Attribute…)
Entry(String, Attribute…)
Entry(String…) : A special constructor which takes a list of strings
representing a LDIF form of the entry
All those constructors will assume that the default schema will be used.
We can then inject a Schema by adding it to the constructor :
Entry(SchemaManager) : an empty constructor
Entry(SchemaManager, DN)
Entry(SchemaManager, String) : The DN is a string
Entry(SchemaManager, DN, Attribute…)
Entry(SchemaManager, String, Attribute…)
Entry(SchemaManager, String…) : A special constructor which takes a list
of strings representing a LDIF form of the entry
Thoughts ?
--
Regards,
Cordialement,
Emmanuel Lécharny
www.nextury.com
Re: Entry API
Posted by Emmanuel Lecharny <el...@gmail.com>.
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
Re: Entry API
Posted by Matthew Swift <Ma...@Sun.COM>.
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<el...@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
>
>
Re: Entry API
Posted by Alex Karasulu <ak...@gmail.com>.
On Thu, Feb 4, 2010 at 10:00 PM, Emmanuel Lécharny <el...@apache.org>wrote:
> On 2/4/10 8:54 PM, Alex Karasulu wrote:
>
>> On Thu, Feb 4, 2010 at 8:38 PM, Emmanuel Lecharny<elecharny@gmail.com
>> >wrote:
>> 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.
>>
>>
>
> Another possibility (in conjonction with he fact that we might want to have
> schema aware entries) is to use a factory to build entries, instead of
> having a constructor.
>
> If we have to keep the Interface, what would be the name for the class ?
> EntryImpl ? DefaultEntry?
>
>
I see what you're getting at. Sometimes I feel like this IEntry for the
interface name might be best so there's room to have a simple Entry class as
the default implementation while still offering an interface to implement
for API users.
Alex
Re: Entry API
Posted by Kiran Ayyagari <ay...@gmail.com>.
> Another possibility (in conjonction with he fact that we might want to have
> schema aware entries) is to use a factory to build entries, instead of
> having a constructor.
I don't know if the factory is really required here cause what I think
of is just a *Entry*. It will be aware of schema if
SchemaManager is injected else not (i.e equivalent to DefaultClientEntry)
>
> If we have to keep the Interface, what would be the name for the class ?
> EntryImpl ? DefaultEntry?
to me EntryImpl sounds good, cause DefaultEntry gives an impression
that there exists another implementation.
Kiran Ayyagari
Re: Entry API
Posted by Emmanuel Lécharny <el...@apache.org>.
On 2/4/10 8:54 PM, Alex Karasulu wrote:
> On Thu, Feb 4, 2010 at 8:38 PM, Emmanuel Lecharny<el...@gmail.com>wrote:
>
> 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.
>
Another possibility (in conjonction with he fact that we might want to
have schema aware entries) is to use a factory to build entries, instead
of having a constructor.
If we have to keep the Interface, what would be the name for the class ?
EntryImpl ? DefaultEntry?
--
Regards,
Cordialement,
Emmanuel Lécharny
www.nextury.com
Re: Entry API
Posted by Alex Karasulu <ak...@gmail.com>.
On Thu, Feb 4, 2010 at 8:38 PM, Emmanuel Lecharny <el...@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