4
Java Installation and Configuration

This chapter details what you need to know to install and configure JServer within your Oracle8i database. To configure Java memory, see the "Java Memory Usage" section in Chapter 5, "Security and Performance".

• Initializing a Java-Enabled Database

• Configuring JServer

• Enabling the Java Client

Initializing a Java-Enabled Database

If you installed Oracle8i with JServer, the database is Java-enabled. That is, it is ready to run Java stored procedures, JDBC, SQLJ, and CORBA/EJB objects. If you are using your own scripts to create your Oracle instance, you must initialize the JServer explicitly.

You install JServer in one of three ways:

• Oracle8i Typical or Minimal Install--Choose the Typical or Minimal Oracle8i installation, which results in JServer being automatically installed.

• Oracle8i Custom Install--Choose the JServer option within a "Custom" Oracle8i installation.

• Manual Install--Install JServer by invoking the initjvm.sql script.

Manual Install

If you did not install JServer through any of the Oracle8i install options, you can add JServer to an existing database with the initjvm.sql script in ORACLE_HOME/javavm/install.

The initjvm.sql script loads the initial set of Java classes necessary to support Java, initializes the tables for supporting Java and for the CORBA namespace, and publishes top-level entry points through call-specifications. The initjvm.sql script loads the support Java classes into the database, which include the following:

• the standard Java runtime

• bytecode verifier and optimizer

• Java and SQLJ compilers

• JDBC runtime

• CORBA ORB and EJB runtime

• some additional support classes, such as DBMS_JAVA, which are described in "Package DBMS_JAVA"

The initjvm.sql script performs the following actions:

1. Loads the classes to the SYS schema.

2. Creates public synonyms for the loaded classes to be accessible to all users.

3. Alters some of these classes to run with definer's rights to support CORBA callouts.

4. Defines database start up and shut down triggers.

   Note: The initjvm.sql script can take up to an hour to execute.

Requirements

Initializing a Java-enabled database requires a SHARED_POOL_SIZE of 50 MB, a JAVA_POOL_SIZE of about 20 MB, an additional 30 MB of system tablespace, and enough rollback segments. If the script fails for some reason, such as a lack of resources, you can adjust resources as necessary and re-execute initjvm.sql. Refer to "Java Memory Usage" and the /javavm/README.txt file for the most up-to-date information on database initialization file configuration parameters and requirements.

In addition, there are specific requirements for enabling EJB and CORBA communications. The initial settings that the Oracle8i JServer installations furnish should be sufficient to get you started. Consult the specifics of the documentation in the Oracle8i Enterprise JavaBeans and CORBA Developer's Guide and the Net8 Administrator's Guide for more details.

Package DBMS_JAVA

When initializing the JServer, the initjvm.sql script creates the PL/SQL package DBMS_JAVA. Some entrypoints of DBMS_JAVA are for your use; others are only for internal use. The corresponding Java class DbmsJava provides methods for accessing RDBMS functionality from Java.

The DBMS_JAVA package supplies the following entrypoints:

FUNCTION longname (shortname VARCHAR2) RETURN VARCHAR2

Return the full name from a Java schema object. Because Java classes and methods can have names exceeding the maximum SQL identifier length, Aurora uses abbreviated names internally for SQL access. This function simply returns the original Java name for any (potentially) truncated name. An example of this function is to print the fully qualified name of classes that are invalid:

select dbms_java.longname (object_name) from user_objects 
   where object_type = 'JAVA CLASS' and status = 'INVALID';

FUNCTION shortname (longname VARCHAR2) RETURN VARCHAR2

You can specify a full name to the database by using the shortname() routine of the DBMS_JAVA package, which takes a full name as input and returns the corresponding short name. This is useful when verifying that your classes loaded by querying the USER_OBJECTS view.

Refer to "Shortened Class Names" and Oracle8i Java Stored Procedures Developer's Guide for examples of these functions.

FUNCTION get_compiler_option(what VARCHAR2, optionName VARCHAR2)
PROCEDURE set_compiler_option(what VARCHAR2, optionName VARCHAR2,

	value VARCHAR2)
PROCEDURE reset_compiler_option(what VARCHAR2, optionName VARCHAR2)

These three entry points control the options of the JServer Java and SQLJ compiler Oracle8i delivers. See "Compiling Java Classes" for an example of these options. Additionally, both the Oracle8i Java Stored Procedures Developer's Guide and the Oracle8i SQLJ Developer's Guide and Reference document the options and these entry points.

PROCEDURE set_output (buffersize NUMBER)

This procedure redirects the output of Java stored procedures and triggers to the DBMS_OUTPUT package. See "Redirecting Output on the Server" for an example.

