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. Clé dans la table des types de renvoi
Abréviation Signification
I Iterator
L List
M Map
O Object
RS ResultSet
S String
T Classe générique pouvant être une classe d'encapsuleur 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. Le type T paramétré doit être défini.

Les itérateurs de pureQuery sont de type ResultIterator. Vous devez les fermer avec la méthode ResultIterator.close() une fois que vous avez fini de les utiliser.

List<T>
Indique qu'un objet List de type T est renvoyé. Lorsque l'instruction SQL indiquée est une requête, chaque élément correspond à une ligne du résultat de la requête.
Toutes les lignes du résultat de la requête sont matérialisées lorsque la méthode est appelée et tout objet ResultSet de base de données sous-jacent est fermé.
Map<String,Object>
Indique qu'un objet Map est créé et renvoyé. Les libellés de la colonne de renvoi de l'instruction SQL indiquée deviennent les clés de la mappe. Les libellés de la colonne sont convertis en minuscules pour une plus grande conformité au style de codage Java courant. Les valeurs de la colonne correspondante 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 du résultat de la requête sont matérialisées lorsque la méthode est appelée et tout objet ResultSet de base de données sous-jacent est fermé.

Restriction pour le retour 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