Oracle Forms Server Release 6i:
Deploying Forms Applications to the Web with iAS
Patch 2

A86202-01

PrevNext

Library

Solution Area

Contents

Index

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 Forms Server. A dedicated JVM is created for each Forms Server 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:

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:

C.4.4 Import a Java class into PL/SQL

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

  1. In Forms Builder, open the module (Form module, PL/SQL library, or Menu module) where you want to place the generated PL/SQL packages.

  2. Choose Program->Import Java Classes... from the menu to display the Import Java Classes dialog box.

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

  4. Click Options... to specify importing options, if required. For additional information, see Section C.4.3, "Specify options for importing".

  5. Click Import to start the importing process.

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

 

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:

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:

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:

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:

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 Forms Server 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 Forms Server 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

C.6.2 Java in the Forms Server

C.6.3 Builder CLASSPATH Updates

C.6.4 Builder Restrictions

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:

IS_NULL built-in

GET_ARRAY_LENGTH built-in

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

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

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.

See Also ORA_JAVA.LAST_ERROR.

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.

See also ORA_JAVA.LAST_EXCEPTION.

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;

Prev Next
Oracle
Copyright © 2000 Oracle Corporation.

All Rights Reserved.

Library

Solution Area

Contents

Index