Profiles and Customization

Customization Options and Choosing a Customizer

This section discusses options for profile customization, which fall into three categories:

general options you specify to the customizer harness, which apply regardless of which customizer you use
customizer-specific options you specify to your customizer through the customizer harness
SQLJ options, which determine basic aspects of customization, such as whether to customize at all and which customizer to use

All categories of options are specified through the SQLJ command line or properties files.

To choose a customizer other than the default Oracle customizer, you can use either the customizer harness -customizer option (discussed in "General Customizer Harness Options"), or the SQLJ -default-customizer option (discussed in "SQLJ Options for Profile Customization").

General Customizer Harness Options

The customizer harness provided with Oracle SQLJ offers several general options for your customizations. These apply regardless of the particular customizer you are using.

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 Profile Customizer (-P)" and "Properties File Syntax".

The customizer harness supports the following 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 (only relevant if specifying .jar files to customize).
-help--Display customizer options (SQLJ command-line-only).
-verbose--Display status messages during customization.

The following options, related to database connections for customization, are supported by the customizer harness but are not used by the Oracle customizer:

-user--Specify the username 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.

In addition, the following commands function as customizer harness options but are implemented through specialized customizers provided with Oracle SQLJ.

-print--Output the contents of the specified profiles, in text format.
-debug--Insert debugging information into the specified profiles, to be output at runtime.

Backup Option (-backup)

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

Command-line syntax

-P-backup<=true/false>

Command-line example

-P-backup

Properties file syntax

profile.backup<=true/false>

Properties file example

profile.backup

Default value

false

Connection Context Option (-context)

Use the -context option to limit customizations to profiles that correspond to the specified connection context classes. Fully specify the classes and use a comma-separated list to specify multiple classes. For example:

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

Command-line syntax

-P-context=ctx_class1<,ctx_class2,...>

Command-line example

-P-context=foo.bar.MyCtxtClass

Properties file syntax

profile.context=ctx_class1<,ctx_class2,...>

Properties file example

profile.context=foo.bar.MyCtxtClass

Default value

none (customize all profiles)

Customizer Option (-customizer)

Use the -customizer option to specify which customizer to use. Fully specify the class name, such as in the following example:

-P-customizer=sqlj.runtime.profile.util.AuditorInstaller

Note:
If you do not set this option, then SQLJ will use the customizer specified in the SQLJ -default-customizer option.

Command-line syntax

-P-customizer=customizer_class

Command-line example

-P-customizer=a.b.c.MyCustomizer

Properties file syntax

profile.customizer=customizer_class

Properties file example

profile.customizer=a.b.c.MyCustomizer

Default value

oracle.sqlj.runtime.util.OraCustomizer

.jar File Digests Option (-digests)

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

Command-line syntax

-P-digests=algo1<,algo2,...>

Command-line example

-P-digests=SHA,MD5

Properties file syntax

profile.digests=algo1<,algo2,...>

Properties file example

profile.digests=SHA,MD5

Default value

SHA,MD5

Help Option (-help)

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

Notes:

You can use the -P-help option on the SQLJ command line only, not in a SQLJ properties file.

No customizations are done if the -P-help flag is enabled, even if you specify profiles to customize on the command line.

Command-line syntax

-P-help <-P-customizer=customizer_class>

Command-line example

-P-help

Properties file syntax

n/a

Properties file example

n/a

Default value

none

Verbose Option (-verbose)

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.

Command-line syntax

-P-verbose<=true/false>

Command-line example

-P-verbose

Properties file syntax

profile.verbose<=true/false>

Properties file example

profile.verbose

Default value

none

User Option (-user)

Set the -user option to specify a user schema if your customizer uses database connections.

Note:
The Oracle customizer does not currently use database connections.

In addition to specifying the schema, you can optionally specify the password or 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:

-user=scott/tiger
-user=scott@jdbc:oracle:oci8:@
-user=scott/tiger@jdbc:oracle:oci8:@

Command-line syntax

-P-user=username</password><@url>

Command-line examples


     
-P-user=scott
-P-user=scott/tiger
-P-user=scott/tiger@jdbc:oracle:oci8:@

Properties file syntax

profile.user=username</password><@url>

Properties file examples


     
profile.user=scott
profile.user=scott/tiger
profile.user=scott/tiger@jdbc:oracle:oci8:@

Default value

null

Password Option (-password)

Use the -password option if your customizer uses database connections.

Note:
The Oracle customizer does not currently use database connections.

The password can also be set with the -user option, as described in "User Option (-user)".

Command-line syntax

-P-password=password

Command-line example

-P-password=tiger

Properties file syntax

profile.password=password

Properties file example

profile.password=tiger

Default value

null

URL Option (-url)

Use the -url option if your customizer uses database connections.

Note:
The Oracle customizer does not currently use database connections.

The URL can also be set with the -user option, as described in "User Option (-user)".

Command-line syntax

-P-url=url

Command-line example

-P-url=jdbc:oracle:oci8:@

Properties file syntax

profile.url=url

Properties file example

profile.url=jdbc:oracle:oci8:@

Default value

jdbc:oracle:oci8:@

JDBC Driver Option (-driver)

Use the -driver option to register a comma-separated list of JDBC drivers if your customizer uses database connections. For example:

-P-driver=sun.jdbc.odbc.JdbcOdbcDriver,oracle.jdbc.driver.OracleDriver

There must be no space on either side of the comma.

