netscape.ldap
Class LDAPSearchResults

java.lang.Object
  extended bynetscape.ldap.LDAPSearchResults
All Implemented Interfaces:
java.util.Enumeration, java.io.Serializable

public class LDAPSearchResults
extends java.lang.Object
implements java.util.Enumeration, java.io.Serializable

The results of an LDAP search operation, represented as an enumeration. Note that you can only iterate through this enumeration once: if you need to use these results more than once, make sure to save the results in a separate location.

You can also use the results of a search in progress to abandon that search operation.

Version:
1.0
See Also:
LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean), LDAPConnection.abandon(netscape.ldap.LDAPSearchResults), Serialized Form

Field Summary
(package private) static long serialVersionUID
           
 
Constructor Summary
  LDAPSearchResults()
          Constructs an enumeration of search results.
(package private) LDAPSearchResults(LDAPConnection conn, LDAPSearchConstraints cons, java.lang.String base, int scope, java.lang.String filter, java.lang.String[] attrs, boolean attrsOnly)
           
(package private) LDAPSearchResults(java.util.Vector v)
          Constructs an enumeration of search results.
(package private) LDAPSearchResults(java.util.Vector v, LDAPConnection conn, LDAPSearchConstraints cons, java.lang.String base, int scope, java.lang.String filter, java.lang.String[] attrs, boolean attrsOnly)
           
 
Method Summary
(package private)  void add(LDAPException e)
          Add exception
(package private)  void add(LDAPMessage msg)
          Add search entry of referral
(package private)  void addReferralEntries(LDAPSearchResults res)
           
(package private)  void associate(LDAPSearchListener l)
          Prepares to return asynchronous results from a search
(package private)  void associatePersistentSearch(LDAPSearchListener l)
           
(package private)  void closeOnCompletion(LDAPConnection toClose)
          For asynchronous search, this mechanism allows the programmer to close a connection whenever the search completes.
 int getCount()
          Returns a count of queued search results immediately available for processing.
(package private)  int getMessageID()
          Returns message ID.
 LDAPControl[] getResponseControls()
          Returns the controls returned with this search result.
 boolean hasMoreElements()
          Returns true if there are more search results to be returned.
 LDAPEntry next()
          Returns the next LDAP entry from the search results and throws an exception if the next result is a referral, or if a sizelimit or timelimit error occurred.
 java.lang.Object nextElement()
          Returns the next result from a search.
(package private)  java.lang.Object nextReferralElement()
           
(package private)  void quicksort(LDAPEntry[] toSort, LDAPEntryComparator compare, int low, int high)
          Basic quicksort algorithm.
(package private)  void setMsgID(int msgID)
          Sets the message ID for this search request.
 void sort(LDAPEntryComparator compare)
          Sorts the search results.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

serialVersionUID

static final long serialVersionUID
See Also:
Constant Field Values
Constructor Detail

LDAPSearchResults

public LDAPSearchResults()
Constructs an enumeration of search results. Note that this does not actually generate the results; you need to call LDAPConnection.search to perform the search and get the results.

See Also:
LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean)

LDAPSearchResults

LDAPSearchResults(LDAPConnection conn,
                  LDAPSearchConstraints cons,
                  java.lang.String base,
                  int scope,
                  java.lang.String filter,
                  java.lang.String[] attrs,
                  boolean attrsOnly)

LDAPSearchResults

LDAPSearchResults(java.util.Vector v)
Constructs an enumeration of search results. Used when returning results from a cache.

Parameters:
v - the vector containing LDAPEntries
See Also:
LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean)

LDAPSearchResults

LDAPSearchResults(java.util.Vector v,
                  LDAPConnection conn,
                  LDAPSearchConstraints cons,
                  java.lang.String base,
                  int scope,
                  java.lang.String filter,
                  java.lang.String[] attrs,
                  boolean attrsOnly)
Method Detail

add

void add(LDAPMessage msg)
Add search entry of referral

Parameters:
msg - LDAPSearchResult or LDAPsearchResultReference

add

void add(LDAPException e)
Add exception

Parameters:
e - exception

associate

void associate(LDAPSearchListener l)
Prepares to return asynchronous results from a search

Parameters:
l - Listener which will provide results

associatePersistentSearch

void associatePersistentSearch(LDAPSearchListener l)

addReferralEntries

void addReferralEntries(LDAPSearchResults res)

closeOnCompletion

void closeOnCompletion(LDAPConnection toClose)
For asynchronous search, this mechanism allows the programmer to close a connection whenever the search completes.

Parameters:
toClose - connection to close when the search terminates

quicksort

void quicksort(LDAPEntry[] toSort,
               LDAPEntryComparator compare,
               int low,
               int high)
