From dev-return-37919-apmail-directory-dev-archive=directory.apache.org@directory.apache.org Thu Apr 28 20:28:10 2011 Return-Path: X-Original-To: apmail-directory-dev-archive@www.apache.org Delivered-To: apmail-directory-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id A73673173 for ; Thu, 28 Apr 2011 20:28:10 +0000 (UTC) Received: (qmail 53792 invoked by uid 500); 28 Apr 2011 20:28:10 -0000 Delivered-To: apmail-directory-dev-archive@directory.apache.org Received: (qmail 53735 invoked by uid 500); 28 Apr 2011 20:28:10 -0000 Mailing-List: contact dev-help@directory.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Apache Directory Developers List" Delivered-To: mailing list dev@directory.apache.org Received: (qmail 53728 invoked by uid 99); 28 Apr 2011 20:28:10 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 28 Apr 2011 20:28:10 +0000 X-ASF-Spam-Status: No, hits=1.5 required=5.0 tests=FREEMAIL_FROM,HTML_MESSAGE,RCVD_IN_DNSWL_LOW,RFC_ABUSE_POST,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (nike.apache.org: domain of akarasulu@gmail.com designates 74.125.82.44 as permitted sender) Received: from [74.125.82.44] (HELO mail-ww0-f44.google.com) (74.125.82.44) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 28 Apr 2011 20:28:03 +0000 Received: by wwa36 with SMTP id 36so3556442wwa.1 for ; Thu, 28 Apr 2011 13:27:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:sender:in-reply-to:references:date :x-google-sender-auth:message-id:subject:from:to:content-type; bh=WN1o8M7mHENRneenOj9Gdc+llXcGE2k5HRvn3woi/dA=; b=GIe3zIUsN0kTzlxIMH6tIRKkymvyDPlm6arN8ZuguzpTNVA+O+hkqdhoKNG0xNR1iM fBlAv0/+wtbyDoobNDfd5TM+dcyzOeCZIy8pLeER2SM6nD3CS960he72eADDMFdRAVw8 KyWYXVxJ+Uqg+KK9hT2mYTX9VzQAIYS6/RlxI= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:sender:in-reply-to:references:date :x-google-sender-auth:message-id:subject:from:to:content-type; b=mYVYO+73wA3+5GYXYJsGBvhE1wuBHArCY3rLbGpVr6D9/WW3vRu4KU+vzG7Z6gCnwe syywJeOLP/vK3r/OCoNDFW8SG1pvWv+tmhXacIgg30YnrWrsUxDBw/YPMg8zX4Q+jWUu fjwcXI8DFDCfYRrR9HH7xP08Z9z3FXFGjp9Hw= MIME-Version: 1.0 Received: by 10.216.81.203 with SMTP id m53mr1773391wee.9.1304022463188; Thu, 28 Apr 2011 13:27:43 -0700 (PDT) Sender: akarasulu@gmail.com Received: by 10.216.237.142 with HTTP; Thu, 28 Apr 2011 13:27:43 -0700 (PDT) In-Reply-To: <4DB97238.4060909@gmail.com> References: <4DB94AA0.5030302@gmail.com> <4F5C26AF-2E6A-442C-A694-097C3851A62B@marcelot.net> <4DB97238.4060909@gmail.com> Date: Thu, 28 Apr 2011 23:27:43 +0300 X-Google-Sender-Auth: 6ls2Ywb8RKcFcBs-AX-8gq6tzhQ Message-ID: Subject: Re: Search result in LDAP API From: Alex Karasulu To: Apache Directory Developers List , elecharny@apache.org Content-Type: multipart/alternative; boundary=0016e6dd97e1b290cd04a200630c X-Virus-Checked: Checked by ClamAV on apache.org --0016e6dd97e1b290cd04a200630c Content-Type: text/plain; charset=ISO-8859-1 On Thu, Apr 28, 2011 at 4:57 PM, Emmanuel Lecharny wrote: > On 4/28/11 3:40 PM, Stefan Seelmann wrote: > >> On Thu, Apr 28, 2011 at 2:20 PM, Pierre-Arnaud Marcelot >> wrote: >> >>> On 28 avr. 2011, at 13:39, Kiran Ayyagari wrote: >>> >>> On Thu, Apr 28, 2011 at 4:38 PM, Emmanuel Lecharny >>>> wrote: >>>> >>>>> Hi guys, >>>>> >>>>> yesterday, as I started to write the doc about the Search Operation, I >>>>> faced >>>>> some issue. Let me explain. >>>>> >>>>> When you do a simple search, you get back a cursor : >>>>> >>>>> SearchCursor cursor = connection.search( "ou=system", >>>>> "(objectclass=*)", SearchScope.ONELEVEL ); >>>>> >>>>> The SearchCursor extends Cursor. >>>>> >>>>> That means you get some Response when you do a search, so you have to >>>>> write >>>>> such code to get back the entries : >>>>> >>>>> while ( cursor.next() ) >>>>> { >>>>> Entry entry = >>>>> ((SearchResultEntry)(cursor.get())).getEntry(); >>>>> >>>>> which is just horrible. >>>>> >>>> I completely agree. >>> We are creating this API to make the user's life easier and not embarrass >>> him with such constructions. >>> I'm pretty sure 90% of the users of the API won't know there are multiple >>> types of responses to search. >>> Most of them only expect entries. >>> >>> On the other hand, LDAP experts know everything about the spec and the >>> API should also ease their work and allow them to access everything. >>> >> I totally agree with Pierre-Arnaud. For power-users the search() >> method should return the data structures as defined in the LDAP spec. >> But most users only want to get Entry objects (not even >> SearchResultEntry objects). So I'd suggest to keep the current >> search() methods as is and add another convenience search method. >> >> The LdapConnection interface already defines a lot of convenience methods: >> - exists() >> - lookup() >> - move() >> - moveAndRename() >> - rename() >> >> So why not some more for search: >> Cursor searchForEntries( Dn baseDn, String filter, SearchScope >> scope, String... attributes ) // skips SearchResultReference >> Cursor searchForEntries( Dn baseDn, String filter, SearchScope >> scope, ReferralHandlingMethod referalHandling, String... attributes ) >> > > I like this idea ! Cursor searchEntries() is fine. > > >> Another idea is to distinguish low-level and convenience methods by >> their method signature: >> >> a) Low-level methods: a XyzRequest object is passed and the according >> XyzResponse (or a Cursor with the SearchResultXyz objects for search) >> is returned. Examples >> BindResponse bind(BindRequest bindRequest) >> ModifyResponse modify(ModifyRequest modRequest) >> ModifyDnResponse modifyDn(ModifyDnRequest modDnRequest) >> SearchCursor search(SearchRequest searchRequest) >> etc. >> -> those methods don't throw LdapException (but maybe IOException) >> but the sucess/failure must be extracted from the response object. >> > yes. That's also a good way to get out of this dead end. Using the > high-level objects leads to get back a high-level response, for LDAP gurus. > Otherwise, we simply returns a cursor of Entry. > > Anyway, this is what 99% of users are expecting, most of them don't even > know what a referral is, and if the referral chasing is activated, they will > just don't see them. > > > 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 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. > >> >> Thoughts? >> >> I too agree with Emmanuel, good compromise Stefan. I still think however we should add to the low level API the getEntry, getReferral, getIntermediate accessors plus the checks like isEntry, isReferral, isIntermediate. Regards, Alex --0016e6dd97e1b290cd04a200630c Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable

