Generator utility

The pureQuery Generator utility generates implementation classes for interfaces that declare annotated methods.

This topic contains the following sections:

To understand the conventions that are used in the diagrams, see How to read syntax diagrams.

Overview

The pureQuery Generator utility requires parameters that specify the Eclipse environment to use, the database, JDBC driver, and interface to use when generating an implementation class.

The Generator analyzes the content of the input interface file and creates Java™ code that queries or updates the data object referenced in the @Select, @Update, and @Call annotations. It generates the code to populate the target bean on a query operation and uses the bean contents on update as input data.

Many pureQuery users build their applications using the workbench. In that environment, the pureQuery Generator is automatically invoked for all pureQuery annotated method interfaces that are contained in a Java project that has pureQuery support enabled. The generation of interface implementations happens as part of the normal build process for Java projects.

However, you can also invoke the pureQuery Generator from a command line. You must have IBM® Data Studio Developer or IBM Optim™ Development Studio installed. Depending on which of these two products you have installed, you must include the following .jar file in either the system classpath or JVM classpath when you run the Generator utility:

The Generator utility does not start Data Studio Developer or Optim Development Studio. It only makes use of the infrastructure and plugins that these products provide.

Options files

An options file lists the interface or interfaces that you want the pureQuery Generator utility to process, and the options that tell the Generator how to process the interfaces. You can set default options that apply to all of the interfaces that you list in an options file. You can also set options for interfaces so that you can override the default options and set other options that are specific to individual interfaces.

In the command to run the Generator, you can specify the file to use with the -optionsFile option.

For example, a simple options file for the pureQuery Generator might look like this:
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 
In this example, the line that begins with defaultOptions specifies the driver to use when connecting to the database, the URL for connecting to the database, and the user name and password. These settings apply to all of the interfaces that are in the options file. The lines that are specific to the first two interfaces set options for those interfaces only.
You can also include comments in options files by prefacing each line of a comment with a # symbol. If you need this symbol to appear in the value of one of the options, enclose the value in double-quotation marks, like this:
-pkgVersion "ver#1"
When you run the Generator from a command line and use an options file, pureQuery recognizes options in the following order of precedence:
  1. Options on the command line
  2. Options for individual interfaces in the specified options file
  3. Default options in the specified options file

Syntax for the command to run the Generator utility if you are not using an options file

You can choose to use only the command if you want to use the same options for all of the interfaces that you specify.

Read syntax diagramSkip visual syntax diagram
                                                                                    (1)   
>>-java--org.eclipse.core.launcher.Main-- -application--com.ibm.pdq.tools.Generator------>

>-- -data--temporary-workspace-- -driverName--JDBC-driver------->

>-- -url--connection-URL-- -username--user-ID-- -password--password-->

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

>--+----------------------------+------------------------------->
   '- -userClasspath--classpath-'   

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

>--+--------------------------------+--------------------------->
   '- -pkgVersion-- -+-AUTO-------+-'   
                     '-version-ID-'     

>--+----------------------------------+------------------------->
   '- -rootPkgName--package-name-stem-'   

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

>--+---------------------+--+-----------------------+----------->
   '- -xmlFile--XML-file-'  |                   (2) |   
                            '-| Trace options |-----'   

                .------------------------------.   
                V                              |   
>-- -interface----Java-package.interface.class-+---------------->

>--+---------------------------------------------+-------------><
   '- -baseDataOverride--Java-package.class-name-'   

Notes:
  1. You can specify the options in any order.
  2. For the syntax, see the description of these options.

Syntax for the command to run the Generator utility if you are using an options file

You can use an options file to specify the names of the interfaces and the options for creating the DB2® packages or DBRM files. With an options file, you can specify different options for the different interfaces.

If you are using the workbench, you can list in an options file (such as the Default.genProps file) only those interfaces that you want to specify options for individually. The defaultOptions line applies to all of the interfaces that are in a Java project.

Read syntax diagramSkip visual syntax diagram
                                                                                    (1)   
>>-java--org.eclipse.core.launcher.Main-- -application--com.ibm.pdq.tools.Generator------>

>-- -data--temporary-workspace-- -driverName--JDBC-driver------->

>-- -url--connection-URL-- -username--user-ID-- -password--password-->

>-- -optionsFile--file-name--+------------------------+--------->
                             |              .-FALSE-. |   
                             '- -noCleanup--+-TRUE--+-'   

>-- -rootPath--root_path--+----------------------------+-------->
                          '- -userClasspath--classpath-'   

