SearchResults

```
public interface SearchResults
```
Interface for retrieving the results of a search request. This interface is more specialized to data model searches than the standard Collection interface. The interface is structured so that implementing classes may employ more efficient streaming algorithms, whereby the implementing classes may stream results in from the datastore in parallel to a client's processing of the returned results. The key is in the exception/error handling portion of the interface, where errors that may be encountered at any point in the data retrieval can be deferred to the entry that caused the error, allowing for best effort retrieval of data, instead of a rigid all or nothing approach. If an error is detected at any point in the retrieval of data, however, the current contents of the object will stay in tact, but no other results will be obtained from the data store.
Users should note that a SearchResults instance may hold on to system resources such as data store connections or cursors. It is recommended that each instance be explicitly closed, preferably within a try/finally block to guarantee that resources are returned to the system. For example: SearchResults results = null; try { results = ...; ... } finally { if (results != null) results.close(); }

See Also:

SearchResultsIterator, SearchResultsStatus

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`clear()` Clears the current contents, cancels the search, and closes any live connection to the data store, freeing up any resources allocated to that connection.
`void`	`close()` Cancels the search, and closes any live connection to the data store, freeing up any resources allocated to that connection.
`boolean`	`equals(java.lang.Object o)` Overrides the Object.equals behavior, returning true if the objects both hold the same results.
`SearchResultsStatus`	`getStatus()` Returns the final status of the search.
`boolean`	`isClosed()` Is the result set closed?
`boolean`	`isEmpty()` Returns whether there are any results.
`boolean`	`isSorted()` Is the result set sorted?
`SearchResultsIterator`	`iterator()` Returns an iterator over the elements in this collection.
`int`	`size()` Returns the number of results returned.
`int`	`size(SearchResultsStatus status)` Returns the number of results returned.
`java.util.Collection`	`toCollection()` Returns the results returned as a Collection.
`java.util.Collection`	`toCollection(SearchResultsStatus status)` Returns the results returned as a Collection.

- Method Detail
  - clear
```
void clear()
```
    Clears the current contents, cancels the search, and closes any live connection to the data store, freeing up any resources allocated to that connection. The object should no longer be used at this point.
  - close
```
void close()
```
    Cancels the search, and closes any live connection to the data store, freeing up any resources allocated to that connection. The object can only be used to read through the entries that were returned prior to closure at this point.
  - equals
```
boolean equals(java.lang.Object o)
```
    Overrides the Object.equals behavior, returning true if the objects both hold the same results. Any errors are detected while processing any of the results are not taken int consideration. Note that not all SearchResults instances will support this functionality.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    o - Object to compare (must be a SearchResults).
    
    Returns:
    
    True if both objects hold the same results.
  - isEmpty
```
boolean isEmpty()
         throws PartialResultsException
```
    Returns whether there are any results.
    
    Returns:
    
    True if no results were found, false if at least one was found.
    
    Throws:
    
    PartialResultsException - Thrown if an error was detected trying to determine if a result was obtained from the data store.
  - isSorted
```
boolean isSorted()
          throws PartialResultsException
```
    Is the result set sorted?
    
    Returns:
    
    True if the result set is sorted
    
    Throws:
    
    PartialResultsException
  - isClosed
```
boolean isClosed()
          throws PartialResultsException
```
    Is the result set closed?
    
    Returns:
    
    True if the result set is closed
    
    Throws:
    
    PartialResultsException
  - iterator
```
SearchResultsIterator iterator()
```
    Returns an iterator over the elements in this collection. There are no guarantees concerning the order in which the elements are returned.
    
    Returns:
    
    SearchResultsIterator to use in iteration.
  - size
```
int size()
  throws PartialResultsException
```
    Returns the number of results returned. To obtain the correct number of results, the call will block until all results can be retrieved from the data store (or an error is detected), possibly making this an expensive call. This method calls toCollection() internally and may yield poor performance.
    
    Returns:
    
    Total number of results returned. If this cannot be determined then the result will be -1.
    
    Throws:
    
    PartialResultsException - Thrown if an error was detected trying to retrieve all results from the data store, most likely to a size limit threshold violation.
  - size
```
int size(SearchResultsStatus status)
```
    Returns the number of results returned. To obtain the correct number of results, the call will block until all results can be retrieved from the data store (or an error is detected), possibly making this an expensive call. Unlike the other size() method, this method does not throw an exception on error, but instead returns the number of results obtained before any error and reports the error, if any, in the provided parameter. This method calls toCollection() internally and may yield poor performance.
    
    Parameters:
    
    status - SearchResultsStatus to fill with the final status of the search. If an error was detected, the details will be provided here. This parameter is optional, if not provided (null), no status will be returned.
    
    Returns:
    
    Total number (or number before error) of results returned.
  - toCollection
```
java.util.Collection toCollection()
                           throws PartialResultsException
```
    Returns the results returned as a Collection. To fill the collection with the entire set of results, the call will block until all results can be retrieved from the data store (or an error is detected), possibly making this an expensive call. To avoid a potential OutOfMemory, this method doesn't retrin the data in memory, so calling the method again will get an empty collection because the result had been iterated through.
    
    Returns:
    
    All results in a Collection.
    
    Throws:
    
    PartialResultsException - Thrown if an error was detected trying to retrieve all results from the data store, most likely to a size limit threshold violation.
  - toCollection
```
java.util.Collection toCollection(SearchResultsStatus status)
```
    Returns the results returned as a Collection. To fill the collection with the entire set of results, the call will block until all results can be retrieved from the data store (or an error is detected), possibly making this an expensive call. To avoid a potential OutOfMemory, this method doesn't retrin the data in memory, so calling the method again will get an empty collection because the result had been iterated through. Unlike the other toCollection() method, this method does not throw an exception on error, but instead returns the results obtained before any error and reports the error, if any, in the provided parameter.
    
    Parameters:
    
    status - SearchResultsStatus to fill with the final status of the search. If an error was detected, the details will be provided here. This parameter is optional, if not provided (null), no status will be returned.
    
    Returns:
    
    All results in a Collection.
  - getStatus
```
SearchResultsStatus getStatus()
```
    Returns the final status of the search. To determine the final status, the entire set of results must be retrieved. The call will block until all results can be retrieved from the data store (or an error is detected), possibly making this an expensive call.
    
    Returns:
    
    SearchResultsStatus holding the final status of the search.

clear

close

equals

isEmpty

isSorted

isClosed

iterator

size

size

toCollection

toCollection

getStatus