Return types for inline methods that query in-memory Java collections

When you use methods in the Data interface to query an in-memory collection, those methods can return objects of these types.

The second table shows the return types for each method in the Data interface that you can use to query collections.

Table 1. Key to the table of return types
Abbreviation Meaning
I Iterator
L List
M Map
O Object
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.
   
queryXxx() methods 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.queryList() X              
Data.queryList() with returnClass   X            
Data.queryIterator()             X  
Data.queryIterator() with returnClass               X
Data.queryFirst()     X          
Data.queryFirst() with returnClass         X      

Description of return types

List<T>
Specifies that a List object of type T is returned. 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 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.
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.

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