PROCEDURE loadjava(options varchar2)
PROCEDURE loadjava(options varchar2, resolver varchar2)
PROCEDURE dropjava(options varchar2)

These procedures allow you to load and drop classes within the database using a call rather than through the loadjava or dropjava command-line tools. To execute within your Java application, do the following:

call dbms_java.loadjava('... options...');
call dbms_java.dropjava('... options...');

The options are identical to those specified for the loadjava and dropjava command-line tools. Each option should be separated by a blank. You should not separate the options with a comma. The only exception for this is the loadjava -resolver option, which contains blanks. For -resolver, you should specify all other options first, separate these options by a comma, and then specify the -resolver option with its definition. You should not specify the following options, because they relate to the database connection for the loadjava command-line tool: -thin, -oci8, -user, -password. The output is directed to stderr.

For more information on the available options, see "loadjava".

PROCEDURE grant_permission( grantee varchar2, 

	permission_type varchar2,

	permission_name varchar2, 

	permission_action varchar2 )



PROCEDURE restrict_permission( grantee varchar2, 

	permission_type varchar2,

	permission_name varchar2, 

	permission_action varchar2)



PROCEDURE grant_policy_permission( grantee varchar2, 

	permission_schema varchar2, 

	permission_type varchar2,

	permission_name varchar2)



PROCEDURE revoke_permission(permission_schema varchar2, 

	permission_type varchar2,

	permission_name varchar2,

	permission_action varchar2)



PROCEDURE disable_permission(key number)



PROCEDURE enable_permission(key number)



PROCEDURE delete_permission(key number)

These entry points control the JVM permissions. See "Setting Permissions" for a description and example of these options.

PROCEDURE start_debugging(host varchar2, port number,

	timeout number)



PROCEDURE stop_debugging



PROCEDURE restart_debugging(timeout number)

These entry points start and stop the debug agent when debugging. See "Debugging Server Applications" for a description and example of these options.

Configuring JServer

When you install JServer as part of your normal Oracle8i installation, you will encounter configuration requirements for JServer within the Oracle8i Database Configuration Assistant and the Net8 Assistant. However, if you install using initjvm.sql, you must configure either by bringing up certain configuration tools or manually editing the initialization files.

The main configuration for Java classes within Oracle8i includes configuring Java memory requirements, the type of database processes, and the underlying connection protocol to the server.

• Java memory requirements--You must have at least 20 MB of JAVA_POOL_SIZE and 50 MB of SHARED_POOL_SIZE. If you installed JServer through the Oracle installer, these parameters are configured correctly. If you installed using the SQL script initjvm.sql, see "Java Memory Usage" for information on configuring these parameters within the database initialization files.

• Database processes--You must decide whether to use dedicated server processes or MTS processes for your database server.

• Connection protocol--The presentation layer within the database defines the type of connection your client is using to access the database. In most networking protocols, the presentation layer is responsible for making sure data is represented in a format the application and session layers can accommodate. Within the database, a presentation is a service protocol that accepts incoming network requests and activates routines in the database kernel layer or in the Aurora JVM to process the requests. Currently, the two basic presentation types are Net8 and GIOP. The GIOP presentation is used for IIOP connections for EJB and CORBA applications. Most database connections default to the Net8 connection type.

  Presentation protocol	Description
  GIOP	Accepts IIOP or IIOP over SSL requests for CORBA or EJB applications. See the Oracle8i Enterprise JavaBeans and CORBA Developer's Guide for configuration information.
  Net8	Processes incoming Net8 requests for database SQL services from Oracle tools (such as SQL*Plus) and customer-written applications (using Forms, Pro*C, or the OCI). See "Configuring Multi-Threaded Server" in Chapter 9 of the Net8 Administrator's Guide for configuration information.

You will require a different configuration for your database type and connection configuration, depending on the type of Java application, as listed below:

Java API	Database type	Connection configuration
Java stored procedures	Java stored procedures can run either in dedicated server mode or multi-threaded server (MTS) mode. If you are primarily developing Java stored procedures, you can run them in the dedicated server configuration.	Java clients or PL/SQL clients that trigger a Java stored procedure connect over a Net8 connection. See the Net8 Administrator's Guide for information on configuring a Net8 connection.
Enterprise Java Beans (EJB) or CORBA	EJB and CORBA applications run only in the MTS configuration. See Net8 Administrator's Guide for information on configuring MTS.	EJB and CORBA clients use the CORBA Internet Inter-Orb Protocol (IIOP). See the Oracle8i Enterprise JavaBeans and CORBA Developer's Guide for information on IIOP configuration.
Both Java stored procedures and EJB or CORBA applications	If you are combining both EJB and CORBA applications with Java stored procedures in a single application, you can configure both application types as follows: Configure your database to support EJB and CORBA applications in an MTS configuration Configure your database to support stored procedures in a dedicated server configuration.	You must configure both a Net8 and an IIOP connection.

