2 Java Applications on Oracle Database

2.2.1 Java Supported APIs

For the Oracle Database 10g release, we offer the following Java APIs—Java stored procedures, JNDI, and JDBC, and SQLJ.

• JNDI—Store objects in a JNDI namespace.

• JDBC and SQLJ—You can access SQL data through SQLJ or JDBC. See Chapter 3, "Invoking Java in the Database", for examples of each Java API.

• Java stored procedures—The lifetime of a Java stored procedure session is identical to the SQL session in which it is embedded. This concept is familiar to PL/SQL users. Any state represented in Java transparently persists for the lifetime of the RDBMS session, simplifying the process of writing stored procedures, triggers, and methods for Oracle Abstract Data Types. Individual invocations of Java code within a session are known as calls. For example, a call may be initiated by a SQL call.

  
  

  Note: The concepts of call and session apply across all uses of Oracle Database.

2.4.1 Java Classes Loaded in the Database

To make Java files available to the OracleJVM, you must load them into the Oracle database as schema objects. As Figure 2-2 illustrates, loadjava can invoke the JVM's Java compiler, which compiles source files into standard class files.

The figure also shows that loadjava can set the values of options stored in a system database table. Among other things, these options affect the processing of Java source files.

Figure 2-2 Loading Java into the Oracle Database

Each Java class is stored as a schema object. The name of the object is derived from the fully qualified name (full name) of the class, which includes the names of containing packages. For example, the full name of class Handle is:

oracle.aurora.rdbms.Handle

In the name of a Java schema object, slashes replace dots, so the full name of the class becomes:

oracle/aurora/rdbms/Handle

The Oracle RDBMS accepts Java names up to 4000 characters long. However, the names of Java schema objects cannot be longer than 31 characters, so if a name is longer than that, the system generates an alias (short name) for the schema object. Otherwise, the full name is used. You can specify the full name in any context that requires it. When needed, name mapping is handled by the RDBMS. See "Shortened Class Names" for more information.

2.5.1 Compiling Java Classes

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

• You can compile the source explicitly on your client machine, before loading it into the database, through a Java compiler, such as javac.

• You can ask the database to compile the source during the loading process managed within the loadjava tool.

• You can force the compilation to occur dynamically at runtime.

  
  

  Note: If you decide to compile through loadjava, you can specify compiler options. See "Specifying Compiler Options" for more information.

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

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()}

}

2.5.2 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 OracleJVM searches database schemas for class objects. With Oracle Database, 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 whether all interdependent classes are located. 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.

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, Oracle Database 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.

• loading using Oracle's default resolver, which searches the definer's schema and PUBLIC:

  loadjava -resolve 
  

• loading using your own resolver spec definition containing the SCOTT schema, OTHER schema, and PUBLIC:

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

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 within which to search for these class schema objects.

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

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

2.5.3 Loading Classes

This section gives an overview of loading your classes into the database using the loadjava tool. You can also execute loadjava within your SQL. See Chapter 11, "Schema Object Tools" for complete information on loadjava.

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

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

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

The dropjava tool performs the reverse of the loadjava tool: it deletes schema objects that correspond to Java files. 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.

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

• Defining the Same Class Twice

• Designating Database Privileges and JVM Permissions

• Loading JAR or ZIP Files

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

2.5.4 How to Grant Execute Rights

If you load all classes within your own schema and do not reference any class outside of your schema, you already have execution rights. You have the privileges necessary for your objects to invoke other objects loaded in the same schema. That is, the ability for class A to invoke class B. Class A must be given the right to invoke class B.

The classes that define a Java application are stored within Oracle Database under the SQL schema of their owner. By default, classes that reside in one user's schema are not executable by other users, because of security concerns. You can allow other users (schemas) the right to execute your class through the loadjava -grant option. You can grant execution rights to a certain user or schema. You cannot grant execution rights to a role, which includes the super-user DBA role. The setting of execution rights is the same as used to grant or revoke privileges in SQL DDL statements.

Figure 2-3 Execution Rights

For information on JVM security permissions, see Chapter 10, "Oracle Database Java Application Performance".

2.5.5 Controlling the Current User

During execution of Java or PL/SQL, there is always a current user. Initially, this is the user who creates the session.

Invoker's and definer's rights is a SQL concept that is used dynamically when executing SQL, PL/SQL, or JDBC. The current user controls the interpretation of SQL and determines privileges. For example, if a table is referenced by a simple name, it is assumed that the table belongs in the user's schema. In addition, the privileges that are checked when resources are requested are based on the privileges granted to the current user.

In addition, for Java stored procedures, the call specifications use a PL/SQL wrapper. So, you could specify definer's rights on either the call specification or on the Java class itself. If either is redefined to definer's rights, then the called method executes under the user that deployed the Java class.

