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.  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.  What design decisions and conventions in the API will best direct confused and LDAP ignorant users? 

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.

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.

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.

Also note there are other currents that will also impact your design down the line when you consider how this API can be used with ORM tools for LDAP, things like connection pooling etc.

Anyways this is looking great.  Wish I had a hand in more of the details.

On Thu, Jul 23, 2009 at 4:26 AM, Emmanuel Lecharny <elecharny@apache.org> wrote:
Alex Karasulu wrote:
On Wed, Jul 22, 2009 at 7:27 PM, Emmanuel Lecharny <elecharny@apache.org>wrote:

 
Hi guys,

following one thread started more than a month ago, I would like to get
your opinion about the DeleteRequest implementation.

We currently have the following methods (Thanks to Kiran who implemented
them) :

delete( LdapDN )
delete( LdapDN, boolean deleteChildren )
delete( LdapDN, DeleteListener )
delete( LdapDN, boolean deleteChildren, DeleteListener )
delete( DeleteRequest );
delete( DeleteRequest, DeleteListener );

   

Why not have a delete() and a deleteTree() method and do away with the
deleteChildren parameter?  The parameter permutes the number of method
overloads and I think it's just more clear to use another method name all
together due to the nature of the operation. Here's what this looks like:

delete( LdapDN )
deleteTree( LdapDN )
delete( LdapDN, DeleteListener )
deleteTree( LdapDN, DeleteListener )
 
That's an idea. We should also add some methods in order to allow a user to pass a String instead of a DN :
delete( String )
deleteTree( String )
delete( String, DeleteListener )
deleteTree( String,DeleteListener )


I don't see the point to having delete take the DeleteRequest. I guess this
is for convenience in the codec?  If so then might this not be best a
package friendly method overload?
 
It's just convenient if you have to add some controls.


 
If we exclude the last parameter, used only for asynchronous requests, we
have some other options :

- delete( String ) // instead of a LdapDN
- the boolean (deleteChildren) is associated with a control, we can pass it
to the DeleteRequest Object.

is the following list of methods enough then ? :
delete( String [, DeleteListener] )
delete( LdapDN [, DeleteListener] )
delete( DeleteRequest [, DeleteListener] )

   

Hmmm if I want to delete a tree of entries then I will have no choice but to
wrap my LdapDN in a DeleteRequest which I must now create, just to add the
control to delete the subtree.
 
Yes, true. IMO, your proposal (deleteTree) is probably better.



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





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