9 Oracle Database Java Application Performance

Accelerator Overview

Most Ahead-Of-Time native compilers compile the bytecode directly into a platform-dependent language. For portability requirements, this is not feasible. Figure 9-1 illustrates how an accelerator translates the Java classes into a version of C that is platform-independent. The C code is compiled and linked to supply the final platform-dependent, natively compiled, shared libraries or dynamic-link libraries (DLLs).

Figure 9-1 Native Compilation Using Accelerator

Description of "Figure 9-1 Native Compilation Using Accelerator"

Given a JAR file, an accelerator performs the following:

1. Verifies the classes that are loaded in the database.

2. Retrieves the Java bytecodes for these classes from the database and stores them in a project directory where the accelerator was called.

3. Translates the Java bytecodes to C code.

4. Compiles and links the C code using the C compiler for your platform.

   The accelerator translates, compiles, and links the retrieved classes on the client. For this reason, you must natively compile the code on the intended platform environment in which this application will be deployed. The result is a single deployment JAR file for all classes within the project.

5. The resulting shared library is loaded into the $ORACLE_HOME/javavm/admin directory.

Oracle Database Core Java Class Libraries

All core Java class libraries and Oracle-provided Java code within Oracle Database are 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, orajox10java_lang.so on Sun Solaris and orajox10java_lang.dll on Microsoft Windows hold java.lang classes. Specifics of packaging and naming can vary from platform to platform. The Oracle JVM uses natively compiled Java files internally and opens them, as necessary, at run time.

Natively Compiling Java Application Class Libraries

The command-line tool, ncomp, is an accelerator that natively compiles your code and loads it in Oracle Database. However, to use ncomp, you must first satisfy the installation requirements.

You must perform the following before calling the accelerator:

1. Install a C compiler for the intended platform on the computer where you are running ncomp.

2. Verify that the correct compiler and linker commands are referenced within the System*.properties file located in the $ORACLE_HOME/javavm/jahome directory. Because the compiler and linker information is platform-specific, the configuration for these items is detailed in the README for your platform.

3. Set the JAVA_HOME environment variable to the location where your Java Development Kit (JDK) is installed.

4. Grant the user that runs ncomp the following role and security permissions:

   1. JAVA_DEPLOY

      The user must be assigned the JAVA_DEPLOY role to be able to deploy the shared libraries on the server, which can be performed using the ncomp and deploync utilities. For example, this role can be assigned to the user DAVE, as follows:

      SQL> GRANT JAVA_DEPLOY TO DAVE;
      
      

   2. FilePermission

      The accelerator stores the shared libraries with the natively compiled code on the server. To enable the 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 of granting FilePermission for all desired directories is to grant the user the JAVASYSPRIV role, as follows:

      SQL> GRANT JAVASYSPRIV TO DAVE;
      
      

      You must run the following grant by a party that has the permission to run this grant, given that $ORACLE_HOME is equivalent to /private/oracle on the server:

      call dbms_java.grant_permission(<user>, 'java.io.FilePermission', '/private/oracle/-', 'read,write');
      
      

      The following example demonstrates Larry giving Dave FilePermission for $ORACLE_HOME, where $ORACLE_HOME is located in /private/oracle. You cannot provide an environment variable to the grant_permission() method. Once completed, Dave can run ncomp.

      connect larry/larry
      
      REM Grant DAVE permission to read and write the ncomp file.
      call dbms_java.grant_permission('DAVE', 'java.io.FilePermission', '/private/oracle/-','read,write');
      
      REM commit the changes to the PolicyTable
      commit;
      
      

   Note:

   DBA role contains both the JAVA_DEPLOY role and FilePermission for all files under $ORACLE_HOME.

Running the Accelerator

All the Java classes contained within a JAR file must already be loaded within the database. Run the ncomp tool to instruct the accelerator to natively compile all these classes. The following code natively compiles all classes within the pubProject.jar file:

