Closing Iterator objects explicitly after using only a portion of a query result

If you do not use all of the rows of a query result that is contained in an Iterator, you must explicitly close that Iterator when you are finished with it.

Returning a query result as any Java type other than Iterator causes the entire result to be consumed when the query is executed and used to populate the returned object. However, a returned Iterator consumes the result one row at a time as your application performs each next() operation

If you use an Iterator to read an entire query result, pureQuery closes the Iterator after the last row is read. Closing an Iterator frees database resources that were needed to produce the Iterator.

However, if the entire query result in an Iterator is not consumed, you must explicitly close the Iterator.

For example, to close an Iterator named customers, you would use the following code, which casts the Iterator to a ResultIterator and then calls the ResultIterator.close() method:

((ResultIterator) customers).close();

pureQuery methods that return an Iterator always return type java.util.Iterator, which pureQuery constructs as a com.ibm.pdq.runtime.ResultIterator. A ResultIterator provides applications with the means to close explicitly an Iterator's underlying ResultSet and to free any resources associated with the ResultSet in the client or in the server.

The ResultIterator interface is defined as follows:

package com.ibm.pdq.runtime;

import java.util.Iterator;

public interface ResultIterator<T> extends Iterator<T>
{
   // release any resources associated with this Iterator
   public void close();
}

Feedback