h2. Searching

Searching is the most important operation in *LDAP*. It has to be fast. Very fast. On the other hand, as the server does not do a lot of processing while looking for entries, the client has to provide sufficient information in order to get accurate results.

The idea is to define a search *API* that is easy to use in the simplest cases, but provides all the necessary bolts if you need to send complex search requests.

{note:warn}
This part of the API is very likely to change in the next milestone to provide an easier way to get the results in the simple cases.
{note}

h3. Simple Search

Let's first look at a simple search. What we basically need to process a search is a starting point in the tree, a filter, a scope. Here is an example:

{code:java}
    @Test
    public void testSimpleSearch() throws Exception
    {
        SearchCursor cursor = connection.search( "ou=system", "(objectclass=*)", SearchScope.ONELEVEL );
        
        while ( cursor.next() )
        {
            Response response = cursor.get();
            assertNotNull( response );
            assertTrue( response instanceof SearchResultEntry );
            System.out.println( ((SearchResultEntry)response).getEntry() );
        }

        SearchResultDone done = cursor.getSearchResultDone();

        assertNotNull( done );
        assertEquals( ResultCodeEnum.SUCCESS, done.getLdapResult().getResultCode() );

        cursor.close();
    }
{code}

In this example the _connection_ has been previously created. We just search for all the entries starting at *ou=system* and their children, which have an _ObjectClass_ attribute (all the entries have such an attribute, so we should get back all the entries). The scope (_ONELEVEL_) says we just search one level under the starting base.

We get back a cursor, which can be iterated forward. Every call to the _get()_ method will return a response, which will be either a _SearchResultEntry_, a _SearchResultReference_ or an _IntermediateResponse_.