The syntax of the loadjava tool command is as follows:

loadjava {-user | -u} user [@database] [options]
file.java | file.class | file.jar | file.zip |
file.sqlj | resourcefile | URL...
  [-casesensitivepub]
  [-cleargrants]
  [-debug]
  [-d | -definer]
  [-dirprefix prefix]
  [-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"]
  [-resolveonly]
  [-S | -schema schema]
  [-stdout]
  [-stoponerror]
  [-s | -synonym]
  [-tableschema schema]
  [-t | -thin]

  [-unresolvedok]
  [-v | -verbose]
  [-jarsasdbobjects]
  [-prependjarnames]
  [-nativecompile]

Table 13-2 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 two exceptions to this, as follows:

• 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 the loadjava tool to skip the digest table lookup.

• The -grant option is cumulative. Every user specified in every invocation of the loadjava tool for a given class in a given schema has the EXECUTE privilege.

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, .sqlj, .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.

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 and static.

• 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 to VARCHAR.

  • java.lang.String as an argument and return type is mapped to VARCHAR.

  • 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, or java.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 the loadjava 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 is host: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 is 5521.

  • SID is the database instance identifier. In a default installation, it is ORCL.

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.