ncomp -user scott/tiger pubProject.jar

If you change any of the classes within this JAR file, then the accelerator recompiles the shared library for the package that contains the changed classes. It will not recompile all shared libraries. However, if you want all classes within a JAR file to be recompiled, regardless of whether they were natively compiled previously, then run the ncomp with the -force option, as follows:

ncomp -user scott/tiger -force pubProject.JAR

The ncomp Tool

The accelerator, implemented within the ncomp tool, natively compiles all classes within the specified JAR or ZIP file or the list of classes. It 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, then you can natively compile your Java classes, as follows:

ncomp -user SCOTT/TIGER myClasses.jar

There are options that let you control the details of native compilation.

Syntax

ncomp [ options ] class_designation_file
  -user | -u username/password [@database_url]
  [-load]
  [-projectDir | -d project_directory]
  [-force]
  [-lightweightDeployment]
  [-noDeploy]
  [-outputJarFile | -o jar_filename]
  [-thin]
  [-oci | -oci8]
  [-update]
  [-verbose]

Argument Summary

Table 9-1 summarizes the ncomp arguments. class_designation_file can be a file.jar, file.zip, or file.classes file.

Argument Details

Table 9-1 summarizes all the arguments. This section explains the following arguments in detail.

• user

  {-user | -u} user/password[ @database_url ]
  
  

  The permissible forms of @database_url depend on whether you specify -oci, which is the default, or -thin:

  • -oci:@database_url is optional. If you do not specify, then ncomp uses the user's default database. If specified, then database_url can be a TNS name or an Oracle Net Services name-value list.

  • -thin:@database_url is required. The format is host:lport:SID.

    where:

    • host is the name of the computer running the database.

    • lport is the listener port that has been configured to listen for Oracle Net Services connections. In a default installation, it is 5521.

    • SID is the database instance identifier. In a default installation, it is ORCL.

• lightweightDeployment

  The accelerator places compilation information and the compiled shared libraries in a single JAR file, copies the shared libraries to $ORACLE_HOME/javavm/admin on the server, and deploys the compilation information to the server. If you want to place the shared libraries on the server yourself, then you can do so using the lightweightDeployment option. This option enables you to perform the deployment in two stages:

  1. Natively compile your JAR file with the -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 in the deployment JAR file. As a result, the deployment JAR file is much smaller.

  2. Deploy as follows:

     Copy all output shared libraries from the lib directory of the native compilation project directory to $ORACLE_HOME/javavm/admin on the server.

     Note:

     You need to have FilePermission to write to this directory. FilePermission is included in the DBA and JAVASYSPRIV roles.

     Deploy the lightweight deployment JAR file to the server using deploync.

Errors

Any error that occurs during native compilation is printed to the screen. Errors that occur during deployment of shared libraries to the server or during run time 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, then the 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:

• Recompile the shared library

• Reload the Java class into the database

If you choose to load the correct Java class into the database instead of recompiling the classes, then the corrected class and all classes included in the resolution validation for that class are processed in the interpreted mode. These classes are processed regardless of whether they are located within the same shared library or in a different shared library. This means that the JVM will not run these classes natively. All the other natively compiled classes will continue to run in the native format. When you run the statusnc command on the reloaded class or any of its referred classes, they will have a NEED_NCOMPING status message.

The possible errors for a Java class are:

• The Java class does not exist in the database. If you do not load the Java class into Oracle Database, then the accelerator does not include the class in the shared library. The class is skipped.

• The Java class is invalid. That is, one of its references may not be found.

• For any Java class that is unresolved, the accelerator will try to resolve it before natively compiling. However, if the class cannot be resolved, then it is ignored by the accelerator.

A possible error during deployment of natively compiled JAR file is that the native compilation of your JAR file runs correctly, but the deployment fails. In this case, do not recompile the JAR file, but deploy the natively compiled output JAR file with the deploync command.

Native Compilation Usage Scenarios

The following scenarios demonstrate how each of the ncomp tool options can be used:

