On Thu, Jul 23, 2009 at 9:41 AM, Emmanuel Lecharny <elecharny@apache.org> wrote:
Alex Karasulu wrote:
BTW, with a client API we'll be encountering a spectrum of people who know
much to almost nothing about LDAP but all should be able to use it easily.
We need to think like our most ignorant users.  
Totally agree.

A good API will talk to you
when you don't know anything.  I know I've been a monkey myself looking at
API java docs to find a square peg to fill a square hole.
It's just a brute force issue ;)



 What design
decisions and conventions in the API will best direct confused and LDAP
ignorant users?
 
The less we expose, the better. This is why we think that at some point, using an XXXRequest Object is probably a better option than using many parameters which won't talk to anyone at first site. Nothing is more annoying than a method with 7 parameters, most of them being String, for instance.

Regarding the deleteTree method, the biggest risk is that it make the users think that this operation will work on any server.

It can work on any server we can swap the implementation under the hood replacing it with either a control based approach if the control is available on the target server or use a recursive implementation.  We can use the Abstract Method Pattern to implement it.
 
That mean we have to check if the control exists on the server, and if not, write the reursive code to do so. Certainly not a hammer to put in all the users' hands ! Not to mention the danger of a quick and misleaded deleteTree done on the top of the DiT (remember this rm -rf / we all did once as root ;)


Right but UNIX allows it and if administrators don't guard against it then it's their problem.
 


In this case, we need to balance being true to the protocol (direct and
clear) with providing sufficient insulation to our less savvy users.  One
should be able to delve in deeper to get more out of the API based on their
own proficiency, needs, and exceptional situation in a direct fashion.
 Meanwhile most common cases should be easy and not too involved while still
remaining clear and direct with respect to the protocol and the LDAP access
model.
 
I think this is what we are targeting since day one.

Oh yes I noticed that - not saying this was not the case.
 

This specific situation is a good example.  Our least LDAP savvy users will
just want to delete a node or an entire tree.  They don't know jack about
controls.  Most will not even want to learn about it - they just need to
scratch an itch.  Let's let them scratch the itch without pain and they will
be back again and again even when sometimes it will cost more to scratch
more complex itches.  This is how our API will be more pleasant to use.  So
a user seeing this signature will know exactly what it means without even
reading the java doc statement.  It's self explanatory.
 
Yes. And we can do the same for the ModifyDN operation, splitting it in three methods : rename, move and moveAndRename.

Sorry for beating a dead horse to death especially with this example but I
want to impart how I would approach an access API in case it would help
during your design.
 
He, why do you think we are asking on the ML about this API ? I'm most certainly biased too, and I really appreciate the feedback we get.

Heh yeah right.
 


More important, the number of responses we get is a good sign that these definitions are *very* important to most of us, not to mention our potential users.

This is, IMO, the best way to get a well designed API.

Aye!

--
Alex Karasulu
My Blog :: http://www.jroller.com/akarasulu/
Apache Directory Server :: http://directory.apache.org
Apache MINA :: http://mina.apache.org