Skip Headers
Oracle® Database Java Developer's Guide
11g Release 2 (11.2)

E10588-07
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

A DBMS_JAVA Package

This chapter provides a description of the DBMS_JAVA package. The functions and procedures in this package provide an entry point for accessing RDBMS functionality from Java.

longname

FUNCTION longname (shortname VARCHAR2) RETURN VARCHAR2

The function returns the fully qualified name of the specified Java schema object. Because Java classes and methods can have names exceeding the maximum SQL identifier length, Oracle JVM uses abbreviated names internally for SQL access. This function returns the original Java name for any truncated name. An example of this function is to display the fully qualified name of classes that are invalid:

SELECT dbms_java.longname (object_name) FROM user_objects
WHERE object_type = 'JAVA CLASS' AND status = 'INVALID';

shortname

FUNCTION shortname (longname VARCHAR2) RETURN VARCHAR2

You can specify a full name to the database by using the shortname() routine of the DBMS_JAVA package, which takes a full name as input and returns the corresponding short name. This is useful when verifying that your classes loaded by querying the USER_OBJECTS view.

get_compiler_option

FUNCTION get_compiler_option(name VARCHAR2, optionName VARCHAR2) RETURN VARCHAR2

This function returns the value of the option specified through the optionName parameter. It is one of the functions used to control the options of the Java and SQLJ compiler supplied with Oracle Database.

set_compiler_option

PROCEDURE set_compiler_option(name VARCHAR2, optionName VARCHAR2, value VARCHAR2)

This procedure is used to set the options of the Java and SQLJ compiler supplied with Oracle Database.

reset_compiler_option

PROCEDURE reset_compiler_option(name VARCHAR2, optionName VARCHAR2)

This procedure is used to reset the specified compiler option to the default value.

resolver

FUNCTION resolver (name VARCHAR2, owner VARCHAR2, type VARCHAR2) RETURN VARCHAR2

This function returns the resolver specification for the object specified in name and in the schema specified in owner, where the object is of the type specified in type. The caller must have EXECUTE privilege and have access to the given object to use this function.

The name parameter is the short name of the object.

The value of type can be either SOURCE or CLASS.

If there is an error, then NULL is returned. If the underlying object has changed, then ObjectTypeChangedException is thrown.

You can call this function as follows:

SELECT dbms_java.resolver('tst', 'SCOTT', 'CLASS') FROM DUAL;

This would return:

DBMS_JAVA.RESOLVER('TST','SCOTT','CLASS')
-----------------------------------------
((* SCOTT)(* PUBLIC))

derivedFrom

FUNCTION derivedFrom (name VARCHAR2, owner VARCHAR2, type VARCHAR2) RETURN VARCHAR2

This function returns the source name of the object specified in name of the type specified in type and in the schema specified in owner. The caller must have EXECUTE privilege and have access to the given object to use this function.

The name parameter, as well as the returned source name, is the short name of the object.

The value of type can be either SOURCE or CLASS.

If there is an error, then NULL is returned. If the underlying object has changed, then ObjectTypeChangedException is thrown.

The returned value will be NULL if the object was not compiled in Oracle JVM.

You can call this function as follows:

SELECT dbms_java.derivedFrom('tst', 'SCOTT', 'CLASS') FROM DUAL;

This would return:

DBMS_JAVA.DERIVEDFROM('TST','SCOTT','CLASS')
-----------------------------------------
tst

fixed_in_instance

FUNCTION fixed_in_instance (name VARCHAR2, owner VARCHAR2, type VARCHAR2) RETURN NUMBER

This function returns the permanently kept status for object specified in name of the type specified in type and in the schema specified in owner. The caller must have EXECUTE privilege and have access to the given object to use this function.

The name parameter is the short name for the object.

The value of type can be either of RESOURCE, SOURCE, CLASS, or SHARED_DATA.

The number returned is either 0, indicating the status is not kept, or 1, indicating the status is kept.

You can call this function as follows:

SELECT dbms_java.fixed_in_instance('tst', 'SCOTT', 'CLASS') FROM DUAL;

