2 Java Applications on Oracle Database

Compiling Java Classes

Compilation of the Java source code can be done in one of the following ways:

• You can compile the source explicitly on a client system 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, which is managed by the loadjava utility.

• You can force the compilation to occur dynamically at run time.

This section includes the following topics:

• Compiling Source Through javac

• Compiling Source Through loadjava

• Compiling Source at Run Time

• Specifying Compiler Options

• Recompiling Automatically

javac -encoding

PROCEDURE set_compiler_option(name VARCHAR2, option VARCHAR2, value VARCHAR2);

FUNCTION get_compiler_option(name VARCHAR2, option VARCHAR2) RETURNS VARCHAR2;

PROCEDURE reset_compiler_option(name VARCHAR2, option VARCHAR2);

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

Resolving Class Dependencies

Many Java classes contain references to other classes, which is the essence of reusing code. A conventional JVM searches for .class, .zip, and .jar files within the directories specified in CLASSPATH. In contrast, the Oracle JVM searches database schemas for class objects. In Oracle Database, because you load all Java classes into the database, you may 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 predefined Java application programming interfaces (APIs), such as java.lang.* , are loaded within the PUBLIC schema. If your classes depend on other classes you have defined, then you will probably load them all within your own schema. For example, if your schema is SCOTT, the database resolver searches the SCOTT schema before searching the PUBLIC schema. The listing of schemas to search is known as a resolver specification. Resolver specifications are defined for each class. This is in contrast to a classic JVM, where 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, then the class is listed as invalid. Unsuccessful resolution at run time produces a ClassNotFound exception. Also, run-time 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 specification for a valid class schema object that satisfies the reference. If all references are resolved, then 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 specification that searches the definer's schema first and then searches the PUBLIC schema. 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 specification.

Classes can be resolved in the following ways:

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

  loadjava -resolve
  
  

• Loading using your own resolver specification definition:

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

  In the preceding example, the resolver specification definition includes the SCOTT schema, OTHER schema, and PUBLIC.

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

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

The first parameter within the resolver specification is for the class schema object, and the second parameter defines the schema within which to search for these class schema objects.

Allowing References to Nonexistent Classes

You can specify a special option within a resolver specification that allows an unresolved reference to a nonexistent class. Sometimes, internal classes are never used within a product. In a normal Java environment, this is not a problem, because as long as the methods are not called, the JVM ignores them. However, the Oracle Database resolver tries to resolve all classes referenced within the JAR file, including the unused classes. If the reference cannot be validated, then the classes within the JAR file are marked as invalid.

To ignore references, you can specify the wildcard, minus sign (-), within the resolver specification. 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 specification schema list.

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

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.

In addition, you can define that all classes not found are to be ignored. However, this is dangerous, because a class that has a dependent class will be marked as valid, even if the dependent class does not exist. However, the class can never run without the dependent class. In this case, you will receive an exception at run time.

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

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

If you later intend to load the nonexistent classes that required you to use such a resolver, then you should not use a resolver containing the minus sign (-) wildcard. 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 Oracle JVM, the verification process occurs at class resolution. The resolver may find one of the following problems and issue the appropriate Oracle error code:

A resolver with the minus sign (-) wildcard marks your class valid, regardless of whether classes referenced by your class are present. Because of inheritance and interfaces, you may want to write valid Java methods that use an instance of a class as if it were an instance of a superclass or of a specific interface. When the method being verified uses a reference to class A as if it were a reference to class B, the resolver must check that A either extends or implements B. For example, consider the following potentially valid method, whose signature implies a return of an instance of B, but whose body returns an instance of A:

B myMethod(A a)
{ 
  return a; 
}

The method is valid only if A extends B or A implements the interface B. If A or B have been resolved using the minus sign (-) wildcard, then the resolver does not know that this method is safe. In this case, the resolver replaces the bytecodes of myMethod with bytecodes that throw an exception if myMethod is called.

A resolver without the minus sign (-) wildcard ensures that the class definitions of A and B are found and resolved properly if they are present in the schemas they specifically identify. The only time you may consider using the alternative resolver is if you must load an existing JAR file containing classes that reference other nonsystem classes, which are not included in the JAR file.

Loading Classes

This section gives an overview of loading your classes into the database using the loadjava utility. You can also run loadjava from within SQL commands.

Unlike a conventional JVM, which compiles and loads from files, the Oracle JVM 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 run your classes within the database.

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

