Return types for inline methods that query databases

When you use the query() methods in the Data interface to query databases, those methods can return entire query results in objects of the following types.

Table 2 shows the return types for each query method in the Data interface.

Table 1. Key to the table of return types
Abbreviation Meaning
I Iterator
L List
M Map
O Object
RS ResultSet
S String
T generic class, which can be a wrapper class for a primitive Java type, or a bean
Table 2. Return types for each queryXxx() method in the Data interface.
  Return types
queryXxx() methods RS L<M<S,O>> L<T> M<S,O> M<S,O>[] <T> <T>[] I<M<S,O>> I<T>
Data.queryArray()         X        
Data.queryArray() with returnClass             X    
Data.queryArray() with RowHandler             X    
Data.queryList()   X              
Data.queryList() with returnClass     X            
Data.queryList() with RowHandler     X            
Data.queryIterator()               X  
Data.queryIterator() with returnClass                 X
Data.queryIterator() with RowHandler                 X
Data.queryFirst()       X          
Data.queryFirst() with returnClass           X      
Data.queryFirst() with RowHandler           X      
Data.queryResults() X                
Data.query() with ResultHandler           X      

The following list describes the basic return types:

Iterator<T>

Specifies that an Iterator object is returned, with each element corresponding to a row. The parameterized type T must be specified.

Iterators in pureQuery are of type ResultIterator. You must close them with the ResultIterator.close() method after you finish using them.

List<T>
Specifies that a List object of type T is returned. When the given SQL statement is a query, each element corresponds to a row of the query result.
All query result rows are materialized when the method is called and any underlying database ResultSet object is closed.
Map<String,Object>
Specifies that a Map object is constructed and returned. The return column labels of the specified SQL statement become the keys of the map. The column labels are converted to lowercase for closer conformity with common Java coding style. The corresponding column values from a row of the query result become the values of the Map object.

If the provided SQL statement is a query and if more than one row qualifies, the value from the first row is returned.

Any underlying database ResultSet object is closed

<T>

Specifies that a scalar or bean is returned. A scalar could be a wrapper such as Double, or a String, Date, or Timestamp.

If more than one row qualifies, the value from the first row is returned.

Any underlying database ResultSet object is closed.

<T>[]
Specifies that an array of type T is returned, such as Employee[], Integer[], or String[]. Each element corresponds to a row of the query result.
All query result rows are materialized when the method is called and any underlying database ResultSet object is closed.

Restriction for returning <T> objects

When you use a method of the Data interface, do not specify a generic <T> class that is any of the <primitive Java type>.class classes, such as int.class.

Information regarding SQL null values is lost whenever information queried from SQL is stored in a primitive Java type. Also, Java requires that a generic method that specifies generic <T> class of a <primitive Java type>.class must return an instance of the wrapper class that is appropriate for that primitive Java type.

For example, Java does not allow method invocations such as this:
int tCount = data.queryFirst("select ...", int.class, p);
because the definition of the queryFirst() method is this:
<T> T data.queryFirst(String sql, Class<T> returnType, Object... params);
The declared class of tCount must be Integer.
Integer tCount = data.queryFirst("select ...", Integer.class, p);

Feedback