• Natively Compiling on a Test Platform With Java Classes Already Loaded in the Database

• Natively Compiling Java Classes Not Loaded in the Database

• Clean Compile and Generate Output for Future Deployment

• Controlling Native Compilation Build Environment

• Natively Compiling Specific Classes

• Natively Compiling Packages That Are Fully or Partially Modified

Natively Compiling on a Test Platform With Java Classes Already Loaded in the Database

If all classes are loaded into the database and you have completed your testing of the application, then you can use the accelerator to natively compile the tested classes. The accelerator accepts a JAR or ZIP file or a file with a list of classes to determine the packages and classes to be included in the native compilation. It then retrieves all the designated classes from the server and natively compiles them into shared libraries. Each library contains a single package of classes.

Assuming that the classes have already been loaded on the server, you run 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, then the accelerator recompiles only the packages that contain the changed classes. It will not recompile all the packages.

Natively Compiling Java Classes Not Loaded in the Database

Once you have tested the designated classes, you may wish to natively compile them on a host other than the test computer. After 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 command loads the classes through loadjava and then performs native compilation of classes in the class designation file, pubProject.jar:

ncomp -user SCOTT/TIGER@dbhost:5521:orcl -thin -load pubProject.jar

Clean Compile and Generate Output for Future Deployment

If you want all classes within a class designation file to be recompiled, regardless of whether they were previously natively compiled, then run ncomp with the -force option. You may 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 Oracle Database instances. You can specify the native compilation deployment JAR file with the -outputJarFile option. The following command forces a recompilation of all Java classes in the class designation file, pubProject.jar, and creates a deployment JAR file, pubworks.jar:

ncomp -user SCOTT/TIGER -force -outputJarFile pubworks.jar pubProject.jar

The deployment JAR file contains the shared libraries for your classes, and the installation classes specified to these shared libraries. It does not contain the original Java classes. To deploy the natively compiled deployment JAR file to any Oracle Database instance of the appropriate platform type, you must do the following:

1. Load the original Java classes into the destination server. For example, the class designation file, pubProject.jar, would be loaded into the database using the loadjava tool.

2. Deploy the natively compiled deployment JAR file using the deploync tool.

Controlling Native Compilation Build Environment

By default, the accelerator uses the directory where ncomp is run as its build environment. It downloads several class files into this directory and then uses this directory for the compilation and linking process.

If you do not want to the accelerator to store any of its files in the current directory, then create a working directory and specify it as the project directory with the -projectDir option. The following command directs the accelerator to use /tmp/jaccel/pubComped as the build directory.

ncomp -user SCOTT/TIGER -projectDir /tmp/jaccel/pubComped pubProject.jar

Natively Compiling Specific Classes

You can specify one or more classes, which are to be natively compiled, in a .classes file. You can use the following syntax to specify packages or individual classes or both within this file:

• Specify classes within one or more packages, as follows:

  import com.myDomain.myPackage.*;
  import com.myDomain.myPackage.mySubPackage.*;
  
  

  Note:

  Java has no formal notion of a subpackage. You must specify each package independently.

• Specify an individual class, as follows:

  import com.myDomain.myPackage.myClass;
  
  

Once explicitly listed, specify the name and location of this class designation file on the command line.

Consider 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 command directs the accelerator to compile all the classes designated in the pubworks.classes file:

ncomp -user SCOTT/TIGER /tmp/jaccel/pubComped/pubworks.classes

All the classes in myPackage and hisSubPackage and the individual classes, herClass and myClass, are compiled.

Natively Compiling Packages That Are Fully or Partially Modified

If you change any of the classes within the deployment JAR file, then the 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 the classes in a JAR file to be recompiled, regardless of whether they were previously natively compiled, then you must run ncomp with the -force option, as follows:

ncomp -user scott/tiger -force pubProject.JAR

The deploync Tool

