A script-enabled browser is required for this page to function properly.

Controlling Java Object Persistence

The ORA_JAVA package provides two Built-ins that allow you to explicitly control the persistence of any Java objects you create. By default, when you create a Java object in PL/SQL (by calling a constructor or using an ORA_JAVA Built-in to create an object), the persistence of the object is the duration of the PL/SQL trigger from which the object was created.

Once the program unit has completed, the Java objects are freed by the JVM. Using the persistence functions in the ORA_JAVA package, you can mark an object you create as global, which means that the object will not be freed by the JVM when the program unit ends. The object will remain valid until you explicitly unmark it as a global which allows the JVM to free the object when the next round of garbage collection runs.

Marking a Java Object as Persistent

To mark an object as a global reference, use the ORA_JAVA.NEW_GLOBAL_REF. This Built-in takes the object you wish to make global as a parameter and returns a new object that is the global version of the original object. Since PL/SQL does not have global variables, you will need to store the returned global object in a package variable so that its value is kept.

Unmarking a Java Object

To unmark an object as a global reference, use the ORA_JAVA.DELETE_GLOBAL_REF. This Built-in takes the global object as a parameter and removes it as a global reference.

Persistent Objects and Memory Considerations

Using these Built-ins changes the way that objects are managed by the JVM. You should take care that for any long-running process, you delete any global references you have created when you no longer have any use for them. Accumulating large numbers of global references without removing them will increase the memory consumption of the JVM and will affect the scalability of your application.

Example

Consider the case where a Java Vector object is to be used to collate data from several different locations in Forms application code. To do this:

The following code sample shows the declaration of a PL/SQL package to store global references:

PACKAGE globals AS
   vec ora_java.jobject;
END;
The following code sample shows a PL/SQL trigger unit creating a persistent object:
DECLARE
   vec ora_java.jobject;
BEGIN
   vec := Vector.new;
   globals.vec := ORA_JAVA.NEW_GLOBAL_REF(vec);
END;

The following code sample shows the PL/SQL trigger unit accessing the persistent object to add data:

BEGIN
  . . .
  Vector.add (globals.vec,’some data’);
  . . .
END;

The following code sample shows the deletion of the global reference:

BEGIN 
   ...
   ORA_JAVA.DELETE_GLOBAL_REF(vec);
   ...
END;

NEW_GLOBAL_REF Built-in

DELETE_GLOBAL_REF Built-in