C
Java Importer

Oracle Forms Developer 6i includes the Java Importer. This appendix includes the following sections covering the description and use of the Java Importer and the resulting files.

C.1 Overview

C.1.1 Importing Java and Building Applications

The Java Importer allows Forms developers to generate PL/SQL packages to access Java classes and then program with the generated PL/SQL in their Forms applications. The PL/SQL generated by the Java Importer is robust, offering support for the original Java class' constructors, methods, and fields.

Beyond simply mapping static methods to PL/SQL functions and procedures, the Java Importer provides support for persistent Java objects, with support for type mapping and array objects.

Forms developers can conveniently access the imported Java through the generated PL/SQL using the new ORA_JAVA package and its built-ins. Internally, the generated PL/SQL packages use the Java Native Interface (JNI) standard and an internal JNI package to act as the bridge between PL/SQL and Java.

C.1.2 Running Applications with Imported Java

Imported Java runs in the middle tier. The corresponding generated PL/SQL package calls into the Java class and the Java methods execute in a dedicated Java Virtual Machine (JVM) on the Form Services. A dedicated JVM is created for each Form Services application instance that uses the generated PL/SQL package to call the imported Java.

C.2 Components

The Java Importer feature includes the following pieces:

the Java Importer tool

The importer tool runs in Form Builder, imports Java classes, and generates PL/SQL packages that provide PL/SQL access to the imported Java. The importer provides a variety of user options for generating the PL/SQL packages.
the runform API, including the ORA_JAVA package

The ORA_JAVA package is a helper package that provides error handling, array, and persistency support. (There is also an internal JNI package used to call Java methods, but you do not need to know the contents of this package or call it directly.)

C.3 Installation Requirements

The Java Importer is installed with Forms 6i Release 2. When installed, the JAR file containing the Java Importer, importer.java, must be in CLASSPATH. By default, the filesystem location for importer.java is ORACLE_HOME/TOOLS/COMMON60/JAVA/importer.jar.

To enable importer operation, however, JDK or JRE 1.2 or higher must be installed on both the builder and server machines.

C.3.1 Imported Java Requirements

To import any Java class with the Java Importer tool, the Java class must be located in the system's CLASSPATH.

C.4 Importing Java

C.4.1 Using the Java Importer Tool

The Java Importer tool provides a convenient Java class browser to easily access and import multiple Java classes. For each Java class selected and imported, the tool generates a PL/SQL package in the current, open module in the object navigator.

C.4.2 Invoke the Import Java Classes dialog box

To display the Import Java Classes dialog box, choose Program->Import Java Classes... from the main menu.

The components and buttons in this dialog box are:

Select Java Classes (browser)

The Class browser provides a hierarchical display of all the Java class files in the order that are defined in the current CLASSPATH environment variable.
The class files (represented by leaf nodes) are organized and displayed in their packages (represented by folder nodes).
Expand/collapse a folder to show/hide the contents.
You can select one or more Java classes (SHIFT-Click in Windows for multiple selection).

Import Classes

This text box displays the fully qualified class names of the class files you have selected. Multiple class names are separated by semi-colons (;).
You can also type the fully qualified class name in this field, which is case-sensitive, e.g., java.lang.String.

Messages

This display-only panel shows the status during the importing process.

Import

This button starts the importing process.
Button is enabled when you have selected one or more class files in the Class browser, or entered a fully qualified class name in the text box.

Options...

Displays the Import Java Class Options dialog box. See Section C.4.3, "Specify options for importing".

Close

Closes this dialog box.

C.4.3 Specify options for importing

To display the Import Java Class Options dialog box, click Options... in the Import Java Classes dialog box.

The options are:

Include inherited methods/fields. Default is not checked. Check this box if you want to map all the inherited methods and fields to procedures and functions. This option generates functions and procedures for all methods contained in the specific class and its predecessors.
Include get/set for public fields. Default is not checked. Check this box if you want to map each public non-constant or non-static field to a function that gets the value and to a procedure that sets the value.
Generate persistent names. Default is not checked. If unchecked, for overloaded Java methods where the generated PL/SQL function and procedure names cannot be resolved to unique PL/SQL signatures, an incremental identifier is appended to the function or procedure name.

Check this box if the Java class you are importing will change and you want to use the same persistent PL/SQL function, procedure, variable, and type names throughout all the changes to the Java class. (Note: You must regenerate the PL/SQL package to access the Java class changes in PL/SQL.) If checked, generated PL/SQL function and procedure names for all Java methods include persistent and unique 4-digit identifiers appended to the names.

The persistent identifier numbers are generated based on the method signature. With "Generate Persistent names" selected, each time the same Java class is imported with the Java Importer, the PL/SQL functions and procedures generated for the same Java methods will have the same 4-digit identifiers appended.

For more information and examples of the standard and persistent naming, refer to Section C.5.1.4.1, "What is different between persistent and default naming?"
Ask before overwriting existing packages. Default is checked. Uncheck this box if you do not want to be prompted before existing PL/SQL packages are overwritten by newly generated packages.

C.4.4 Import a Java class into PL/SQL

Take these steps to import one or more Java class files:

In Forms Builder, open the module (Form module, PL/SQL library, or Menu module) where you want to place the generated PL/SQL packages.
Choose Program->Import Java Classes... from the menu to display the Import Java Classes dialog box.
In the Class browser, select one or more Java class files. You cannot select a directory (folder).

If you do not see the Java class file you want to import, make sure the class file is located in the current classpath.

