[Client API] Search operation

[Emmanuel Lecharny <el...@apache.org>]

let's move to the Search operation now. It's the most complex operation, 
and we have to be carefull not to have a hundreds of overloaded methods. 
We will try to keep the 90/10 approach.

Basically, the search operation has many parameters :
- baseDN
- scope
- derefAliases
- sizeLimit
- timeLimit
- typesOnly
- filter
- attributes

Out of them, the most used parameters are :
- baseDN
- filter
- scope
- attributes
- sizeLimit

The two firsts are absolutely mandatory. The three later are frequent. 
Then you have the others.

What I would suggest is that the four first parameters are always 
present in a search request :
search( String dn, String filter, ScopeEnum scope, String... attributes )

Note that the attributes is a varargs parameter.
Now, it makes it impossible to add a fifth parameter, as the varargs 
must be the last one.

All other parameters can be set using the SearchRequest object, with 
setters, and the following method :

search( SearchRequest request )
or
search( SearchRequest request, SearchListener listener ) for the 
non-blocking form.

Do you have better ideas ?

Thanks !

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

Re: [Client API] Search operation

[Emmanuel Lecharny <el...@apache.org>]

Alex Karasulu wrote:
> As a rule things start getting ugly with API methods when you have more than
> 4 arguments and more than 4 overloads.
>   
True.
> The most important thing to realize is what changes most with each search
> request.  The base does change most.  The filter does but sometimes does not
> need to be provided since people just want everything.  I can see something
> like:
>
> conn.search() => searches the rootDSE ? Or should this be conn.getRootDse()
> ?
>   
I would rather use a getRootDse() instead of a weird search request with 
no baseDn. So +1
> conn.search( baseDN ) => searches the base with one level scope and
> (objectClass=*)
> conn.search( baseDN, filter )
> conn.search( baseDN, filter, scope )
>   
We can add those three methods.
> Attributes and size/time limits might be best left to be overridden in the
> SearchRequest? 
I think that the Attributes should be the forth param. Anything else 
should be handled using a SearchRequest object.

> However these parameters should be set to some smart default
> when using the signatures above.  For example the sizeLimit may default to
> 1000 entries.
>   
Exactly.
> NOTE: timeLimit != timeout where the timeLimit is the limit for a search
> operation on the server, and the timeout is the time the client will wait at
> most for any operation to complete before disconnecting/abandoning the
> client request.
>   
TimeLimit is handled by the server, not the client. So yes, they are 
different values. We should have a default timeout value on the client, 
stored into the connection though.
> Also I was wondering how the Cursor interface fits into this.  Right now we
> used the DirectoryListener.
>   
Man, it fits just fine :) You have to see it...

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

Re: [Client API] Search operation

[Stefan Seelmann <se...@apache.org>]

Alex Karasulu wrote:
> 
> Attributes and size/time limits might be best left to be overridden in
> the SearchRequest? However these parameters should be set to some smart
> default when using the signatures above.  For example the sizeLimit may
> default to 1000 entries.

As already suggested it would be good to define such default values for
the whole connection.

Kind Regards,
Stefan

Re: [Client API] Search operation

[Emmanuel Lecharny <el...@apache.org>]

Alex Karasulu wrote:
> Hi Emmanuel,
>   
<snip/>
> The most important thing to realize is what changes most with each search
> request.  The base does change most.  The filter does but sometimes does not
> need to be provided since people just want everything.  I can see something
> like:
>
> conn.search() => searches the rootDSE ? Or should this be conn.getRootDse()
> ?
>   
I have implented both features : a simple search() with no argument 
returns the rootDSE, but I also added the two methods :

getRootDSE()
and
getRootDSE( String... attributes )

so you can explicitely request for the RootDSE, and grab one specific 
attribute if needed. I still have to define the same operation for the 
asynchronous mode.

> conn.search( baseDN ) => searches the base with one level scope and
>   
OBJECT would be better. It's like you want the attributes of a specific 
entry, no need to look down the tree...
> (objectClass=*)
> conn.search( baseDN, filter )
> conn.search( baseDN, filter, scope )
>   

Yeah, I guess those methods are needed. it's too painful to add all the 
params when you only want an entry
> Attributes and size/time limits might be best left to be overridden in the
> SearchRequest? However these parameters should be set to some smart default
> when using the signatures above.  For example the sizeLimit may default to
> 1000 entries.
>   
I guess it should be set into the LdapConnection object, as suggested bu 
Stefan.

> Also I was wondering how the Cursor interface fits into this.  Right now we
> used the DirectoryListener.
>   
I'm using it for the synchronous search : works pretty well, so far.

Continuing ...

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

Re: [Client API] Search operation

[Alex Karasulu <ak...@gmail.com>]

Hi Emmanuel,

On Wed, Apr 1, 2009 at 2:38 PM, Emmanuel Lecharny <el...@apache.org>wrote:

> let's move to the Search operation now. It's the most complex operation,
> and we have to be carefull not to have a hundreds of overloaded methods. We
> will try to keep the 90/10 approach.
>

Yep it is insane.


>
> Basically, the search operation has many parameters :
> - baseDN
> - scope
> - derefAliases
> - sizeLimit
> - timeLimit
> - typesOnly
> - filter
> - attributes
>
> Out of them, the most used parameters are :
> - baseDN
> - filter
> - scope
> - attributes
> - sizeLimit
>

As a rule things start getting ugly with API methods when you have more than
4 arguments and more than 4 overloads.

The most important thing to realize is what changes most with each search
request.  The base does change most.  The filter does but sometimes does not
need to be provided since people just want everything.  I can see something
like:

conn.search() => searches the rootDSE ? Or should this be conn.getRootDse()
?
conn.search( baseDN ) => searches the base with one level scope and
(objectClass=*)
conn.search( baseDN, filter )
conn.search( baseDN, filter, scope )

Attributes and size/time limits might be best left to be overridden in the
SearchRequest? However these parameters should be set to some smart default
when using the signatures above.  For example the sizeLimit may default to
1000 entries.

NOTE: timeLimit != timeout where the timeLimit is the limit for a search
operation on the server, and the timeout is the time the client will wait at
most for any operation to complete before disconnecting/abandoning the
client request.


> The two firsts are absolutely mandatory. The three later are frequent. Then
> you have the others.
>
> What I would suggest is that the four first parameters are always present
> in a search request :
> search( String dn, String filter, ScopeEnum scope, String... attributes )
>
> Note that the attributes is a varargs parameter.
> Now, it makes it impossible to add a fifth parameter, as the varargs must
> be the last one.
>
> All other parameters can be set using the SearchRequest object, with
> setters, and the following method :
>
> search( SearchRequest request )
> or
> search( SearchRequest request, SearchListener listener ) for the
> non-blocking form.
>
> Do you have better ideas ?
>

Don't know there's much to think about  but I'm sure things will pop into
our heads as we think about this.  I suggest taking as much time as we need
to on this since it is by far the most important operation.

Also I was wondering how the Cursor interface fits into this.  Right now we
used the DirectoryListener.

Alex