This would return:

DBMS_JAVA.FIXED_IN_INSTANCE('TST','SCOTT','CLASS')
-----------------------------------------
0

Consider the following statement:

SELECT dbms_java.fixed_in_instance('java/lang/String', 'SYS', 'CLASS') FROM DUAL;

This would return:

DBMS_JAVA.FIXED_IN_INSTANCE('JAVA/LANG/STRING','SYS','CLASS')
-------------------------------------------------------------
1

set_output

PROCEDURE set_output (buffersize NUMBER)

This procedure redirects the output of Java stored procedures and triggers to the DBMS_OUTPUT package.

export_source

PROCEDURE export_source(name VARCHAR2, schema VARCHAR2, blob BLOB)

PROCEDURE export_source(name VARCHAR2, blob BLOB)

PROCEDURE export_source(name VARCHAR2, clob CLOB)

PROCEDURE export_source(name varchar2, schema varchar2, src CLOB)

These procedures are used to export the Java source as a Java source schema object to Oracle Database. The source is specified through the name parameter. The source can be exported into a BLOB or CLOB object. The internal representation of the source uses the UTF8 format, so that format is used to store the source in the BLOB as well. The source schema object is created in the specified schema. If the schema is not specified then the current schema is used.

export_class

PROCEDURE export_class(name VARCHAR2, schema VARCHAR2, blob BLOB)

PROCEDURE export_class(name VARCHAR2, blob BLOB)

These procedures are used to export Java classes specified through the name parameter as Java class schema objects to Oracle Database. You cannot export a class into a CLOB object, only into a BLOB object. If the schema is specified, then the class schema object is created in this schema, else in the current schema.

export_resource

PROCEDURE export_resource(name VARCHAR2, schema VARCHAR2, blob BLOB)

PROCEDURE export_resource(name VARCHAR2, blob BLOB)

PROCEDURE export_resource(name VARCHAR2, schema VARCHAR2, clob CLOB)

PROCEDURE export_resource(name VARCHAR2, clob CLOB)

The resource specified through the name parameter is exported to Oracle Database as a resource schema object in the schema specified through the schema parameter. If the schema is not specified then the current schema is used. The resource can be exported into either a CLOB object or BLOB object.

loadjava

PROCEDURE loadjava(options VARCHAR2)
PROCEDURE loadjava(options VARCHAR2, resolver VARCHAR2)

These procedures enable you to load classes in to the database using a call, rather than through the loadjava command-line tool. You can call this procedure within your Java application as follows:

CALL dbms_java.loadjava('... options...');

The options are identical to those specified on the command line. Each option should be separated by a space. Do not separate the options with a comma. The only exception to this is the loadjava -resolver option, which contains spaces. For -resolver, specify all other options first, separate these options by a comma, and then specify the -resolver options, as follows:

CALL dbms_java.loadjava('... options...', 'resolver_options');

Do not specify the -thin, -oci, -user, and -password options, because they relate to the database connection. The output is directed to System.err. The output typically goes to a trace file, but can be redirected.

dropjava

PROCEDURE dropjava(options VARCHAR2)

This procedure enables you to drop classes within the database using a call, rather than through the dropjava command-line tool. You can call this procedure within your Java application as follows:

CALL dbms_java.dropjava('... options...');

grant_permission

PROCEDURE grant_permission(grantee VARCHAR2, permission_type VARCHAR2, permission_name VARCHAR2, 
permission_action VARCHAR2)

This method is used to grant permission to specific users or roles.

grant_permission

PROCEDURE grant_permission(grantee VARCHAR2, permission_type VARCHAR2, permission_name VARCHAR2, 
permission_action VARCHAR2, key OUT NUMBER)

This method is used to grant permission to specific users or roles. The key can be used for fine-grained access control.

restrict_permission

PROCEDURE restrict_permission(grantee VARCHAR2, permission_type VARCHAR2, permission_name VARCHAR2, 
permission_action VARCHAR2) 

This method is used to specify limitations or exceptions to general rules.

restrict_permission