The dropjava utility performs the reverse of loadjava. It deletes schema objects that correspond to Java files. Always use dropjava to delete a Java schema object created with loadjava. Dropping with SQL data definition language (DDL) commands will not update the auxiliary data maintained by loadjava and dropjava. You can also run dropjava from within SQL commands.

After loading the classes and resources, you can access the USER_OBJECTS view in your database schema to verify whether your classes and resources have been loaded properly.

Defining the Same Class Twice

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

• You can load either a particular Java .class file or its .java file, but not both.

  Oracle Database tracks whether you loaded a class file or a source file. If you want to update the class, then you must load the same type of file that you originally loaded. If you want to update the other type, then you must drop the first before loading the second. For example, if you loaded x.java as the source for class y, then to load x.class, you must first drop x.java.

• You cannot define the same class within two different schema objects in the same schema. For example, suppose x.java defines class y and you want to move the definition of y to z.java. If x.java has already been loaded, then loadjava rejects any attempt to load z.java, which also defines y. Instead, do either of the following:

  • Drop x.java, load z.java, which defines y, and then load the new x.java, which does not define y.

  • Load the new x.java, which does not define y, and then load z.java, which defines y.

Designating Database Privileges and JVM Permissions

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

• CREATE PROCEDURE and CREATE TABLE privileges to load into your schema.

• CREATE ANY PROCEDURE and CREATE ANY TABLE privileges to load into another schema.

• oracle.aurora.security.JServerPermission.loadLibraryInClass. classname.

  See Also:

  "Permission for Loading Classes"

Loading JAR or ZIP Files

The loadjava utility 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 a JAR or ZIP file to loadjava, it opens the archive and loads the members of the archive 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, then 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.

Granting Execute Rights

If you load all classes within your own schema and do not reference any class outside your schema, then you already have rights to run the classes. You have the privileges necessary for your objects to call other objects loaded in the same schema. That is, the ability for class A to call class B. Class A must be given the right to call 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 cannot be run by other users, because of security concerns. You can provide other users the right to run your class through the loadjava -grant option. You can grant rights to run your classes to a certain user or schema, but you cannot grant rights to a role, which includes the superuser DBA role. The setting of rights to run classes is the same as used to grant or revoke privileges in SQL DDL statements.

Figure 2-3 Rights to Run Classes

Description of "Figure 2-3 Rights to Run Classes"

Controlling the Current User

When running Java or PL/SQL code, 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 running SQL, PL/SQL, or Java Database Connectivity (JDBC). The current user controls the interpretation of SQL and determines privileges. For example, if a table is referenced by a simple name, then it is assumed that the table belongs to 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. Therefore, you can 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 runs under the user that deployed the Java class.

By default, Java stored procedures run without changing the current user, that is, with the privileges of their invoker, and 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, and not the definer.

On the other hand, definer-rights procedures are bound to the schema in which they reside. They run 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 this, the procedure must also reside at each regional site. This causes a maintenance problem.

To solve the problem, the company installs an invoker-rights 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

Description of "Figure 2-4 Invoker-Rights Solution"

Occasionally, you may want to override the default invoker-rights behavior. Suppose headquarters wants the analyze procedure to calculate sales commissions and update a central payroll table. This 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 shown in Figure 2-5, the solution is to have the analyze procedure call the definer-rights procedure, calcComm, which in turn updates the payroll table.

Figure 2-5 Indirect Access

Description of "Figure 2-5 Indirect Access"

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

Different definers can have different privileges, and applications can consist of many classes. Therefore, use the -definer option carefully ensuring that classes have only the required privileges.

Checking Java Uploads

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

Table 2-7 lists the key columns in USER_OBJECTS and their description.

Object Name and Type

An OBJECT_NAME in USER_OBJECTS is the alias. The fully qualified name is stored as an alias if it exceeds 31 characters.

If the server uses an alias for a schema object, then you can use the LONGNAME() function of the DBMS_JAVA package to receive it from a query as a fully qualified name, without having to know the alias or the conversion rules.

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

This statement displays the fully qualified name of the Java source schema objects. Where no alias is used, no conversion occurs.

You can use the SHORTNAME() function of the DBMS_JAVA package to use a fully qualified name as a query criterion, without having to know whether it was converted to an alias in the database.

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

This statement displays the OBJECT_TYPE of the schema object with the specified fully qualified name. This presumes that the fully qualified name is representable in the database character set.

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

Status

STATUS is a character string that indicates the validity of a Java schema object. A Java source schema object is VALID if it compiled successfully, and a Java class schema object is VALID if it was resolved successfully. A Java 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
       WHERE object_type IN ('JAVA SOURCE', 'JAVA CLASS', 'JAVA RESOURCE')
       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';

