Oracle9i SQLJ Developer's Guide and Reference Release 1 (9.0.1) Part Number A90212-01 |
|
Profiles and profile customization are introduced in "SQLJ Profiles".
This chapter presents more technical detail and discusses customizer options and how to use customizers other than the default Oracle customizer.
The following topics are covered:
SQLJ profiles contain information about your embedded SQL operations, with a separate profile being created for each connection context class that your application uses. Profiles are created during the SQLJ translator's code generation phase and customized during the customization phase. Customization enables your application to use vendor-specific database features. Separating these vendor-specific operations into your profiles enables the rest of your generated code to remain generic.
Each profile contains a series of entries for the SQLJ statements that use the relevant connection context class, where each entry corresponds to one SQL operation in your application.
Profiles exist as serialized objects stored in resource files packaged with your application. Because of this, profiles can be loaded, read, and modified (added to or re-customized) at any time. When profiles are customized, information is only added, never removed. Multiple customizations can be made without losing preceding customizations, so that your application maintains the capability to run in multiple environments. This is known as binary portability.
For profiles to have binary portability, SQLJ industry-standard requirements have been met in the Oracle SQLJ implementation.
During code generation, the translator creates each profile as follows:
sqlj.runtime.profile.Profile
class.
.ser
file name extension.
Oracle SQLJ provides an option to have the translator automatically convert these
Note:
.ser
files to .class
files. (The.ser
files are not supported by some browsers, and can be cumbersome when loading translated applications into the server.) However, this prevents any further customization of the profile. For information, see "Conversion of .ser File to .class File (-ser2class)".
As discussed in "Code Generation", profile file names for application Foo
are of the form:
Foo_SJProfilen.ser
SQLJ generates Foo_SJProfile0.ser
, Foo_SJProfile1.ser
, and so on, as needed (depending on how many connection context classes you use in your code). Or, if the -ser2class
option is enabled, then SQLJ generates Foo_SJProfile0.class
, Foo_SJProfile1.class
, and so on.
Each profile has a getConnectedProfile()
method that is called during SQLJ runtime. This method returns something equivalent to a JDBC Connection
object, but with added functionality. This is further discussed in "Functionality of a Customized Profile at Runtime".
Below is a sample SQLJ executable statement with the profile entry that would result. For simplicity, the profile entry is presented as plain text with irrelevant portions omitted.
Note that in the profile entry, the host variable is replaced by JDBC syntax (the question mark).
Presume the following declaration:
#sql iterator Iter (double sal, String ename);
And presume the following executable statements:
String empname = 'Smith'; Iter it; ... #sql it = { SELECT ename, sal FROM emp WHERE ename = :empname };
================================================================= ... #sql { SELECT ename, sal FROM emp WHERE ename = ? }; ... PREPARED_STATEMENT executed via EXECUTE_QUERY role is QUERY descriptor is null contains one parameter 1. mode: IN, java type: java.lang.String (java.lang.String), sql type: VARCHAR, name: ename, ... result set type is NAMED_RESULT result set name is Iter contains 2 result columns 1. mode: OUT, java type: double (double), sql type: DOUBLE, name: sal, ... 2. mode: OUT, java type: java.lang.String (java.lang.String), sql type: VARCHAR, name: ename, ... =================================================================
Note:
This profile entry is presented here as text for convenience only; profiles are not actually in text format. They can be printed as text, however, using the SQLJ |
By default, running the sqlj
script on a SQLJ source file includes an automatic customization process, where each profile created during the code generation phase is customized for use with your particular database. The default customizer is the Oracle customizer, oracle.sqlj.runtime.OraCustomizer
, which optimizes your profiles to use type extensions and performance enhancements specific to Oracle9i.
You can also run the sqlj
script to customize profiles created previously. On the SQLJ command line, you can specify .ser
files individually, .jar
files containing .ser
files, or both.
Regardless of whether you use the Oracle customizer or an alternative customizer, SQLJ uses a front-end customization utility known as the customizer harness in accomplishing your customizations.
When you run SQLJ, you can specify customization options for the customizer harness (for general customization settings that apply to any customizer you use) and for your customizer (for settings used by the particular customizer). In either case, you can specify these options either on the command line or in a properties file. This is discussed in "Customization Options and Choosing a Customizer".
The following paragraphs detail how Oracle implements the customizer harness and the Oracle customizer. This information is not necessary for most SQLJ developers.
The customizer harness is a command-line tool that is an instance of the class sqlj.runtime.profile.util.CustomizerHarness
. A CustomizerHarness
object is created and invoked each time you run the SQLJ translator. During the customization phase, the harness creates and invokes an object of the customizer class you are using (such as the default Oracle customizer), and loads your profiles.
The Oracle customizer is defined in the oracle.sqlj.runtime.OraCustomizer
class. All customizers must be JavaBeans components that adhere to the JavaBeans API to expose their properties and must implement the sqlj.runtime.profile.util.ProfileCustomizer
interface, which specifies a customize()
method. It is the implementation of this method in a particular customizer that does the work of customizing profiles.
For each profile to be customized, the customizer harness calls the customize()
method of the customizer object.
The SQLJ customization process during translation consists of the following steps, as applicable, either during the customization stage of an end-to-end SQLJ run, or when you run SQLJ to customize existing profiles only:
.jar
files (applicable when you run SQLJ for customization only, specifying one or more .jar
files on the command line).
.ser
files automatically created during an end-to-end SQLJ run, .ser
files specified on the command line for customization only, or .ser
files extracted from .jar
files specified on the command line for customization only).
customize()
method of the customizer object instantiated in step 2 (customizers used with Oracle SQLJ must have a customize()
method).
customize()
method typically creates and registers a profile customization within the profile. (This depends on the intended functionality of the customizer, however. Some might have a specialized purpose that does not require a customization to be created and registered in this way.)
.ser
file.
.jar
contents, inserting each customized .ser
file to replace the original corresponding uncustomized .ser
file (applicable when you run SQLJ for customization only, specifying one or more .jar
files on the command line).
When the harness calls the customize()
method to customize a profile, it passes in the profile object, a SQLJ connection context object (if you are using a customizer that requires a connection), and an error log object (which is used in logging error messages during the customization).
The same error log object is used for all customizations throughout a single running of SQLJ, but its use is transparent. The customizer harness reads messages written to the error log object and reports them in real-time to the standard output device (whatever SQLJ uses, typically your screen).
Recall that each profile has a set of entries, where each entry corresponds to a SQL operation. (These would be the SQL operations in your application that use instances of the connection context class associated with this profile.)
A customize()
method implements special processing on these entries. It could be as simple as checking each entry to verify its syntax, or it could be more complicated, such as creating new entries that are equivalent to the original entries but are modified to use features of your particular database.
The following paragraphs detail how Oracle implements the customization process. This information is not necessary for most SQLJ developers.
In the case of the Oracle customizer, the customize()
method creates a data structure that has one entry for each entry in the original profile. The original entries are never changed, but the new entries are customized to take advantage of features of Oracle9i. For example, if you are using BLOBs, a generic getObject()
call used to retrieve a BLOB in the original entry is replaced by a getBLOB()
call.
These new entries are encapsulated in an object of a customization class that implements the sqlj.runtime.profile.Customization
interface, and this customization object is installed into the profile object. (Customization objects, like profile objects, are serializable.)
The customizer harness then registers the customization, which is accomplished through functionality of the profile object. Registration allows a profile to keep track of the customizations that it contains.
Any errors encountered during customization are posted to the error log and reported by the customizer harness as appropriate.
A Customization
object has an acceptsConnection()
method called at runtime to determine if the customization can create a connected profile object for a given SQLJ connection context object. A connected profile object--an instance of a class that implements the sqlj.runtime.profile.ConnectedProfile
interface--represents a mapping between a profile object and a JDBC connection. It is equivalent to a JDBC Connection
object (underlying a SQLJ connection context object) with the ability to create statements, but supports additional vendor-specific functionality.
The customizer harness outputs error and status messages in much the same way as the SQLJ translator, outputting them to the same output device. None of the warnings regarding customization are suppressible, however. (See "Translator Error, Warning, and Information Messages".)
Error messages reported by the customizer harness fall into four categories:
Status messages reported by the customizer harness during customization allow you to determine whether a profile was successfully customized. They fall into three categories:
.jar
file modification status
backup
option is enabled)
Additional customizer-specific errors and warnings might be reported by the customize()
method of the particular customizer.
During customization, the profile customizer writes messages to its error log, and the customizer harness reads the log contents in real-time and outputs these messages to the SQLJ output device, along with any other harness output. You never need to access error log contents directly.
A customized profile is a static member of the connection context class with which it is associated. For each SQLJ statement in your application, the SQLJ runtime determines the connection context class and instance associated with that statement, then uses the customized profile of the connection context class, together with the underlying JDBC connection of the particular connection context instance, to create a connected profile. This connected profile is the vehicle that the SQLJ runtime uses in applying vendor-specific features to the execution of your SQLJ application.
The following paragraphs details how the Oracle SQLJ runtime uses customized profiles. This information is not necessary for most SQLJ developers.
In executing a SQLJ statement, the SQLJ runtime uses methods of the connection context object associated with the statement, and the profile object associated with the connection context class, as follows:
getConnectedProfile()
method.
getConnectedProfile()
method calls the getConnectedProfile()
method of the profile object associated with the connection context class, passing it a connection. (This is the connection instance underlying the connection context instance used for the SQL operation.)
getConnectedProfile()
method calls the acceptsConnection()
method of each Customization
object registered in the profile. The first Customization
object that accepts the connection creates the connected profile that is passed back to the runtime.
Throughout this manual there is discussion of the SQLJ runtime layer and SQLJ profiles. Oracle SQLJ, however, offers the alternative of generating Oracle JDBC code directly, instead of generating standard code that calls the SQLJ runtime for SQL operations (which in turn contains calls to Oracle JDBC). With Oracle-specific code generation, there are no profile files, and the role of the SQLJ runtime layer is greatly reduced during program execution.
Oracle-specific code supports all Oracle-specific extended features.
You can specify Oracle-specific code generation through the Oracle SQLJ translator -codegen=oracle
setting. (The default setting, -codegen=iso
, results in standard code generation.)
See "Code Generation (-codegen)" for information about syntax for this option.
The remainder of this section covers the following topics:
Oracle-specific code generation offers many advantages over standard SQLJ code generation:
.ser
) are produced. This is especially convenient if you are loading a translated application into the database or porting it to another system--there are fewer components.
None of this functionality holds true for standard generated code.
By comparison, there are relatively few disadvantages:
-debug
, -verify
, and -print
options. (These options are described in "Customizer Harness Options that Invoke Specialized Customizers". The AuditorInstaller
invoked by the -debug
option is described in "AuditorInstaller Customizer for Debugging".)
Be aware of the following requirements of your environment if you use Oracle-specific code generation:
runtime
and runtime-nonoracle
, are not supported for Oracle-specific code generation. You must have one of the following Oracle SQLJ runtime libraries in your classpath:
These runtime libraries are further discussed in "Requirements for Using Oracle SQLJ".
When coding a SQLJ application where Oracle-specific code generation will be used, be aware of the following programming considerations and restrictions:
stmtcache
option is unavailable. See "Translator/Customizer Usage Changes with Oracle-Specific Code Generation" immediately below.
However, if Oracle-specific code and standard code must share the same connection, do one of the following:
or:
This limitation regarding mixing code is especially significant for server-side code, because all Java code running in a given session uses the same JDBC connection and SQLJ connection context. (Also see "Server-Side Considerations with Oracle-Specific Code Generation".)
OUT
parameters, INOUT
parameters, SELECT INTO
variables, or return arguments on SQL statements.
For example, avoid statements such as the following:
#sql { SELECT * FROM EMP INTO :(x[i++]), :(f_with_sideffect()[i++]), :(a.b[i]) };
or:
#sql x[i++] = { VALUES f(:INOUT (x[i++]), :OUT (f_with_sideffect())) };
Evaluation of arguments is performed "in place" in the generated code. This may result in different behavior than when evaluation is according to standard SQLJ code generation.
java.sql.SQLData
interface, given that JPublisher-generated Java classes do not otherwise require a type map), then your iterator declarations and connection context declarations must specify the same type map(s). Specify this through the declaration with
clause.
For example, if you declare a connection context class as follows:
#sql context TypeMapContext with (typeMap="MyTypeMap");
and you populate an iterator instance from a SQLJ statement that uses an instance of this connection context class, as follows:
TypeMapContext tmc = new TypeMapContext(...); ... MyIterator it; #sql [tmc] it = ( SELECT pers, addr FROM tab WHERE ...);
then the iterator declaration is required to have specified the same type map, as follows:
#sql iterator MyIterator with (typeMap="MyTypeMap") (Person pers, Address addr);
For general information about with
clauses, see "Declaration WITH Clause".
Some options that were previously available only as Oracle customizer options are useful for Oracle-specific code generation as well. Because profile customization is not applicable with Oracle-specific code generation, these options have been made available through other means.
To alter the statement cache size or disable statement caching when generating Oracle-specific code, use method calls in your code instead of using the customizer stmtcache
option. The sqlj.runtime.ref.DefaultContext
class, as well as any connection context class you declare, now has the following static methods:
and the following instance methods:
By default, statement caching is enabled.
See "Connection Context Methods for Statement Cache Size" for more information. (This is a subsection under "Statement Caching", which provides an overview of statement caching.)
In addition, the following options are now available as front-end Oracle SQLJ translator options as well as Oracle customizer options:
-optcols
--Enable iterator column type and size definitions to optimize performance.
-optparams
--Enable parameter size definitions to optimize JDBC resource allocation (used in conjunction with optparamdefaults
).
-optparamdefaults
--Set parameter size defaults for particular datatypes (used in conjunction with optparams
).
See "Options for Code Generation, Column Optimizations, and Parameter Optimizations".
Be aware of the following:
-codegen=oracle
, you will receive an error.
-optcols
option only if you are using online semantics-checking (where you have used the SQLJ translator -user
, -password
, and -url
options appropriately to request a database connection during translation).
-optcols
, -optparams
, and -optparamdefaults
options, including default values, is the same as for the corresponding customizer options.
Note the following considerations if your SQLJ code will run in the server:
-codegen=iso
setting.
Therefore, to use Oracle-specific generated code in the server, you must translate and compile the SQLJ code on a client and then load the individual components into the server. (See "Translating SQLJ Source on a Client and Loading Components".)
ExecutionContext
object is shared by both the calling module and the called module. Therefore, both modules should be translated with the same -codegen
setting.
To ensure interoperability with existing code that has been translated with standard code generation, it is advisable for any code translated with Oracle-specific code generation for use in a Java stored procedure to instantiate and use its own execution context instance, as in the following example:
public static method() throws SQLException { Execution Context ec = new ExecutionContext(); ... #sql [ec] { SQL operation }; ... }
This section discusses options for profile customization, which fall into three categories:
This includes general options, connection options, and options that invoke specialized customizers.
All categories of options are specified through the SQLJ command line or properties files.
The following topics are included in this section:
To choose a customizer other than the default Oracle customizer, you can use either the customizer harness customizer
option (discussed in "Overview of Customizer Harness Options") or the SQLJ -default-customizer
option (discussed in "SQLJ Options for Profile Customization").
The customizer harness provided with Oracle SQLJ offers a number of options that are not specific to a particular customizer. The harness uses these options in its front-end coordination of the customization process.
Customizer harness option settings on the SQLJ command line have the following syntax:
-P-option=value
Or, in a SQLJ properties file:
profile.option=value
Enable boolean options (flags) either with:
-P-option
or:
-P-option=true
Boolean options are disabled by default, but you can explicitly disable them with:
-P-option=false
This option syntax is also discussed in "Options to Pass to the Profile Customizer (-P)" and "Properties File Syntax".
The customizer harness supports the following general options:
backup
--Save a backup copy of the profile before customizing it.
context
--Limit customizations to profiles associated with the listed connection context classes.
customizer
--Specify the customizer to use.
digests
--Specify digests for .jar
file manifests (relevant only if specifying .jar
files to customize).
help
--Display customizer options (specified in SQLJ command-line only).
verbose
--Display status messages during customization.
The customizer harness supports the following options for customizer database connections. Currently, these are used by the Oracle customizer if you enable its optcols
option for column definitions (for performance optimization). In addition, they are used by the SQLCheckerCustomizer
if you use this specialized customizer to perform online semantics-checking on profiles.
user
--Specify the user name for the connection used in this customization.
password
--Specify the password for the connection used in this customization.
url
--Specify the URL for the connection used in this customization.
driver
--Specify the JDBC driver for the connection used in this customization.
For information about the Oracle customizer optcols
flag, see "Oracle Customizer Column Definition Option (optcols)". For information about the SQLCheckerCustomizer
, see "SQLCheckerCustomizer for Profile Semantics-Checking".
The following commands function as customizer harness options, but are implemented through specialized customizers provided with Oracle SQLJ.
debug
--Insert debugging information into the specified profiles, to be output at runtime.
print
--Output the contents of the specified profiles, in text format.
verify
--Perform semantics-checking on a profile that was produced during a previous execution of the SQLJ translator (equivalent to semantics-checking performed on source code during translation). This is a shortcut to invoke SQLCheckerCustomizer
, which is described in "SQLCheckerCustomizer for Profile Semantics-Checking".
This section describes general options supported by the customizer harness.
Use the backup
flag to instruct the harness to save a backup copy of each .jar
file and standalone .ser
file before replacing the original. (Separate backups of .ser
files that are within .jar
files are not necessary.)
Backup file names are given the extension .bak
n
, where n
indicates digits used as necessary where there are similarly named files. For each backup file created, an informational message is issued.
If an error occurs during customization of a standalone .ser
file, then the original .ser
file is not replaced and no backup is created. Similarly, if an error occurs during customization of any .ser
file within a .jar
file, then the original .jar
file is not replaced and no backup is created.
-P-backup<=true/false>
-P-backup
profile.backup<=true/false>
profile.backup
false
Use the context
option to limit customizations to profiles that correspond to the specified connection context classes. Fully qualify the class names and use a comma-separated list to specify multiple classes. For example:
-P-context=sqlj.runtime.ref.DefaultContext,foo.bar.MyCtxtClass
There must be no space on either side of the comma.
If this option is not specified, then all profiles are customized, regardless of their associated connection context classes.
-P-context=ctx_class1<,ctx_class2,...>
-P-context=foo.bar.MyCtxtClass
profile.context=ctx_class1<,ctx_class2,...>
profile.context=foo.bar.MyCtxtClass
none (customize all profiles)
Use the customizer
option to specify which customizer to use. Fully qualify the class name, such as in the following example:
-P-customizer=oracle.sqlj.runtime.util.OraCustomizer
If you do not set this option, then SQLJ will use the customizer specified in the SQLJ -default-customizer
option. Unless set otherwise, this is the following:
oracle.sqlj.runtime.util.OraCustomizer
-P-customizer=customizer_class
-P-customizer=a.b.c.MyCustomizer
profile.customizer=customizer_class
profile.customizer=a.b.c.MyCustomizer
none (use default, set in SQLJ -default-customizer
option)
When a .jar
file is produced, the jar
utility can optionally include one or more digests for each entry, based on one or more specified algorithms, so that the integrity of the .jar
file entries can later be verified. Digests are similar conceptually to checksums, for readers familiar with those.
If you are customizing profiles in a .jar
file and want the jar
utility to add new digests (or update existing digests) when the .jar
file is updated, then use the digests
option to specify a comma-separated list of one or more algorithms. These are the algorithms that jar
will use in creating the digests for each entry. The jar
utility produces one digest for each algorithm for each .jar
file entry in the jar
manifest file. Specify algorithms as follows:
-P-digests=SHA,MD5
There must be no space on either side of the comma.
In this example, there will be two digests for each entry in the .jar
manifest file--an SHA
digest and an MD5
digest.
For information about .jar
files and the jar
utility, see the following Web site:
http://www.javasoft.com/products/jdk/1.1/docs/guide/jar/index.html
-P-digests=algo1<,algo2,...>
-P-digests=SHA,MD5
profile.digests=algo1<,algo2,...>
profile.digests=SHA,MD5
SHA,MD5
Use the help
option to display the option lists of the customizer harness and the default customizer or a specified customizer. For the harness and Oracle customizer, this includes a brief description and the current setting of each option.
Display the option lists for the harness and default customizer as follows (where the default customizer is the Oracle customizer or whatever you have specified in the SQLJ -default-customizer
option):
-P-help
Use the help
option in conjunction with the customizer
option to display the option list of a particular customizer, as follows:
-P-help -P-customizer=sqlj.runtime.profile.util.AuditorInstaller
-P-help <-P-customizer=customizer_class>
-P-help
n/a
n/a
none
Use the verbose
flag to instruct the harness to display status messages during customizations. These messages are written to the standard output device--wherever SQLJ writes its other messages.
-P-verbose<=true/false>
-P-verbose
profile.verbose<=true/false>
profile.verbose
none
This section describes connection options supported by the customizer harness. These are used as follows:
optcols
option, then there is no need to set the customizer harness user
, password
, url
, and driver
options.
SQLCheckerCustomizer
, a specialized customizer that performs semantics-checking on profiles, uses the customizer harness user
, password
, url
, and driver
settings for online checking.
Use -P-verify
on the SQLJ command line to invoke this customizer.
Set the user
option to specify a database schema if your customizer uses database connections.
In addition to specifying the schema, you can optionally specify the password, URL, or both in your user
option setting. The password is preceded by a forward-slash (/), and the URL is preceded by an "at" sign (@), as in the following examples:
-P-user=scott/tiger -P-user=scott@jdbc:oracle:oci:@ -P-user=scott/tiger@jdbc:oracle:oci:@
-P-user=username</password><@url>
-P-user=scott -P-user=scott/tiger -P-user=scott/tiger@jdbc:oracle:oci:@
profile.user=username</password><@url>
profile.user=scott profile.user=scott/tiger profile.user=scott/tiger@jdbc:oracle:oci:@
null
Use the password
option if your customizer uses database connections.
The password can also be set with the user
option, as described in "Customization User Option (user)".
-P-password=password
-P-password=tiger
profile.password=password
profile.password=tiger
null
Use the url
option if your customizer uses database connections.
The URL can also be set with the user
option, as described in "Customization User Option (user)".
-P-url=url
-P-url=jdbc:oracle:oci:@
profile.url=url
profile.url=jdbc:oracle:oci:@
jdbc:oracle:oci:@
Use the driver
option to register a comma-separated list of JDBC driver classes if your customizer uses database connections. For example:
-P-driver=sun.jdbc.odbc.JdbcOdbcDriver,oracle.jdbc.OracleDriver
There must be no space on either side of the comma.
-P-driver=dvr_class1<,dvr_class2,...>
-P-driver=sun.jdbc.odbc.JdbcOdbcDriver
profile.driver=dvr_class1<,dvr_class2,...>
profile.driver=sun.jdbc.odbc.JdbcOdbcDriver
oracle.jdbc.OracleDriver
The customizer harness supports the following options that invoke specialized customizers:
debug
--This invokes the AuditorInstaller
customizer, used in debugging.
print
--This invokes a customizer that prints a text version of a profile.
verify
--This invokes the SQLCheckerCustomizer
customizer, which performs semantics-checking on a profile.
The debug
option runs a specialized customizer, called the AuditorInstaller
, that inserts debugging statements into profiles. Use this option in conjunction with a SQLJ command line file list to insert debugging statements into the specified profiles. These profiles must already be customized from a previous SQLJ run.
For detailed information about this customizer, including additional options that it supports, see "AuditorInstaller Customizer for Debugging".
The debugging statements will execute during SQLJ runtime (when someone runs your application), displaying a trace of method calls and values returned.
Following are examples of how to specify the debug
option:
sqlj -P-debug Foo_SJProfile0.ser Bar_SJProfile0.ser sqlj -P-debug *.ser
sqlj -P-debug profile_list
sqlj -P-debug Foo_SJProfile*.ser
profile.debug
(Also specify profiles in the SQLJ file list.)
profile.debug
n/a
The print
option runs a specialized customizer that prints profiles in text format. Use this option in conjunction with a SQLJ command line file list to output the contents of one or more specified profiles. The output goes to the standard SQLJ output device, typically the user screen.
Following are examples of how to specify the print
option:
sqlj -P-print Foo_SJProfile0.ser Bar_SJProfile0.ser sqlj -P-print *.ser
For sample output, see "Sample Profile Entry".
sqlj -P-print profile_list
sqlj -P-print Foo_SJProfile*.ser
profile.print
(Also specify profiles in SQLJ file list.)
profile.print
n/a
The verify
option runs a specialized customizer, called the SQLCheckerCustomizer
, that performs semantics-checking on a profile. This is equivalent to the semantics-checking that is performed on source code during translation. The profile will have been created during a previous execution of the SQLJ translator.
This option is useful for checking semantics against the runtime database, after deployment, and after the source code may no longer be available.
For detailed information about this customizer, including additional options that it supports, see "SQLCheckerCustomizer for Profile Semantics-Checking".
Following are examples of how to specify the verify
option. Both of these examples use the SQLCheckerCustomizer
default semantics-checker, which employs online checking through the specified database connection.
sqlj -P-verify -P-user=scott -P-password=tiger -P-url=jdbc:oracle:oci:@ Foo_SJProfile0.ser Bar_SJProfile0.ser
(The preceding is a single wrap-around command line.)
sqlj -P-verify -P-user=scott -P-password=tiger -P-url=jdbc:oracle:oci:@ *.ser
sqlj -P-verify <conn params> profile_list
sqlj -P-verify <conn params> Foo_SJProfile*.ser
profile.verify
(You must also specify profiles, and typically customizer harness connection options, in the SQLJ command line.)
profile.verify
n/a
You can set customizer-specific options, such as options for the Oracle customizer, on the SQLJ command line or in a SQLJ properties file. The syntax is similar to that for setting customizer harness options.
Set a customizer option on the SQLJ command line by preceding it with:
-P-C
Or set it in a SQLJ properties file by preceding it with:
profile.C
This option syntax is also discussed in "Options to Pass to the Profile Customizer (-P)" and "Properties File Syntax".
The remainder of this section discusses features of the Oracle customizer, which supports several options.
Most of these options are boolean and are enabled as follows:
-P-Coption
or:
-P-Coption=true
Boolean options are disabled by default, but you can explicitly disable them with:
-P-Coption=false
Numeric or string options are set similarly:
-P-Coption=value
This section describes options that are specific to the Oracle customizer, beginning with an overview of the options supported.
The Oracle customizer implements the following options:
compat
--Display version compatibility information.
force
--Instruct the customizer to customize even if a valid customization already exists.
optcols
--Enable iterator column type and size definitions to optimize performance.
optparams
--Enable parameter size definitions to optimize JDBC resource allocation (used in conjunction with optparamdefaults
).
optparamdefaults
--Set parameter size defaults for particular datatypes (used in conjunction with optparams
).
showSQL
--Display SQL statement transformations.
stmtcache
--Set the statement cache size (the number of statements that can be cached for each connection during runtime) for performance optimization, or set it to zero to disable statement caching.
summary
--Display a summary of Oracle features used in your application.
Any output displayed by these options is written to the standard output device, wherever SQLJ writes its other messages.
Use the compat
flag to instruct the Oracle customizer to display information about compatibility of your application with different versions of the Oracle database and Oracle JDBC drivers. This can be accomplished either during a full SQLJ translation run or on profiles previously created.
To see compatibility output when translating and customizing the application MyApp
:
sqlj <...SQLJ options...> -P-Ccompat MyApp.sqlj
In this example, the MyApp
profiles will be created, customized, and checked for compatibility in a single running of SQLJ.
To see compatibility output for MyApp
profiles previously created:
sqlj <...SQLJ options...> -P-Ccompat MyApp_SJProfile*.ser
In this example, the MyApp
profiles were created (and possibly customized) in a previous running of SQLJ and will be customized (if needed) and checked for compatibility in the above running of SQLJ.
Following are two output samples from a -P-Ccompat
setting when using the default Oracle customizer. The first example indicates that the application can be used with all Oracle JDBC driver versions:
MyApp_SJProfile0.ser: Info: compatible with all Oracle JDBC drivers
This second example indicates that the application can be used only with 8.1 or later Oracle JDBC driver versions:
MyApp_SJProfile0.ser: Info: compatible with Oracle 8.1 or later JDBC driver
-P-Ccompat<=true/false>
-P-Ccompat
profile.Ccompat<=true/false>
profile.Ccompat
false
Use the force
flag to instruct the Oracle customizer to force the customization of a given profile (specified on the command line) even if a valid customization already exists in that profile. For example:
sqlj -P-Cforce MyApp_SJProfile*.ser
This will customize all the MyApp
profiles, regardless of whether they have already been customized. Otherwise, by default, the Oracle customizer will not reinstall over a previously existing customization unless the previous one had been installed with an older version of the customizer.
-P-Cforce<=true/false>
-P-Cforce
profile.Cforce<=true/false>
profile.Cforce
false
Use the optcols
flag to instruct the Oracle customizer to determine types and sizes of iterator or result set columns and add this information to the profile. This enables the SQLJ runtime to automatically register the columns with the Oracle JDBC driver when your application runs, saving round trips to Oracle depending on the particular driver implementation. Specifically, this is effective for the Thin driver and positional iterators.
For an overview of column definitions, see "Column Definitions".
Note:
For Oracle-specific code generation, where profile customization is not applicable, use the SQLJ translator That section also has some additional conceptual information. |
You can enable or disable the customizer optcols
flag on the SQLJ command line or in a properties file.
Enable it on the command line as follows:
-P-Coptcols
or:
-P-Coptcols=true
This flag is disabled by default, but you can also disable it explicitly. Disable it on the command line as follows:
-P-Coptcols=false
Column definitions require the customizer to make a database connection to examine columns of tables being queried, so the customizer harness user
, password
, and url
options must be set appropriately (as well as the customizer harness driver
option if you are not using the default OracleDriver
class). For example:
sqlj <...SQLJ options...> -P-user=scott/tiger@jdbc:oracle:oci:@ -P-Coptcols MyApp.sqlj
(Note that as with the SQLJ translator, you can optionally set the password and URL in the user
option instead of in the password
and url
options.)
Or you can insert column definitions into a previously existing profile (in this case you must also use the Oracle customizer force
option to force a recustomization):
sqlj -P-user=scott/tiger@jdbc:oracle:oci:@ -P-Cforce -P-Coptcols MyApp_SJProfile*.ser
Or you can insert column definitions into previously existing profiles in a .jar
file:
sqlj -P-user=scott/tiger@jdbc:oracle:oci:@ -P-Cforce -P-Coptcols MyAppProfiles.jar
When you run the Oracle customizer with its optcols
flag enabled (either during translation and creation of a new profile or during customization of an existing profile), you can also enable the customizer harness verbose
flag. This will instruct the Oracle customizer to display information about what iterators and result sets are being processed and what their column type and size definitions are. For example:
sqlj -P-user=scott/tiger@jdbc:oracle:oci:@ -P-verbose -P-Cforce -P-Coptcols MyApp_SJProfile*.ser
For general information about the verbose
flag, see that section under "Overview of Customizer Harness Options".
You can execute the Oracle customizer with its summary
flag enabled on an existing profile to determine if column definitions have been added to that profile:
sqlj -P-Csummary MyApp_SJProfile*.ser
For general information about the summary
flag, see that section under "Overview of Customizer-Specific Options".
Note:
An error will be generated if you enable the Oracle customizer The customizer does not have to connect to the same schema or even the same database that your application will connect to at runtime, but the relevant columns will have to be in the same order and of identical types and sizes to avoid runtime errors.
For information about the customizer harness connection options, see the |
-P-Coptcols<=true/false>
-P-Coptcols
profile.Coptcols<=true/false>
profile.Coptcols
false
Use the optparams
flag to enable parameter size definitions. If this flag is enabled, SQLJ will register your input and output parameters (host variables) to optimize JDBC resource allocations according to sizes you specify.
For an overview of parameter size definitions and a discussion of source code hints, see "Parameter Size Definitions".
Note:
For Oracle-specific code generation, where profile customization is not applicable, use the SQLJ translator That section also has some additional conceptual information. |
You can enable or disable the optparams
flag on the command line or in a SQLJ properties file.
Enable it on the command line as follows:
-P-Coptparams
or:
-P-Coptparams=true
This flag is disabled by default, but you can also disable it explicitly. Disable it on the command line as follows:
-P-Coptparams=false
Following is a command-line example (omitting a setting for the optparamdefaults
option, which is discussed in the next section):
sqlj <...SQLJ options...> -P-Coptparams -P-Coptparamdefaults=defaults-string MyApp.sqlj
Or you can enable parameter size definitions for a previously existing profile, as in the next example.
sqlj -P-Coptparams -P-Coptparamdefaults=defaults-string MyApp_SJProfile*.ser
Or for previously existing profiles in a .jar
file:
sqlj -P-Coptparams -P-Coptparamdefaults=defaults-string MyAppProfiles.jar
-P-Coptparams<=true/false>
-P-Coptparams
profile.Coptparams<=true/false>
profile.Coptparams
false
If you enable the optparams
option to set parameter sizes, use the optparamdefaults
option as desired to set default sizes for specified datatypes. If optparams
is not enabled, then any optparamdefaults
setting is ignored.
For an overview of parameter size definitions and a discussion of source code hints, see "Parameter Size Definitions".
Note:
For Oracle-specific code generation, where profile customization is not applicable, use the SQLJ translator That section also has important additional conceptual and syntax information. Functionality of the two options is equivalent. |
You can set the optparamdefaults
flag on the command line or in a SQLJ properties file.
Set it on the command line as follows:
-P-Coptparamdefaults=datatype1(size1),datatype2(size2),...
Following is a command-line example, including the optparams
setting as well:
sqlj <...SQLJ options...> -P-Coptparams -P-Coptparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyApp.sqlj
The syntax is explained in "Parameter Default Size (-optparamdefaults)".
Or you can specify parameter size defaults for a previously existing profile (in which case you must also use the Oracle customizer force
option to force a recustomization):
sqlj -P-Cforce -P-Coptparams -P-Coptparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyApp_SJProfile*.ser
Or you can specify parameter size defaults for previously existing profiles in a .jar
file:
sqlj -P-Cforce -P-Coptparams -P-Coptparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyAppProfiles.jar
-P-Coptparamdefaults=defaults-string
-P-Coptparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()
profile.Coptparamdefaults=defaults-string
profile.Coptparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()
null
Use the showSQL
flag to display any SQL statement transformations performed by the Oracle customizer. Such transformations are necessary in cases where SQLJ supports syntax that Oracle9i does not.
To show SQL transformations when translating and customizing the application MyApp
:
sqlj <...SQLJ options...> -P-CshowSQL MyApp.sqlj
In this example, the MyApp
profiles will be created and customized and their SQL transformations displayed in a single running of SQLJ.
To show SQL transformations when customizing MyApp
profiles previously created:
sqlj <...SQLJ options...> -P-CshowSQL MyApp_SJProfile*.ser
In this example, the MyApp
profiles were created (and possibly customized) in a previous running of SQLJ and will be customized (if needed) and have their SQL transformations displayed in the above running of SQLJ.
The showSQL
output might include an entry such as this:
MyApp.sqlj:14: Info: <<<NEW SQL>>> #sql {BEGIN ? := VALUES(tkjsSET_f1); END}; in file MyApp, line 14, we had:#sql {set :v1= VALUES(tkjsSET_f1) };
SQLJ supports the SET
statement, but Oracle9i does not. During customization, the Oracle customizer replaces the SET
statement with an equivalent PL/SQL block.
-P-CshowSQL<=true/false>
-P-CshowSQL
profile.CshowSQL<=true/false>
profile.CshowSQL
false
Use the Oracle customizer stmtcache
option to set the statement cache size--the number of statements that can be cached for each database connection as your application runs--or to disable statement caching.
The default statement cache size is 5. For an overview of statement caching, see "Statement Caching".
Important:
If you use Oracle-specific code generation, through the SQLJ translator |
You can set the statement cache size on the command line or in a properties file.
To use the command line to set the statement cache size to 15 (for example) for the application MyApp
:
sqlj <...SQLJ options...> -P-Cstmtcache=15 MyApp.sqlj
To disable statement caching, set the cache size to 0:
sqlj <...SQLJ options...> -P-Cstmtcache=0 MyApp.sqlj
You can also alter the statement cache size in an existing profile, without re-translating the application (but you must also use the Oracle customizer force
option to force a recustomization):
sqlj -P-Cforce -P-Cstmtcache=15 MyApp_SJProfile0.ser
If you have multiple profiles, you can set their statement cache sizes individually by running SQLJ separately for each profile, after you have translated your application:
sqlj -P-Cforce -P-Cstmtcache=10 MyApp_SJProfile0.ser sqlj -P-Cforce -P-Cstmtcache=15 MyApp_SJProfile1.ser sqlj -P-Cforce -P-Cstmtcache=0 MyApp_SJProfile2.ser
Of course, you must determine which profile corresponds to each of your connection context classes. This is determined as follows: Profile 0 will correspond to the connection context class used for the first executable statement in your application; Profile 1 will correspond to the connection context class used for the first executable statement that does not use the first connection context class, and so on. You can verify the correlation by using the customizer harness print
option to examine each profile.
-P-Cstmtcache=value
-P-Cstmtcache=10
profile.Cstmtcache=value
profile.Cstmtcache=10
5
Use the summary
flag to instruct the Oracle customizer to display a summary of Oracle features used in an application being translated, or in specified profile files. This is useful in identifying features that would prevent portability to other platforms and can be accomplished either during a full SQLJ translation run or on profiles previously created.
To see summary output when translating and customizing the application MyApp
:
sqlj <...SQLJ options...> -P-Csummary MyApp.sqlj
In this example, the MyApp
profiles will be created, customized, and summarized in a single running of SQLJ.
To see summary output for MyApp
profiles previously created:
sqlj <...SQLJ options...> -P-Csummary MyApp_SJProfile*.ser
In this example, the MyApp
profiles were created (and possibly customized) in a previous running of SQLJ and will be customized (if needed) and summarized in the above running of SQLJ.
Following are two samples resulting from a -P-Csummary
setting when using the default Oracle customizer. The first example indicates no Oracle features are used:
MyApp_SJProfile0.ser: Info: Oracle features used: MyApp_SJProfile0.ser: Info: * none
This second example indicates that Oracle features are used--namely, several Oracle extended datatypes from the oracle.sql
package--and lists them:
MyApp_SJProfile0.ser: Info: Oracle features used: MyApp_SJProfile0.ser: Info: * oracle.sql.NUMBER: 2 MyApp_SJProfile0.ser: Info: * oracle.sql.DATE: 2 MyApp_SJProfile0.ser: Info: * oracle.sql.CHAR: 2 MyApp_SJProfile0.ser: Info: * oracle.sql.RAW: 2
-P-Csummary<=true/false>
-P-Csummary
profile.Csummary<=true/false>
profile.Csummary
false
Oracle SQLJ provides additional, specialized customizers described elsewhere in this manual, and these customizers also have command-line options:
SQLCheckerCustomizer
(for profile semantics-checking)--See "SQLCheckerCustomizer for Profile Semantics-Checking" for general information, and "SQLCheckerCustomizer Options" for information about its options.
AuditorInstaller
(for debugging)--See "AuditorInstaller Customizer for Debugging" for general information, and "AuditorInstaller Options" for information about its options.
The following SQLJ options relate to profile customization and are described elsewhere in this manual:
-default-customizer
--Specify the default profile customizer to use if none is specified in the customizer harness -customizer
option.
-profile
--Specify whether to customize during this running of SQLJ.
As discussed previously, you can specify a .jar
file on the SQLJ command line in order to customize any profiles that the .jar
file contains.
When using a .jar
file for profiles, the manifest entry for each profile must contain the line:
SQLJProfile: TRUE
Accomplish this by: 1) creating a plain text file with two lines for each profile that will be included in the .jar
file--one line specifying the path or package and name, and one line as above; and 2) using the jar
utility -m
option to input this file.
The two lines must be consecutive (no blank line in between), and there must be a blank line preceding line-pairs for additional profiles.
For example, presume your MyApp
application (in the directory foo/bar
) has three profiles, and you will be creating a .jar
file that will include these profiles.
In this case, complete the following steps:
Name: foo/bar/MyApp_SJProfile0.ser SQLJProfile: TRUE Name: foo/bar/MyApp_SJProfile1.ser SQLJProfile: TRUE Name: foo/bar/MyApp_SJProfile2.ser SQLJProfile: TRUE
Presume you call this file MyAppJarEntries.txt
jar
to create the .jar
file, use the -m
option to input your text file as follows (presume you want to call the .jar
file myjarfile.jar
):
jar -cvfm myjarfile.jar MyAppJarEntries.txt foo/bar/MyApp_SJProfile*.ser foo/bar/*.class
As the jar
utility constructs the manifest during creation of the .jar
file, it reads your text file and inserts the SQLJProfile: TRUE
line into the manifest entry of each profile. It accomplishes this by matching the names in the manifest with the names you specify in your text file.
When you specify a .jar
file on the SQLJ command line, each profile in the .jar
file is deserialized and customized.
A .jar
file is successfully customized only if all the profiles it contains are successfully customized. After a successful customization, each profile has been reserialized into a .ser
file, the .jar
file has been modified to replace the original .ser
files with the customized .ser
files, and the .jar
file manifest has been updated to indicate the new entries.
If any error is encountered in the customization of any profile in a .jar
file, then the .jar
file customization has failed, and the original .jar
file is left unchanged.
Oracle provides a special customizer, SQLCheckerCustomizer
, that will perform semantics-checking on a profile that was produced during previous execution of the translator. This semantics-checking is similar to what is normally performed during translation of the source code.
This is particularly useful when the database to be used at runtime differs from what was available to use for semantics-checking during translation. In these circumstances, you can use SQLCheckerCustomizer
after deployment, against the runtime database, typically in a scenario where the source code is no longer available.
You can specify the checker to use. If you accept the default OracleChecker
front end, SQLCheckerCustomizer
will perform online semantics-checking using an appropriate online checker.
Following are examples of how to specify the Oracle customizer harness verify
option to run SQLCheckerCustomizer
in its default mode. Because it defaults to an online checker, you typically must provide connection parameters through the customizer harness user
, password
, and url
options. (The first example is a single wrap-around command line.)
sqlj -P-verify -P-user=scott -P-password=tiger -P-url=jdbc:oracle:oci:@ Foo_SJProfile0.ser Bar_SJProfile0.ser sqlj -P-verify -P-user=scott -P-password=tiger -P-url=jdbc:oracle:oci:@ *.ser
The verify
option results in the customizer harness instantiating and invoking the following class:
sqlj.runtime.profile.util.SQLCheckerCustomizer
This class coordinates semantics-checking of the SQL operations in the profile. You can specify a semantics-checker or accept the default OracleChecker
semantics-checker front end.
The -P-verify
option is equivalent to the following:
-P-customizer=sqlj.runtime.profile.util.SQLCheckerCustomizer
This overrides the customizer specified in the SQLJ -default-customizer
option.
sqlj -P-verify <conn params> profile_list
sqlj -P-verify <conn params> Foo_SJProfile*.ser
profile.verify
(You must also specify profiles, and typically customizer harness connection options, in the SQLJ command line.)
profile.verify
n/a
Like any customizer, SQLCheckerCustomizer
has its own options, which can be set using the -P-C
prefix on the SQLJ command line (or profile.C
, instead of -P-C
, in a SQLJ properties file).
SQLCheckerCustomizer
supports the following options:
checker
--Specify the semantics-checker to use. The default is the OracleChecker
front end, as for checking during SQLJ translation.
warn
--Specify the categories of warnings and messages to display during semantics-checking of the profile. This is equivalent to the SQLJ -warn
flag for warning categories during translation-time semantics-checking, supports the same settings, and uses the same defaults. See "Translator Warnings (-warn)".
The checker
option allows you to specify the semantics-checker to use in checking the SQL operations in a profile.
This defaults to the Oracle semantics-checker front end, oracle.sqlj.checker.OracleChecker
, which for SQLCheckerCustomizer
chooses an appropriate online checker for your environment. For more information about OracleChecker
, see "Semantics-Checkers and the OracleChecker Front End (default checker)".
Following is a full command-line example, showing how to use the SQLCheckerCustomizer
checker
option, in conjunction with the customizer harness verify
option and connection options.
sqlj -P-verify -P-user=scott -P-password=tiger -P-url=jdbc:oracle:oci:@ -P-Cchecker=abc.def.MyChecker *.ser
(This is a single wrap-around command line.)
-P-Cchecker=checker_class
-P-Cchecker=a.b.c.MyChecker
profile.Cchecker=checker_class
profile.Cchecker=a.b.c.MyChecker
oracle.sqlj.checker.OracleChecker
The warn
option is equivalent to the SQLJ translator -warn
option, allowing you to choose the categories of warnings and messages to be displayed as semantics-checking is performed on a profile.
For a complete description of the functionality and possible settings of these options, see "Translator Warnings (-warn)".
This defaults to the all,noverbose,noportable
settings, resulting in all warning categories except verbose
and portable
being enabled. You will receive any warnings regarding inheritance hierarchy requirements, data precision, conversion loss for nullable data, and strict matching for named iterators. These are the same defaults as for warnings during SQLJ translation.
Following is a full command-line example showing how to use the SQLCheckerCustomizer
warn
option, in conjunction with the customizer harness verify
option and connection options. This would result in only portability warnings being displayed.
sqlj -P-verify -P-user=scott -P-password=tiger -P-url=jdbc:oracle:oci:@ -P-Cwarn=none,portable *.ser
(This is a single wrap-around command line.)
-P-Cwarn=comma-separated_list_of_flags
-P-Cwarn=none,verbose
profile.Cwarn=comma-separated_list_of_flags
profile.Cwarn=none,verbose
all,noverbose,noportable
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|