This topic contains the following sections:
To understand the conventions that are used in the diagrams, see How to read syntax diagrams.
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. The pureQuery Generator is automatically invoked for all pureQuery annotated method interfaces that are contained in a Java project that with pureQuery support enabled. The generation of interface implementations happens as part of the normal build process for Java projects.
However, you can also run the pureQuery Generator from a command line. You must have IBM® Data Studio, IBM Optim™ Development Studio, or IBM Data Studio Developer installed. Depending on the installed product, 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 uses the infrastructure and plug-ins that these products provide.
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.
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.-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.
@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.You can choose to use only the command if you want to use the same options for all of the interfaces that you specify.
(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-' >--+---------------------------+------------------------------->< | .-AUTO-. | '- -lineSeparator--+-CRLF-+-' +-CR---+ '-LF---'
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.
(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) | | .-AUTO-. | '-| Trace options |-----' '- -lineSeparator--+-CRLF-+-' +-CR---+ '-LF---'
The remaining two syntax diagrams describe how to create entries in options files.
This syntax diagram shows the default options that you can set for all of the interfaces that you list in an options file.
(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-' >--+---------------------------+------------------------------->< | .-AUTO-. | '- -lineSeparator--+-CRLF-+-' +-CR---+ '-LF---'
This syntax diagram shows the options that you can set for each interface that you list in an options file.
(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-' >--+---------------------------+------------------------------->< | .-AUTO-. | '- -lineSeparator--+-CRLF-+-' +-CR---+ '-LF---'
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.
(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-' >--+---------------------------+------------------------------->< | .-AUTO-. | '- -lineSeparator--+-CRLF-+-' +-CR---+ '-LF---'
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:
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.
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.
Verification of the version at run time is based on the consistency token, not the version name.
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.
This option can be specified with the -rootPkgExclusion option to control the DB2 package names created by the StaticBinder utility.
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:
-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 |
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.
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.
>>-+------------------------+--+---------------------------+--->< '- -traceFile--file-name-' | .-OFF-----. | '- -traceLevel--+-ALL-----+-' +-SEVERE--+ +-WARNING-+ +-INFO----+ +-CONFIG--+ +-FINE----+ +-FINER---+ '-FINEST--'