Note: If you edit the CLASSPATH during a Form Builder session, you must restart the builder so the Java Importer can pick up the CLASSPATH changes.
Click Options... to specify importing options, if required. For additional information, see Section C.4.3, "Specify options for importing".
Click Import to start the importing process.
When done, click OK.

C.5 Building Applications with Imported Java

C.5.1 Description of the Generated PL/SQL

C.5.1.1 What Gets Generated?

The Java Importer generates one PL/SQL package for each class imported. Within each generated PL/SQL package, the Java Importer generates PL/SQL functions and procedures that correspond to Java public fields, methods, and constructors. Private and protected methods do not generate corresponding PL/SQL.

C.5.1.2 How is the Java Mapped to PL/SQL?

The PL/SQL package generated maps Java to PL/SQL as follows:

Java PL/SQL Description

public constructor

function (called "new")

Generates a different "new" function for each public constructor. The "new" function returns an instance of the object.

public method
(with return type)
example:
public int getAge()

function

If an instance method, the instance of the class is passed as first argument to the function to identify the object. If a static method, the instance argument is not necessary.

public method
(with return type void)
public void setAge(int age)

procedure

If an instance method, the instance of the class is passed as first argument to the procedure to identify the object. If a static method, the instance argument is not necessary.

public static constant field
example:
public static final int RETIRE_AGE=60;

package variable
(of appropriate type)

When PL/SQL package is first referenced, initialization code sets value of package variable.

public field
(non-static or non-constant)
example:
public String gender;

Options:
If "Include get/set for public fields" checkbox is selected:

function, procedure

Public field is mapped to a function, which will get the value and procedure, which will set the value. If an instance field, the instance of the class is passed as first argument to the function and procedure. If a static field, the instance argument is not necessary.

If "Include get/set for public fields" checkbox is not selected:

No PL/SQL is generated.

Java	PL/SQL	Description
public constructor	function (called "new")	Generates a different "new" function for each public constructor. The "new" function returns an instance of the object.
public method (with return type) example: public int getAge()	function	If an instance method, the instance of the class is passed as first argument to the function to identify the object. If a static method, the instance argument is not necessary.
public method (with return type void) public void setAge(int age)	procedure	If an instance method, the instance of the class is passed as first argument to the procedure to identify the object. If a static method, the instance argument is not necessary.
public static constant field example: public static final int RETIRE_AGE=60;	package variable (of appropriate type)	When PL/SQL package is first referenced, initialization code sets value of package variable.
public field (non-static or non-constant) example: public String gender;	Options: If "Include get/set for public fields" checkbox is selected:
	function, procedure	Public field is mapped to a function, which will get the value and procedure, which will set the value. If an instance field, the instance of the class is passed as first argument to the function and procedure. If a static field, the instance argument is not necessary.
	If "Include get/set for public fields" checkbox is not selected:
	No PL/SQL is generated.

C.5.1.3 What are the importer mapping options?

The following Java Importer options in the Import Java Class Options dialog box affect the mapping of Java to PL/SQL in the generated PL/SQL package:

If the "Include inherited methods/fields" checkbox is selected, the importer maps inherited methods and fields to the appropriate functions and procedures as described above.
If the "Include get/set for public fields" checkbox is selected, the importer maps each public non-constant or non-static field to a function that gets the value and to a procedure that sets the value. This option is described in the table above.

C.5.1.4 How does PL/SQL naming vary?

The naming convention for the generated PL/SQL is to name the corresponding PL/SQL function or procedure with the same name as the corresponding Java program element. In the following cases, however, the PL/SQL naming will not be identical to the Java program element name:

where the Java name is too long (PL/SQL has a 30-character limit), the importer truncates names longer than 30 characters.
where the Java names are not unique within the first 30-characters, the importer creates unique names within the 30-character PL/SQL maximum.
where Java methods are overloaded and the generated PL/SQL function and procedure names cannot be resolved to unique PL/SQL signatures, the importer appends an incremental identifier to the function or procedure name. (Note: This does not apply when "Generate persistent names" is selected as an import option.)

For example, 2 different Java methods called methodA--methodA(int) and methodA(java.long.Float)--would continue to have the same names in the PL/SQL package because the PL/SQL signatures are unique: methodA(NUMBER) and methodA(ORA_JAVA.JOBJECT).

In another example, however, for 2 different Java methods called methodB--methodB(char) and methodB(byte)--different names are required in the PL/SQL package because the PL/SQL signatures would be identical: methodB(PLS_INTEGER). So the first methodB in the Java class remains methodB in the PL/SQL package, but the second methodB becomes methodB_0.
where the Java names are reserved words in PL/SQL, the importer creates unique names by adding an underscore to the generated PL/SQL name.

For example, a Java method named value would generate the name value_ in the PL/SQL package.

C.5.1.4.1 What is different between persistent and default naming?

Regardless of whether the "Generate persistent names" option is selected in the Import Java Class Options dialog box, the importer creates unique names for all functions and procedures in the PL/SQL package. But the default names (if the "Generate persistent names" option is not selected) and persistent names differ.

What is standard naming?

With standard naming, functions and procedures are generated to the same name as the corresponding Java method, provided the function and procedure names can be unique. In the case of overloaded Java methods where the generated PL/SQL function and procedure names cannot be resolved to unique PL/SQL signatures, the importer appends an incremental identifier to the function or procedure name.

Example 1

Start with the following Java class:

