12.6 The loadjava Tool
The loadjava
tool creates schema objects from files and loads them
into a schema. Schema objects can be created from Java source, class, and data
files.
You must have the following SQL database privileges to load classes:
-
CREATE PROCEDURE
andCREATE TABLE
privileges to load into your schema. -
CREATE ANY PROCEDURE
andCREATE ANY TABLE
privileges to load into another schema. -
oracle.aurora.security.JServerPermission.loadLibraryInClass.
classname
.
You can run the loadjava
tool either from the command line or by using the loadjava
method contained in the DBMS_JAVA
class. To run the tool from within your Java application, do the following:
call dbms_java.loadjava('... options...');
The options are the same as those that can be specified on the command line with the loadjava
tool. Separate each option with a space. Do not separate the options with a comma. The only exception for this is the -resolver
option, which contains spaces. For -resolver
, specify all other options in the first input parameter and the -resolver
options in the second parameter, 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 for the loadjava
command-line tool. The output is directed to stderr
. Set serveroutput
on, and call dbms_java.set_output
, as appropriate.
Note:
The loadjava
tool is located in the bin
directory under $ORACLE_HOME
.
Just before the loadjava
tool exits, it checks whether the processing was successful. All failures are summarized preceded by the following header:
The following operations failed
Some conditions, such as losing the connection to the database, cause the loadjava
tool to terminate prematurely. These errors are displayed with the following syntax:
exiting: error_reason
This section covers the following:
12.6.1 loadjava Tool Syntax
The syntax of the loadjava
tool command is as follows:
Note:
-
The
(* -)
option is the preferred option over the-genmissing
and-genmissingjar
options for resolving class references. -
The the
-genmissing
and-genmissingjar
options cannot be used in an option file or an option table. These options are applicable to all the classes to be loaded and cannot be used only for specific classes.
loadjava {-user | -u} user [@database] [options] file.java | file.class | file.jar | file.zip | resourcefile | URL... [-casesensitivepub] [-cleargrants] [-debug] [-d | -definer] [-dirprefix prefix] [-add-modules module-list] [-module module-name] [-automatic] [-hotload] [-e | -encoding encoding_scheme] [-fileout file] [-f | -force] [-genmissing] [-genmissingjar jar_file] [-g | -grant user [, user]...] [-help] [-jarasresource] [-noaction] [-nosynonym] [-nousage] [-noverify] [-o | -oci | oci8] [-optionfile file] [-optiontable table_name] [-publish package] [-pubmain number] [-recursivejars] [-r | -resolve] [-R | -resolver "resolver_spec"] [-append-resolver "resolver_spec"] [-prepend-resolver "resolver_spec"] [-resolveonly] [-S | -schema schema] [-stdout] [-stoponerror] [-s | -synonym] [-tableschema schema] [-t | -thin]
[-unresolvedok] [-v | -verbose] [-jarsasdbobjects] [-prependjarnames] [-nativecompile]
12.6.2 loadjava Tool Argument Summary
This section summarizes the loadjava
tool command
arguments. If you run the loadjava
tool multiple times, specifying the same
files and different options, then the options specified in the most recent invocation
hold.
However, there are the following two exceptions to this rule:
-
If the
loadjava
tool does not load a file because it matches a digest table entry, then most options on the command line have no effect on the schema object. The exceptions are-grant
and-resolve
, which always take effect. You must use the-force
option to direct theloadjava
tool to skip the digest table look up. -
The
-grant
option is cumulative. Every user specified in every invocation of theloadjava
tool for a given class in a given schema has theEXECUTE
privilege.
Table 12-2 loadjava Argument Summary
Argument | Description |
---|---|
|
Specifies any number and combination of |
|
Specifies the host name and the port of the proxy server. If you do not have physical access to the server host or the loadjava –u HR –r –v –proxy proxy_server:1020 http://my.server.com/this/is /the/path/my.jar
Password: password
When the URL support is used inside the server, you should have proper Java permissions to access to the remote source. The URL support also includes |
|
Instructs to create case-sensitive names, when the package is published. Unless the names are already all upper case, it usually requires quoting the names in PL/SQL. |
|
Specifies that the -grant HR -cleargrants |
|
Turns on SQL logging. |
|
Confers definer privileges upon classes. By default, class schema objects run with
the privileges of their invoker. This option is conceptually similar
to the UNIX |
|
Specifies that the prefix should be deleted from the name of any files or
JAR entries that start with |
-add-modules
<module-list> |
Specifies a comma-separated list of modules to automatically add, when a class being loaded is invoked as the main class in a Java session. Any modules explicitly required by these modules are also added to the session. |
|
Uses the When loading into a named module, the default resolver is
|
-prepend-resolver <"resolver-spec"> |
Prepends the specified list of resolver terms to the default resolver. |
-append-resolver
<"resolver-spec"> |
Appends the specified list of resolver terms
to the default resolver. For example, you can specify the
--append-resolve ((* -)) option to add this term to
the end of the default resolver.
|
-automatic |
Creates an automatic module from any JAR file that is loaded without any module-info. |
-hotload |
Captures the current list of packages
defined by the specified modules, in the module-data
object during hotloading. If packages are added later, or removed from
these modules, the module must be reloaded or re-hotloaded.
|
-module <name> |
Loads classes into the specified module.
This option is not required when you load JAR files that either have a
module-info JAR entry or if the -automatic
loadjava option is specified. It is also not required if a
module-info file is also loaded from the standard
corresponding directory location by the same loadjava
command. It throws an error if the module name specified does not match
the name specified in the module-info class or JAR file
loaded. If a module name is not specified or inferred, then objects are
loaded into the unnamed module.
|
|
Identifies the source file encoding for the compiler, overriding the matching value, if any, in the System.getProperty("file.encoding"); This option is relevant only when loading a source file. |
|
Displays all message to the designated file. |
|
Forces files to be loaded, even if they match digest table entries. |
|
Determines what classes and methods are referred to by the classes that the Because detecting references from source is more difficult than detecting references from class files, and because source is not generally used for distributing libraries, the The schema in which the missing classes are loaded will be the one specified by the |
|
Performs the same actions as |
|
Grants the Granting the Note:
|
|
Displays usage message on how to use the |
|
Loads the whole JAR file into the schema as a resource, instead of unpacking the JAR file and loading each class within it.Foot 1 |
|
Takes no action on the files. Actions include creating the schema objects, granting
execute permissions, and so on. The typical use is within an option
file to suppress creation of specific classes in a JAR. When used on
the command line, unless overridden in the option file, it will
cause the |
|
Specifies that the |
|
Treats the JAR files contained in other JAR files as resources. This is the default
behavior. This option is used to override the
|
|
Specifies that a public synonym for the classes should not be created. This is the
default behavior. This overrides the |
|
Suppresses the specified usage message, when either no option is specified or the
|
|
Causes the classes to be loaded without byte code verification.
|
|
Directs the |
|
Specifies the file can be provided with |
|
Works like the |
|
Specifies the |
|
Specifies a special case applied to methods with a single argument, which is of type
|
|
Compiles, if necessary, and resolves external references in classes after all classes on the command line have been loaded. If you do not specify the |
|
Causes the |
|
Designates the schema where schema objects are created. If not specified, then the
Finally, you must have the Note: The above-mentioned privileges allow the grantee to create and manipulate tables in any schema except the SYS schema. For security reasons, Oracle recommends that you use these settings only with great caution. |
|
Causes the output to be directed to |
|
Stops processing when an error occurs. Usually, if an error occurs while the
This option does not report |
|
Creates a |
|
Creates the |
|
Directs the |
|
Ignores unresolved errors,when combined with the |
|
Specifies a user name, password, and database connection string. The files will be loaded into this database instance. |
|
Directs the |
|
Creates a separate Database object containing the entire content of the JAR file, in addition to the database objects that are created for the classes and the resources in the JAR file. Database JAR objects are always created for module JARs and multi-release JARs. |
|
Prepends the name of the class or resource, when loading classes and resources from a JAR file. For module JARs, use the JAR file name rather than the module name as the database object prefix. |
Footnote 1
If you load a JAR file in this manner, then you cannot use it for resolution or execution.
12.6.3 loadjava Tool Argument Details
This section describes the details of some of the loadjava
tool arguments whose behavior is more complex than the summary descriptions contained in the loadjava Argument Summary table.
File Names
You can specify as many .class
, .java
,
.jar
, .zip
, and resource files as you want and in any
order. If you specify a JAR or ZIP file, then the loadjava
tool processes
the files in the JAR or ZIP. There is no JAR or ZIP schema object. If a JAR or ZIP contains
another JAR or ZIP, the loadjava
tool does not process them.
The best way to load files is to put them in a JAR or ZIP and then load the archive. Loading archives avoids the resource schema object naming complications. If you have a JAR or ZIP that works with the Java Development Kit (JDK), then you can be sure that loading it with the loadjava
tool will also work, without having to learn anything about resource schema object naming.
Schema object names are different from file names, and the loadjava
tool names different types of schema objects differently. Because class files are self-identifying, the mapping of class file names to schema object names done by the loadjava
tool is invisible to developers. Source file name mapping is also invisible to developers. The loadjava
tool gives the schema object the fully qualified name of the first class defined in the file. JAR and ZIP files also contain the names of their files.
However, resource files are not self identifying. The loadjava
tool generates Java resource schema object names from the literal names you supply as arguments. Because classes use resource schema objects and the correct specification of resources is not always intuitive, it is important that you specify resource file names correctly on the command line.
The perfect way to load individual resource files correctly is to run the loadjava
tool from the top of the package tree and specify resource file names relative to that directory.
Note:
The top of the package tree is the directory you would name in a CLASSPATH
.
If you do not want to follow this rule, then observe the details of resource file naming that follow. When you load a resource file, the loadjava
tool generates the resource schema object name from the resource file name, as literally specified on the command line. For example, if you type:
% cd /home/HR/javastuff % loadjava options alpha/beta/x.properties % loadjava options /home/HR/javastuff/alpha/beta/x.properties
Although you have specified the same file with a relative and an absolute path name, the loadjava
tool creates two schema objects, alpha/beta/x.properties
and ROOT/home/HR/javastuff/alpha/beta/x.properties
. The name of the resource schema object is generated from the file name as entered.
Classes can refer to resource files relatively or absolutely. To ensure that the loadjava
tool and the class loader use the same name for a schema object, enter the name on the command line, which the class passes to getResource()
or getResourceAsString()
.
Instead of remembering whether classes use relative or absolute resource names and changing directories so that you can enter the correct name on the command line, you can load resource files in a JAR, as follows:
% cd /home/HR/javastuff % jar -cf alpharesources.jar alpha/*.properties % loadjava options alpharesources.jar
To simplify the process further, place both the class and resource files in a JAR, which makes the following invocations equivalent:
% loadjava options alpha.jar % loadjava options /home/HR/javastuff/alpha.jar
The preceding loadjava
tool commands imply that you can use any path name to load the contents of a JAR file. Even if you run the redundant commands, the loadjava
tool would realize from the digest table that it need not load the files twice. This implies that reloading JAR files is not as time-consuming as it might seem, even when few files have changed between the different invocations of the loadjava
tool.
definer
{-definer | -d}
This option is identical to the definer rights in stored procedures and is conceptually similar to the UNIX setuid
facility. However, you can apply the -definer
option to individual classes, in contrast to setuid
, which applies to a complete program. Moreover, different definers may have different privileges. Because an application can consist of many classes, you must apply -definer
with care to achieve the desired results. That is, classes run with the privileges they need, but no more.
noverify
[-noverify]
This option causes the classes to be loaded without bytecode verification. oracle.aurora.security.JServerPermission(Verifier)
must be granted to run this option. Also, this option must be used in conjunction with -resolve
.
The verifier ensures that incorrectly formed Java binaries cannot be loaded for running on the server. If you know that the JAR or classes you are loading are valid, then the use of this option will speed up the process associated with the loadjava
tool. Some Oracle Database-specific optimizations for interpreted performance are put in place during the verification process. Therefore, the interpreted performance of your application may be adversely affected by using this option.
optionfile
[-optionfile <file>]
This option enables you to specify a file with different options that you can specify with the loadjava
tool. This file is read and processed by the loadjava
tool before any other loadjava
tool options are processed. The file can contain one or more lines, each of which contains a pattern and a sequence of options. Each line must be terminated by a newline character (\n
).
For each file or JAR entry that is processed by the loadjava
tool, the long name of the schema object that is going to be created is checked against the patterns. Patterns can end in a wildcard (*
) to indicate an arbitrary sequence of characters, or they must match the name exactly.
Options to be applied to matching Java schema objects are supplied on the rest of the line. Options are appended to the command-line options, they do not replace them. In case more than one line matches a name, the matching rows are sorted by length of pattern, with the shortest first, and the options from each row are appended. In general, the loadjava
tool options are not cumulative. Rather, later options override earlier ones. This means that an option specified on a line with a longer pattern will override a line with a shorter pattern.
This file is parsed by a java.io.StreamTokenizer
.
You can use Java comments in this file. A line comment begins with a #
. Empty lines are ignored. The quote character is a double quote ("
). That is, options containing spaces should be surrounded by double quotes. Certain options, such as -user
and -verbose
, affect the overall processing of the loadjava
tool and not the actions performed for individual Java schema objects. Such options are ignored if they appear in an option file.
To help package applications, the loadjava
tool looks for the META-INF/loadjava-options
entry in each JAR it processes. If it finds such an entry, then it treats it as an options file that is applied for all other entries in the JAR file. However, the loadjava
tool does some processing on entries in the order in which they occur in the JAR.
If the loadjava
tool has partially processed entities before it processes META-INF/loadjava-options
, then it attempts to patch up the schema object to conform to the applicable options. For example, the loadjava
tool alters classes that were created with invoker rights when they should have been created with definer rights. The fix for -noaction
is to drop the created schema object. This yields the correct effect, except that if a schema object existed before the loadjava
tool started, then it would have been dropped.
optiontable
[-optiontable table_name]
This option enables you to specify the properties of classes persistently. No mechanism is provided for loading the table. The table name must contain three character columns, PATTERN, OPTION, and VALUE. The value of PATTERN is interpreted in the same way as a pattern in an option file. The other two columns are the same as the corresponding command-line options and take an operand. Suppose, you create a table FOO with the following command:
create table foo (pattern varchar2(2000), option_name varchar2(2000), value varchar2(2000));
Then, you can use the optiontable
option in the following way:
loadjava -optiontable foo myjar.jar
For options that do not take an operand, the VALUE column should be NULL. The rows are processed in the same way as the lines of an option file are processed. To determine the options for a given schema object, the rows are examined and for any match the option is appended to the list of options. If two rows have the same pattern and contradictory options, such as -synonym and -nosynonym, then it is unspecified which will prevail. If two rows have the same pattern and option columns, then it is unspecified which VALUE will prevail.
publish
[-publish <package>] [-pubmain <number>]
The publishing options cause the loadjava
tool to create PL/SQL wrappers for methods contained in the processed classes. Typically, a user wants to publish wrappers for only a few classes in a JAR. These options are most useful when specified in an option file.
To be eligible for publication, the method must satisfy the following:
-
It must be a member of a
public
class. -
It must be declared
public
andstatic
. -
The method signature should satisfy the following rules so that it can be mapped:
-
Java arithmetic types for arguments and return values are mapped to
NUMBER
. -
char
as an argument and return type is mapped toVARCHAR
. -
java.lang.String
as an argument and return type is mapped toVARCHAR
. -
If the only argument of the method has type
java.lang.String
, special rules apply, as listed in the-pubmain
option description. -
If the return type is
void
, then a procedure is created. -
If the return type is an arithmetic,
char
, orjava.lang.String
type, then a function is created.
-
Methods that take arguments or return types that are not covered by the preceding rules are not eligible. No provision is made for OUT
and IN OUT
SQL arguments, OBJECT
types, and many other SQL features.
resolve
{-resolve | -r}
Use -resolve
to force the loadjava
tool to compile and resolve a class that has previously been loaded. It is not necessary to specify -force
, because resolution is performed after, and independent of, loading.
resolver
{-resolver | -R} resolver_specification
This option associates an explicit resolver specification with the class schema objects that the loadjava
tool creates or replaces.
A resolver specification consists of one or more items, each of which consists of a name specification and a schema specification expressed in the following syntax:
"((name_spec schema_spec) [(name_spec schema_spec)] ...)"
A name specification is similar to a name in an import
statement. It can be a fully qualified Java class name or a package name whose final element is the wildcard character asterisk (*
) or simply an asterisk (*
). However, the elements of a name specification must be separated by slashes (/
), not periods (.
). For example, the name specification a/b/*
matches all classes whose names begin with a.b
. The special name *
matches all class names.
A schema specification can be a schema name or the wildcard character dash (-
). The wildcard does not identify a schema, but directs the resolve operation not to mark a class invalid, because a reference to a matching name cannot be resolved. Use dash (-
) when you must test a class that refers to a class you cannot or do not want to load. For example, GUI classes that a class refers to but does not call, because when run in the server there is no GUI.
When looking for a schema object whose name matches the name specification, the resolution operation looks in the schema named by the partner schema specification.
The resolution operation searches schemas in the order in which the resolver specification lists them. For example,
-resolver '((* HR) (* PUBLIC))'
This implies that search for any reference first in HR
and then in PUBLIC
. If a reference is not resolved, then mark the referring class invalid and display an error message.
Consider the following example:
-resolver "((* HR) (* PUBLIC) (my/gui/* -))"
This implies that search for any reference first in HR
and then in PUBLIC
. If the reference is to a class in the package my.gui
and is not found, then mark the referring class valid and do not display an error. If the reference is not to a class in my.gui
and is not found, then mark the referring class invalid and produce an error message.
user
{-user | -u} user/password[@database_url]
By default, the loadjava
tool loads into the logged in schema specified by the -user
option. You use the -schema
option to specify a different schema to load into. This does not require you to log in to that schema, but does require that you have sufficient permissions to alter the schema.
The permissible forms of @
database_url
depend on whether you specify -oci
or -thin
, as described:
-
-oci:@
database_url
is optional. If you do not specify, then theloadjava
tool uses the user's default database. If specified,database_url
can be a TNS name or an Oracle Net Services name-value list. -
-thin:@
database_url
is required. The format ishost
:
lport
:
SID
.where:
-
host
is the name of the computer running the database. -
lport
is the listener port that has been configured to listen for Oracle Net Services connections. In a default installation, it is5521
. -
SID
is the database instance identifier. In a default installation, it isORCL
.
-
The following are examples of the loadjava
tool commands:
-
Connect to the default database with the default OCI driver, load the files in a JAR into the
TEST
schema, and then resolve them:loadjava -u joe -resolve -schema TEST ServerObjects.jar Password: password
-
Connect with the JDBC Thin driver, load a class and a resource file, and resolve each class:
loadjava -thin -u HR@dbhost:5521:orcl \ -resolve alpha.class beta.props Password: password
-
Add Betty and Bob to the users who can run
alpha.class
:loadjava -thin -schema test -u HR@localhost:5521:orcl \ -grant BETTY,BOB alpha.class Password: password
jarsasdbobjects
This option indicates that JARs processed by the current loadjava
tool are to be stored in the database along with the classes they contain, and knowledge of the association between the classes and the JAR is to be retained in the database. In other words, this argument indicates that the JARs processed by the current loadjava
tool are to be stored in the database as database resident JARs.
prependjarnames
This option is used with the -jarsasdbobjects
option. This option enables classes with the same names coming from different JARs to coexist in the same schema.
Related Topics