Skip Headers
Oracle® Database Java Developer's Guide,
11g Release 1 (11.1)

Part Number B31225-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

4 Java Installation and Configuration

This chapter describes how to install and configure of Oracle JVM. It also describes how to enable the Java client. This chapter covers the following topics:

Initializing a Java-Enabled Database

If you install Oracle Database with Oracle JVM option, then the database is Java-enabled. That is, it is ready to run Java stored procedures, Java Database Connectivity (JDBC), and SQLJ.

This section contains the following topics:

Configuring with Oracle Database Template

Configure Oracle JVM option within the database template. This is the recommended method for Java installation.

The Database Configuration Assistant enables you to create database templates for defining what each database instance installation will contain. Choose Oracle JVM option to have the Java platform installed within your database.

Modifying an Existing Oracle Database to Include Oracle JVM

If you have already installed Oracle Database without Oracle JVM, then you can add Java to your database through the modify mode of the Database Configuration Assistant of Oracle Database 10g. The modify mode enables you to choose the features, such as Oracle JVM, that you would like to install on top of an existing Oracle Database instance.

Configuring Oracle JVM

Before you install Oracle JVM as part of your normal Oracle Database installation, you need to ensure that the configuration requirements for Oracle JVM are fulfilled. The main configuration for Java classes within Oracle Database includes configuring the:

Using The DBMS_JAVA Package

Installing Oracle JVM creates the DBMS_JAVA PL/SQL package. Some entry points of DBMS_JAVA are for external use. That is, these entry points are used by developers. Other entry points are only for internal use. The corresponding Java class, DbmsJava, provides methods for accessing database functionality from Java.

Enabling the Java Client

To run Java between the client and server, your must perform the following:

  1. Install J2SE on the Client

  2. Set Up Environment Variables

  3. Test Install with Samples

Install J2SE on the Client

The client requires Java Development Kit (JDK) 1.5.2 or later. To confirm the version of JDK you are using, run the following commands on the command line:

$ which java

$ which javac

$ java -version
java version "1.5.2"

Set Up Environment Variables

After installing JDK on your client, add the directory path to the following environment variables:


    This variable must be set to the top directory of the installed JDK base.

  • $PATH

    This variable must include $JAVA_HOME/bin.


    This variable must include $JAVA_HOME/lib.

JAR Files Necessary for Java2 Clients

To ensure that the Java client successfully communicates with the server, include the following files in the CLASSPATH:

  • For JDK 1.5.2, include $JAVA_HOME/lib/dt.jar

  • For JRE 1.5.2, include $JAVA_HOME/lib/rt.jar

  • For any interaction with JDBC, include $ORACLE_HOME/jdbc/lib/

  • For any client that uses SSL, include $ORACLE_HOME/jlib/jssl-1_2.jar and $ORACLE_HOME/jlib/javax-ssl-1_2.jar

  • For any client that uses the Java Transaction API (JTA) functionality, include $ORACLE_HOME/jlib/jta.jar

  • For any client that uses the Java Naming and Directory Interface (JNDI) functionality, include $ORACLE_HOME/jlib/jndi.jar

  • If you are using the accelerator for native compilation, include $JAVA_HOME/lib/tools.jar

JAR Files Included for Clients that use SQLJ

You must include the $ORACLE_HOME/sqlj/lib/ file for SQLJ.

In addition to this file, add the appropriate file, as follows:

  • For a Java client using the current release of JDBC, include $ORACLE_HOME/sqlj/lib/

  • For a Java2 Platform, Enterprise Edition (J2EE) client using the current release of JDBC, include $ORACLE_HOME/sqlj/lib/

  • For any JDK client using JDBC 8.1.7 or earlier version, include $ORACLE_HOME/sqlj/lib/

Server Application Development on the Client

If you develop and compile your server applications on the client and want to use the same Java Archive (JAR) files that are loaded on the server, then include $ORACLE_HOME/lib/ in CLASSPATH. This is not required for running Java clients.

Test Install with Samples

When you install Oracle Database with Oracle JVM option, a set of samples is also installed and available in the $ORACLE_HOME/javavm/demo directory. These samples can be compiled and run as a test of your installation.

If these samples do not compile or run, then the environment may be incorrectly set. Similarly, if these samples compile and run, but a code written by you does not, then a problem exists within the build environment or code.


When verifying your installation, it is important that you run these examples using the supplied makefiles.

Verify that the samples work before using more complex build environments, such as Visual Cafe, JDeveloper, or VisualAge.

Two-Tier Duration for Java Session State

Prior to 11g release 1 (11.1), Java session state was single-tier, which included all values associated with running Java, such as System property values and static variable values, the set of classes loaded during the session and so on. The duration of this state used to start with the first invocation of a Java method in the RDBMS session and it used to last till JVM exited, either due to a call to java.lang.System.exit or similar OracleRuntime methods, an uncaught exception, a fatal error, or the end of the RDBMS session. This required modifying Java code and also failed to fully complete the termination of the session before the end of the RDBMS call. This made it impossible to start a new Java session within the same call.

Starting with 11g release 1 (11.1), Java session state is split into two tiers. One tier has a longer duration and it encompasses the duration of the other tier. The duration of the shorter tier is the same as before, that is, it starts when a Java method is invoked and ends when JVM exits. The duration of the longer tier starts when a Java method is invoked in the RDBMS session for the first time. This session lasts until the RDBMS session ends or the session is explicitly terminated by a call to the function dbms_java.endsession_and_related_state. This is addressed by the addition of the following two PL/SQL functions to the DBMS_JAVA package, which account for the two kinds of Java session duration:

Most of the values associated with running Java remain in the shorter tier. The values that can be useful for multiple invocations of JVM have been moved to the longer tier. For example, the system property values established by dbms_java.set_property and the output redirection specifications.

Setting System Properties

Within an RDBMS session you can maintain a set of values that are added to the system properties whenever a Java session is started in the RDBMS session. This set of values remains valid for the duration of the longer tier of Java session state, which is typically the same as the duration the RDBMS session.

There is a set of PL/SQL functions in the DBMS_JAVA package for setting, retrieving, removing and displaying key value pairs in an internal, RDBMS session duration table, where both elements of a pair are strings (VARCHAR2) and there is at most one pair for a given key. These functions are as follows:


This function enables you to establish a value for a system property that is then used for the duration of the current RDBMS session, whenever a Java session is initialized. The first argument is the name of the property and the second is the value to be established for it. The return value for set_property is null unless there is some error. For example, if an attempt is made to set a value for a prescribed property, then an error message is returned.



This function returns any value previously established by set_property. It returns null if there is no such value.



This function removes any value previously established by set_property. The return value is null unless an error occurred, in which case an error message is returned.

FUNCTION remove_property(name VARCHAR2) RETURN VARCHAR2;


This function displays a message of the form name = value for the input name, or for all established property bindings, if name is null. The return value for this function is null on successful completion, otherwise it is an error message. The output is displayed to wherever you have currently directed your Java output.


Before initializing the Java session, the values from this table are added to the set of default system property values already maintained by Oracle JVM. When you run a Java method by using the command-line interface, the values determined by the -D option, if present, override the values set in the table. As soon as you terminate the Java session, the values established by the -D option become obsolete and the keys are set to the original values as present in the table.