Class myclass
{

public void p1(int x);
public void p1(long x);
public void p1(char x);

Import the class with the Java Importer. Without persistent naming ("Generate persistent names" is not selected), the resulting PL/SQL for the above methods is the following:

-- Method: p1 (C)V
PROCEDURE p1 (

obj   ORA_JAVA.JOBJECT,
a0    PLS_INTEGER);

-- Method: p1 (I)V
PROCEDURE p1_1 (

obj   ORA_JAVA.JOBJECT,
a0    NUMBER);

-- Method: p1 (J)V
PROCEDURE p1_2 (

obj   ORA_JAVA.JOBJECT,
a0    NUMBER);

Note that the procedures were not generated in the order the Java methods appear in the Java class file. The order for the above PL/SQL procedures correspond to the Java methods in this sequence:

public void p1(char x);
public void p1(int x);
public void p1(long x);

Example 2

The following example uses the previous Java class, but with one method--p1(long x)--removed. Start with the following Java class:

Class myclass
{

public void p1(int x);
public void p1(char x);

Import the class with the Java Importer. Without persistent naming ("Generate persistent names" is not selected), the resulting PL/SQL for the above methods is the following:

-- Method: p1 (C)V
PROCEDURE p1 (

obj   ORA_JAVA.JOBJECT,
a0    PLS_INTEGER);

-- Method: p1 (I)V
PROCEDURE p1 (

obj   ORA_JAVA.JOBJECT,
a0    NUMBER);

Note that both procedures are called p1. Because each has a unique signature, the importer resolved each method to a unique procedure signature and did not append an identifier. Note that the removal of a method from the Java class affected the names of the generated procedure names.

What is persistent naming?

Persistent naming forces a persistent and unique 4-digit identifier appended to the end of all function or procedure names. As long as "Generate persistent names" remains selected each time you generate PL/SQL from a Java class--even if the Java class has changed--the functions and procedure names (including appended identifiers) remain the same.

The persistent identifier numbers are generated based on the method signature. With "Generate Persistent names" selected, each time the same Java class is imported with the Java Importer, the PL/SQL functions and procedures generated for the same Java methods will have the same 4-digit identifiers.

Persistent naming is recommended if the Java class you are importing will change and you want to use the same persistent PL/SQL function, procedure, variable, and type names throughout all the changes to the Java class. (Note: You must regenerate the PL/SQL package to access the Java class changes in PL/SQL.)

Example 3

Start with the following Java class:

Class myclass
{

public void p1(int x);
public void p1(long x);
public void p1(char x);

Import the class with the Java Importer. With persistent naming ("Generate persistent names" is selected), the resulting PL/SQL for the above methods is the following:

-- Method: p1 (C)V
PROCEDURE p1_7384 (

obj   ORA_JAVA.JOBJECT,
a0    PLS_INTEGER);

-- Method: p1 (I)V
PROCEDURE p1_3150 (

obj   ORA_JAVA.JOBJECT,
a0    NUMBER);

-- Method: p1 (J)V
PROCEDURE p1_4111 (

obj   ORA_JAVA.JOBJECT,
a0    NUMBER);

Note that all of the procedure names include a unique 4-digit identifier appended to the name.

Example 4

The following example uses the previous Java class, but with one method--p1(long x)--removed. Start with the following Java class:

Class myclass
{

public void p1(int x);
public void p1(char x);

Import the class with the Java Importer. With persistent naming ("Generate persistent names" is selected), the resulting PL/SQL for the above methods is the following:

-- Method: p1 (C)V
PROCEDURE p1_7384 (

obj   ORA_JAVA.JOBJECT,
a0    PLS_INTEGER);

-- Method: p1 (I)V
PROCEDURE p1_3150 (

obj   ORA_JAVA.JOBJECT,
a0    NUMBER);

Note that all of the procedure names include a unique 4-digit identifier appended to the name. Note that these identifiers are the same numbers generated in the previous example (Example 3) and that the removal of a method from the Java class did not effect the numbering, and therefore, the names of the procedures.

C.5.1.5 What happens if I regenerate the PL/SQL?

There are options when regenerating a PL/SQL package from the same Java class. Two options in the Import Java Class Options dialog box can effect how you regenerate the PL/SQL package:

Checking the "Ask before overwriting existing packages" checkbox causes the importer to ask if you want to overwrite the existing package(s). Choose to overwrite the package(s) (and all included functions and procedures) if appropriate.
Refer to Section C.5.1.4.1, "What is different between persistent and default naming?" for information on the difference in the PL/SQL generated when "Generate persistent names" is checked and not checked. Note: Changing the setting for the "Generate persistent names" option from when you last generated a PL/SQL package from the same Java class will change the procedure and function names, because the identifiers appended (or not appended) to the function and procedure names will change.

C.5.2 Java Types

The following lists Java types and the PL/SQL types to which the Java Importer maps them:

Java Type	Converted to...	Notes
Any Java array	ORA_JAVA.JARRAY	ORA_JAVA.JARRAY is subtype of ORA_JAVA.JOBJECT
boolean	BOOLEAN
byte	PLS_INTEGER
char	PLS_INTEGER
double	NUMBER
float	NUMBER
int	NUMBER
long	NUMBER
Any Java object	ORA_JAVA.JOBJECT
short	PLS_INTEGER
java.lang.String	VARCHAR2
Any Java exception	ORA_JAVA.JEXCEPTION	ORA_JAVA.JEXCEPTION is subtype of ORA_JAVA.JOBJECT

Note that Java arrays and Java objects map to special ORA_JAVA types, ORA_JAVA.JARRAY and ORA_JAVA.JOBJECT. Also note that because the Java int and PL/SQL int type support is different, the Java int maps to a PL/SQL number type.

C.5.2.1 Java Type Information in the PL/SQL Package

The generated PL/SQL package spec includes comments that provide Java type and signature information for the imported Java. The type and signature information in the comments is JNI-based. These comments immediately proceed the PL/SQL signature for the generated item.

In this example, the following Java methods:

public void p1(char x);
public void p1(int x);
public void p1(long x);

are mapped to the following in the generated PL/SQL package:

-- Method: p1 (C)V
PROCEDURE p1 (

obj   ORA_JAVA.JOBJECT,
a0    PLS_INTEGER);

-- Method: p1 (I)V
PROCEDURE p1_1 (

obj   ORA_JAVA.JOBJECT,
a0    NUMBER);

-- Method: p1 (J)V
PROCEDURE p1_2 (

obj   ORA_JAVA.JOBJECT,
a0    NUMBER);

Note the comments above each generated procedure.

-- Method: p1 (C)V

indicates that the original Java was a method named p1 that takes a char as an argument.

-- Method: p1 (I)V

indicates that the original Java was a method named p1 that takes an int as an argument.

-- Method: p1 (J)V

indicates that the original Java was a method named p1 that takes a long as an argument.

C.5.2.2 Arrays

The ORA_JAVA package includes built-ins that provide routines to create an array, get, and set the value of an array element.

For usage information, refer to the documentation for the following ORA_JAVA built-ins:

ORA_JAVA.NEW_<java_type>_ARRAY
ORA_JAVA.GET_<java_type>_ARRAY_ELEMENT
ORA_JAVA.SET_<java_type>_ARRAY_ELEMENT
ORA_JAVA.GET_ARRAY_LENGTH

Note that <java_type> refers to any object type or any Java scalar.

C.5.3 Persistence

By default, when a user creates 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.

ORA_JAVA package built-ins, however, allow the user to manage persistent objects using global references.

C.5.3.1 Global References

Use the ORA_JAVA.NEW_GLOBAL_REFERENCE to make an object persistent beyond the duration of the PL/SQL trigger in which it was created. Use the ORA_JAVA.DELETE_GLOBAL_REFERENCE to destroy the object.

For usage information, refer to the documentation for the following ORA_JAVA built-ins:

ORA_JAVA.NEW_GLOBAL_REFERENCE
ORA_JAVA.DELETE_GLOBAL_REFERENCE

For each ORA_JAVA.NEW_GLOBAL_REFERENCE created, call an ORA_JAVA.DELETE_GLOBAL_REFERENCE when you are done with the reference. Global references are not removed by garbage collection; they must be explicitly deleted.

Note: The variable used to store the global reference must be defined as a package variable.

C.5.4 Error Handling

The ORA_JAVA package includes built-ins that provide routines to check if any exceptions or errors occur while PL/SQL is calling Java.

When an error occurs as PL/SQL calls Java, one of the following PL/SQL exceptions is raised:

ORA_JAVA.JAVA_ERROR
ORA_JAVA.JAVA_EXCEPTION

C.5.4.1 Errors

Errors can occur when PL/SQL attempts to call a Java method. This is not an exception thrown by the Java method, but an error condition resulting from the attempt to call the method. The following are possible errors that can occur:

Unable to initialize JVM.
Argument n cannot be null.
Specified array index is out of range.
Specified array size is illegal.
Our of range conversion error occurred for argument n.
Invalid integer conversion error occurred for argument n.
Invalid object type for argument n.

When the ORA_JAVA.JAVA_ERROR exception is raised, use the ORA_JAVA.LAST_ERROR built-in to get the text of the error. In this context, errors are Form Services events.

For usage information, refer to the documentation for the following ORA_JAVA built-ins:

ORA_JAVA.LAST_ERROR
ORA_JAVA.CLEAR_ERROR

C.5.4.2 Exceptions

Exceptions are standard Java exceptions. When an ORA_JAVA.EXCEPTION_THROWN exception is raised, that indicates that a Java exception was thrown from the method called.

When the ORA_JAVA.EXCEPTION_THROWN exception is raised, use the ORA_JAVA.LAST_EXCEPTION built-in to get the exception. In this context, exceptions are Java events that the Form Services can detect and communicate to the application.

For usage information, refer to the documentation for the following ORA_JAVA built-ins:

ORA_JAVA.LAST_EXCEPTION
ORA_JAVA.CLEAR_EXCEPTION

C.6 Limitations

C.6.1 Java/PL/SQL Issues/Requirements

java.lang.String objects are mapped to varchar2, which has a size limitation of 32KB.
A Forms application must not reference an invalid Java object through the generated PL/SQL package.

C.6.2 Java in the Form Services

Java imported with the Java Importer and referenced in Forms applications must exist in the middle-tier of the application.
When PL/SQL calls imported Java on the Form Services, a separate Java virtual machine (JVM) starts for each runtime process started. The amount of memory used by each JVM includes the overhead of the JVM process plus the memory used for Java application execution and Java object storage.

C.6.3 Builder CLASSPATH Updates

Once a Java class has been loaded into a Form Builder session, changes to the class are not reflected in the running of the class. To run the class with the changes reflected, you must restart the builder.
If you have imported a Java class during a Form Builder session and then make changes to the class, you must restart the builder and then import the changed Java class. The Java Importer does not pick up changes made to a Java class during the same Form Builder session in which that class was previously imported.
If you edit the CLASSPATH during a Form builder session, you must restart the builder so the Java Importer can see the CLASSPATH changes.

Note: You can still import classes added to the CLASSPATH during a builder session, even though they are not listed in the Import Java Classes dialog box. To import a class that is now in the CLASSPATH but not listed in the Import Java Classes dialog box, enter the fully qualified class name in the Import Classes text field.

C.6.4 Builder Restrictions

You cannot use the Java Importer and its features in conjunction with web preview mode in Form Builder.

C.7 ORA_JAVA Built-ins Reference

NEW_GLOBAL_REF built-in

DELETE_GLOBAL_REF built-in

LAST_EXCEPTION built-in

CLEAR_EXCEPTION built-in

LAST_ERROR built-in

CLEAR_ERROR built-in

See NEW_<java_type>_ARRAY built-in for the following:

NEW_OBJECT_ARRAY built-in

NEW_BYTE_ARRAY built-in

NEW_CHAR_ARRAY built-in

NEW_SHORT_ARRAY built-in

NEW_INT_ARRAY built-in

NEW_LONG_ARRAY built-in

NEW_FLOAT_ARRAY built-in

NEW_DOUBLE_ARRAY built-in

NEW_STRING_ARRAY built-in

NEW_BOOLEAN_ARRAY built-in

IS_NULL built-in

GET_ARRAY_LENGTH built-in

See GET_<java_type>_ARRAY_ELEMENT built-in for the following:

GET_OBJECT_ARRAY_ELEMENT built-in

GET_BYTE_ARRAY_ELEMENT

GET_CHAR_ARRAY_ELEMENT

GET_SHORT_ARRAY_ELEMENT

GET_INT_ARRAY_ELEMENT

GET_LONG_ARRAY_ELEMENT

GET_FLOAT_ARRAY_ELEMENT

GET_DOUBLE_ARRAY_ELEMENT

GET_STRING_ARRAY_ELEMENT

GET_BOOLEAN_ARRAY_ELEMENT

See SET_<java_type>_ARRAY_ELEMENT built-in for the following:

SET_OBJECT_ARRAY_ELEMENT

SET_BYTE_ARRAY_ELEMENT

SET_CHAR_ARRAY_ELEMENT

SET_SHORT_ARRAY_ELEMENT

SET_INT_ARRAY_ELEMENT

SET_LONG_ARRAY_ELEMENT

SET_FLOAT_ARRAY_ELEMENT

SET_DOUBLE_ARRAY_ELEMENT

SET_STRING_ARRAY_ELEMENT

SET_BOOLEAN_ARRAY_ELEMENT

C.7.1 NEW_GLOBAL_REF built-in

Description

Returns a reference handle that can be used as a global variable to reference an object of type ORA_JAVA.JOBJECT.

Syntax

FUNCTION NEW_GLOBAL_REF

(obj IN ORA_JAVA.JOBJECT)
RETURN ORA_JAVA.JOBJECT;

Parameters

obj

Is a valid instance of the Java class you want to create a global reference to. The actual parameter can be any object of type `ORA_JAVA.JOBJECT`.

Returns

An object of the PL/SQL type ORA_JAVA.JOBJECT.

Usage Notes

Use this built-in when you want an object to persist beyond the duration of the PL/SQL trigger in which it was created. This is the only mechanism that will create a persistent Java object. It must be used for objects whose scope is larger than the PL/SQL trigger.

The object that you want to create a global reference to must be valid.

The reference handle created remains active until it is explicitly deleted by ORA_JAVA.DELETE_GLOBAL_REF. This means the same object can be used in many trigger points.

Example

PROCEDURE foo IS

obj ORA_JAVA.JOBJECT;
...

BEGIN

obj := myclass.new;
mypkg.instobj := ORA_JAVA.NEW_GLOBAL_REF(obj);
...

END;

C.7.2 DELETE_GLOBAL_REF built-in

Description

Deletes the global reference object that was created by ORA_JAVA.NEW_GLOBAL_REF.

Syntax

PROCEDURE DELETE_GLOBAL_REF (obj IN ORA_JAVA.JOBJECT);

Parameters

obj

Is a valid global reference object that you want to delete.

Usage Notes

You must use this built-in to delete unwanted global reference objects to release the memory allocated for the objects.

Example

PROCEDURE foo IS

obj ORA_JAVA.JOBJECT;
...

BEGIN

obj := myclass.new;
mypkg.instobj := ORA_JAVA.NEW_GLOBAL_REF(obj);
...

END;
...
ORA_JAVA.DELETE_GLOBAL_REF (mypkg.instobj);

C.7.3 LAST_EXCEPTION built-in

Description

Returns the last Java exception that occurred when calling Java from PL/SQL. Use when the PL/SQL exception raised is ORA_JAVA.EXCEPTION_THROWN.

Syntax

FUNCTION LAST_EXCEPTION RETURN ORA_JAVA.JEXCEPTION;

Parameters

None

Returns

An object of type ORA_JAVA.JEXCEPTION, which is a subtype of ORA_JAVA.JOBJECT.

Usage Notes

Whenever you issue a call to a Java method in a PL/SQL block, it is good practice to use this built-in in the exception-handling part of the calling block to handle the ORA_JAVA.EXCEPTION_THROWN type of PL/SQL exception that can occur, e.g., NULL pointer. Note that when ORA_JAVA.EXCEPTION_THROWN is thrown, this indicates that an exception was thrown from within the Java method that was being called.

Example

/* This example assumes you have imported the 
** java.lang.Exception class.
*/
PROCEDURE foo IS

obj ORA_JAVA.JOBJECT;
excp ORA_JAVA.JEXCEPTION;

BEGIN

obj := jfoo.new;
jfoo.addElement(obj);

EXCEPTION

WHEN ORA_JAVA.EXCEPTION_THROWN THEN


excp := ORA_JAVA.LAST_EXCEPTION;
message('    Java Exception: ' || exception_.toString(excp));


...

END;

C.7.4 CLEAR_EXCEPTION built-in

Description

Removes the last exception retrieved by ORA_JAVA.LAST_EXCEPTION.

Syntax

PROCEDURE CLEAR_EXCEPTION;

Parameters

None

Example

/* This example assumes you have imported the 
** java.lang.Exception class.
*/
PROCEDURE foo IS

obj ORA_JAVA.JOBJECT;
excp ORA_JAVA.JOBJECT;

BEGIN

obj := jfoo.new;
jfoo.addElement(obj);
...

EXCEPTION

WHEN ORA_JAVA.EXCEPTION_THROWN THEN


excp := ORA_JAVA.LAST_EXCEPTION;
message('    Java Exception: ' || exception_.toString(excp));
ORA_JAVA.CLEAR_EXCEPTION;

END;

C.7.5 LAST_ERROR built-in

Description

Returns the error text of the last PL/SQL exception that occurred when calling Java from PL/SQL. Use when the PL/SQL exception raised is ORA_JAVA.JAVA_ERROR.

Syntax

FUNCTION LAST_ERROR RETURN VARCHAR2;

Parameters

None

Returns

VARCHAR2

Usage Notes

Whenever you issue a call to a Java method in a PL/SQL block, it is good practice to use this built-in in the exception-handling part of the calling block to handle the ORA_JAVA.JAVA_ERROR type of PL/SQL exception. Note that when ORA_JAVA.JAVA_ERROR is thrown, this doesn't indicate that an exception was thrown from within the Java method that was being called.

See Section C.5.4, "Error Handling" for additional information.

Example

/*
** Example of an invalid array element error.
*/
PROCEDURE foo IS

arr   ORA_JAVA.JARRAY;
n     PLS_INTEGER;

BEGIN

...
arr := ORA_JAVA.NEW_BYTE_ARRAY(5);
n   := ORA_JAVA.GET_BYTE_ARRAY_ELEMENT(arr, 5);
...

EXCEPTION

WHEN ORA_JAVA.JAVA_ERROR THEN


message('  Alert: ' || ORA_JAVA.last_error);

END;

C.7.6 CLEAR_ERROR built-in

Description

Removes the last error text retrieved by ORA_JAVA.LAST_ERROR.

Syntax

PROCEDURE CLEAR_ERROR;

Parameters

None

Example

/*
** Example of retrieving the value of an invalid array element.
*/
PROCEDURE foo IS

arr   ORA_JAVA.JARRAY;
n     PLS_INTEGER;

BEGIN

...
arr := ORA_JAVA.NEW_BYTE_ARRAY(5);
n   := ORA_JAVA.GET_BYTE_ARRAY_ELEMENT(arr, -1);
...

EXCEPTION

WHEN ORA_JAVA.JAVA_ERROR THEN


message('  Alert: ' || ORA_JAVA.last_error);
ORA_JAVA.CLEAR_ERROR;

END;

C.7.7 NEW_<java_type>_ARRAY built-in

Description

Creates a new array of the specified Java type.

Syntax

FUNCTION NEW_OBJECT_ARRAY (

length IN PLS_INTEGER,
clsname IN VARCHAR2) RETURN ORA_JAVA.JARRAY;

FUNCTION NEW_BYTE_ARRAY (

length IN PLS_INTEGER) RETURN ORA_JAVA.JARRAY;

FUNCTION NEW_CHAR_ARRAY (

length IN PLS_INTEGER) RETURN ORA_JAVA.JARRAY;

FUNCTION NEW_SHORT_ARRAY (

length IN PLS_INTEGER) RETURN ORA_JAVA.JARRAY;

FUNCTION NEW_INT_ARRAY (

length IN PLS_INTEGER) RETURN ORA_JAVA.JARRAY;

FUNCTION NEW_LONG_ARRAY (

length IN PLS_INTEGER) RETURN ORA_JAVA.JARRAY;

FUNCTION NEW_FLOAT_ARRAY (

length IN PLS_INTEGER) RETURN ORA_JAVA.JARRAY;

FUNCTION NEW_DOUBLE_ARRAY (

length IN PLS_INTEGER) RETURN ORA_JAVA.JARRAY;


FUNCTION NEW_STRING_ARRAY (

length IN PLS_INTEGER) RETURN ORA_JAVA.JARRAY;

FUNCTION NEW_BOOLEAN_ARRAY (

length IN PLS_INTEGER) RETURN ORA_JAVA.JARRAY;

Parameters

length

Is the size of the array to be created (i.e., the number of array elements).

clsname

Is the fully qualified name of the class file. Use '.' (period) as separators in the name, e.g., java.lang.String.
Required only when creating an array of the Object data type.

Returns

An object of the PL/SQL type ORA_JAVA.JARRAY, which is a subtype of ORA_JAVA.JOBJECT.

Usage Notes

The new array is valid only in the PL/SQL trigger it was created. Use the ORA_JAVA.NEW_GLOBAL_REF built-in to increase the persistency of the array beyond the duration of the trigger.

Example

/*
** Example of creating an array of data type object.
*/
PROCEDURE create_object_array IS

arr ORA_JAVA.JOBJECT;

BEGIN

arr := ORA_JAVA.NEW_OBJECT_ARRAY(3, 'java.lang.String');
...

END;

/*
** Example of creating an array of data type char with one element.
*/
PROCEDURE create_char_array IS

arr ORA_JAVA.JOBJECT;

BEGIN

arr := ORA_JAVA.NEW_CHAR_ARRAY(1);
...

END;

C.7.8 GET_<java_type>_ARRAY_ELEMENT built-in

Description

Returns the current value for a given element in a given array of the specified Java type. The value is returned in its corresponding PL/SQL type.

Syntax

FUNCTION GET_OBJECT_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER) RETURN ORA_JAVA.JOBJECT;

FUNCTION GET_BYTE_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER) RETURN PLS_INTEGER;

FUNCTION GET_CHAR_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER) RETURN PLS_INTEGER;

FUNCTION GET_SHORT_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER) RETURN PLS_INTEGER;