PROCEDURE restrict_permission(grantee VARCHAR2, permission_type VARCHAR2, permission_name VARCHAR2, 
permission_action VARCHAR2, key OUT NUMBER) 

This method is used to specify limitations or exceptions to general rules. The key can be used for fine-grained access control.

grant_policy_permission

PROCEDURE grant_policy_permission(grantee VARCHAR2, permission_schema VARCHAR2, permission_type VARCHAR2, 
permission_name VARCHAR2) 

This method is used to grant and limit PolicyTablePermission.

grant_policy_permission

PROCEDURE grant_policy_permission(grantee VARCHAR2, permission_schema VARCHAR2, permission_type VARCHAR2, 
permission_name VARCHAR2, key OUT NUMBER) 

This method is used to grant and limit PolicyTablePermission. The key can be used for fine-grained access control.

revoke_permission

PROCEDURE revoke_permission(permission_schema VARCHAR2, permission_type VARCHAR2, permission_name VARCHAR2, 
permission_action VARCHAR2) 

This method is used to disable a granted permission.

disable_permission

PROCEDURE disable_permission(key NUMBER) 

This method is used to disable a granted permission.

enable_permission

PROCEDURE enable_permission(key NUMBER) 

This method is used to enable a permission.

delete_permission

PROCEDURE delete_permission(key NUMBER)

This method is used to delete a granted permission.

set_preference

procedure set_preference(user VARCHAR2, type VARCHAR2, abspath VARCHAR2, key VARCHAR2, value VARCHAR2)

This procedure inserts or updates a row in the SYS:java$prefs$ table as follows:

CALL dbms_java.set_preference('SCOTT', 'U', '/my/package/method/three', 'windowsize', '22:32');

The user parameter specifies the name of the schema to which the preference should be attached. If the logged in schema is not SYS, then user must specify the current logged in schema or the INSERT will fail. The type parameter can take either the value U, indicating user preference, or S, indicating system preference. The abspath parameter specifies the absolute path for the preference. key is the preference key used for the lookup, and value is the value of the preference key.

runjava

FUNCTION runjava(cmdline VARCHAR2) RETURN VARCHAR2;

This function takes the Java command line as its only argument and runs it in Oracle JVM.

runjava_in_current_session

FUNCTION runjava_in_current_session(cmdline VARCHAR2) RETURN VARCHAR2;

This function is the same as the runjava function, except that it does not clear Java state remaining from previous use of Java in the session, prior to executing the current command line.

set_property

FUNCTION set_property(name VARCHAR2, value VARCHAR2) RETURN VARCHAR2;

This function establishes a value for a system property that is then used for the duration of the current RDBMS session, whenever a Java session is initialized.

If a database-related exception is thrown, then the return value of the set_property function is a VARCHAR that includes the exception in the form of a message. This prevents the termination of the function as a database error prior to return. If there is no error, then the return value of the function is null.

Note:

In order to execute the SET_PROPERTY function, a user must have write permission on SYS:java.util.PropertyPermission for the property name. You can grant this permission using the following command:
call dbms_java.grant_permission( '<user_name>', 'SYS:java.util.PropertyPermission', '<property_name>', 'write' );

get_property

FUNCTION get_property(name VARCHAR2) RETURN VARCHAR2;

This function returns any value previously established by set_property.

remove_property

FUNCTION remove_property(name VARCHAR2) RETURN VARCHAR2;

This function removes any value previously established by set_property.

Note:

In order to execute the remove_property function, a user must have write permission on SYS:java.util.PropertyPermission for the property name. You can grant this permission using the following command:
call dbms_java.grant_permission( '<user_name>', 'SYS:java.util.PropertyPermission', '<property_name>', 'write' );

show_property

FUNCTION show_property(name VARCHAR2) RETURN VARCHAR2;

This function displays a message of the form name = value for the input name, or for all established property bindings, if name is null.

set_output_to_sql