>--+-----------------------+-----------------------------------><
   |                   (2) |   
   '-| Trace options |-----'   

Notes:
  1. You can specify the options in any order.
  2. For the syntax, see the description of these options.

The remaining two syntax diagrams describe how to create entries in options files.

Syntax for specifying default options in an options file for the Generator utility

This syntax diagram shows the default options that you can set for all of the interfaces that you list in an options file.

Read syntax diagramSkip visual syntax diagram
                     (1)                              
>>-defaultOptions--=------ -driverName--JDBC-driver------------->

>-- -url--connection-URL-- -username--user-ID-- -password--password-->

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

>--+----------------------------+--+-----------------------+---->
   '- -userClasspath--classpath-'  |                   (2) |   
                                   '-| Trace options |-----'   

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

>--+--------------------------------+--------------------------->
   '- -pkgVersion-- -+-AUTO-------+-'   
                     '-version-ID-'     

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

>--+---------------------+-------------------------------------->
   '- -xmlFile--XML-file-'   

>--+---------------------------------------------+-------------><
   '- -baseDataOverride--Java-package.class-name-'   

Notes:
  1. You can specify the options in any order.
  2. For the syntax, see the description of these options.

Syntax for overriding default options in an options file for the Generator utility

This syntax diagram shows the options that you can set for each interface that you list in an options file.

Read syntax diagramSkip visual syntax diagram
                             (1)                              
>>-Java-package.interface--=------ -driverName--JDBC-driver----->

>-- -url--connection-URL-- -username--user-ID-- -password--password-->

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

>--+--------------------------------+--------------------------->
   '- -pkgVersion-- -+-AUTO-------+-'   
                     '-version-ID-'     

>--+----------------------------------+------------------------->
   '- -rootPkgName--package-name-stem-'   

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

>--+---------------------+-------------------------------------->
   '- -xmlFile--XML-file-'   

>--+---------------------------------------------+-------------><
   '- -baseDataOverride--Java-package.class-name-'   

Notes:
  1. You can specify the options in any order.

Descriptions of options

-baseDataOverride Java-package.class-name
Lets you specify the name of a Java class that the generated implementation class will extend. By default, generated implementation classes extend the class com.ibm.pdq.runtime.generator.BaseData. By specifying your own class, you can extend the generated implementation class with your own methods.
-collection collection-name
Use this option, which supports the development of applications that use static SQL, if you plan to run the StaticBinder utility later. This option specifies the qualifier for the packages that the pureQuery StaticBinder utility binds. The qualifier must meet the constraints for collection names for the DB2 database that you are using.
If you do not specify this parameter, the value defaults to NULLID.
-data path
Specifies the absolute path of a temporary Eclipse workspace for the Generator utility to use.
-driverName name
The name of the JDBC driver to use to connect to the database.
-forceSingleBindIsolation TRUE|FALSE
Specifies whether you plan to create a DB2 package for only a single isolation level and do not want a number appended to the name of the package to indicate the isolation level. The default value is false, which means that a numeric indicator is appended.
Use this option together with the -isolationLevel option of the StaticBinder utility.

If you want to use the -isolationLevel option to bind a single statement set into two or three different packages, with each package at a different isolation level, do not use the -forceSingleBindIsolation option when you run the Configure utility on the pureQueryXML file in which the statement set appears.

For example, in an options file for the StaticBinder utility, suppose that you included these two entries:

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

If you used the -forceSingleBindIsolation option when you ran the Configure utility on the captureFile.pdqxml file, the StaticBinder utility performs these actions:

  1. Bind the package MYPKGA at the UR isolation level.
  2. Rebind the package MYPKGA at the CS isolation level.

The result is a single MYPKGA package that is bound at the CS isolation level.

If you want the result to be two MYPKGA packages, one at the UR and the other at the CS isolation level, do not use the -forceSingleBindIsolation option when you run the Configure utility on captureFile.pdqxml.

-interface java-package.interface-class
The name of the compiled interface for which you want the pureQuery Generator utility to create an implementation class. The name must be fully qualified with the name of the Java package in which the class is located.
Java-package.interface (at the beginning of a line in an options file)
Specifies that the options on the line apply only to the SQL statements in the specified interface. These options override options that you specify as defaults.
You must qualify the name of the interface with the name of the Java package to which the interface belongs.
-noCleanup TRUE|FALSE
If the pureQuery Generator utility needs to create a Java project in the specified Eclipse workspace, this option specifies whether the pureQuery Generator utility deletes the Java project after generating the implementation.
TRUE
The pureQuery Generator utility does not delete the Java project.
FALSE
The pureQuery Generator utility deletes the Java project. This is the default value.
-optionsFile file-name
The name of the file, including its absolute or relative path, that lists the interfaces that you want to generate implementation classes for.
An options file can contain a set of default options, as well as a list of interfaces, with a set of options for each interface. When you specify an options file, you can also specify some options on the command line. Options provided as default options are used for an interface unless they are overridden by options listed specifically for that interface, or by options provided on the command line.
-password password
The password to use to connect to the data source.
-pkgVersion AUTO|version-ID
Use this option, which supports the development of applications that use static SQL, if you plan to run the StaticBinder utility later. This option specifies the package version to use when packages are bound.

