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, IBM Optim™ Development Studio, or IBM Data 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 the product. 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 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"

In an options file, you can create an entry that specifies generation properties that are applied to a set of Java interfaces. You create a line that starts with groupOptions.group-name. The group identifier is the value of group-name. The value group-name is the string that is assigned to an interface with the pureQuery @Group annotation.

The following example @Group annotation is specified for the interface CalculateTax:
@Group ("Payroll")
public Interface CalculateTax {
…
}
When this groupOptions.Payroll entry is specified in an options file, the Generator utility generates implementation classes for interface CalculateTax with the specified option settings.
groupOptions.Payroll= -collection Payroll -url "jdbc:db2://com.prod.hr:50000/DB01" 
For information about the @Group annotation, see Controlling how pureQuery utilities process interfaces.
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. Options specified with a groupOptions entry in the specified options file
  4. 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-'   

>--+-----------------------------------------+------------------>
   |                   .-INTERFACE---------. |   
   '- -rootPkgPattern--+-INTERFACE_JAVAPKG-+-'   
                       '-JAVAPKG_INTERFACE-'     

>--+----------------------------------------------+------------->
   '- -rootPkgExclusion--="--pureQueryXML-file--"-'   

>--+---------------------------------------+-------------------->
   |                             .-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.

Syntax for specifying a groupOptions entry in an options file for the Generator utility

This syntax diagram shows the options that you can set for interfaces are applied to a set of Java interfaces with the group identifier group-name. The group-name is assigned to an interface with the pureQuery @Group annotation. The value group_name is case sensitive. For each value group_name, only one groupOptions entry is allowed in the options file.

The property -rootPkgName cannot be specified as an option.

Read syntax diagramSkip visual syntax diagram
                                        (1)   
>>-+----------------------------------+------------------------->
   '-groupOptions--.--group-name--= --'       

>-- -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.

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 ID is automatically generated by using the current timestamp. A single timestamp is used for the version ID.
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.

This option cannot be specified with the with the -rootPkgPattern option.

-rootPkgPattern INTERFACE|INTERFACE_JAVAPKG|JAVAPKG_INTERFACE
Controls how the Java Interface name and Java package name are used to create a DB2 package name. This option specifies root package names without specifying the -rootPkgName option. This option cannot be specified with the with the -rootPkgName option.

This option can be specified with the -rootPkgExclusion option to control the DB2 package names created by the StaticBinder utility.

The following list describes the supported values:
INTERFACE
The root name is determined in the default manner using only the Java Interface name.
INTERFACE_JAVAPKG
The static DB2 root package name is constructed from pureQuery Interface name followed by the Java package name.
JAVAPKG_INTERFACE
The static DB2 root package name is constructed from Java package name followed by the pureQuery Interface name.

When constructing the root package name from a Java package name, period character delimiter is be replaced by the underscore character.

If the total length of the Java package path plus the Interface name is greater than one less than the database maximum, an error is reported and the bind of that package is not be performed.

If the Interface name is com.acme.payroll.report.monthly.CommissionData, the following table lists the generated root package name for the -rootPkgPattern option values:

Table 1. The constructed root package name based on the Java Interface name com.acme.payroll.report.monthly.CommissionData
-rootPkgPattern option value Constructed DB2 root package name
INTERFACE CommissionData
INTERFACE_JAVAPKG CommissionData_com_acme_payroll_report_monthly
JAVAPKG_INTERFACE com_acme_payroll_report_monthly_CommissionData
JAVAPKG_INTERFACE specfied with the option -rootPkgExclusion="com.acme payroll_report_monthly_CommissionData
Note: DB2 for iSeries® has a maximum package name length is 10 characters, this option is not recommended for use with DB2 for iSeries. The maximum length is 128 characters for most supported versions of DB2 for z/OS® databases and DB2 for Linux, UNIX, and Windows database.
-rootPkgExclusion="package_prefix"
Specifies that the Generator utility removes the string specified by package_prefix when creating the root package name. This option can be specified only when the option -rootPkgPattern is also specified with a value of INTERFACE_JAVAPKG, or JAVAPKG_INTERFACE.

package_prefix specifies a period-delimited name that denotes the first part of the Java package name.

For example, if all Java package names in a project begin with com.acme, you can use this option to remove this redundant portion from the generated package names. At generation time, if the Java package name does not begin with the specified string, the utility attempts to use the full Java package name.

For example, if the Java Interface name is com.acme.payroll.report.monthly.CommissionData and the option -rootPkgExclusion="com.acme" is specified, the string com.acme is excluded when creating the DB2 root package name.

-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