Syntaxe des méthodes annotées pour les requêtes de collections Java intégrées à la mémoire

Lorsque vous utilisez les méthodes annotées pour lancer une requête sur les collections intégrées à la mémoire, les définitions de ces méthodes doivent être conformes à la syntaxe suivante.
Lire le diagrammeSauter le diagramme
>>-@Select--(--sql--=--"--instruction-SQL--"--)----------------->

>--+--------------------------------------------------------------------------------------+-->
   '-@Handler--(--+-parameterHandler--=--nom-classe----------------------------------+--)-'   
                  +-resultHandler--=--nom-classe-------------------------------------+        
                  +-resultHandler--=--nom-classe--,--parameterHandler--=--nom-classe-+        
                  +-rowHandler--=--nom-classe----------------------------------------+        
                  '-rowHandler--=--nom-classe--,--parameterHandler--=--nom-classe----'        

>--modificateurs--type-renvoi--nom-méthode--(--+-----------------------------------+--);-><
                                               | .-,-----------------------------. |       
                                               | V                               | |       
                                               '---type-paramètre--nom-paramètre-+-'       

Pour comprendre les conventions utilisées dans le diagramme de syntaxe, voir Comment lire les diagrammes de syntaxe.

Lire le diagrammeSauter le diagramme
type-renvoi:

>>-+-Iterator<T>--------+--------------------------------------><
   +-List<T>------------+   
   +-Map<String,Object>-+   
   +-T------------------+   
   '-T[]----------------'   

@Select
Indique que la méthode exécute une instruction SQL SELECT. Cette annotation Java signale que la méthode correspondante est une méthode pureQuery. Le générateur pureQuery traite l'interface pour générer l'implémentation de la méthode.
sql
Fournit l'instruction SQL qui doit s'exécuter lorsque la méthode associée est appelée. A l'exception d'une capacité ajoutée à laquelle une collection fait référence dans la clause FROM, la syntaxe doit être conforme à la syntaxe SQL92 standard. pureQuery définit également un nombre de marqueurs de paramètres. Ces marqueurs correspondent aux paramètres d'entrée des méthodes intégrées ou annotées.
@Handler
Dirige pureQuery pour utiliser une classe d'implémentation fournie au lieu de la procédure par défaut de pureQuery lors de l'exécution de la méthode annotée.
parameterHandler
Indique une implémentation de l'interface com.ibm.pdq.handlers.ParameterHandler. Si vous définissez cet attribut, pureQuery utilise la classe pour définir les valeurs des paramètres de l'objet java.sql.PreparedStatement pour l'instruction SQL.
resultHandler
Indique une implémentation de l'interface com.ibm.pdq.handlers.ResultHandler<RES>. Si vous définissez cet attribut, pureQuery utilise la classe pour créer l'objet renvoyé par la méthode annotée. La méthode handle() de la classe traite java.sql.ResultSet pour une instruction SQL et renvoie le contenu dans un objet de type <RES>.
rowHandler
Indique une implémentation de l'interface com.ibm.pdq.handlers.RowHandler<ROW>. Si vous définissez cet attribut, pureQuery utilise la classe pour créer l'objet représentant chaque ligne de résultats de la requête renvoyés par la méthode annotée. Cette méthode handle() de la classe traite une seule ligne de java.sql.ResultSet pour une instruction SQL et renvoie le contenu dans un objet de type <ROW>.
type-renvoi
Indique le type de renvoi de la méthode.

Le deuxième tableau indique les types de renvoi possibles pour les méthodes annotées lançant une requête sur les collections intégrées à la mémoire.

Tableau 1. Clé dans la table des types de renvoi
Abréviation Signification
I Iterator
L Liste
M Map
O Objet
S String
T Classe générique pouvant être une classe d'encapsulation pour un type de primitif Java, ou un bean.
Tableau 2. Types de renvoi en fonction du type d'annotation
  I<M<S,O>> I<T> L<M<S,O>> L<T> M<S,O> M<S,O>[] <T>
@Select X X X X X X X

Lorsque vous utilisez une méthode annotée, ne spécifiez pas qu'une annotation @Select renvoie un type Java primitif, ou un objet Array, List ou Iterator de type Java primitif.

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 = myGenericMethod( int.class );
où la définition de myGenericMethod est :
<T> T myGenericMethod( Class<T> cl );
La classe déclarée de tCount doit être Integer.
Integer tCount = myQuery.myGenericMethod( Integer.class );
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é. Chaque élément correspond à une ligne du résultat de la requête.
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.
<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 qualifient suite à la requête, la valeur de la première ligne est renvoyée.

<T>[]
Indique qu'un tableau de type T est renvoyé, tel que Employee[], Integer[] ou String[]. Chaque élément correspond à une ligne du résultat de la requête.
nom-méthode
Spécifie le nom de la méthode d'interface.
type-paramètre nom-paramètre

Ces paramètres sont comparés aux marqueurs de paramètres définis dans l'instruction SQL conformément aux règles ci-dessous. Ces paramètres peuvent être de type scalaire, des classes de bean ou des objets Map. Si l'instruction SQL utilise la notation :name pour les références des paramètres, le premier type de paramètre doit être un bean ou une mappe. Les noms de propriétés du bean ou de l'objet Map sont utilisés pour établir une comparaison avec les occurrences :name dans la chaîne SQL.

Au moins un paramètre Iterator, Array ou List itérable est requis pour que pureQuery puisse identifier l'instruction SELECT correspondante comme une requête lancée sur la collection intégrée à la mémoire. Faites référence à ce paramètre dans la clause FROM de l'instruction SELECT en utilisant la syntaxe décrite dans Marqueurs de paramètres de la clause FROM des requêtes de collections Java intégrées à la mémoire.

Si l'instruction SQL utilise la notation ? pour les marqueurs de paramètres, vous pouvez fournir uniquement des valeurs scalaires.

Si vous utilisez la notation ?n, les paramètres correspondants doivent être de types scalaire (à moins qu'ils ne soient compris dans la clause FROM, auquel cas ils doivent correspondre à des collections ou des objets Array).

Si vous utilisez la notation ?n.name, les paramètres correspondants doivent être des classes de bean ou des objets Map. Les notations ?n et ?n.name peuvent être mélangées dans une seule requête, mais ne peuvent pas être mélangées à des marqueurs de paramètres ? autonomes.


Commentaires