FUNCTION GET_INT_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER) RETURN NUMBER;

FUNCTION GET_LONG_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER) RETURN NUMBER;

FUNCTION GET_FLOAT_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER) RETURN NUMBER;

FUNCTION GET_DOUBLE_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER) RETURN NUMBER;

FUNCTION GET_STRING_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER) RETURN VARCHAR2;

FUNCTION GET_BOOLEAN_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER) RETURN BOOLEAN;

Parameters

arr

Is a valid array of the specified type. The actual parameter is the array of type `ORA_JAVA.JARRAY`.

pos

Is the position of the element in the array. Note that the position of the first element is 0. For example, in an array of size 3, the positions of the elements are 0, 1,and 2.

Returns

A value of the corresponding PL/SQL type (PLS_INTEGER, NUMBER, VARCHAR2, BOOLEAN, or ORA_JAVA.JOBJECT).

Usage Notes

The array of the specified type must be valid.

If the length of the array is unknown, use ORA_JAVA.GET_ARRAY_LENGTH to determine the size of the array first.

Can only get one value at a time.

Example

/*
** Example of getting 3 values of an array of data type object.
*/
PROCEDURE get_object_array IS

arr ORA_JAVA.JARRAY;
obj1 ORA_JAVA.JOBJECT;
obj2 ORA_JAVA.JOBJECT;
obj3 ORA_JAVA.JOBJECT;

