Oracle8i Java Developer's Guide
Release 3 (8.1.7)

Part Number A83728-01





Go to previous page Go to beginning of chapter Go to next page

Preparing Java Class Methods for Execution

For your Java methods to be executed, you must do the following:

  1. Decide when your source is going to be compiled.

  2. Decide if you are going to use the default resolver or another resolver for locating supporting Java classes within the database.

  3. Load the classes into the database. If you do not wish to use the default resolver for your classes, you should specify a separate resolver on the load command.

  4. Publish your class or method.

Compiling Java Classes

Compilation of your source can be performed in one of the following ways:

Compiling Source through javac

You can compile your Java with a conventional Java compiler, such as javac. After compilation, you load the compiled binary into the database, rather than the source itself. This is a better option, because it is normally easier to debug your Java code on your own system, rather than debugging it on the database.

Compiling Source through loadjava

When you specify the -resolve option on loadjava for a source file, the following occurs:

  1. The source file is loaded as a source schema object.

  2. The source file is compiled.

  3. Class schema objects are created for each class defined in the compiled .java file.

  4. The compiled code is stored in the class schema objects.

JServer logs all compilation errors both to loadjava's logfile and the USER_ERRORS view. For more information on the USER_ERRORS view, see the Oracle8i Reference for a description of this table.

Compiling Source at Runtime

When you load the Java source into the database without the -resolve option, JServer compiles the source automatically when the class is needed during runtime. The source file is loaded into a source schema object.

JServer logs all compilation errors both to loadjava's logfile and the USER_ERRORS view. For more information on the USER_ERRORS view, see the Oracle8i Reference for a description of this table.

Specifying Compiler Options

There are two ways to specify options to the compiler.

The following sections describe your compiler options:

Default Compiler Options

When compiling a source schema object for which there is neither a JAVA$OPTIONS entry nor a command line value for an option, the compiler assumes a default value as follows:

Compiler Options on the Command Line

The loadjava compiler option, encoding, identifies the encoding of the .java file. This option overrides any matching value in the JAVA$OPTIONS table. The values are identical to the javac -encoding option. This option is relevant only when loading a source file.

Compiler Options Specified in a Database Table

Each JAVA$OPTIONS row contains the names of source schema objects to which an option setting applies; you can use multiple rows to set the options differently for different source schema objects.

You can set JAVA$OPTIONS entries by means of the following functions and procedures, which are defined in the database package DBMS_JAVA:

The parameters for these methods are described below:

Parameter   Description  


The name parameter is a Java package name, a fully qualified class name, or the empty string. When the compiler searches the JAVA$OPTIONS table for the options to use for compiling a Java source schema object, it uses the row whose name most closely matches the schema object's fully qualified class name. A name whose value is the empty string matches any schema object name.  


The option parameter is either 'online', 'encoding' or 'debug'. For the values you can specify for these options, see the Oracle8i SQLJ Developer's Guide and Reference.  

A schema does not initially have a JAVA$OPTIONS table. To create a JAVA$OPTIONS table, use the DBMS_JAVA package's java.set_compiler_option procedure to set a value. The procedure will create the table if it does not exist. Specify parameters in single quotes. For example:

SQL> execute dbms_java.set_compiler_option('x.y', 'online', 'false');

Table 2-1 represents a hypothetical JAVA$OPTIONS database table. The pattern match rule is to match as much of the schema name against the table entry as possible. The schema name with a higher resolution for the pattern match is the entry that applies. Because the table has no entry for the encoding option, the compiler uses the default or the value specified on the command line. The online option shown in the table matches schema object names as follows:

Automatic Recompilation

JServer provides a dependency management and automatic build facility that will transparently recompile source programs when you make changes to the source or binary programs upon which they depend. Consider the following cases:

public class A
      B b;
      public void assignB () {b = new B()}
public class B
      C c;
      public void assignC () {c = new C()}
public class C
      A a;
      public void assignA () {a = new A()}

The system tracks dependencies at a class level of granularity. In the preceding example, you can see that classes A, B, and C depend on one another, because A holds an instance of B, B holds an instance of C, and C holds an instance of A. If you change the definition of class A by adding a new field to it, the dependency mechanism in Oracle8i flags classes B and C as invalid. Before you use any of these classes again, Oracle8i attempts to resolve them again and recompile, if necessary. Note that classes can be recompiled only if source is present on the server.