By default, Java stored procedures execute without changing the current user—that is, with the privileges of their invoker, not their definer. Invoker-rights procedures are not bound to a particular schema. Their unqualified references to schema objects (such as database tables) are resolved in the schema of the current user, not the definer.

On the other hand, definer-rights procedures are bound to the schema in which they reside. They execute with the privileges of their definer, and their unqualified references to schema objects are resolved in the schema of the definer.

Invoker-rights procedures let you reuse code and centralize application logic. They are especially useful in applications that store data in different schemas. In such cases, multiple users can manage their own data using a single code base.

Consider a company that uses a definer-rights procedure to analyze sales. To provide local sales statistics, the procedure analyze must access sales tables that reside at each regional site. To do so, the procedure must also reside at each regional site. This causes a maintenance problem.

To solve the problem, the company installs an invoker-rights (IR) version of the procedure analyze at headquarters. Now, as Figure 2-4 shows, all regional sites can use the same procedure to query their own sales tables.

Figure 2-4 Invoker-Rights Solution

Occasionally, you might want to override the default invoker-rights behavior. Suppose headquarters would like the procedure analyze to calculate sales commissions and update a central payroll table. That presents a problem because invokers of analyze should not have direct access to the payroll table, which stores employee salaries and other sensitive data. As Figure 2-5 shows, the solution is to have procedure analyze call the definer-rights (DR) procedure calcComm, which, in turn, updates the payroll table.

Figure 2-5 Indirect Access

To override the default invoker-rights behavior, specify the loadjava option -definer, which is similar to the UNIX facility setuid, except that -definer applies to individual classes, not whole programs. Alternatively, you can execute the SQL DDL that changes the AUTHID of the current user.

Different definers can have different privileges, and applications can consist of many classes. So, use the option -definer carefully, making sure that classes have only the privileges they need.

2.5.6 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-7 below.

SQL> SELECT dbms_java.longname(object_name) FROM user_objects 

     WHERE object_type='JAVA SOURCE';

SQL*Plus> SELECT object_type FROM user_objects 

          WHERE object_name=dbms_java.shortname('known_fullname');

SQL> select * from javasnm;

SHORT                          LONGNAME

----------------------------------------------------------------------

/78e6d350_BinaryExceptionHandl sun/tools/java/BinaryExceptionHandler

/b6c774bb_ClassDeclaration     sun/tools/java/ClassDeclaration

/af5a8ef3_JarVerifierStream1   sun/tools/jar/JarVerifierStream$1

COL object_name format a30

COL object_type format a15

SELECT object_name, object_type, status

   FROM user_objects

   WHERE object_type IN ('JAVA SOURCE', 'JAVA CLASS', 'JAVA RESOURCE')

   ORDER BY object_type, object_name;

SELECT object_name, object_type, status

   FROM user_objects

   WHERE object_name LIKE '%Alerter';

2.5.7 Publishing

Oracle Database enables clients and SQL to invoke Java methods that are loaded within the database, once published. You publish either the object itself or individual methods. 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. 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. See Chapter 6, "Publishing Java Classes With Call Specs" for more details.

2.8.1 Supply the ClassLoader in Class.forName

Oracle Database uses resolvers for locating classes within schemas. Every class has a specified resolver associated with it and each class can have a different resolver associated with it. Thus, the locating of classes is dependent on the definition of the associated resolver. The ClassLoader knows which resolver to use, based upon the class that is specified. When you supply a ClassLoader to Class.forName(), your class is looked up in the schemas defined within the resolver of the class. The syntax for this variant of Class.forName is as follows:

Class forName (String name, boolean initialize, ClassLoader loader);

The following examples show how to supply the class loader of either the current class instance or the calling class instance.

Class c1 = Class.forName (x.whatClass(), true, x.getClass().getClassLoader());