BEGIN

arr := myclass.getMyArray;
obj1 := ORA_JAVA.GET_OBJECT_ARRAY_ELEMENT(arr, 0);
obj2 := ORA_JAVA.GET_OBJECT_ARRAY_ELEMENT(arr, 1);
obj3 := ORA_JAVA.GET_OBJECT_ARRAY_ELEMENT(arr, 2);
...

END;

C.7.9 SET_<java_type>_ARRAY_ELEMENT built-in

Description

Changes the value of a given element in a given array of the specified Java type to a given value.

Syntax

PROCEDURE SET_OBJECT_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER,
value IN ORA_JAVA.JOBJECT);

PROCEDURE SET_BYTE_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER,
value IN PLS_INTEGER);

PROCEDURE SET_CHAR_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER,
value IN PLS_INTEGER);

PROCEDURE SET_SHORT_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER,
value IN PLS_INTEGER);

PROCEDURE SET_INT_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER,
value IN NUMBER);

PROCEDURE SET_LONG_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER,
value IN NUMBER);

PROCEDURE SET_FLOAT_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER,
value IN NUMBER);

PROCEDURE SET_DOUBLE_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER,
value IN NUMBER);

PROCEDURE SET_STRING_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER,
value IN VARCHAR2);

