On Thu, Jul 23, 2009 at 9:41 AM, Emmanuel Lecharny <[email protected]>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