The preceding statement finds any OBJECT_NAME entries that end with the characters Alerter.

Publishing

Oracle Database enables clients and SQL to call Java methods that are loaded in the database after they are published. You publish either the object itself or individual methods. If you write a Java stored procedure that you intend to call with a trigger, directly or indirectly in SQL data manipulation language (DML) or in PL/SQL, then you must publish individual methods in the class. Using a call specification, specify how to access the method. Java programs consist of many methods in many classes. However, only a few static methods are typically exposed with call specifications.

Auditing

In releases prior to Oracle Database 10g release 2 (10.2), Java classes in the database cannot be audited directly. However, you can audit the PL/SQL wrapper. Typically, all Java stored procedures are started from some wrappers. Therefore, all Java stored procedures can be audited, though not directly.

In Oracle Database 10g release 2 (10.2), you can audit DDL statements for creating, altering, or dropping Java source, class, and resource schema objects, as with any other DDL statement. Oracle Database 10g release 2 (10.2) provides auditing options for auditing Java activities easily and directly. You can also audit any modification of Java sources, classes, and resources.

You can audit database activities related to Java schema objects at two different levels, statement level and object level. At the statement level you can audit all activities related to a special pattern of statements. Table 2-8 lists the statement auditing options and the corresponding SQL statements related to Java schema objects.

For example, if you want to audit the ALTER JAVA SOURCE DDL statement, then enter the following statement at the SQL prompt:

AUDIT ALTER JAVA SOURCE

Object level auditing provides finer granularity. It enables you to identify specific problems by zooming into specific objects. Table 2-9 lists the object auditing options for each Java schema object. The entry X in a cell indicates that the corresponding SQL command can be audited for that Java schema object. The entry NA indicates that the corresponding SQL command is not applicable for that Java schema object.

Supply 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. As a result, the locating of classes is dependent on the definition of the associated resolver. The ClassLoader instance knows which resolver to use, based on the class that is specified. When you supply a ClassLoader instance to Class.forName(), your class is looked up in the schemas defined in the resolver of the class. The syntax of 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);
  ...
}

Supply Class and Schema Names to classForNameAndSchema()

You can resolve the problem of where to find the class by supplying the resolver, which can identify the schemas to be searched. Alternatively, you can supply the schema in which the class is loaded. If you know in which schema the class is loaded, then you can use the classForNameAndSchema() method, which is in the DbmsJava class provided by Oracle Database. This method takes both the name of the class and the schema in which the class resides and 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();
  writeName (schema.getName());
  writeName (c1.getName());
}

Class restore()
{
  String schemaName = readName();
  String className = readName();
  return DbmsJava.classForNameAndSchema (schemaName, className);
}

Supply Class and Schema Names to lookupClass()

You can supply a String value containing both the schema and class names to the oracle.aurora.util.ClassForName.lookupClass() method. When called, 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 the SCOTT schema, use the following:

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

Supply Class and Schema Names when Serializing

When you deserialize a class, part of the operation is to lookup a class based on a name. 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 deserializing 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, then the schema names are read out and used when performing the class lookup. If used on a client, then the schema names are ignored.

Class.forName Example

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

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

The preceding example uses the following methods for locating a class:

• To use the resolver of the class of an instance, call 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 call the ForName() method without any parameters. It sets the from variable to the calling class. Then, call the lookupWithClassLoader() method to locate the class using the resolver of the calling class.

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

Overview of Operating System Resources

In general, your operating system resources contain the following:

Operating System Resource Access

By default, a Java user does not have direct access to most operating system resources. A system administrator can give permissions to a user to access these resources by modifying the JVM security restrictions. The JVM security enforced upon system resources conforms to Java2 security.

Operating System Resource Lifetime

You can access operating system resources using the standard core Java classes and methods. Once you access a resource, the time that it remains active varies according to the type of resource. Memory is garbage collected. Files, threads, and sockets persist across calls when you use a dedicated mode server. In shared server mode, files, threads, and sockets terminate when the call ends.

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 memory is freed by the garbage collector. The garbage collector was created to collect all unused Java object memory. However, it does not close operating system constructs. All operating system constructs must be closed by the program before the Java object is garbage 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, then the operating system holds the file handle construct open until the call ends or JVM exits. This may 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 before closing the socket.

For performance reasons, the garbage collector cannot examine each object to see if it contains a handle. As a result, 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 to 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();
}