The dependency system enables you to rely on Oracle8i to manage dependencies between classes, to recompile, and to resolve automatically. You must only force compilation and resolution yourself only if you are developing and you want to find problems early. The loadjava utility also provides the facilities for forcing compilation and resolution if you do not want to allow the dependency management facilities to perform this for you.

Resolving Class Dependencies

Many Java classes contain references to other classes, which is the essence of reusing code. A conventional Java virtual machine searches for classes, ZIP, and JAR files within the directories specified in the CLASSPATH. In contrast, the Aurora Java virtual machine searches database schemas for class objects. With Oracle8i, you load all Java classes within the database, so you might need to specify where to find the dependent classes for your Java class within the database.

All classes loaded within the database are referred to as class schema objects and are loaded within certain schemas. All JVM classes, such as java.lang.*, are loaded within PUBLIC. If your classes depend upon other classes you have defined, you will probably load them all within your own schema. For example, if your schema is SCOTT, the database resolver (the database replacement for CLASSPATH) searches the SCOTT schema before PUBLIC. The listing of schemas to search is known as a resolver spec. Resolver specs are per-class, whereas in a classic Java virtual machine, CLASSPATH is global to all classes.

When locating and resolving the interclass dependencies for classes, the resolver marks each class as valid or invalid, depending on if all interdependent classes are located or not. If the class that you load contains a reference to a class that is not found within the appropriate schemas, the class is listed as invalid. Unsuccessful resolution at runtime produces a "class not found" exception. Furthermore, runtime resolution can fail for lack of database resources if the tree of classes is very large.


As with the Java compiler, loadjava resolves references to classes, but not to resources. Be sure to correctly load the resource files your classes need.  

For each interclass reference in a class, the resolver searches the schemas specified by the resolver spec for a valid class schema object that satisfies the reference. If all references are resolved, the resolver marks the class valid. A class that has never been resolved, or has been resolved unsuccessfully, is marked invalid. A class that depends on a schema object that becomes invalid is also marked invalid.

To make searching for dependent classes easier, Oracle8i provides a default resolver and resolver spec that searches first the definer's schema and then PUBLIC. This covers most of the classes loaded within the database. However, if you are accessing classes within a schema other than your own or PUBLIC, you must define your own resolver spec.

The -resolver option specifies the objects to search within the schemas defined. In the example above, all class schema objects are searched within SCOTT, OTHER, and PUBLIC. However, if you wanted to search for only a certain class or group of classes within the schema, you could narrow the scope for the search. For example, to search only for the classes "my/gui/*" within the OTHER schema, you would define the resolver spec as follows:

loadjava -resolve -resolver '((* SCOTT) ("my/gui/*" OTHER) (* PUBLIC))'

The first parameter within the resolver spec is for the class schema object; the second parameter defines the schema to search for these class schema objects.

Allowing References to Non-Existent Classes

You can specify a special option within a resolver spec that allows an unresolved reference to a non-existent class. Sometimes, internal classes are never used within a product. For example, some ISVs do not remove all references to internal test classes from the JAR file before shipping. In a normal Java environment, this is not a problem, because as long as the methods are not called, Sun Microsystems's JVM ignores them. However, the Oracle8i resolver tries to resolve all classes referenced within the JAR file--even unused classes. If the reference cannot be validated, the classes within the JAR file are marked as invalid.

To ignore references, you can specify the "-" wildcard within the resolver spec. The following example specifies that any references to classes within "my/gui" are to be allowed even if it is not present within the resolver spec schema list.

loadjava -resolve -resolver '((* SCOTT) (* PUBLIC) ("my/gui/*" -))'

In addition, you can define that all classes not found are to be ignored. Without the wildcard, if a dependent class is not found within one of the schemas, your class is listed as invalid and cannot be run. However, this is also dangerous, because if there is a dependent class on a used class, you mark a class as valid that can never run without the dependent class. In this case, you will receive an exception at runtime.

To ignore all classes not found within SCOTT or PUBLIC, specify the following resolver spec:

loadjava -resolve -resolver "((* SCOTT) (* PUBLIC) (* -))"


Never use a resolver containing "-" if you later intend to load the classes that were causing you to use such a resolver in the first place. Instead, include all referenced classes in the schema before resolving.  

ByteCode Verifier

According to the JVM specification, .class files are subject to verification before the class they define is available in a JVM. In JServer, the verification process occurs at class resolution. The resolver might find one of the following problems and issue the appropriate Oracle error code:


