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<[email protected]>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
