directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Emmanuel Lecharny <elecha...@apache.org>
Subject Re: Client API : Delete request
Date Thu, 23 Jul 2009 13:41:27 GMT
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. 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 ;)


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

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.

Thanks for the feedback.

-- 
--
cordialement, regards,
Emmanuel L├ęcharny
www.iktek.com
directory.apache.org



Mime
View raw message