The ORA_JAVA
built-in package provides a function and a procedure
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 the ORA_JAVA
package 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 function and procedure 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.
To mark an object as a global reference, use the ORA_JAVA.NEW_GLOBAL_REF
function. This built-in function 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.
To unmark an object as a global reference, use the ORA_JAVA.DELETE_GLOBAL_REF
procedure. This built-in procedure takes the global object as a parameter and
removes it as a global reference.
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.
Consider the case where a Java Vector object is to be used to collate data from several different locations in Reports application code. To do this:
create an instance of the Java object using the generated Vector PL/SQL package
create a global reference from the Java object and store it in a package variable
use the package variable whenever we want to reference the original Java Vector object to add an element to the Vector object
destroy the global reference when it is not longer necessary to access the Vector object
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;
Copyright © 1984, 2005, Oracle. All rights reserved.