Types de renvoi pour les méthodes intégrées qui interrogent des bases de données

Lorsque vous utilisez des méthodes query() dans l'interface Data pour interroger des bases de données, ces méthodes peuvent renvoyer des résultats de requête entiers dans des objets des types suivants.

Le tableau 2 présente les types de renvoi pour chaque méthode de requête dans l'interface Data.

Tableau 1. Légende des types de renvoi du tableau
Abréviation Signification
I Iterator
L List
M Mappe
O Objet
RS ResultSet
S Chaîne
T classe générique, pouvant être une classe d'encapsulation pour un type Java primitif ou un bean
Tableau 2. Types de renvoi pour chaque méthode queryXxx() dans l'interface Data
  Types de renvoi
Méthodes queryXxx() 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() avec returnClass             X    
Data.queryArray() avec RowHandler             X    
Data.queryList()   X              
Data.queryList() avec returnClass     X            
Data.queryList() avec RowHandler     X            
Data.queryIterator()               X  
Data.queryIterator() avec returnClass                 X
Data.queryIterator() avec RowHandler                 X
Data.queryFirst()       X          
Data.queryFirst() avec returnClass           X      
Data.queryFirst() avec RowHandler           X      
Data.queryResults() X                
Data.query() avec ResultHandler           X      

La liste suivante décrit les types de renvoi de base :

Iterator<T>

Spécifie qu'un objet Iterator est renvoyé, chaque élément correspondant à une ligne. La type T paramétré doit être indiqué.

Les objets Iterator dans pureQuery sont de type ResultIterator. Vous devez les fermer à l'aide de la méthode ResultIterator.close() après avoir terminé de les utiliser.

List<T>
Spécifie qu'un objet List de type T est renvoyé. Lorsque l'instruction SQL donnée est une requête, chaque élément correspond à une ligne du résultat de la requête.
Toutes les lignes de résultat de requête sont matérialisées lorsque la méthode est appelée et que l'éventuel objet ResultSet de base de données sous-jacent est fermé.
Map<String,Object>
Indique qu'un objet Map est généré et renvoyé. Les libellés de colonne de renvoi de l'instruction SQL spécifiée deviennent les clés de la mappe. Les libellés de colonne sont convertis en minuscules pour une meilleure conformité au style de codage Java courant. Les valeurs de colonne correspondantes provenant d'une ligne du résultat de la requête deviennent les valeurs de l'objet Map.

Si l'instruction SQL fournie est une requête et si plusieurs lignes sont éligibles, la valeur de la première ligne est renvoyée.

L'éventuel objet ResultSet de base de données sous-jacent est fermé

<T>

Indique qu'un scalaire ou un bean est renvoyé. Un scalaire peut être une classe d'encapsulation telle que Double, ou encore String, Date ou Timestamp.

Si plusieurs lignes sont éligibles, la valeur de la première ligne est renvoyée.

L'éventuel objet ResultSet de base de données sous-jacent est fermé.

<T>[]
Indique qu'un tableau de type T est renvoyé, tel que Employee[], Integer[] ou String[]. Chaque élément correspond à une ligne dans le résultat de la requête.
Toutes les lignes de résultat de requête sont matérialisées lorsque la méthode est appelée et que l'éventuel objet ResultSet de base de données sous-jacent est fermé.

Restriction concernant le renvoi des objets <T>

Lorsque vous utilisez une méthode de l'interface Data, ne spécifiez pas de classe générique <T> qui soit l'une des classes <type Java primitif>.class, telles que la classe int.class.

Les informations relatives aux valeurs SQL null sont perdues chaque fois que les informations demandées par SQL sont stockées dans un type Java primitif. De plus, Java nécessite qu'une méthode générique, spécifiant une classe générique <T> de type <type Java primitif>.class, renvoie une instance de la classe d'encapsulation appropriée à ce type Java primitif.

Par exemple, Java n'autorise pas les appels de méthode tels que :
int tCount = data.queryFirst("select ...", int.class, p);
car la définition de la méthode queryFirst() est la suivante :
<T> T data.queryFirst(String sql, Class<T> returnType, Object... params);
La classe déclarée de tCount doit être Integer.
Integer tCount = data.queryFirst("select ...", Integer.class, p);

Commentaires