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