You can deploy any deployment JAR file with the deploync command. This includes the default output JAR file, file_depl.jar, or the JAR file created when you use the ncomp -outputJarFile option. The operating system and Oracle Database version must be the same as the platform where it was natively compiled.

Syntax

deploync [options] deployment.jar
  -user | -u username/password [@database_url]
  [-projectDir | -d project_directory]
  [-thin]
  [-oci | -oci8]

Argument Summary

Table 9-2 summarizes the deploync arguments.

Example

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

The statusnc Tool

After the native compilation is completed, you can check the status of the Java classes using the statusnc command. This tool prints the status of each class either to the screen or to a designated file. In addition, it always saves the output in the JACCELERATOR$STATUS table. The values can be the following:

Syntax

statusnc [ options ] class_designation_file
  -user user/password[@database_url]
  [-output | -o filename]
  [-projectDir | -d directory]
  [-thin]
  [-oci | -oci8]

Argument Summary

Table 9-3 summarizes the statusnc arguments. The class_designation_file can be a .jar, .zip, or .classes file.

Example

statusnc -user SCOTT/TIGER -output pubStatus.txt /tmp/jaccel/PubComped/pub.jar

Configuring Memory Initialization Parameters

You can modify the following database initialization parameters to tune your memory usage to reflect your application needs more accurately:

• SHARED_POOL_SIZE

  Shared pool memory is used by the class loader within the JVM. The class loader, on an average, uses about 8 KB of memory for each loaded class. Shared pool memory is used when loading and resolving classes into the database. It is also used when compiling the source in the database or when using Java resource objects in the database.

  The memory specified in SHARED_POOL_SIZE is consumed transiently when you use loadjava. The database initialization process requires SHARED_POOL_SIZE to be set to 50 MB because it loads the Java binaries for approximately 8,000 classes and resolves them. The SHARED_POOL_SIZE resource is also consumed when you create call specifications and as the system tracks dynamically loaded Java classes at run time.

• JAVA_POOL_SIZE

  The Oracle JVM memory manager allocates all other Java state during run time from the amount of memory allocated using JAVA_POOL_SIZE. This memory includes the shared in-memory representation of Java method and class definitions, as well as the Java objects migrated to session space at end-of-call. In the first case, you will be sharing the memory cost with all Java users. In the second case, in a shared server, you must adjust JAVA_POOL_SIZE allocation based on the actual amount of state held in static variables for each session.

• JAVA_SOFT_SESSIONSPACE_LIMIT

  This parameter lets you specify a soft limit on Java memory usage in a session, which will warn you if you must increase your Java memory limits. Every time memory is allocated, the total memory allocated is checked against this limit.

  When a user's session Java state exceeds this size, Oracle JVM generates a warning that is written into the trace files. Although this warning is an informational message and has no impact on your application, you should understand and manage the memory requirements of your deployed classes, especially as they relate to usage of session space.

• JAVA_MAX_SESSIONSPACE_SIZE

  If a Java program, which can be called by a user, running in the server can be used in a way that is not self-limiting in its memory usage, then this setting may be useful to place a hard limit on the amount of session space made available to it. The default is 4 GB. This limit is purposely set extremely high to be normally invisible.

  When a user's session Java state attempts to exceeds this size, the application can receive an out-of-memory failure.

Initializing Pool Sizes within Database Templates

You can set the defaults for JAVA_POOL_SIZE and SHARED_POOL_SIZE in the database installation template. The Database Configuration Assistant enables you to modify these values in the Memory section, as shown in Figure 9-2.

Figure 9-2 Configuring Oracle JVM Memory Parameters

Description of "Figure 9-2 Configuring Oracle JVM Memory Parameters"

Java Pool Memory

Java pool memory is used in server memory for all session-specific Java code and data within the JVM. Java pool memory is used in different ways, depending on what mode the Oracle Database server is running in.

Java Pool Memory Used within a Dedicated Server

The following is what constitutes the Java pool memory used within a dedicated server:

