Utilitaire Generator

L'utilitaire Generator de pureQuery génère les classes d'implémentation pour les interfaces déclarant des méthodes annotées.

Cette rubrique contient les sections suivantes :

Pour comprendre les conventions utilisées dans les diagrammes, voir Lecture des diagrammes de syntaxe.

Présentation

L'utilitaire Generator de pureQuery requiert des paramètres permettant de spécifier l'environnement Eclipse à utiliser, la base de données, le pilote JDBC et l'interface à utiliser lors de la génération d'une classe d'implémentation.

L'utilitaire Generator analyse le contenu du fichier d'interface en entrée et crée un code Java qui analyse ou met à jour l'objet de données référencé dans les annotations @Select, @Update et @Call. Il génère le code permettant de remplir le bean cible d'une opérations d'analyse et utilise son contenu pour la mise à jour en tant que données d'entrée.

La plupart des utilisateurs pureQuery génère leurs applications à l'aide du plan de travail. Dans cet environnement, l'utilitaire Generator de pureQuery est automatiquement appelé pour toutes les interfaces de méthode annotée pureQuery que contient un projet Java dont le support pureQuery est activé. La génération des implémentations d'interface a lieu dans le cadre du processus normal de génération des projets Java.

Toutefois, vous pouvez également appeler l'utilitaire Generator de pureQuery à partir d'une ligne de commande. IBM® Data Studio Developer ou IBM Optim Development Studio doit être installé. Selon le produit installé, vous devez inclure le fichier .jar suivant dans le chemin d'accès aux classes du système ou le chemin d'accès aux classes JVM lors de l'exécution de l'utilitaire Generator :

L'utilitaire Generator ne lance pas Data Studio Developer ni Optim Development Studio. Il utilise uniquement l'infrastructure et les plugins offert pas ces produits.

Fichiers d'options

Un fichier d'options répertorie la ou les interfaces que l'utilitaire pureQuery Generator doit traiter, ainsi que les options indiquant à l'utilitaire Generator comment traiter les interfaces. Vous pouvez définir les options par défaut s'appliquant à toutes les interfaces répertoriées dans un fichier d'options. Vous pouvez également définir des options d'interface afin de remplacer les options par défaut et d'en définir d'autres spécifiques aux interfaces individuelles.

Dans la commande d'exécution de l'utilitaire Generator, vous pouvez vérifier le fichier à utiliser à l'aide de l'option -optionsFile.

Par exemple, un fichier d'options simple pour l'utilitaire pureQuery Generator peut se présenter comme suit :
defaultOptions = -driverName com.ibm.db2.jcc.DB2Driver -url jdbc:db2://SRVR01:50000/DB01 -username user01 -password passw0rd
com.myCompany.MyInterfaceA = -collection NULLID
com.myCompany.MyInterfaceB = -collection COLL01 -xmlFile C:\overrides\myInterfaceB_sql2.xml
com.myCompany.MyInterfaceC = -url jdbc:db2://SRVR01:50001/DB02 -username user02 -password pass02 
Dans cet exemple, la ligne commençant par defaultOptions indique le pilote à utiliser lors de la connexion à la base de données, l'URL de connexion à la base de données, le nom d'utilisateur et le mot de passe. Ces paramètres s'appliquent à toutes les interfaces se trouvant dans le fichier d'options. Les lignes spécifiques aux deux premières interfaces définissent les options pour ces interfaces uniquement.
Vous pouvez également inclure des commentaires dans les fichiers d'options en insérant le symbole # au début de chaque ligne de commentaire. Si ce symbole doit également apparaître dans la valeur de l'une des options, placez la valeur entre guillemets, comme suit :
-pkgVersion "ver#1"
Lorsque vous exécutez l'utilitaire Generator à partir d'une ligne de commande et utilisez un fichier d'options, pureQuery reconnaît les options selon l'ordre de priorité suivant :
  1. Options dans la ligne de commande
  2. Options pour les interfaces individuelles dans le fichier d'options indiqué
  3. Options par défaut dans le fichier d'options spécifié

Syntaxe de la commande d'exécution de l'utilitaire Generator si vous n'utilisez pas de fichier d'options

Vous pouvez utiliser uniquement la commande si vous souhaitez utiliser les mêmes options pour toutes les interfaces que vous spécifiez.