FUNCTION set_output_to_sql (id VARCHAR2,
stmt VARCHAR2,
bindings VARCHAR2,
no_newline_stmt VARCHAR2 default null,
no_newline_bindings VARCHAR2 default null,
newline_only_stmt VARCHAR2 default null,
newline_only_bindings VARCHAR2 default null,
maximum_line_segment_length NUMBER default 0,
allow_replace NUMBER default 1,
from_stdout NUMBER default 1,
from_stderr NUMBER default 1,
include_newlines NUMBER default 0,
eager NUMBER default 0) return VARCHAR2;

set_output_to_sql defines a named output specification that constitutes an instruction for executing a SQL statement, whenever output to the default

System.out and System.err streams occurs.

remove_output_to_sql

FUNCTION remove_output_to_sql (id VARCHAR2) return VARCHAR2;

remove_output_to_sql deletes a specification created by set_output_to_sql.

enable_output_to_sql

FUNCTION enable_output_to_sql (id VARCHAR2) return VARCHAR2;

enable_output_to_sql reenables a specification created by set_output_to_sql and subsequently disabled by disable_output_to_sql.

disable_output_to_sql

FUNCTION disable_output_to_sql (id VARCHAR2) return VARCHAR2;

disable_output_to_sql disables a specification created by set_output_to_sql.

query_output_to_sql

FUNCTION query_output_to_sql (id VARCHAR2) return VARCHAR2;

query_output_to_sql returns a message describing a specification created by set_output_to_sql.

set_output_to_java

FUNCTION set_output_to_java (id VARCHAR2,
class_name VARCHAR2,
class_schema VARCHAR2,
method VARCHAR2,
bindings VARCHAR2,
no_newline_method VARCHAR2 default null,
no_newline_bindings VARCHAR2 default null,
newline_only_method VARCHAR2 default null,
newline_only_bindings VARCHAR2 default null,
maximum_line_segment_length NUMBER default 0,
allow_replace NUMBER default 1,
from_stdout NUMBER default 1,
from_stderr NUMBER default 1,
include_newlines NUMBER default 0,
eager NUMBER default 0,
initialization_statement VARCHAR2 default null,
finalization_statement VARCHAR2 default null)return VARCHAR2;

set_output_to_java defines a named output specification that constitutes an instruction for executing a Java method whenever output to the default System.out and System.err streams occurs.

remove_output_to_java

FUNCTION remove_output_to_java (id VARCHAR2) return VARCHAR2;

remove_output_to_java deletes a specification created by set_output_to_java.

enable_output_to_java

FUNCTION enable_output_to_java (id VARCHAR2) return VARCHAR2;

enable_output_to_java reenables a specification created by set_output_to_java and subsequently disabled by disable_output_to_java.

disable_output_to_java

FUNCTION disable_output_to_java (id VARCHAR2) return VARCHAR2;

disable_output_to_java disables a specification created by set_output_to_java.

query_output_to_java

FUNCTION query_output_to_java (id VARCHAR2) return VARCHAR2;

query_output_to_java returns a message describing a specification created by set_output_to_java.

set_output_to_file

FUNCTION set_output_to_file (id VARCHAR2,
file_path VARCHAR2,
allow_replace NUMBER default 1,
from_stdout NUMBER default 1,
from_stderr NUMBER default 1) return VARCHAR2;

set_output_to_file defines a named output specification that constitutes an instruction to capture any output sent to the default System.out and

System.err streams and append it to a specified file.

remove_output_to_file

FUNCTION remove_output_to_file (id VARCHAR2) return VARCHAR2;

remove_output_to_file deletes a specification created by set_output_to_file.

enable_output_to_file

FUNCTION enable_output_to_file (id VARCHAR2) return VARCHAR2;

enable_output_to_file reenables a specification created by set_output_to_file and subsequently disabled by disable_output_to_file.

disable_output_to_file

FUNCTION disable_output_to_file (id VARCHAR2) return VARCHAR2;

disable_output_to_file disables a specification created by set_output_to_file.

query_output_to_file

FUNCTION query_output_to_file (id VARCHAR2) return VARCHAR2;

query_output_to_file returns a message describing a specification created by set_output_to_file.

enable_output_to_trc