If the resolver determines that the class is malformed, the resolver does not mark it valid. When the resolver rejects a class, it issues an ORA-29545 error (badly formed class). The loadjava tool reports the error. For example, this error is thrown if the contents of a .class file are not the result of a Java compilation or if the file has been corrupted.  


In some situations, the resolver allows a class to be marked valid, but will replace bytecodes in the class to throw an exception at runtime. In these cases, the resolver issues an ORA-29552 (verification warning), which loadjava will report. The loadjava tool issues this warning when the Java Language Specification would require an IncompatibleClassChangeError be thrown. JServer relies on the resolver to detect these situations, supporting the proper runtime behavior the JLS requires.  

The resolver also issues warnings, as defined below:

For more information on class resolution and loading your classes within the database, see the Oracle8i Java Tools Reference.

Loading Classes

This section gives an overview of the main points you should understand when loading your classes into the database. It discusses various options for the loadjava tool, but does not go into all the details. You can also execute loadjava within your SQL. See the Oracle8i Java Tools Reference for complete information on loadjava.

Unlike a conventional Java virtual machine, which compiles and loads from files, the Aurora Java virtual machine compiles and loads from database schema objects.

.java source files or
.sqlj source files  

correspond to Java source schema objects  

.class compiled Java files  

correspond to Java class schema objects  

.properties Java resource files,
.ser SQLJ profile files, or data files  

correspond to Java resource schema objects  

You must load all classes or resources into the database to be used by other classes within the database. In addition, at loadtime, you define who can execute your classes within the database.

The loadjava tool performs the following for each type of file:

Schema object   loadjava operations on object  

.java source files  

  1. It creates a source schema object within the definer's schema unless another schema is specified

  2. It loads the contents of the source file into a schema object

  3. It creates a class schema objects for all classes defined in the source file

  4. If -resolve is requested, it does the following:

    a. It compiles the source schema object

    b. It resolves the class and its dependencies

    c. It stores the compiled class into a class schema object


.sqlj source files  

  1. It creates a source schema object within the definer's schema unless another schema is specified

  2. It loads contents of the source file into the schema object

  3. It creates a class schema objects for all classes and resources defined in the source file

  4. If -resolve is requested, it does the following:

    a. It translates and compile the source schema object

    b. It stores the compiled class into a class schema object

    c. It stores profile into .ser resource schema object and customizes it


.class compiled Java files  

  1. It creates a class schema object within the definer's schema unless another schema is specified

  2. It loads the class file into the schema object

  3. It resolves and verify the class and its dependencies if -resolve is specified


.properties Java resource files  

  1. It creates a resource schema object within the definer's schema unless another schema is specified

  2. It loads resource file into a schema object


.ser SQLJ profile  

  1. It creates a resource schema object within the definer's schema unless another schema is specified

  2. It loads .ser resource file into a schema object and customizes it


The dropjava tool performs the reverse of the loadjava tool: it deletes schema objects that correspond to Java files. You should always use dropjava to delete a Java schema object created with loadjava. Dropping with SQL DDL commands will not update auxiliary data maintained by loadjava and dropjava. You can also execute dropjava from within SQL commands.


More options for loadjava are available. However, this section discusses only the major options. See the Oracle8i Java Tools Reference for complete information on loadjava and dropjava.  

You must abide by certain rules when loading classes into the database, which are detailed in the following sections:

After loading, you can access the USER_OBJECTS view in your database schema to verify that your classes and resources loaded properly. For more information, see "Checking Java Uploads".

Two Definitions of the Same Class

You cannot have two different definitions for the same class. This rule affects you in two ways:

Need Database Privileges and JVM Permissions

You must have the following SQL database privileges to load classes:

Loading JAR or ZIP Files

The loadjava tool accepts .class, .java, .properties, .sqlj, .ser, .jar, or .zip files. The JAR or ZIP files can contain source, class, and data files. When you pass loadjava a JAR or ZIP file, loadjava opens the archive and loads its members individually. There is no JAR or ZIP schema object. If the JAR or ZIP content has not changed since the last time it was loaded, it is not reloaded; therefore, there is little performance penalty for loading JAR or ZIP files. In fact, loading JAR or ZIP files is the simplest way to use loadjava.


JServer does not reload a class if it has not changed since the last load. However, you can force a class to be reloaded through the loadjava -force option.  

How to Grant Execute Rights

When you are loading your classes, you can grant execution rights to another user through an option for loadjava. There are two methods for defining who can execute your class:

Figure 2-2 Invoker's Versus Definer's Rights

With the example in Figure 2-2, which class, A or B, is checked when the method in class C is executed? This depends on invoker's or definer's rights.