Lire le diagrammeSauter le diagramme
                                                                                    (1)   
>>-java--org.eclipse.core.launcher.Main-- -application--com.ibm.pdq.tools.Generator------>

>-- -data--espace_travail_temporaire---------------------------->

>-- -driverName--pilote_JDBC------------------------------------>

>-- -url--URL_connexion-- -username--ID_utilisateur-- -password--mot_de_passe-->

>--+------------------------+-- -rootPath--chemin_racine-------->
   |              .-FALSE-. |                              
   '- -noCleanup--+-TRUE--+-'                              

>--+--------------------------------+--------------------------->
   '- -userClasspath--chemin_classe-'   

>--+----------------------------------+------------------------->
   |               .-NULLID---------. |   
   '- -collection--+-nom_collection-+-'   

>--+--------------------------------+--------------------------->
   '- -pkgVersion-- -+-AUTO-------+-'   
                     '-ID_version-'     

>--+----------------------------------+------------------------->
   '- -rootPkgName--racine_nom_module-'   

>--+---------------------------------------+-------------------->
   |                             .-FALSE-. |   
   '- -forceSingleBindIsolation--+-TRUE--+-'   

>--+------------------------+--+--------------------------+----->
   '- -xmlFile--fichier_XML-'  |                      (2) |   
                               '-| options de trace |-----'   

                .-------------------------------.   
                V                               |   
>-- -interface----package-java.interface.classe-+--------------->

>--+---------------------------------------------+-------------><
   '- -baseDataOverride--package_java.nom_classe-'   

Remarques:
  1. Vous pouvez spécifier les options dans n'importe quel ordre.
  2. Pour la syntaxe, voir la description de ces options.

Syntaxe d'exécution de la commande de l'utilitaire Generator si vous utilisez un fichier d'options

Vous pouvez utiliser un fichier d'options pour spécifier les noms des interfaces et les options de création des modules DB2 ou des fichiers DBRM. Avec un fichier d'options, vous pouvez spécifier différentes options pour les différentes interfaces.

Si vous utilisez le plan de travail, vous pouvez faire figurer dans un fichier d'options (Default.genProps par défaut, par exemple) uniquement les interfaces dont vous souhaitez individuellement spécifier des options. La ligne defaultOptions s'applique à toutes les interfaces d'un projet Java.

Lire le diagrammeSauter le diagramme
                                                                                    (1)   
>>-java--org.eclipse.core.launcher.Main-- -application--com.ibm.pdq.tools.Generator------>

>-- -data--espace_travail_temporaire---------------------------->

>-- -driverName--pilote_JDBC------------------------------------>

>-- -url--URL_connexion-- -username--ID_utilisateur-- -password--mot_de_passe-->

>-- -optionsFile--nom_fichier--+------------------------+------->
                               |              .-FALSE-. |   
                               '- -noCleanup--+-TRUE--+-'   

>-- -rootPath--chemin_racine------------------------------------>

>--+--------------------------------+--------------------------->
   '- -userClasspath--chemin_classe-'   

>--+--------------------------+--------------------------------><
   |                      (2) |   
   '-| options de trace |-----'   

Remarques:
  1. Vous pouvez spécifier les options dans n'importe quel ordre.
  2. Pour la syntaxe, voir la description de ces options.

Les deux diagrammes de syntaxe restants expliquent comment créer des entrées dans des fichiers d'options.

Syntaxe de spécification des options par défaut dans un fichier d'options pour l'utilitaire Generator

Ce diagramme de syntaxe affiche les options par défaut que vous pouvez définir pour toutes interfaces figurant dans un fichier d'options.

Lire le diagrammeSauter le diagramme
                     (1)                              
>>-defaultOptions--=------ -driverName--pilote_JDBC------------->

>-- -url--URL_connexion-- -username--ID_utilisateur-- -password--mot_de_passe-->

>--+------------------------+-- -rootPath--chemin_racine-------->
   |              .-FALSE-. |                              
   '- -noCleanup--+-TRUE--+-'                              

>--+--------------------------------+--------------------------->
   '- -userClasspath--chemin_classe-'   

>--+--------------------------+--------------------------------->
   |                      (2) |   
   '-| options de trace |-----'   