void workForCaller() {

ClassLoader c1 =   oracle.aurora.vm.OracleRuntime.getCallerClass().getClassLoader();

...

Class c = Class.forName (name, true, c1);

2.8.2 Supply Class and Schema Names to classForNameAndSchema

You can resolve the problem of where to find the class by either supplying the resolver, which knows the schemas to search, or by supplying the schema in which the class is loaded. If you know in which schema the class is loaded, you can use the classForNameAndSchema method. Oracle Database provides a method in the DbmsJava class, which takes in both the name of the class and the schema in which the class resides. This method locates the class within the designated schema.

import oracle.aurora.rdbms.ClassHandle;

import oracle.aurora.rdbms.Schema;

import oracle.aurora.rdbms.DbmsJava;


void save (Class c1) {

ClassHandle handle = ClassHandle.lookup(c1);

Schema schema = handle.schema();

writeNmae (schema.getName());

writeName (c1.getName());

}


Class restore() {

String schemaName = readName();

String className = readName();

return DbmsJava.classForNameAndSchema (schemaName, className);

}

2.8.3 Supply Class and Schema Names to lookupClass

You can supply a single String, containing both the schema and class names, to the oracle.aurora.util.ClassForName.lookupClass method. When invoked, this method locates the class in the specified schema. The string must be in the following format:

"<schema>:<class>"

For example, to locate com.package.myclass in schema SCOTT, execute the following:

oracle.aurora.util.ClassForName.lookupClass("SCOTT:com.package.myclass");

2.8.4 Supply Class and Schema Names when Serializing

When you de-serialize a class, part of the operation is to lookup a class based on a name. In order to ensure that the lookup is successful, the serialized object must contain both the class and schema names.

Oracle Database provides the following classes for serializing and de-serializing objects:

• oracle.aurora.rdbms.DbmsObjectOutputStream

This class extends java.io.ObjectOutputStream and adds schema names in the appropriate places.

• oracle.aurora.rdbms.DbmsObjectInputStream

This class extends java.io.ObjectInputStream and reads streams written by DbmsObjectOutputStream. You can use this class in any environment. If used within Oracle Database, the schema names are read out and used when performing the class lookup. If used on a client, the schema names are ignored.

2.8.5 Class.forName Example

The following example shows several methods for looking up a class.

• To use the resolver of this instance's class, invoke lookupWithClassLoader. This method supplies a class loader to the Class.forName method in the from variable. The class loader specified in the from variable defaults to this class.

• To use the resolver from a specific class, call ForName with the designated class name, followed by lookupWithClassLoader. The ForName method sets the from variable to the specified class. The lookupWithClassLoader method uses the class loader from the specified class.

• To use the resolver from the calling class, first invoke the ForName method without any parameters. It sets the from variable to the calling class. Then, invoke the lookupWithClassLoader to locate the class using the resolver of the calling class.

• To lookup a class in a specified schema, invoke the lookupWithSchema method. This provides the class and schema name to the classForNameAndSchema method.

import oracle.aurora.vm.OracleRuntime;

import oracle.aurora.rdbms.Schema;

import oracle.aurora.rdbms.DbmsJava;


public class ForName {


  private Class from;

  /* Supply an explicit class to the constructor */

  public ForName(Class from) {

    this.from = from;

  }

  /* Use the class of the code containing the "new ForName()" */

  public ForName() {

    from = OracleRuntime.getCallerClass();

  }


  /* lookup relative to Class supplied to constructor */

  public Class lookupWithClassLoader(String name) throws ClassNotFoundException {

    /* A ClassLoader uses the resolver associated with the class*/

    return Class.forName(name, true, from.getClassLoader());

  }


  /* In case the schema containing the class is known */

  static Class lookupWithSchema(String name, String schema) {

    Schema s = Schema.lookup(schema);

    return DbmsJava.classForNameAndSchema(name, s);

  }

}

2.9.1 Overview of Operating System Resources

In general, your operating system resources contain the following:

2.9.2 Garbage Collection and Operating System Resources

Imagine that memory is divided into two realms: Java object memory and operating system constructs. The Java object memory realm contains all objects and variables. Operating system constructs include resources that the operating system allocates to the object when it asks. These resources include files, sockets, and so on.

Basic programming rules dictate that you close all memory—both Java objects and operating system constructs. Java programmers incorrectly assume that all memory is freed by the garbage collector. The garbage collector was created to collect all unused Java object memory. However, it does not close any operating system constructs. All operating system constructs must be closed by the program before the Java object is collected.

For example, whenever an object opens a file, the operating system creates the file and gives the object a file handle. If the file is not closed, the operating system will hold the file handle construct open until the call ends or JVM exits. This can cause you to run out of these constructs earlier than necessary. There are a finite number of handles within each operating system. To guarantee that you do not run out of handles, close your resources before exiting the method. This includes closing the streams attached to your sockets. You should close the streams attached to the socket before closing the socket.

So why not expand the garbage collector to close all operating system constructs? For performance reasons, the garbage collector cannot examine each object to see if it contains a handle. Thus, the garbage collector collects Java objects and variables, but does not issue the appropriate operating system methods for freeing any handles.

Example 2-4 shows how you should close the operating system constructs.

public static void addFile(String[] newFile) {

 File inFile = new File(newFile);

 FileReader in = new FileReader(inFile);

 int i;


 while ((i = in.read()) != -1)

    out.write(i);

 /*closing the file, which frees up the operating system file handle*/

 in.close();

 }

2.10.1 Thread Life Cycle

In the single-threaded execution case, the call ends when one of the following events occurs:

1. The thread returns to its caller.

2. An exception is thrown and is not caught in Java code.

3. The System.exit(), oracle.aurora.vm.OracleRuntime.exitCall() method is invoked.

If the initial thread creates and starts other Java threads, the rules about when a call ends are slightly more complicated. In this case, the call ends in one of the following two ways:

1. The main thread returns to its caller, or an exception is thrown and not caught in this thread, and all other non-daemon threads complete execution. Non-daemon threads complete either by returning from their initial method or because an exception is thrown and not caught in the thread.

2. Any thread invokes the System.exit() or oracle.aurora.vm.OracleRuntime.exitCall() method.

In shared server mode, when a call ends because of a return or uncaught exceptions, the OracleJVM throws a ThreadDeathException in all daemon threads. The ThreadDeathException essentially forces threads to stop execution. For other considerations, see "Operating System Resources Affected Across Calls".

In both dedicated and shared server mode, when a call ends because of a call to System.exit() or oracle.aurora.vm.OracleRuntime.exitCall(), the OracleJVM ends the call abruptly and terminates all threads, but does not throw ThreadDeathException.

During the execution of a single call, a Java program can recursively cause more Java code to be executed. For example, your program can issue a SQL query using JDBC or SQLJ that in turn causes a trigger written in Java to be invoked. All the preceding remarks regarding call lifetime apply to the top-most call to Java code, not to the recursive call. For example, a call to System.exit() from within a recursive call will exit the entire top-most call to Java, not just the recursive call.

2.11.1 End-of-Call Migration

In shared server mode, Oracle Database preserves the state of your Java program between calls by migrating all objects that are reachable from static variables into session space at the end of the call. Session space exists within the client's session to store static variables and objects that exist between calls. OracleJVM performs this migration operation at the end of every call, without any intervention by you.

This migration operation is a memory and performance consideration; thus, you should be aware of what you designate to exist between calls, and keep the static variables and objects to a minimum. If you store objects in static variables needlessly, you impose an unnecessary burden on the memory manager to perform the migration and consume per-session resources. By limiting your static variables to only what is necessary, you help the memory manager and improve your server's performance.

To maximize the number of users who can execute your Java program at the same time, it is important to minimize the footprint of a session. In particular, to achieve maximum scalability, an inactive session should take up as little memory space as possible. A simple technique to minimize footprint is to release large data structures at the end of every call. You can lazily recreate many data structures when you need them again in another call. For this reason, the OracleJVM has a mechanism for calling a specified Java method when a session is about to become inactive, such as at end-of-call time.

This mechanism is the EndOfCallRegistry notification. It enables you to clear static variables at the end of the call and reinitialize the variables using a lazy initialization technique when the next call comes in. You should execute this only if you are concerned about the amount of storage you require the memory manager to store in between calls. It becomes a concern only for more complex stateful server applications you implement in Java.

The decision of whether to null-out data structures at end-of-call and then recreate them for each new call is a typical time and space trade-off. There is some extra time spent in recreating the structure, but you can save significant space by not holding on to the structure between calls. In addition, there is a time consideration, because objects—especially large objects—are more expensive to access after they have been migrated to session space. The penalty results from the differences in representation of session, as opposed to call-space based objects.

Examples of data structures that are candidates for this type of optimization include:

• Buffers or caches.

• Static fields, such as Arrays, that once initialized, can remain unchanged during the course of the program.

• Any dynamically built data structure that could have a space-efficient representation between calls and a more speed-efficient representation for the duration of a call. Because this can be tricky and complicate your code, making it hard to maintain, so you should consider doing this only after demonstrating that the space saved is worth the effort.

public static void registerCallback(Callback thunk, Object value);

public static void registerCallback(Callback thunk);

static void runCallbacks()

Interface oracle.aurora.memoryManager.Callback

public void act(Object value)

2.11.2 Operating System Resources Affected Across Calls

In shared server mode, the OracleJVM closes any open operating system resources at the end of a database call, as shown in the following table:

You should close resources that are local to a single call when the call ends. However, for static objects that hold on to operating system resources, you must be aware of how these resources are affected after the call ends.

public class Concat {

  static File outFile = new File("outme.txt");

  FileWriter out = new FileWriter(outFile);


public static void addFile(String[] newFile) {

 File inFile = new File(newFile);

 FileReader in = new FileReader(inFile);

 int i;


 while ((i = in.read()) != -1)

    out.write(i);

 in.close();

 }

}

public class Concat {


public static void addFile(String[] newFile) {

 /*open the output file each call; make sure the input*/

 /*file is written out to the end by making it "append=true"*/

 FileWriter out = new FileWriter("outme.txt", TRUE); 

 File inFile = new File(newFile);

 FileReader in = new FileReader(inFile);

 int i;


 while ((i = in.read()) != -1)

    out.write(i);

 in.close();

 /*close the output file between calls*/

 out.close();

 }

}