PROCEDURE enable_output_to_trc;

This procedure reenables printing the output to System.out and System.err in the .trc file that was disabled by the disable_output_to_trc procedure.

disable_output_to_trc

PROCEDURE disable_output_to_trc;

This procedure prevents output to System.out and System.err from appearing in the .trc file.

query_output_to_trc

FUNCTION query_output_to_trc return VARCHAR2;

This function returns a value indicating whether printing output to System.out and System.err in the .trc file is currently enabled.

endsession

FUNCTION endsession RETURN VARCHAR2;

This function clears any Java session state remaining from previous execution of Java in the current RDBMS session.

endsession_and_related_state

FUNCTION endsession_and_related_state RETURN VARCHAR2;

This function clears any Java session state remaining from previous execution of Java in the current RDBMS session and all supporting data related to running Java.

set_native_compiler_option

PROCEDURE set_native_compiler_option(optionName VARCHAR2,
value VARCHAR2);

This procedure sets a native-compiler option to the specified value for the current schema.

unset_native_compiler_option

PROCEDURE unset_native_compiler_option(optionName VARCHAR2,
value VARCHAR2);

This procedure unsets a native-compiler option/value pair for the current schema.

compile_class

FUNCTION compile_class(classname VARCHAR2) return NUMBER;

This function compiles all methods defined by the class that is identified by classname in the current schema.

uncompile_class

FUNCTION uncompile_class(classname VARCHAR2,
permanentp NUMBER default 0) return NUMBER;

This function uncompiles all methods defined by the class that is identified by classname in the current schema.

compile_method

FUNCTION compile_method(classname  VARCHAR2,
methodname VARCHAR2,
methodsig  VARCHAR2) return NUMBER;

This function compiles the method specified by name and Java type signatures defined by the class, which is identified by classname in the current schema.

uncompile_method

FUNCTION uncompile_method(classname  VARCHAR2,
methodname VARCHAR2,
methodsig  VARCHAR2,
permanentp NUMBER default 0) return NUMBER;

This function uncompiles the method specified by the name and Java type signatures defined by the class that is identified by classname in the current schema.

start_jmx_agent

procedure start_jmx_agent(port VARCHAR2 default NULL,
ssl  VARCHAR2 default NULL,
auth VARCHAR2 default NULL);

This procedure starts the JMX agent in a specific session. Generally, the agent remains active for the duration of the session.

set_runtime_exec_credentials

procedure set_runtime_exec_credentials(dbuser varchar2, 
osuser varchar2, 
ospass varchar2);

where, dbuser is the name of a database user or a schema name and osuser, ospass are OS account credentials.

Associates the database user/schema dbuser with the osuser/ospass operating system (OS) credential pair. This association is encrypted and stored in a table owned by the SYS user. Once the new and valid association is established, every new OS process forked by the java.lang.Runtime.exec methods or every ProceessBuilder invoked by dbuser to run an OS command runs as the UID osuser, and not as the OS ID of the Oracle process. That is, the UID bits of the forked process are set to UID osuser.

Note:

DBAs and security administrators can use this procedure to tighten security of Java applications deployed to Oracle Database. By specifying lesser-privileged accounts, a DBA can limit the power and access rights of spawned processes as appropriate. You must be the SYS user to use the set_runtime_exec_credentials procedure, otherwise the ORA-01031: insufficient privileges error is raised. Use of invalid account credentials results in an IOException, when a new process is created.

Following examples show how to use this procedure:

Example 1

The following command binds user/schema DBUSER to credentials osuser/ospass:

dbms_java.set_runtime_exec_credentials('DBUSER', 'osuser', 'ospass');

Example 2

Either of the following commands unbinds the association of DBUSER and credentials osuser/ospass:

dbms_java.set_runtime_exec_credentials('DBUSER', '', '');
dbms_java.set_runtime_exec_credentials('DBUSER', null, null);

Note:

To use the set_runtime_exec_credentials procedure, you must configure the Oracle jssu facility to setuid root during oracle product installation, otherwise the process spawn via jssu failed... IOException may be raised at process creation time.