>--+----------------------------------+------------------------->
   |               .-NULLID---------. |   
   '- -collection--+-nom_collection-+-'   

>--+--------------------------------+--------------------------->
   '- -pkgVersion-- -+-AUTO-------+-'   
                     '-ID_version-'     

>--+---------------------------------------+-------------------->
   |                             .-FALSE-. |   
   '- -forceSingleBindIsolation--+-TRUE--+-'   

>--+------------------------+----------------------------------->
   '- -xmlFile--fichier_XML-'   

>--+---------------------------------------------+-------------><
   '- -baseDataOverride--package_java.nom_classe-'   

Remarques:
  1. Vous pouvez spécifier les options dans n'importe quel ordre.
  2. Pour la syntaxe, voir la description de ces options.

Syntaxe de substitution des options par défaut dans un fichier d'options pour l'utilitaire Generator

Ce diagramme de syntaxe affiche les options que vous pouvez définir pour chaque interface figurant dans un fichier d'options.

Lire le diagrammeSauter le diagramme
                             (1)                              
>>-package_java.interface--=------ -driverName--pilote_JDBC----->

>-- -url--URL_connexion-- -username--ID_utilisateur-- -password--mot_de_passe-->

>--+----------------------------------+------------------------->
   |               .-NULLID---------. |   
   '- -collection--+-nom_collection-+-'   

>--+--------------------------------+--------------------------->
   '- -pkgVersion-- -+-AUTO-------+-'   
                     '-ID_version-'     

>--+----------------------------------+------------------------->
   '- -rootPkgName--racine_nom_module-'   

>--+---------------------------------------+-------------------->
   |                             .-FALSE-. |   
   '- -forceSingleBindIsolation--+-TRUE--+-'   

>--+------------------------+----------------------------------->
   '- -xmlFile--fichier_XML-'   

>--+---------------------------------------------+-------------><
   '- -baseDataOverride--package_java.nom_classe-'   

Remarques:
  1. Vous pouvez spécifier les options dans n'importe quel ordre.

Descriptions des options

-baseDataOverride package_java.nom_classe
Indique le nom d'une classe Java que l'implémentation générée va étendre. Par défaut, les classes d'implémentation générées étendent la classe com.ibm.pdq.runtime.generator.BaseData. Si vous spécifiez votre propre classe, vous pouvez étendre la classe d'implémentation générée avec vos propres méthodes.
-collection nom_collection
Vous utiliserez cette option, qui prend en charge le développement d'applications faisant intervenir des instructions SQL statiques, si vous prévoyez d'exécuter l'utilitaire StaticBinder par la suite. Cette option permet d'indiquer le qualificatif des modules pour lesquels l'utilitaire pureQuery StaticBinder définit des accès. Ce qualificatif doit satisfaire aux contraintes applicables aux noms de collection pour la base de données DB2 que vous utilisez.
Si vous ne définissez pas ce paramètre, celui-ci prend la valeur par défaut NULLID.
-data chemin
Spécifie le chemin d'accès absolu d'un espace de travail Eclipse temporaire utilisé par l'utilitaire Generator.
-driverName nom
Nom du pilote JDBC à utiliser pour établir la connexion à la base de données.
-forceSingleBindIsolation TRUE | FALSE
Indique si vous prévoyez la création d'un package DB2 pour un niveau d'isolement unique et si vous souhaitez associer un nombre au nom du package pour indiquer son niveau d'isolement. La valeur par défaut est FALSE, ce qui signifie que l'indicateur numérique est attaché.
Utilisez cette option avec l'option -isolationLevel de l'utilitaire StaticBinder.

Si vous souhaitez utiliser l'option -isolationLevel pour définir les accès d'un seul jeu d'instructions en deux ou trois packages différents (chaque package à un autre niveau d'isolement), n'utilisez pas l'option -forceSingleBindIsolation lorsque vous exécutez l'utilitaire Configure sur le fichier pureQueryXML dans lequel apparaît le jeu d'instructions.

Par exemple, dans un fichier d'options pour l'utilitaire StaticBinder, supposez que vous avez inclus les deux entrées suivantes :

C:/dir/captureFile.pdqxml:MYPKGA = -isolationLevel UR
C:/dir/captureFile.pdqxml:MYPKGA = -isolationLevel CS