On Thu, Apr 28, 2011 at 4:57 PM, Emmanue= l Lecharny <ele= charny@gmail.com> wrote:
On 4/28/11 3:40 PM, Stefan Seelmann wrote= :
On Thu, Apr 28, 2011 at 2:20 PM, Pierre-Arnaud Marcelot<pa@marcelot.net> =A0wrote:
On 28 avr. 2011, at 13:39, Kiran Ayyagari wrote:

On Thu, Apr 28, 2011 at 4:38 PM, Emmanuel Lecharny<elecharny@gmail.com> =A0wrote:
Hi guys,

yesterday, as I started to write the doc about the Search Operation, I face= d
some issue. Let me explain.

When you do a simple search, you get back a cursor :

=A0 =A0 =A0 =A0SearchCursor cursor =3D connection.search( "ou=3Dsyste= m",
"(objectclass=3D*)", SearchScope.ONELEVEL );

The SearchCursor extends Cursor<Response>.

That means you get some Response when you do a search, so you have to write=
such code to get back the entries :

=A0 =A0 =A0 =A0while ( cursor.next() )
=A0 =A0 =A0 =A0{
=A0 =A0 =A0 =A0 =A0 =A0Entry entry =3D ((SearchResultEntry)(cursor.get()))= .getEntry();

which is just horrible.
I completely agree.
We are creating this API to make the user's life easier and not embarra= ss him with such constructions.
I'm pretty sure 90% of the users of the API won't know there are mu= ltiple types of responses to search.
Most of them only expect entries.

On the other hand, LDAP experts know everything about the spec and the API = should also ease their work and allow them to access everything.
I totally agree with Pierre-Arnaud. For power-users the search()
method should return the data structures as defined in the LDAP spec.
But most users only want to get Entry objects (not even
SearchResultEntry objects). So I'd suggest to keep the current
search() methods as is and add another convenience search method.

The LdapConnection interface already defines a lot of convenience methods:<= br> - exists()
- lookup()
- move()
- moveAndRename()
- rename()

So why not some more for search:
Cursor<Entry> =A0searchForEntries( Dn baseDn, String filter, SearchSc= ope
scope, String... attributes ) // skips SearchResultReference
Cursor<Entry> =A0searchForEntries( Dn baseDn, String filter, SearchSc= ope
scope, ReferralHandlingMethod referalHandling, String... attributes )

I like this idea ! Cursor<Entry> searchEntries() is fine.


Another idea is to distinguish low-level and convenience methods by
their method signature:

a) Low-level methods: a XyzRequest object is passed and the according
XyzResponse (or a Cursor with the SearchResultXyz objects for search)
is returned. Examples
=A0 =A0 BindResponse bind(BindRequest bindRequest)
=A0 =A0 ModifyResponse modify(ModifyRequest modRequest)
=A0 =A0 ModifyDnResponse modifyDn(ModifyDnRequest modDnRequest)
=A0 =A0 SearchCursor search(SearchRequest searchRequest)
=A0 =A0 etc.
=A0 =A0 -> =A0those methods don't throw LdapException (but maybe IO= Exception)
but the sucess/failure must be extracted from the response object.
yes. That's also a good way to get out of this dead end. Using the high= -level objects leads to get back a high-level response, for LDAP gurus. Oth= erwise, we simply returns a cursor of Entry.

Anyway, this is what 99% of users are expecting, most of them don't eve= n know what a referral is, and if the referral chasing is activated, they w= ill just don't see them.


b) Convenience methods: =A0higher-level objects (Dn, Rdn, Strings) are
passed and returned. Examples
=A0 =A0void modify(String dn, Modification... modifications)
=A0 =A0void rename (Dn entryDn, Rdn newRdn)
=A0 =A0Cursor<Entry> =A0search( Dn baseDn, String filter, SearchScop= e scope,
String... attributes )
=A0 -> =A0those methods throw an LdapException in case of an error that=
contains the LDAP error code and message.

We already have those convenient methods.

Thoughts?


I too agree = with Emmanuel, good compromise Stefan. I still think however we should add = to the low level API the getEntry, getReferral, getIntermediate accessors p= lus the checks like isEntry, isReferral, isIntermediate.

Regards,
Alex=A0

--0016e6dd97e1b290cd04a200630c--