PROCEDURE SET_BOOLEAN_ARRAY_ELEMENT (

arr IN ORA_JAVA.JARRAY,
pos IN PLS_INTEGER,
value IN BOOLEAN);

Parameters

arr

Is a valid array of the specified type. The actual parameter is the array of type `ORA_JAVA.JARRAY`.

pos

Is the position of the element in the array to be replaced. Note that the position of the first element is always 0. For example, in an array of size 3, the positions of the elements are 0, 1, and 2.

value

The new value of the specified type to replace the array element.

Usage Notes

The array of the specified type and array element to be replaced must be valid.

If the length of the array is unknown, use ORA_JAVA.GET_ARRAY_LENGTH to determine the size of the array first.

You can only set one value at a time.

Example

/*
** Example of changing 3 values of an array of data type object.
*/
PROCEDURE set_object_array IS

arr ORA_JAVA.JOBJECT;
obj ORA_JAVA.JOBJECT;

BEGIN

arr := ORA_JAVA.NEW_OBJECT_ARRAY(3, 'myapp.foo');
ORA_JAVA.SET_OBJECT_ARRAY_ELEMENT(arr, 0, foo.new('obj1'));
ORA_JAVA.SET_OBJECT_ARRAY_ELEMENT(arr, 1, foo.new('obj2'));
ORA_JAVA.SET_OBJECT_ARRAY_ELEMENT(arr, 2, foo.new('obj3'));
...