For information on JVM security permissions, see Chapter 6, "Oracle8i Java Application Performance".

Checking Java Uploads

You can query the database view USER_OBJECTS to obtain information about schema objects--including Java sources, classes, and resources--that you own. This allows you, for example, to verify that sources, classes, or resources that you load are properly stored into schema objects.

Columns in USER_OBJECTS include those contained in Table 2-2 below.

Table 2-2 Key USER_OBJECT Columns
Name  Description 


name of the object  


type of the object (such as JAVA SOURCE, JAVA CLASS, or JAVA RESOURCE)  


status of the object (VALID or INVALID) (always VALID for JAVA RESOURCE)  

Object Name and Type

An OBJECT_NAME in USER_OBJECTS is the short name. The full name is stored as a short name if it exceeds 31 characters. See "Shortened Class Names" for more information on full and short names.

If the server uses a short name for a schema object, you can use the LONGNAME() routine of the server DBMS_JAVA package to receive it from a query in full name format, without having to know the short name format or the conversion rules.

SQL*Plus> SELECT dbms_java.longname(object_name) FROM user_objects 
          WHERE object_type='JAVA SOURCE';

This routine shows you the Java source schema objects in full name format. Where no short name is used, no conversion occurs, because the short name and full name are identical.

You can use the SHORTNAME() routine of the DBMS_JAVA package to use a full name as a query criterion, without having to know whether it was converted to a short name in the database.

SQL*Plus> SELECT object_type FROM user_objects 
          WHERE object_name=dbms_java.shortname('known_fullname');

This routine shows you the OBJECT_TYPE of the schema object of the specified full name. This presumes that the full name is representable in the database character set.

SVRMGR> select * from javasnm;
SHORT                          LONGNAME
/78e6d350_BinaryExceptionHandl sun/tools/java/BinaryExceptionHandler
/b6c774bb_ClassDeclaration     sun/tools/java/ClassDeclaration
/af5a8ef3_JarVerifierStream1   sun/tools/jar/JarVerifierStream$1


STATUS is a character string that indicates the validity of a Java schema object. A source schema object is VALID if it compiled successfully; a class schema object is VALID if it was resolved successfully. A resource schema object is always VALID, because resources are not resolved.

Example: Accessing USER_OBJECTS

The following SQL*Plus script accesses the USER_OBJECTS view to display information about uploaded Java sources, classes, and resources.

COL object_name format a30
COL object_type format a15
SELECT object_name, object_type, status
   FROM user_objects
   ORDER BY object_type, object_name;

You can optionally use wildcards in querying USER_OBJECTS, as in the following example.

SELECT object_name, object_type, status
   FROM user_objects
   WHERE object_name LIKE '%Alerter';

This routine finds any OBJECT_NAME entries that end with the characters: Alerter.

For more information about USER_OBJECTS, see the Oracle8i Java Stored Procedures Developer's Guide.


Oracle8i enables clients and SQL to invoke Java methods loaded within the database, once published. You publish either the object itself or individual methods, depending on the type of Java application it is, as shown below:

Java API   Publishing method   Reference  

Java stored procedures  

If you write a Java stored procedure that you intend to invoke with a trigger, directly or indirectly in SQL DML or in PL/SQL, you must publish individual methods within the class. You specify how to access it through a call specification. Java programs consist of many methods in many classes; however, only a few static methods are typically exposed with call specifications.  

Oracle8i Java Stored Procedures Developer's Guide.  

Servlet and JavaServer Pages  

Publish the servlet and JavaServer Pages URL within the JNDI namespace.  

Oracle8i Oracle Servlet Engine User's Guide

Oracle JavaServer Pages Developer's Guide and Reference  

CORBA and EJB development  

You do not use call specifications for CORBA or EJB objects. Instead, you publish the object reference for the client to retrieve. Once the object is retrieved, the client can invoke specific methods within the object.

Oracle8i's CORBA and EJB implementations support standard CORBA and Java styles of exposing objects by name, with accompanying CORBA and Java-style specifications of the interfaces to those objects.

  • You publish CORBA IOR's through the publish tool.

  • You publish EJB Home and Remote interfaces through the deployejb tool.


Oracle8i Enterprise JavaBeans Developer's Guide and Reference or the Oracle8i CORBA Developer's Guide and Reference books  

Go to previous page
Go to beginning of chapter
Go to next page
Copyright © 1996-2000, Oracle Corporation.

All Rights Reserved.