Java Stored Procedures Developer's Guide
Release 2 (8.1.6)
Part Number A81358-01
To manage Java schema objects, you use the command-line utilities
dropjava. You can write, compile, and partially test and debug Java stored procedures on the client side in popular Java IDEs. Then, you can use
loadjava to upload the resulting Java source, class, and resource files into the Oracle database as schema objects. In addition, you can use
dropjava to drop given Java source, class, and resource schema objects from your schema.
For a particular Java class, you can load either its source file or class file, but not both. If you create Java class files on the client side, you can use
loadjava to upload them into the Oracle database. Alternatively, you can upload Java source files and let the JServer JVM compile them. In most cases, it is best to compile and debug programs on the client side, then upload the class files for final testing within the database.
Loading Java archives (JARs) or ZIP archives is the simplest way to use
loadjava. Archives cannot be schema objects. Therefore, when passed a JAR or ZIP archive,
loadjava loads the archived files individually. For efficiency, files not modified since the last time they were loaded are not reloaded.
Two objects in the same schema cannot define the same class. Suppose you define class
X in file
A.java, load the file, then move the definition of
X to file
B.java. An attempt to load
B.java will fail because it redefines class
X. Instead, either drop
A.java or load a new version of it that no longer defines
X, then load
All the classes in a Java program must be loaded before its external references can be resolved. One reason for this requirement is that Java programs have multiple source files because the JDK and other client-side tools require a separate source file for each public class. Another reason is that classes often refer to each other, so name resolution is not possible until all the files have been loaded.
You can use
loadjava to force early resolution. When you specify the option
loadjava uses the SQL
RESOLVE statement to resolve external references in uploaded Java classes. All references must be resolved before you can use those classes. If you do not specify the option, Oracle executes the SQL
JAVA statement implicitly at run time.
If all its references to other classes cannot be resolved, a class is marked invalid. At run time, attempts to load an invalid class throw a
ClassNotFound exception, as required by the Java Language Specification.
Java classes are loaded dynamically at run time. In Sun Microsystem's JDK, the class loader locates a class by searching sequentially through the list of directories specified by the environment variable
The JServer JVM uses a similar list known as a resolver spec, but instead of directories, it specifies SQL schemas. When the JVM searches for a class corresponding to a Java name, it searches the list of schemas sequentially until the Java schema object with that name is found. If no such object is found, it generates an error.
Each class has its own resolver spec. For example, the class
X resolver spec lists the schemas to be searched for the classes referenced by
X. A facility known as the resolver maintains reference lists. The resolver searches the listed schemas for valid class schema objects that resolve the references. If all references are resolved, the resolver marks the class valid; otherwise, it marks the class invalid. If a schema object becomes invalid, all its dependent classes are marked invalid.
You can run
loadjava in the following three resolution modes:
loadjavauploads all classes listed on the command line, marks them invalid, and then resolves them. Use this mode when loading classes that refer to each other, or when reloading isolated classes. Any class that depends on classes not yet loaded remains marked invalid.
loadjavaresolves each class as it is loaded. In general, this mode is not recommended, especially when used with a resolver spec that leaves unresolved classes marked valid.
loadjavaloads files but does not compile or resolve them. Instead, files are compiled (if necessary) and resolved at run time. (The resolver runs automatically when the JVM tries to load a class marked invalid.) However, it is best to resolve classes before run time to learn of missing classes early.
Like a Java compiler,
loadjava resolves references to classes but not to resources. So, make sure the resource files that your classes need are loaded correctly.
-resolver binds a resolver spec to the class schema objects that
loadjava creates or replaces. Alternatively, you can use the option
-oracleresolver (the default) to bind a predefined resolver spec to class schema objects. In most cases, the predefined resolver spec will meet your needs.
A resolver spec lists one or more items, each consisting of a name spec and schema spec in the following format:
A name spec is similar to a name in a Java import statement. It can be a Java class full name, a package name whose last part is the wildcard "
*", or just that wildcard. However, the elements of a name spec must be separated by slashes, not periods. For example, the name spec
test/util/* matches all class names that begin with
test.util. The special name spec, "
*", matches all class names.
A schema spec can be a schema name or the wildcard "
-". The wildcard does not identify a schema; it tells the resolver not to mark a class invalid even if a reference cannot be resolved. (Without the wildcard "
-" in a resolver spec, an unresolved reference invalidates the class and generates an error.) Use the wildcard "
-" when a class refers to classes that you cannot (or choose not to) load. For example, JServer cannot run the methods of GUI classes.
When matching a schema object name with a name spec, the resolver searches the schemas specified by the schema spec. The resolver searches schemas in the order they are listed in the resolver spec. For example, the following resolver spec tells the the resolver to search for a reference in schema
SCOTT, then in schema
If it cannot resolve the reference, the resolver marks the referring class invalid and generates an error. The resolver spec below tells the resolver to ignore missing classes in package
utils.gui. So, if a reference to a class in package
utils.gui is not resolved, the resolver marks the referring class valid and generates no error.
To have the resolver ignore all classes not found in schema
SCOTT or schema
PUBLIC, specify the following resolver spec:
loadjava uses the hash table
JAVA$CLASS$MD5$TABLE (called "digest table" from here on) to track the loading of Java schema objects into a given schema. (
MD5 refers to RSA Data Security's MD5 Message-Digest Algorithm, which does the hashing.) If you use
loadjava to load a Java schema object, you must use
dropjava to drop the object. Otherwise, the digest table is not updated properly. If that happens, specify the option
-force to bypass the digest table lookup.
The digest table enables
loadjava to skip files that have not changed since they were last loaded. This improves the performance of makefiles and scripts that invoke
loadjava for a whole list of files.
loadjava detects unchanged files by maintaining a digest table in every schema. The digest table relates a file name to a digest, which is a hash of the file's content. Comparing digests computed for the same file at different times is a fast way to detect a change in the file's content.
For each file it processes,
loadjava computes a digest of the file's content, then looks up the file name in the digest table. If there is a matching entry,
loadjava does not load the file (because a corresponding schema object exists and is up to date). If you specify the option
loadjava shows you the results of its digest table lookups.
Loading a source file creates or updates a Java source schema object and invalidates the class schema objects derived previously from that source file (because they were not compiled from the newly loaded source file). If the class schema objects do not exist, they are created.
To force compilation when you upload a source file, specify the
loadjava displays messages inserted by the compiler into the system database table
USER_ERRORS. For a description of this table, see the Oracle8i Reference.
There are two ways to pass options to the compiler. If you specify the option
-andresolve (which might trigger compilation), then you can specify compiler options on the
loadjava command line. You can also set compiler option values in the database table
JAVA$OPTIONS (called "options table" from here on). Then, you can selectively override those settings using
loadjava command-line options.
A row in the options table contains the names of source schema objects to which an option setting applies. You can use multiple rows for different settings. The option
encoding specifies a character-encoding scheme; the option
online enables online semantics checking (of SQLJ sources only).
The compiler looks up options in the options table unless they are specified on the
loadjava command line. A command-line value overrides and clears a matching entry in the options table. If there are no options-table entries or command-line values for the options, the compiler uses the following default values:
For the non-default values, see the Oracle8i SQLJ Developer's Guide and Reference.
You can get, set, and reset options-table entries using the following function and procedures, which are defined in the utility package
FUNCTION get_compiler_option ( name VARCHAR2, option VARCHAR2) RETURNS VARCHAR2; PROCEDURE set_compiler_option ( name VARCHAR2, option VARCHAR2, value VARCHAR2); PROCEDURE reset_compiler_option ( name VARCHAR2, option VARCHAR2);
name is the name of a Java package, the full name of a class, or the empty string. After searching the options table, the compiler selects the row in which
name most closely matches the full name of the schema object. If
name is the empty string, it matches the name of any schema object.
Initially, a schema does not have an options table. To create one, use the procedure
dbms_java.set_compiler_option to set a value. The procedure creates the table if it does not exist. Enclose parameters in single quotes, as shown in the following example:
For more information about package
DBMS_JAVA, see the Oracle8i Java Developer's Guide.