END;

/*
** Example of changing the value of an array of data type char.
*/
PROCEDURE set_char_array IS

arr ORA_JAVA.JOBJECT;

BEGIN

arr := ORA_JAVA.NEW_CHAR_ARRAY(1);
ORA_JAVA.SET_CHAR_ARRAY_ELEMENT(arr, 0, 2);
...

END;

C.7.10 IS_NULL built-in

Description

Returns a BOOLEAN value that indicates whether or not an object is null.

Syntax

FUNCTION IS_NULL (obj IN ORA_JAVA.JOBJECT) RETURN BOOLEAN;

Parameters

obj

Is a valid instance of the Java class. The actual parameter can be any object of type `ORA_JAVA.JOBJECT`.

Example

PROCEDURE foo IS

obj ORA_JAVA.JOBJECT;
...

BEGIN

obj := myclass.new;
IF NOT ORA_JAVA.IS_NULL(obj) THEN


pck.obj := ORA_JAVA.NEW_GLOBAL_REF(obj);
...


END IF;
...

END;

C.7.11 GET_ARRAY_LENGTH built-in

Description

Returns the size (length) of an array.

Syntax

FUNCTION GET_ARRAY_LENGTH (

arr IN ORA_JAVA.JARRAY) RETURN PLS_INTEGER;