Java Stored Procedure Configuration

To configure the database to run Java stored procedures, you must decide whether you want the database to run in dedicated server mode or MTS mode.

• Dedicated server mode--You must configure the database and clients, as described in the Oracle8i Java Stored Procedures Developer's Guide.

• MTS mode--You must configure the server for MTS mode with the MTS_DISPATCHERS parameter, as described in Chapter 9 of the Net8 Administrator's Guide.

Java, SQL, or PL/SQL clients, which execute Java stored procedures on the server, connect to the database over a Net8 connection. For a full description of how to configure the Net8 connection, see the Net8 Administrator's Guide.

Enterprise JavaBeans and CORBA Configuration

Clients access EJB and CORBA applications in the database over an Inter-Orb Protocol (IIOP) connection. IIOP is an implementation of GIOP over TCP/IP. To support an IIOP connection, you must configure the database in MTS mode with the General Inter-Orb Protocol (GIOP) presentation.

Oracle8i also supports the use of authentication data such as certificates and private keys required for use by SSL in combination with both types of GIOP protocols-- regular GIOP and session-based GIOP.

For a complete description of how to configure MTS, see the Net8 Administrator's Guide. For a full description of how to configure the GIOP presentation, see the Oracle8i Enterprise JavaBeans and CORBA Developer's Guide.

Enabling the Java Client

In order to run Java between the client and server, your client system must perform the following:

1. Install JDK on the Client.

2. Set up CLASSPATH.

3. Verify the Port/SID.

4. Test Install with Samples.

1. Install JDK on the Client

The client system is defined as the system where you execute the JServer tools, such as loadjava, deployejb. You can use the same system for both your client and server.

The client system requires JDK 1.1.6 or later. Solaris 2.6 bundles JDK 1.1.3, which does not work with our samples. Verify that your PATH includes JDK 1.1.6 or later and does not include JDK 1.1.3. To confirm what version of the JDK you are using, perform the following:

$ which java
/usr/local/packages/jdk1.1.6/bin/java 
$ which javac 
/usr/local/packages/jdk1.1.6/bin/javac 
$ java -version
java version "1.1.6"

If JDK 1.1.6 does not appear within these commands, either put your JDK 1.1.6 installation at the start of PATH or remove the 1.1.3 installation. In addition, check your CLASSPATH for references to the incorrect JDK version.

Note: All Oracle8i Java-based client tools work in the Java 2 environment.

2. Set up CLASSPATH

If your client is a Java client involved with a distributed application--CORBA, EJB, or RMI--you must perform one of the following before compiling your client code:

• Set up CLASSPATH to include support JAR or ZIP files.

• Include support JAR or ZIP files within an option on compile line.

For the Java client to work across nodes in a distributed application, it must be compiled with appropriate server stubs. See the documentation for the required JAR or ZIP files within the Oracle8i Enterprise JavaBeans and CORBA Developer's Guide. You can also find out what JAR and ZIP files are required by examining the makefile for the associated sample.

3. Verify the Port/SID

If you do not configure the default listener port numbers or database SID in your installation--such as ports 1521, 2481, and SID orcl--the samples will not work correctly. All the samples expect the default port numbers and database SID provided by an Oracle8i Typical install. If you have different values, specify the new port numbers as follows:

Host type	Directions
UNIX	$ make SERVICE=sess_iiop://localhost:myportnum:mysid
Windows NT	In the control panel, set the system environment variable ORACLE_SERVICE to sess_iiop://localhost:myportnum:mysid

4. Test Install with Samples

We provide a set of samples in $ORACLE_HOME/javavm/demo/demo.tar (or demo.zip for Windows NT). These samples compile and run for a database installed with the Oracle8i Typical install option. Execute these samples as a test of your installation.

$ORACLE_HOME/javavm/demo/examples/jsp/helloworld
$ORACLE_HOME/javavm/demo/examples/corba/basic/helloworld
$ORACLE_HOME/javavm/demo/examples/ejb/basic/helloworld

If these samples do not compile or run, your environment is incorrect. Similarly, if these samples compile and run, but your code does not, then a problem exists within your build environment or code.

Note: It is important that you run these examples using the supplied Makefiles (or batch files on NT) when verifying your installation.

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

---