Si vous avez utilisé l'option -forceSingleBindIsolation lors de l'exécution de l'utilitaire Configure sur le fichier captureFile.pdqxml, l'utilitaire StaticBinder effectue les actions suivantes :

  1. Définition des accès du package MYPKGA au niveau d'isolement UR.
  2. Redéfinition des accès du package MYPKGA au niveau d'isolation CS.

Le résultat est un package MYPKGA unique dont les accès sont définis au niveau d'isolement CS.

Si vous voulez avoir deux packages MYPKGA comme résultat, un au niveau d'isolement UR et l'autre au niveau CS, n'utilisez pas l'option -forceSingleBindIsolation lors de l'exécution de l'utilitaire Configure sur captureFile.pdqxml.

-interface package-java.classe-interface
Nom de l'interface compilée pour laquelle le générateur pureQuery doit créer une classe d'implémentation. Le nom doit être complètement qualifié avec le nom du module Java dans lequel se trouve la classe.
module_Java.interface (au début d'une ligne d'un fichier d'options)
Indique que les options figurant sur la ligne s'appliquent uniquement aux instructions SQL de l'interface spécifiée. Ces options remplacent celles que vous spécifiez par défaut.
Vous devez qualifier le nom de l'interface avec le nom du module Java auquel l'interface appartient.
-noCleanup TRUE|FALSE
Si le générateur pureQuery doit créer un projet Java dans l'espace Eclipse spécifié, cette option indique si le générateur supprime le projet Java après génération de l'implémentation.
TRUE
Le générateur pureQuery ne supprime pas le projet Java.
FALSE
Le générateur pureQuery supprime le projet Java. Il s'agit de la valeur par défaut.
-optionsFile nom_fichier
Nom du fichier, chemin absolu ou relatif inclus, qui répertorie les interfaces pour lesquelles vous voulez générer des classes d'implémentation.
Un fichier d'options peut contenir un ensemble d'options par défaut ainsi qu'une liste d'interfaces avec un ensemble d'options pour chaque interface. Lorsque vous spécifiez un fichier d'options, vous pouvez également indiquer des options dans la ligne de commande. Les options indiquées en tant qu'options par défaut s'appliquent à une interface donnée, excepté si elles sont remplacées par les options spécifiquement répertoriées pour cette interface ou par les options indiquées dans la ligne de commande.
-password mot_de_passe
Mot de passe à utiliser pour établir la connexion à la source de données.
-pkgVersion AUTO|ID_version
Vous utiliserez cette option, qui prend en charge le développement d'applications faisant intervenir des instructions SQL statiques, si vous prévoyez d'exécuter l'utilitaire StaticBinder par la suite. Cette option permet d'indiquer la version du module à utiliser lorsque la définition des accès est effectuée.

DB2 accepte la présence simultanée de plusieurs versions d'un même module, ce qui vous permet de définir les accès des nouveaux modules sans devoir remplacer les anciennes versions des modules portant un nom identique. Si vous rencontrez des difficultés avec une version récente d'un module, vous pouvez toujours utiliser une version plus ancienne de ce module.

Si vous n'utilisez pas cette option, les modules de base de données résultant de définitions d'accès ultérieures sont créés sans version.

AUTO
Indique que la version doit être générée de façon automatique en utilisant l'horodatage en cours.
ID_version
Indique l'identificateur de version d'un package. La chaîne entrée doit être valide pour la version de DB2 que vous utilisez.

La vérification de la version au moment de l'exécution est basée sur la marque de cohérence, et non pas sur le nom de la version.

-rootPkgName racine_nom_module
Vous utiliserez cette option, qui prend en charge le développement d'applications faisant intervenir des instructions SQL statiques, si vous prévoyez d'exécuter l'utilitaire StaticBinder par la suite. Cette option permet d'indiquer la racine du nom à utiliser pour les modules DB2. Lorsque vous créez des modules et définissez des accès pour ces modules, des chiffres représentant les niveaux d'isolement sont ajoutés à ce nom. Des noms complets (racine + chiffre indicateur du niveau d'isolement) sont attribués aux modules. La valeur racine_nom_module doit respecter les contraintes imposées par la base de données DB2 que vous utilisez.

