On 28 avr. 2011, at 17:39, Emmanuel Lecharny wrote: > I like Stefan's idea a lot, but there is something a bit confusing : if a > user tries to do a simple search, he will expect the LdapConnection.search() > to be the method to use. Having to use LdapConnection.searchEntries() instead > is a bit problematic. > > What about transforming the LdapConnection.search( SearchRequest ) method to > LdapConnection.send( SearchRequest ) (and the very same for any complex > request, using a Request instance) : > - LdapConnection.send( AddRequest ) but LdapConnection.add( Entry ) > - LdapConnection.send( BindRequest ) but LdapConnection.bind( dn, password ) > - LdapConnection.send( SearchRequest ) but Cursor<Entry> > LdapConnection.search( base, filter, scope, attrs...) > - ... > > thoughts ?
That's a good idea to guide users to the most obvious methods and draw a clear separation between the high/low level APIs. +1 Regards, Pierre-Arnaud > On 4/28/11 5:04 PM, Pierre-Arnaud Marcelot wrote: >> On 28 avr. 2011, at 16:47, Emmanuel Lécharny wrote: >> >>> On 4/28/11 4:32 PM, Stefan Seelmann wrote: >>>>>> b) Convenience methods: higher-level objects (Dn, Rdn, Strings) are >>>>>> passed and returned. Examples >>>>>> void modify(String dn, Modification... modifications) >>>>>> void rename (Dn entryDn, Rdn newRdn) >>>>>> Cursor<Entry> search( Dn baseDn, String filter, SearchScope scope, >>>>>> String... attributes ) >>>>>> -> those methods throw an LdapException in case of an error that >>>>>> contains the LDAP error code and message. >>>>> We already have those convenient methods. >>>> Yes, but they return a XyzResponse (except for the search) and the >>>> user needs to check the response object to see if the operation was >>>> successful or not (please correct me if I'm wrong). I think that is >>>> not what 99% of the users expect. >>> Ahhh, right I see your point. Throwing an exception in case we had an error >>> is way better in these case, sure. >>>> So my idea of the "high-level" methods" is >>>> - they take high-level objects as arguments >>>> - the return type is void (for bind, unbind, add, modify, moddn, >>>> delete, abandon), boolean (for compare), Cursor<Entry> (for search), >>>> not sure about extended >>>> - they throw an LdapException (or an appropriate sub-type) in case the >>>> result code is not 0 >>> Makes perfect sense. >>> >>>> - we should add support for referral handling and search continuation >>>> (skip, chase, throw exception), not only for search, but also for the >>>> write methods, but that could be done later >>> Yeah, it can be done later. >>>> And the "low-level" methods: >>>> - take XyzRequest objects as single argument >>>> - they return an XyzResponse object (for bind, unbind, add, modify, >>>> moddn, delete, abandon, compare, extended) or a SearchCursor (for >>>> search) >>>> - the respose objects must be inspected to find out if the operation >>>> was sucessful or not, or if there was an referral/search continuation >>>> >>>> So for the existing search() method that would mean: >>>> >>>> SearchCursor search(SearchRequest searchRequest) >>>> -> remains as is >>>> >>>> Cursor<Entry> search(Dn baseDn, String filter, SearchScope scope, >>>> String... attributes) >>>> Cursor<Entry> search(String baseDn, String filter, SearchScope scope, >>>> String... attributes) >>>> -> return value changed, additional overloads to specify referral >>>> handling may be needed >>>> I just think a high-level and low-level API is required and try to >>>> find a consistent rule. >>> Ok, fine. If everybody agree, we can start refactoring the existing API to >>> provide such methods for 1.0.0-M4. Should not be complex. >> ++1. >> This sounds very good. >> This is at the same time convenient and consistent, and provides methods for >> both novice and experienced LDAP people. >> >> Regards, >> Pierre-Arnaud > > > -- > Regards, > Cordialement, > Emmanuel Lécharny > www.iktek.com >