Parameters

arr

Is a valid array.

Returns

PLS_INTEGER.

Usage Notes

Use this built-in to determine the length of an array. You must supply a valid array.

Example

PROCEDURE get_size IS

n PLS_INTEGER;
arr ORA_JAVA.JARRAY;

BEGIN

arr := myclass.getMyArray;
IF NOT ORA_JAVA.IS_NULL(arr) THEN


n := ORA_JAVA.GET_ARRAY_LENGTH(arr);
...


END IF;
...

END;

arr	Is a valid array of the specified type. The actual parameter is the array of type `ORA_JAVA.JARRAY`.
pos	Is the position of the element in the array. Note that the position of the first element is 0. For example, in an array of size 3, the positions of the elements are 0, 1,and 2.

Select Java Classes (browser)	The Class browser provides a hierarchical display of all the Java class files in the order that are defined in the current CLASSPATH environment variable. The class files (represented by leaf nodes) are organized and displayed in their packages (represented by folder nodes). Expand/collapse a folder to show/hide the contents. You can select one or more Java classes (`SHIFT`-Click in Windows for multiple selection).
Import Classes	This text box displays the fully qualified class names of the class files you have selected. Multiple class names are separated by semi-colons (;). You can also type the fully qualified class name in this field, which is case-sensitive, e.g., java.lang.String.
Messages	This display-only panel shows the status during the importing process.
Import	This button starts the importing process. Button is enabled when you have selected one or more class files in the Class browser, or entered a fully qualified class name in the text box.
Options...	Displays the Import Java Class Options dialog box. See Section C.4.3, "Specify options for importing".
Close	Closes this dialog box.

-- Method: p1 (C)V	indicates that the original Java was a method named p1 that takes a char as an argument.
-- Method: p1 (I)V	indicates that the original Java was a method named p1 that takes an int as an argument.
-- Method: p1 (J)V	indicates that the original Java was a method named p1 that takes a long as an argument.

CJava Importer

C.1 Overview

C.1.1 Importing Java and Building Applications

C.1.2 Running Applications with Imported Java

C.2 Components

C.3 Installation Requirements

C.3.1 Imported Java Requirements

C.4 Importing Java

C.4.1 Using the Java Importer Tool

C.4.2 Invoke the Import Java Classes dialog box

C.4.3 Specify options for importing

C.4.4 Import a Java class into PL/SQL

C.5 Building Applications with Imported Java

C.5.1 Description of the Generated PL/SQL

C.5.1.1 What Gets Generated?

C.5.1.2 How is the Java Mapped to PL/SQL?

C.5.1.3 What are the importer mapping options?

C.5.1.4 How does PL/SQL naming vary?

C.5.1.4.1 What is different between persistent and default naming?

C.5.1.5 What happens if I regenerate the PL/SQL?

C.5.2 Java Types

C.5.2.1 Java Type Information in the PL/SQL Package

C.5.2.2 Arrays

C.5.3 Persistence

C.5.3.1 Global References

C.5.4 Error Handling

C.5.4.1 Errors

C.5.4.2 Exceptions

C.6 Limitations

C.6.1 Java/PL/SQL Issues/Requirements

C.6.2 Java in the Form Services

C.6.3 Builder CLASSPATH Updates

C.6.4 Builder Restrictions

C.7 ORA_JAVA Built-ins Reference

C.7.1 NEW_GLOBAL_REF built-in

Description

Syntax

Parameters obj Is a valid instance of the Java class you want to create a global reference to. The actual parameter can be any object of type ORA_JAVA.JOBJECT.

Returns

Usage Notes

Example

C.7.2 DELETE_GLOBAL_REF built-in

Description

Syntax

Parameters obj Is a valid global reference object that you want to delete.

Usage Notes

Example

C.7.3 LAST_EXCEPTION built-in

Description

Syntax

Parameters

Returns

Usage Notes

Example

C.7.4 CLEAR_EXCEPTION built-in

Description

Syntax

Parameters

Example

C.7.5 LAST_ERROR built-in

Description

Syntax

Parameters

Returns

Usage Notes

Example

C.7.6 CLEAR_ERROR built-in

Description

Syntax

Parameters

Example

C.7.7 NEW_<java_type>_ARRAY built-in

Description

Syntax

Parameters length Is the size of the array to be created (i.e., the number of array elements). clsname Is the fully qualified name of the class file. Use '.' (period) as separators in the name, e.g., java.lang.String. Required only when creating an array of the Object data type.

Returns

Usage Notes

Example

C.7.8 GET_<java_type>_ARRAY_ELEMENT built-in

Description

C
Java Importer

Parameters

obj

Is a valid instance of the Java class you want to create a global reference to. The actual parameter can be any object of type `ORA_JAVA.JOBJECT`.

Parameters

obj

Is a valid global reference object that you want to delete.

Parameters

length

Is the size of the array to be created (i.e., the number of array elements).

clsname

Is the fully qualified name of the class file. Use '.' (period) as separators in the name, e.g., java.lang.String.
Required only when creating an array of the Object data type.

Parameters

obj

Is a valid instance of the Java class. The actual parameter can be any object of type `ORA_JAVA.JOBJECT`.

Parameters

arr

Is a valid array.