4 Java Installation and Configuration

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

• Modifying an Existing Oracle Database to Include Oracle JVM

Configuring Oracle JVM

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

  You must have at least 50 MB of JAVA_POOL_SIZE and 96 MB of SHARED_POOL_SIZE.

  See Also:

  "Java Memory Usage"

• Database processes

  You must decide whether to use dedicated server processes or shared server processes for your database server.

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

$ 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"

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:

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

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:

• set_property

• get_property

• remove_property

• show_property

set_property

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;

get_property

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;

remove_property

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;

show_property

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.