|Oracle® Database Java Developer's Guide,
11g Release 2 (11.2)
Part Number E10588-03
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:
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.
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 11g. 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.
Before you install Oracle JVM as part of your standard Oracle Database installation, you must ensure that the configuration requirements for Oracle JVM are fulfilled. The main configuration for Java classes within Oracle Database includes configuring the:
Java memory requirements
See Also:"Java Memory Usage"
You must decide whether to use dedicated server processes or shared server processes for your database server.
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.
See Also:Appendix A, "DBMS_JAVA Package"
To run Java between the client and server, your must perform the following:
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 /usr/local/j2se1.5.2/bin/java $ which javac /usr/local/j2se1.5.2/bin/javac $ java -version java version "1.5.2"
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.
This variable must include
This variable must include
JAR Files Necessary for Java2 Clients
To ensure that the Java client successfully communicates with the server, include the following files in the
CLASSPATHrequirements may vary for Oracle JVMs running on different platforms. You must ensure that all elements of
CLASSPATH, as defined in the script for Oracle JVM utilities, are present.
For JDK 1.5.2, include
For JRE 1.5.2, include
For any interaction with JDBC, include
For any client that uses SSL, include
For any client that uses the Java Transaction API (JTA) functionality, include
For any client that uses the Java Naming and Directory Interface (JNDI) functionality, include
If you are using the accelerator for native compilation, include
JAR Files Included for Clients that Use SQLJ
You must include the
$ORACLE_HOME/sqlj/lib/translator.zip file for SQLJ.
In addition to this file, add the appropriate
.zip file, as follows:
For a Java client using the current release of JDBC, include
For a Java2 Platform, Enterprise Edition (J2EE) client using the current release of JDBC, include
For any JDK client using JDBC 8.1.7 or earlier version, include
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
CLASSPATH. This is not required for running Java clients.
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.
Note: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.
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:
FUNCTION endsession RETURN VARCHAR2;
This function clears any Java session state remaining from previous execution of Java in the current RDBMS session. The return value is a message indicating the action taken.
FUNCTION endsession_and_related_state RETURN VARCHAR2;
This function clears any Java session state remaining from previous execution of Java in the current RDBMS session and all supporting data related to running Java, such as property settings and output specifications. The return value is a message indicating the action taken.
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.
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 establishes 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.
FUNCTION set_property(name VARCHAR2, value VARCHAR2) RETURN VARCHAR2;
This function returns any value previously established by
set_property. It returns null if there is no such value.
FUNCTION get_property(name VARCHAR2) RETURN VARCHAR2;
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.
FUNCTION show_property(name VARCHAR2) RETURN VARCHAR2;
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.