Note:
The Oracle customizer does not currently use database connections.

Command-line syntax

-P-driver=dvr_class1<,dvr_class2,...>

Command-line example

-P-driver=sun.jdbc.odbc.JdbcOdbcDriver

Properties file syntax

profile.driver=dvr_class1<,dvr_class2,...>

Properties file example

profile.driver=sun.jdbc.odbc.JdbcOdbcDriver

Default value

oracle.jdbc.driver.OracleDriver

Profile Print Option (specialized customizer) (-print)

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

The result of the -print option is that the customizer harness invokes a special print customizer that converts the profile information to text format and outputs the results.

For an example of what this output looks like, see "Sample Profile Entry".

Note:
Because the -print option invokes a customizer and only one customizer can run in a single execution of SQLJ, you cannot do any other customization when you use this option.
You also cannot use -P-print and -P-debug at the same time, because the -debug option also invokes a special customizer.

Command-line syntax

sqlj -P-print profile_list

Command-line example

sqlj -P-print Foo_SJProfile*.ser

Properties file syntax

profile.print (must also specify profiles in file list)

Properties file example

profile.print (must also specify profiles in file list)

Default value

n/a

Profile Debug Option (specialized customizer) (-debug)

The -debug option runs a specialized customizer 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.

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

The result of the -debug option is that the customizer harness invokes a special debug customizer to install the debugging statements into the profiles.

For more information about the -debug option, including additional options provided by the debug customizer, see "AuditorInstaller Customizer for Debugging".

Note:
Because the -debug option invokes a customizer and only one customizer can run in a single execution of SQLJ, you cannot do any other customization when you use this option.
You also cannot use -P-print and -P-debug at the same time, because the -print option also invokes a special customizer.

Command-line syntax

sqlj -P-debug profile_list

Command-line example

sqlj -P-debug Foo_SJProfile*.ser

Properties file syntax

profile.debug (must also specify profiles in file list)

Properties file example

profile.debug (must also specify profiles in file list)

Default value

n/a

Customizer-Specific Options (Oracle Customizer)

In addition to setting customizer harness options, you can use the SQLJ command line to specify option settings for the particular customizer you are using.

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 Profile Customizer (-P)" and "Properties File Syntax".

The remainder of this section discusses features of the Oracle customizer, which supports several boolean options. Enable these options (flags) with:

-P-Coption

or:

-P-Coption=true

Boolean options are disabled by default but you can explicitly disable them with:

-P-Coption=false

The Oracle customizer supports the following options:

-compat--Display version compatibility information.
-force--Instruct the customizer to customize even if a valid customization already exists.
-showSQL--Display SQL statement transformations.
-summary--Display a summary of Oracle features used in your application.

To use these options, you must be using the default Oracle customizer (in other words, no other customizer is specified in the SQLJ -default-customizer setting or the customizer harness -customizer setting, and you are not using -print or -debug).

Any output displayed by these options is written to the standard output device, wherever SQLJ writes its other messages.

Oracle Customizer Version Compatibility Option (-compat)

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 samples resulting from a -P-Ccompat setting when using the default Oracle customizer.

Example 1

The application can be used with all Oracle JDBC driver versions:

MyApp_SJProfile0.ser: Info: compatible with all Oracle JDBC drivers

Example 2

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

Note:
If customization does not take place because a valid previous customization is detected, the -compat option reports compatibility regardless.

Command-line syntax

-P-Ccompat<=true/false>

Command-line example

-P-Ccompat

Properties file syntax

profile.Ccompat<=true/false>

Properties file example

profile.Ccompat

Default value

false

Oracle Customizer Force Option (-force)

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 of the MyApp profiles, whether or not 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.

Command-line syntax

-P-Cforce<=true/false>

Command-line example

-P-Cforce

Properties file syntax

profile.Cforce<=true/false>

Properties file example

profile.Cforce

Default value

false

Oracle Customizer Show-SQL Option (-showSQL)

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 Oracle8i 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 Oracle8i does not. During customization, the Oracle customizer replaces the SET statement with an equivalent PL/SQL block.

Note:
If customization does not take place because a valid previous customization is detected, the -showSQL option shows SQL transformations regardless.

Command-line syntax

-P-CshowSQL<=true/false>

Command-line example

-P-CshowSQL

Properties file syntax

profile.CshowSQL<=true/false>

Properties file example

profile.CshowSQL

Default value

false

Oracle Customizer Summary Option (-summary)

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.

Example 1

No Oracle features used:

MyApp_SJProfile0.ser: Info: Oracle features used: 
MyApp_SJProfile0.ser: Info: * none

Example 2

Oracle features used:

MyApp_SJProfile0.ser: Info: Oracle features used: 
MyApp_SJProfile0.ser: Info: * oracle.sql.NUMBER: 2 
MyApp_SJProfile0.ser: Info: * oracle.sql.RAW: 2

In this second sample, the application uses Oracle extended datatypes from the oracle.sql package.

Note:
If customization does not take place because a valid previous customization is detected, the -summary option produces a summary regardless.

Command-line syntax

-P-Csummary<=true/false>

Command-line example

-P-Csummary

Properties file syntax

profile.Csummary<=true/false>

Properties file example

profile.Csummary

Default value

false

SQLJ Options for Profile Customization

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.

See "Default Profile Customizer (-default-customizer)".
-profile--Specify whether to customize during this running of SQLJ.

See "Profile Customization Flag (-profile)".