DB2 allows multiple versions of a package to exist at the same time, so that you can bind new packages without replacing older versions of packages with the same names. If you encounter problems with a newer package, you can use an older version of that package.

If you do not specify this option, database packages that result from subsequent binds are created without a version.

AUTO
Specifies that the version is automatically generated by using the current timestamp.
version-ID
Specifies the version identifier for a package. The string must be valid for the version of DB2 that you are using.

Verification of the version at run time is based on the consistency token, not the version name.

-rootPkgName package-name-stem
Use this option, which supports the development of applications that use static SQL, if you plan to run the StaticBinder utility later. This option specifies the stem of the name to use for DB2 packages. When you create and bind packages, numbers that indicate isolation levels are appended to this name. The full names (name stem plus number indicating the isolation level) are given to the packages.package-name-stem must be within the constraints that are set by the DB2 database that you are using.

If you plan to use the pureQuery StaticBinder utility to generate DBRM files rather than create DB2 packages, package-name-stem must be in uppercase and up to only 7 characters long. If you use the StaticBinder utility to generate a DBRM file and package-name-stem plus the added characters for the isolation level is longer than 7 characters, the StaticBinder utility throws an exception.

Package names must be unique within a single database, so you cannot specify one root package name for more than one interface. You can specify a root package name on the command line if you specify exactly one interface there. Also, you can specify a root package name for interfaces in an options file, but not as part of the defaultOptions line.

-rootPath root-path
The absolute path to the directory that contains the interfaces that you want the Generator utility to process.

For example, the directory might be C:\user\app1\. Within that directory would be the directories that correspond to Java packages, such as C:\user\app1\com\myCompany\.

With the -interface option of the Generator utility, you specify the name of the interface that you want the utility to process, qualifying the name with the name of the package, as in this example: com.myCompany.MyInterface

The interface must be able to compile.

The Generator utility generates an implementation class in the same directory as the corresponding interface. Therefore, each implementation class is created in the same Java package as its interface.

If you run the pureQuery Generator utility with -rootPath set to C:\user\app1\ and -interface set to com.myCompany.MyInterface, the utility generates the class MyInterfaceImpl.java in the directory C:\user\app1\com\myCompany\. The fully-qualified name of the class is com.myCompany.MyInterfaceImpl.

If you do not use the -rootPath option, the pureQuery Generator utility uses the current working directory.

Trace options
You can specify the file to log messages in and the level of information to log.
Read syntax diagramSkip visual syntax diagram
>>-+------------------------+--+---------------------------+---><
   '- -traceFile--file-name-'  |               .-OFF-----. |   
                               '- -traceLevel--+-ALL-----+-'   
                                               +-SEVERE--+     
                                               +-WARNING-+     
                                               +-INFO----+     
                                               +-CONFIG--+     
                                               +-FINE----+     
                                               +-FINER---+     
                                               '-FINEST--'     

-traceFile file-name
Specifies the absolute or relative path and name of the file to use for logging information about the operation.
If the file already exists, pureQuery appends new messages to the existing content of the file. As the default, the entries are written to System.err.
-traceLevel OFF|SEVERE|WARNING|INFO|CONFIG|FINE|FINER|FINEST|ALL
Specifies the type of information to log. The default level is OFF. If you do not specify a file in which to write the log entries and you set this option to any value other than OFF, the entries are written to System.err.
-url connection-URL
The Type 4 JDBC URL for connecting to the database.
-username user ID
The user ID to use to connect to the data source.
-userClasspath classpath
Specifies a classpath that provides the paths of pdq.jar, pdqmgmt.jar, the JAR files for your JDBC driver, and any other JAR or class files that pureQuery needs to resolve any class file dependencies in the interfaces.
-xmlFile XML-file
The name of the XML configuration file that contains SQL that specifies or overrides the SQL in the methods that are defined in the interface. An XML configuration file can also override the definitions of the corresponding beans.

Feedback