Si vous prévoyez de générer des fichiers DBRM avec l'utilitaire pureQuery StaticBinder plutôt que de créer des modules DB2, vous devez utiliser des majuscules pour la valeur racine_nom_module et cette valeur ne doit pas comporter plus de 7 caractères. Si vous utilisez l'utilitaire StaticBinder pour générer un fichier DBRM, cet utilitaire émet une exception dès lors que vous dépassez un total de 7 caractères pour la combinaison racine_nom_module / caractères ajoutés pour le niveau d'isolement.

Les noms de module doivent être uniques au sein d'une même base de données : vous ne pouvez pas attribuer un nom de module racine donné à plusieurs interfaces. Vous pouvez indiquer un nom de module racine dans la ligne de commande si vous y spécifiez une unique interface. Vous pouvez également indiquer un nom de module racine pour des interfaces dans un fichier d'options, mais pas au niveau de la ligne defaultOptions.

-rootPath chemin-racine
Chemin absolu vers le répertoire contenant les interfaces que l'utilitaire Generator doit traiter.

Par exemple, le répertoire peut être C:\user\app1\. Dans ce répertoire se trouvent des sous-répertoires correspondant aux packages Java, tels que C:\user\app1\com\myCompany\.

A l'aide de l'option -interface de l'utilitaire Generator, indiquez le nom de l'interface que l'utilitaire doit traiter, en indiquant son nom avec le nom du package, comme suit : com.myCompany.MyInterface

L'interface doit pouvoir être compilée.

L'utilitaire Generator génère une classe d'implémentation dans le même répertoire que celui de l'interface correspondante. Par conséquent, chaque classe d'implémentation est créée dans le même package Java que son interface.

Si vous exécutez l'utilitaire pureQuery Generator avec -rootPath défini sur C:\user\app1\ et -interface défini sur com.myCompany.MyInterface, l'utilitaire génère la classe MyInterfaceImpl.java dans le répertoire C:\user\app1\com\myCompany\. Le nom qualifié complet de la classe est com.myCompany.MyInterfaceImpl.

Si vous n'utilisez pas l'option -rootPath, l'utilitaire pureQuery Generator utilise le répertoire de travail.

options de trace
Vous pouvez demander à ce que le fichier journalise les messages et préciser le niveau d'information à journaliser.
Lire le diagrammeSauter le diagramme
>>-+--------------------------+--------------------------------->
   '- -traceFile--nom_fichier-'   

>--+---------------------------+-------------------------------><
   |               .-OFF-----. |   
   '- -traceLevel--+-ALL-----+-'   
                   +-SEVERE--+     
                   +-WARNING-+     
                   +-INFO----+     
                   +-CONFIG--+     
                   +-FINE----+     
                   +-FINER---+     
                   '-FINEST--'     

-traceFile nom_fichier
Indique le chemin absolu ou relatif ainsi que le nom du fichier à utiliser pour la journalisation des informations relatives à l'opération.
Si le fichier existe déjà, pureQuery ajoute les nouveaux messages à la suite des messages déjà placés dans ce fichier. Par défaut, les entrées sont écrites dans System.err.
-traceLevel OFF|SEVERE|WARNING|INFO|CONFIG|FINE|FINER|FINEST|ALL
Indique le type d'informations à journaliser. Le niveau par défaut est OFF. Si vous ne spécifiez pas de fichier dans lequel écrire les entrées de journal et que vous associez cette option à une valeur autre qu'OFF, les entrées sont écrites dans System.err.
-url URL_connexion
URL JDBC de type 4 pour la connexion à la base de données.
-username ID utilisateur
ID utilisateur à indiquer pour établir la connexion à la source de données.
-userClasspath chemin_classe
Spécifie un chemin d'accès aux classes qui fournit les chemins d'accès de pdq.jar, pdqmgmt.jar, les fichier JAR de votre pilote JDBC et tout autre fichier JAR ou de classe dont pureQuery a besoin pour résoudre les dépendances de fichier de classe dans les interfaces.
-xmlFile fichier-XML
Nom du fichier de configuration XML contenant les instructions SQL qui spécifient ou remplacent les instructions SQL des méthodes définies dans l'interface. Un fichier de configuration XML peut également écraser les définitions des beans correspondants.

Commentaires