Basic quicksort algorithm.


setMsgID

void setMsgID(int msgID)
Sets the message ID for this search request. msgID is used to retrieve response controls.

Parameters:
msgID - Message ID for this search request

getResponseControls

public LDAPControl[] getResponseControls()
Returns the controls returned with this search result. If any control is registered with LDAPControl, an attempt is made to instantiate the control. If the instantiation fails, the control is returned as a basic LDAPControl.

Returns:
an array of type LDAPControl.
See Also:
LDAPControl.register(java.lang.String, java.lang.Class)

sort

public void sort(LDAPEntryComparator compare)
Sorts the search results.

The comparator (LDAPEntryComparator) determines the sort order used. For example, if the comparator uses the uid attribute for comparison, the search results are sorted according to uid.

The following section of code sorts results in ascending order, first by surname and then by common name.

 String[]  sortAttrs = {"sn", "cn"};
 boolean[] ascending = {true, true};

 LDAPConnection ld = new LDAPConnection();
 ld.connect( ... );
 LDAPSearchResults res = ld.search( ... );
 res.sort( new LDAPCompareAttrNames(sortAttrs, ascending) );
 
NOTE: If the search results arrive asynchronously, the sort method blocks until all the results are returned.

If some of the elements of the Enumeration have already been fetched, the cursor is reset to the (new) first element.

Parameters:
compare - comparator used to determine the sort order of the results
See Also:
LDAPEntryComparator

next

public LDAPEntry next()
               throws LDAPException
Returns the next LDAP entry from the search results and throws an exception if the next result is a referral, or if a sizelimit or timelimit error occurred.

You can use this method in conjunction with the hasMoreElements method to iterate through each entry in the search results. For example:

 LDAPSearchResults res = ld.search( MY_SEARCHBASE,
                         LDAPConnection.SCOPE_BASE, MY_FILTER,
                         null, false );
 while ( res.hasMoreElements() ) {
   try {
     LDAPEntry findEntry = res.next();
   } catch ( LDAPReferralException e ) {
     LDAPUrl refUrls[] = e.getURLs();
     for ( int i = 0; i < refUrls.length; i++ ) {
     // Your code for handling referrals
     }
     continue;
   } catch ( LDAPException e ) {
     // Your code for handling errors on limits exceeded 
     continue; 
   } 
   ...
 }
 

Returns:
the next LDAP entry in the search results.
Throws:
LDAPReferralException - A referral (thrown if the next result is a referral), or LDAPException if a limit on the number of entries or the time was exceeded.
LDAPException
See Also:
hasMoreElements()

nextElement

public java.lang.Object nextElement()
Returns the next result from a search. You can use this method in conjunction with the hasMoreElements method to iterate through all elements in the search results.

Make sure to cast the returned element as the correct type. For example:

 LDAPSearchResults res = ld.search( MY_SEARCHBASE,
                         LDAPConnection.SCOPE_BASE, MY_FILTER,
                         null, false );
 while ( res.hasMoreElements() ) {
   Object o = res.nextElement(); 
   if ( o instanceof LDAPEntry ) { 
     LDAPEntry findEntry = (LDAPEntry)o; 
     ... 
   } else if ( o instanceof LDAPReferralException ) { 
     LDAPReferralException e = (LDAPReferralException)o; 
     LDAPUrl refUrls[] = e.getURLs(); 
     ... 
   } else if ( o instanceof LDAPException ) { 
     LDAPException e = (LDAPException)o; 
     ... 
   } 
 } 
 

Specified by:
nextElement in interface java.util.Enumeration
Returns:
the next element in the search results.
See Also:
hasMoreElements()

nextReferralElement

java.lang.Object nextReferralElement()

hasMoreElements

public boolean hasMoreElements()
Returns true if there are more search results to be returned. You can use this method in conjunction with the nextElement or next methods to iterate through each entry in the results. For example:
 LDAPSearchResults res = ld.search( MY_SEARCHBASE,
                         LDAPConnection.SCOPE_BASE, MY_FILTER,
                         null, false );
 while ( res.hasMoreElements() ) {
   LDAPEntry findEntry = (LDAPEntry)res.nextElement();
   ...
 }
 

Specified by:
hasMoreElements in interface java.util.Enumeration
Returns:
true if there are more search results.
See Also:
nextElement(), next()

getCount

public int getCount()
Returns a count of queued search results immediately available for processing. A search result is either a search entry or an exception. If the search is asynchronous (batch size not 0), this reports the number of results received so far.

Returns:
count of search results immediatly available for processing

getMessageID

int getMessageID()
Returns message ID.

Returns:
Message ID.