If you do not close inFile, then eventually the File object will be garbage collected. Even after the File object is garbage collected, the operating system treats the file as if it were in use, because it was not closed.

End-of-Call Migration

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

This migration operation is a memory and performance consideration. Hence, 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, then 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 the performance of your server.

To maximize the number of users who can run 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 re-create many data structures when you need them again in another call. For this reason, the Oracle JVM has a mechanism for calling a specified Java method when a session is about to become inactive, such as at the end of a call.

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 run 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 complex stateful server applications that you implement in Java.

The decision of whether to null-out data structures at the end of the call and then re-create them for each new call is a typical time and space trade-off. There is some extra time spent in re-creating 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 objects based on call-space.

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

• Buffers or caches.

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

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

Oracle-Specific Support for End-of-Call Optimization

You can register the static variables that you want cleared at the end of the call when the buffer, field, or data structure is created. Within the oracle.aurora.memoryManager.EndOfCallRegistry class, the registerCallback() method takes an object that implements a Callback object. The registerCallback() method stores this object until the end of the call. At the end of the call, the Oracle JVM calls the act() method within all registered Callback objects. The act() method within the Callback object is implemented to clear the user-defined buffer, field, or data structure. Once cleared, the Callback object is removed from the registry.

A weak table holds the registry of end-of-call callbacks. If either the Callback object or value are not reachable from the Java program, then both the object and the value will be dropped from the table. The use of a weak table to hold callbacks also means that registering a callback will not prevent the garbage collector from reclaiming that object. Therefore, you must hold on to the callback yourself if you need it, and you cannot rely on the table holding it back.

The way you use EndOfCallRegistry depends on whether you are dealing with objects held in static fields or instance fields.

Static fields

Use EndOfCallRegistry to clear state associated with an entire class. In this case, the Callback object should be held in a private static field. Any code that requires access to the cached data that was dropped between calls must call a method that lazily creates, or re-creates, the cached data.

Consider the following example:

import oracle.aurora.memoryManager.Callback;
import oracle.aurora.memoryManager.EndOfCallRegistry;

class Example
{
  static Object cachedField = null;
  private static Callback thunk = null;

  static void clearCachedField()
  {
    // clear out both the cached field, and the thunk so they don't
    // take up session space between calls
    cachedField = null;
    thunk = null;
  }

  private static Object getCachedField()
  {
    if (cachedField == null) 
    {
      // save thunk in static field so it doesn't get reclaimed
      // by garbage collector
      thunk = new Callback () {
        public void act(Object obj)
        {
          Example.clearCachedField();
        }
      };
      
      // register thunk to clear cachedField at end-of-call.
      EndOfCallRegistry.registerCallback(thunk);
      // finally, set cached field
      cachedField = createCachedField();
    }
    return cachedField;
  }

  private static Object createCachedField()
  {
    ...
  }
}

The preceding example does the following:

1. Creates a Callback object within a static field, thunk.

2. Registers this Callback object for end-of-call migration.

3. Implements the Callback.act() method to free up all static variables, including the Callback object itself.

4. Provides a method, createCachedField(), for lazily re-creating the cache.

When the user creates the cache, the Callback object is automatically registered within the getCachedField() method. At end-of-call, the Oracle JVM calls the registered Callback.act() method, which frees the static memory.

Instance fields

Use EndOfCallRegistry to clear state in data structures held in instance fields. For example, when a state is associated with each instance of a class, each instance has a field that holds the cached state for the instance and fills in the cached field as necessary. You can access the cached field with a method that ensures the state is cached.

Consider the following example:

import oracle.aurora.memoryManager.Callback;
import oracle.aurora.memoryManager.EndOfCallRegistry;

class Example2 implements Callback
{
  private Object cachedField = null;

  public voidact (Object obj)
  {
    // clear cached field
    cachedField = null;
    obj = null;
  }

  // our accessor method
  private static Object getCachedField()
  {
    if (cachedField == null)
    {
      // if cachedField is not filled in then we need to
      // register self, and fill it in.
      EndOfCallRegistry.registerCallback(self);
      cachedField = createCachedField();
    }
    return cachedField;
  }

  private Object createCachedField()
  {
    ...
  }
}

The preceding example does the following:

1. Implements the instance as a Callback object.

2. Implements the Callback.act() method to free up the instance fields.

3. When the user requests a cache, the Callback object registers itself for the end-of-call migration.

4. Provides a method, createCachedField(), for lazily re-creating the cache.

