Oracle8i Java Tools Reference Release 3 (8.1.7) Part Number A83727-01 |
|
The Java language was designed for a platform-independent, secure development model. To accomplish these goals, some execution performance was sacrificed. Translating Java bytecodes into machine instructions degrades performance. To regain some of the performance loss, you may choose to natively compile certain classes. For example, you may decide to natively compile code with CPU intensive classes.
Without native compilation, the Java code you load to the server is interpreted and the underlying core classes upon which your code relies (java.lang.*
) are natively compiled.
Native compilation provides a speed increase ranging from two to ten times the speed of the bytecode interpretation. The exact speed increase is dependent on several factors, including:
Because Java bytecodes were designed to be compact, natively compiled code can be considerably larger than the original bytecode. However, because the native code is stored in a shared library, it is shared among all users of the database.
Most JVMs use Just-In-Time compilers that convert the Java bytecodes to native machine instructions when methods are invoked. The JServer Accelerator uses an Ahead-Of-Time approach to recompiling the Java classes.
This static compilation approach provides a large, consistent performance gain, regardless of the number of users or the code paths they traverse on the server. After compilation, the tool loads the statically compiled libraries into JServer, which are then shared between users, processes, and sessions.
Most Ahead-Of-Time native compilers compile directly into a platform-dependent language. For portability requirements, this was not feasible. As shown in Figure 1-1, the JServer Accelerator translates the Java classes into a version of C that is platform-independent. This C code is compiled and linked to supply the final platform-dependent, natively compiled shared libraries or DLLs.
Given a JAR file, the JServer Accelerator performs the following:
JServer Accelerator translates, compiles, and links the retrieved classes on the client. For this reason, you must natively compile on the intended platform environment that this application will be deployed to. The result is a single deployment JAR file for all classes within the project.
$ORACLE_HOME/javavm/admin
directory.
All core Java class libraries and Oracle-provided Java code within JServer is natively compiled for greater execution speed. Java classes exist as shared libraries in $ORACLE_HOME/javavm/admin
, where each shared library corresponds to a Java package. For example, orajox8java_lang.so
on Solaris and orajox8java_lang.dll
on Windows NT hold java.lang
classes. Specifics of packaging and naming can vary by platform. The Aurora JVM uses natively compiled Java files internally and opens them, as necessary, at runtime.
The JServer Accelerator can be used by Java application products that need an performance increase and are deployed on JServer. The JServer Accelerator command-line tool, ncomp
, natively compiles your code and loads it in JServer. However, in order to use ncomp
, you must first provide some initial setup.
You must install the following before invoking JServer Accelerator:
ncomp
.
System*.properties
file located in the $ORACLE_HOME/javavm/jahome
directory. Since the compiler and linker information is platform-specific, the configuration for these items is detailed in the README for your platform.
ncomp
the following role and security permissions:
JAVA_DEPLOY
: The user must be assigned to the JAVA_DEPLOY
role in order to be able to deploy the shared libraries on the server, which both the ncomp
and deploync
utilities perform. For example, the role is assigned to DAVE, as follows:
SQL> GRANT JAVA_DEPLOY TO DAVE;
FilePermission
: JServer Accelerator stores the shared libraries with the natively compiled code on the server. In order for JServer Accelerator to store these libraries, the user must be granted FilePermission
for read and write access to directories and files under $ORACLE_HOME
on the server. One method for granting FilePermission
for all desired directories is to grant the user the JAVASYSPRIV role, as follows:
SQL> GRANT JAVASYSPRIV TO DAVE;
See the Security chapter in the Oracle8i Java Developer's Guide for more information JAVASYSPRIV and granting FilePermission
.
JServer Accelerator, implemented within the ncomp
tool, natively compiles all classes within the specified JAR, ZIP, or list of classes. JServer Accelerator natively compiles these classes and places them into shared libraries according to their package. Note that these classes must first be loaded into the database.
If the classes are designated within a JAR file and have already been loaded in the database, you can natively compile your Java classes by executing the following:
ncomp -user SCOTT/TIGER myClasses.jar
There are options that allow you control over how the details of native compilation are handled.
ncomp [ options ] <class_designation_file
>
-user | -u <username>/<password>[@<database_url>]
[-load]
[-projectDir | -d <project_directory>]
[-force]
[-lightweightDeployment]
[-noDeploy]
[-outputJarFile | -o <jar_filename>]
[-thin]
[-oci8]
[-update]
[-verbose]
Note: These options are demonstrated within the Scenarios described in "Native Compilation Usage Scenarios". |
Table 1-56 summarizes the ncomp
arguments. The <class_designation_file>
can be a <file>.jar
, <file>.zip
, or <file>.classes
.
Argument | Description and Values |
---|---|
|
The full pathname and filename of a JAR file that contains the classes that are to be natively compiled. If you are executing in the directory where the JAR file exists and you do not specify the -projectDir option, you may give only the name of the JAR file. |
|
The full pathname and filename of a ZIP file that contains the classes that are to be natively compiled. If you are executing in the directory where the ZIP file exists and you do not specify the -projectDir option, you may give only the name of the ZIP file. |
|
The full pathname and filename of a classes file, which contains the list of classes to be natively compiled. If you are executing in the directory where the classes file exists and you do not specify the -projectDir option, you may give only the name of the classes file. See "Natively Compiling Specific Classes" for a description of a classes file. |
|
Specifies a user, password, and database connect string; the files will be loaded into this database instance. The argument has the form |
|
The native compilation is performed on all classes. Previously compiled classes are not passed over. |
|
Provides an option for deploying shared libraries and native compilation information separately. This is useful if you need to preserve resources when deploying. See "lightweightDeployment" for more information. |
|
Executes loadjava on the specified class designation file. You cannot use this option in combination with a <file>.classes file. |
|
All natively compiled classes output into a deployment JAR file. This option specifies the name of the deployment JAR file and its destination directory. If omitted, the ncomp tool names the output deployment JAR file the same name as the input <file> with "_depl.jar" appended as the suffix. If directory is not supplied, it stores the output JAR file into the project directory (denoted by -projectDir). |
|
Specifies that the native compilation results only in the output deployment JAR file, which is not deployed to the server. The resulting deployment JAR can be deployed to any server using the deploync tool. |
|
The database URL that is provided on the -user option uses a JDBC Thin URL address for the database URL syntax. |
|
The database URL that is provided on the -user option uses an OCI8 URL address for the database URL syntax. However, if neither -oci8 or -thin are specified, the default assumes that you used an OCI8 database URL. |
|
Specifies the full path for the project directory. If not specified, JServer Accelerator uses the directory that ncomp is invoked from as the project directory. This directory must exist; the tool will not create this directory for you. If it does not exist, the current directory is used. |
|
If you add more classes to a <class_designation_file> that has already been natively compiled, this flag informs JServer Accelerator to update the deployment JAR file with the new classes. Thus, JServer Accelerator compiles the new classes and adds them to the appropriate shared libraries. The deployment JAR file is updated. |
|
Output native compilation text with detail. |
The permissible forms of @<database>
depend on whether you specify -oci8
or -thin
; -oci8
is the default.
-oci8
: @<database>
is optional; if you do not specify, then ncomp
uses the user's default database. If specified, then <database>
can be a TNS name or a Net8 name-value list.
-thin
: @<database>
is required. The format is <host>:<lport>:<SID>
.
JServer Accelerator places compilation information and the compiled shared libraries in one JAR file, copies the shared libraries to $ORACLE_HOME/javavm/admin
directory on the server, and deploys the compilation information to the server. If you want to place the shared libraries on the server yourself, you can do so through the lightweightDeployment
option. The lightweightDeployment
option enables you to do your deployment in two stages:
noDeploy
and -lightweightDeployment
options. This creates an deployment JAR file with only ncomp
information, such as transitive closure information. The shared libraries are not saved within the deployment JAR file. Thus, the deployment JAR file is much smaller.
Any errors that occur during native compilation are printed to the screen. Any errors that occur during deployment of your shared libraries to the server or during runtime can be viewed with the statusnc
tool or by referring to the JACCELERATOR$DLL_ERRORS table.
If an error is caught while natively compiling the designated classes, JServer Accelerator denotes these errors, abandons work on the current package, and continues its compilation task on the next package. The native compilation continues for the rest of the packages. The package with the class that contained the error will not be natively compiled at all.
After fixing the problem with the class, you can choose to do one of the following:
If you choose to not recompile the classes, but to load the correct Java class into the database, the corrected class and all classes that are included in the resolution validation for that class--whether located within the same shared library or a different shared library--will be executed in interpreted mode. That is, the JVM will not run these classes natively. All the other natively compiled classes will continue to execute in native format. When you execute the statusnc command on the reloaded class or any of its referred classes, they will have an NEED_NCOMPING status message.
Possible errors for a Java class:
Possible errors for deployment of native compilation JAR file:
The following scenarios demonstrate how each of the options for the ncomp
tool can be used:
If all classes are loaded into the database and you have completed your testing of the application, you can request JServer Accelerator to natively compile the tested classes. JServer Accelerator takes in a JAR, ZIP, or list of classes to determine the packages and classes to be involved in the native compilation. The JServer Accelerator then retrieves all of the designated classes from the server, natively compiles them into shared libraries--each library containing a single package of classes.
Assuming that the classes have already been loaded within the server, you execute the following command to natively compile all classes listed within a class designation file, such as the pubProject.jar
file, as follows:
ncomp -user SCOTT/TIGER pubProject.jar
If you change any of the classes within the class designation file and ask for recompilation, JServer Accelerator recompiles only the packages that contain the changed classes. It will not recompile all packages.
Once tested, you may wish to natively compile the designated classes on another host than the test machine. Once you transfer the designated class file to this platform, the classes in this file must be loaded into the database before native compilation can occur. The following loads the classes through loadjava
and then executes native compilation for the class designation file--pubProject.jar
:
ncomp -user SCOTT/TIGER@dbhost:5521:orcl -thin -load pubProject.jar
If you want all classes within a class designation file to be recompiled--regardless of whether they were previously natively compiled--you execute ncomp
with the -force
option. You might want to use the -force
option to ensure that all classes are compiled resulting in a deployment JAR file that can be deployed to other JServer databases. You can specify the native compilation deployment JAR file with the -outputJarFile
option. The following forces a recompilation of all Java classes within the class designation file--pubProject.jar--
and creates a deployment JAR file with the name of pubworks.jar
:
ncomp -user SCOTT/TIGER -force -outputJarFile pubworks.jar pubProject.jar
The deployment JAR file contains the shared libraries for your classes and installation classes specified to these shared libraries. It does not contain the original Java classes. In order to deploy the natively compiled deployment JAR file to any JServer (of the appropriate platform type), you must do the following:
pubProject.jar
file would be loaded into the database using the loadjava
tool.
By default, the JServer Accelerator uses the directory where ncomp
is executed as its build environment. The JServer Accelerator downloads several class files into this directory, and then uses this directory for the compilation and linking process.
If you do not want to have JServer Accelerator put any of its files into the current directory, create a working directory, and specify this working directory as the project directory with the -projectDir
option. The following directs JServer Accelerator to use /tmp/jaccel/pubComped
as the build directory. This directory must exist before specifying it within the -projectDir option. JServer Accelerator will not create this directory for you.
ncomp -user SCOTT/TIGER -projectDir /tmp/jaccel/pubComped pubProject.jar
You can specify one or more classes, which are to be natively compiled, within a text-based <
file>.classes
file. You use the following Java syntax to specify packages and/or individual classes within this file:
import COM.myDomain.myPackage.*; import COM.myDomain.myPackage.mySubPackage.*;
import COM.myDomain.myPackage.myClass;
Once explicitly listed, you specify the name and location of this class designation file on the command line. Given the following pubworks.classes file:
import COM.myDomain.myPackage.*; import COM.myDomain.hisPackage.hisSubPackage.*; import COM.myDomain.herPackage.herClass; import COM.myDomain.petPackage.petClass;
The following directs JServer Accelerator to compile all classes designated within this file: all classes in myPackage
, hisSubPackage
and the individual classes, herClass
and myClass
. These classes must have already been loaded into the database:
ncomp -user SCOTT/TIGER /tmp/jaccel/pubComped/pubworks.classes
If you change any of the classes within this JAR file, JServer Accelerator will only recompile shared libraries that contain the changed classes. It will not recompile all shared libraries designated in the JAR file. However, if you want all classes within a JAR file to be recompiled--regardless of whether they were previously natively compiled--you execute ncomp
with the -force
option, as follows:
ncomp -user scott/tiger -force pubProject.JAR
You can deploy any deployment JAR file with the deploync
command. This includes the default output JAR file, <file
>_depl.jar
or the JAR created when you used the ncomp
-outputJarFile
option. The operating system and Oracle8i database version must be the same as the platform where it was natively compiled.
deploync [options] <deployment
>.jar
-user | -u <username>/<password>[@<database_url>]
[-projectDir | -d <project_directory>]
[-thin]
[-oci8]
Table 1-57 summarizes the deploync
arguments.
Deploy the natively compiled deployment JAR file, pub.jar
, to the dbhost
database as follows:
deploync -user SCOTT/TIGER@dbhost:5521:orcl -thin /tmp/jaccel/PubComped/pub.jar
After the native compilation is completed, you can check the status for your Java classes through the statusnc
command. This tool will print out--either to the screen or to a designated file--the status of each class. In addition, the statusnc
tool always saves the output within the JACCELERATOR$STATUS table. The values can be the following:
statusnc [ options ] <class_designation_file
>
-user <user>/<password>[@database]
[-output | -o <filename>]
[-projectDir | -d <directory>]
[-thin]
[-oci8]
Table 1-58 summarizes the statusnc
arguments. The <class_designation_file>
can be a <file>.jar
, <file>.zip
, or <file>.classes
.
Argument | Description |
---|---|
|
The full pathname and filename of a JAR file that was natively compiled. |
|
The full pathname and filename of a ZIP file that was natively compiled. |
|
The full pathname and filename of a classes file, which contains the list of classes that was natively compiled. See "Natively Compiling Specific Classes" for a description of a classes file. |
|
Specifies a user, password, and database connect string where the files are loaded. The argument has the form |
|
Designates that the statusnc should output to the specified text file rather than to the screen. |
|
Specifies the full path for the project directory. If not specified, JServer Accelerator uses the directory that ncomp is invoked from as the project directory. |
|
The database URL that is provided on the -user option uses a JDBC Thin URL address for the database URL syntax. |
|
The database URL that is provided on the -user option uses an OCI8 URL address for the database URL syntax. However, if neither -oci8 or -thin are specified, the default assumes that you used an OCI8 database URL. |
statusnc -user SCOTT/TIGER -output pubStatus.txt /tmp/jaccel/PubComped/pub.jar
|
Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|