• The shared part of each Java class used per session.

  This includes read-only memory, such as code vectors, and methods. In total, this can average about 4 KB to 8 KB for each class.

• None of the per-session Java state of each session.

  For a dedicated server, this is stored in the User Global Area (UGA) within the Program Global Area (PGA), and not within the SGA.

Under dedicated servers, the total required Java pool memory depends on the applications running and may range between 10 and 50 MB.

Java Pool Memory Used within a Shared Server

The following is what constitutes the Java pool memory used within a shared server:

• The shared part of each Java class that is used per session.

  This includes read-only memory, such as vectors, and methods. In total, this can average about 4 KB to 8 KB for each class.

• Some of the UGA used for per-session state of each session is allocated from the Java pool memory within the SGA

  Because the Java pool memory size is fixed, you must estimate the total requirement for your applications and multiply by the number of concurrent sessions the applications want to create, to calculate the total amount of necessary Java pool memory. Each UGA grows and shrinks as necessary. However, all UGAs combined must be able to fit within the entire fixed Java pool space.

Under shared servers, this figure could be large. Java-intensive, multiuser benchmarks could require more than 100 MB.

Displaying Used Amounts of Java Pool Memory

You can find out how much of Java pool memory is being used by viewing the V$SGASTAT table. Its rows include pool, name, and bytes. Specifically, the last two rows show the amount of Java pool memory used and how much is free. The total of these two items equals the number of bytes that you configured in the database initialization file.

SVRMGR> select * from v$sgastat;

POOL        NAME                            BYTES
----------- -------------------------- ----------
            fixed_sga                       69424
            db_block_buffers              2048000
            log_buffer                     524288
shared pool free memory                  22887532
shared pool miscellaneous                  559420
shared pool character set object            64080
shared pool State objects                   98504
shared pool message pool freequeue         231152
shared pool PL/SQL DIANA                  2275264
shared pool db_files                        72496
shared pool session heap                    59492
shared pool joxlod: init P                   7108
shared pool PLS non-lib hp                   2096
shared pool joxlod: in ehe                4367524
shared pool VIRTUAL CIRCUITS               162576
shared pool joxlod: in phe                2726452
shared pool long op statistics array        44000
shared pool table definiti                    160
shared pool KGK heap                         4372
shared pool table columns                  148336
shared pool db_block_hash_buckets           48792
shared pool dictionary cache              1948756
shared pool fixed allocation callback         320
shared pool SYSTEM PARAMETERS               63392
shared pool joxlod: init s                   7020
shared pool KQLS heap                     1570992
shared pool library cache                 6201988
shared pool trigger inform                  32876
shared pool sql area                      7015432
shared pool sessions                       211200
shared pool KGFF heap                        1320
shared pool joxs heap init                   4248
shared pool PL/SQL MPCODE                  405388
shared pool event statistics per sess      339200
shared pool db_block_buffers               136000
java pool   free memory                  30261248
java pool   memory in use                19742720
37 rows selected.

Correcting Out of Memory Errors

If you run out of memory while loading classes, then it can fail silently, leaving invalid classes in the database. Later, if you try to call or resolve any invalid classes, then a ClassNotFoundException or NoClassDefFoundException instance will be thrown at run time. You would get the same exceptions if you were to load corrupted class files. You should perform the following:

• Verify that the class was actually included in the set you are loading to the server.

• Use the loadjava -force option to force the new class being loaded to replace the class already resident in the server.

• Use the loadjava -resolve option to attempt resolution of a class during the load process. This enables you to catch missing classes at load time, rather than at run time.

• Double check the status of the newly loaded class by connecting to the database in the schema containing the class, and run the following:

  SELECT * FROM user_objects WHERE object_name = dbms_java.shortname('');
  
  

  The STATUS field should be VALID. If loadjava complains about memory problems or failures, such as lost connection, then increase SHARED_POOL_SIZE and JAVA_POOL_SIZE, and try again.