When the user creates the cache, the Callback object is automatically registered within the getCachedField() method. At end-of-call, the Oracle JVM calls the registered Callback.act() method, which frees the cache.

This approach ensures that the lifetime of the Callback object is identical to the lifetime of the instance, because they are the same object.

The EndOfCallRegistry.registerCallback() Method

The registerCallback() method installs a Callback object within a registry. At the end of the call, the Oracle JVM calls the act() method of all registered Callback objects.

You can register your Callback object by itself or with an Object instance. If you need additional information stored within an object to be passed into act(), then you can register this object with the value parameter, which is an instance of Object.

The following are the valid signatures of the registerCallback() method:

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

public static void registerCallback(Callback thunk);

The following table lists the parameters of registerCallback and their description:

The EndOfCallRegistry.runCallbacks() Method

The signature of the runCallbacks() method is as follows:

static void runCallbacks()

The JVM calls this method at end-of-call and calls act() for every Callback object registered using registerCallback(). It is called at end-of-call, before object migration and before the last finalization step.

The Callback Interface

The interface is declared as follows:

Interface oracle.aurora.memoryManager.Callback

Any object you want to register using EndOfCallRegistry.registerCallback() must implement the Callback interface. This interface can be useful in your application, where you require notification at end-of-call.

The Callback.act() method

The signature of the act() method is as follows:

public void act(Object value)

You can implement any activity that you require to occur at the end of the call. Normally, this method contains procedures for clearing any memory that would be saved to session space.

Operating System Resources Affected Across Calls

In the shared server mode, the Oracle JVM 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.

Files

In the shared server mode, the Oracle JVM automatically closes open operating system constructs when the call ends. This can affect any operating system resources within your Java object. If you have a file opened within a static variable, then the file handle is closed at the end of the call for you. Therefore, if you hold on to the File object across calls, then the next usage of the file handle throws an exception.

In Example 2-5, the Concat class enables multiple files to be written into a single file, outFile. On the first call, outFile is created. The first input file is opened, read, written to outFile, and the call ends. Because outFile is defined as a static variable, it is moved into session space between call invocations. However, the file handle is closed at the end of the call. The next time you call addFile(), you will get an exception.

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

There are workarounds. To ensure that your handles stay valid, close your files, buffers, and so on, at the end of every call, and reopen the resource at the beginning of the next call. Another option is to use the database rather than using operating system resources. For example, try to use database tables rather than a file. Alternatively, do not store operating system resources within static objects that are expected to live across calls. Instead, use operating system resources only within objects local to the call.

Example 2-6 shows how you can perform concatenation, as in Example 2-5, without compromising your operating system resources. The addFile() method opens the outme.txt file within each call, ensuring that anything written into the file is appended to the end. At the end of each call, the file is closed. Two things occur:

• The File object no longer exists outside a call.

• The operating system resource, the outme.txt file, is reopened for each call. If you had made the File object a static variable, then the closing of outme.txt within each call would ensure that the operating system resource is not compromised.

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

Sockets

Sockets are used in setting up a connection between a client and a server. For each database connection, sockets are used at either end of the connection. Your application does not set up the connection. The connection is set up by the underlying networking protocol, TTC or IIOP of Oracle Net.

You may also want to set up another connection, for example, connecting to a specified URL from within one of the classes stored within the database. To do so, instantiate sockets for servicing the client and server sides of the connection using the following:

• The java.net.Socket() constructor creates a client socket.

• The java.net.ServerSocket() constructor creates a server socket.

A socket exists at each end of the connection. The server side of the connection that listens for incoming calls is serviced by a ServerSocket instance. The client side of the connection that sends requests is serviced through a Socket instance. You can use sockets as defined within the JVM with the restriction that a ServerSocket instance within a shared server cannot exist across calls.

The following table lists the socket types and their description:

Threads

In the shared server mode, when a call ends because of a return or uncaught exceptions, the Oracle JVM throws ThreadDeathException in all daemon threads. ThreadDeathException essentially forces threads to stop running. Code that depends on threads living across calls does not behave as expected in the shared server mode. For example, the value of a static variable that tracks initialization of a thread may become incorrect in subsequent calls because all threads are killed at the end of a database call.

As a specific example, the RMI Server, which Sun Microsystems supplies, functions in the shared server mode. However, it is useful only within the context of a single call. This is because the RMI Server forks daemon threads, which in the shared server mode are killed at the end of call, that is, when all non-daemon threads return. If the RMI server session is reentered in a subsequent call, then these daemon threads are not restarted and the RMI server fails to function properly.