com.ibm.itim.dataservices.model
Interface 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

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.