Skip Headers

Oracle® Database Java Developer's Guide
10g Release 1 (10.1)

Part Number B12021-01
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
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

11
Schema Object Tools

This chapter describes the schema object tools that you use in the Oracle Database Java environment. You run these tools from a UNIX shell or the Windows NT DOS prompt.


Note:

All names supplied within these tools are case sensitive. Thus, the schema, user name, and password will not be changed to upper case.


The following sections describe the schema object tools:

Schema Object Tool Overview

Unlike a conventional JVM, which compiles and loads Java files, the OracleJVM compiles and loads schema objects. The three kinds of Java schema objects are as follows:

To make a class file runnable by the OracleJVM, you use the loadjava tool to create a Java class schema object from the class file or the source file and load it into a schema. To make a resource file accessible to the OracleJVM, you use loadjava to create and load a Java resource schema object from the resource file.

The dropjava tool does the reverse of the loadjava tool; it deletes schema objects that correspond to Java files. You should always use dropjava to delete a Java schema object that was created with loadjava; dropping by means of SQL DDL commands will not update auxiliary data maintained by loadjava and dropjava.

What and When to Load

You must load resource files with loadjava. If you create .class files outside the database with a conventional compiler, then you must load them with loadjava. The alternative to loading class files is to load source files and let the Oracle Database system compile and manage the resulting class schema objects. In Oracle Database 10g, the most productive approach is to compile and debug most of your code outside the database, and then load the .class files. For a particular Java class, you can load either its .class file or its .java file, but not both.

The loadjava tool accepts JAR files that contain either source and resource files or class and resource files. You can load a class's source or its class file but not both. When you pass loadjava a JAR file or a ZIP file, loadjava opens the archive and loads its members individually; there are no JAR or ZIP schema objects. A file whose content has not changed since the last time it was loaded is not reloaded; therefore, there is little performance penalty for loading JARs. Loading JAR files is the simplest and most foolproof way to use loadjava.

It is illegal for two schema objects in the same schema to define the same class. For example, suppose a.java defines class x and you want to move the definition of x to b.java. If a.java has already been loaded, then loadjava will reject an attempt to load b.java (which also defines x). Instead, do either of the following:

Resolution

All Java classes contain references to other classes. A conventional JVM searches for classes in the directories, ZIP files, and JARs named in the CLASSPATH. The OracleJVM, by contrast, searches schemas for class schema objects. Each Oracle Database class has a resolver spec, which is the Oracle Database counterpart to the CLASSPATH. For a hypothetical class, alpha, its resolver spec is a list of schemas to search for classes that alpha uses. Notice that resolver specs are per-class, whereas in a classic JVM, CLASSPATH is global to all classes.

In addition to a resolver spec, each class schema object has a list of interclass reference bindings. Each reference list item contains a reference to another class and one of the following:

An Oracle Database facility known as the resolver maintains reference lists. For each interclass reference in a class, the resolver searches the schemas specified by the class's resolver spec for a valid class schema object that satisfies the reference. If all references are resolved, the resolver marks the class valid. A class that has never been resolved, or has been resolved unsuccessfully, is marked invalid. A class that depends on a schema object that becomes invalid is also marked invalid at the time the first class is marked invalid; in other words, invalidation cascades upward from a class to the classes that use it and the classes that use them, and so on. When resolving a class that depends on an invalid class, the resolver first tries to resolve the referenced class, because it may be marked invalid only because it has never been resolved. The resolver does not re-resolve classes that are marked valid.

A class developer can direct loadjava to resolve classes or can defer resolution until run time. The resolver runs automatically when a class tries to load a class that is marked invalid. It is best to resolve before run time to learn of missing classes early; unsuccessful resolution at run time produces a "class not found" exception. Furthermore, run-time resolution can fail for the following reasons:

The loadjava tool has two resolution modes:

  1. Load-and-resolve (-resolve option): Loads all classes you specify on the command line, marks them invalid, and then resolves them. Use this mode when initially loading classes that refer to each other, and in general when reloading isolated classes as well. By loading all classes and then resolving them, this mode avoids the error message that occurs if a class refers to a class that will be loaded later in the execution of the command.
  2. Load-then-resolve (no -resolve option): Resolves each class at runtime.


    Note:

    As with a Java compiler, loadjava resolves references to classes but not to resources; be sure to correctly load the resource files your classes need.


If you can, defer resolution until all classes have been loaded; this technique avoids the situation in which the resolver marks a class invalid because a class it uses has not yet been loaded.

Digest Table

The schema object digest table is an optimization that is usually invisible to developers. The digest table enables loadjava to skip files that have not changed since they were last loaded. This feature improves the performance of makefiles and scripts that invoke loadjava for collections of files, only some of which need to be reloaded. A reloaded archive file might also contain some files that have changed since they were last loaded and some that have not.

The loadjava tool detects unchanged files by maintaining a digest table in each schema. The digest table relates a file name to a digest, which is a shorthand representation of the file's content (a hash). Comparing digests computed for the same file at different times is a fast way to detect a change in the file's content--much faster than comparing every byte in the file. For each file it processes, loadjava computes a digest of the file's content and then looks up the file name in the digest table. If the digest table contains an entry for the file name that has the identical digest, then loadjava does not load the file, because a corresponding schema object exists and is up to date. If you invoke loadjava with the -verbose option, then it will show you the results of its digest table lookups.

Normally, the digest table is invisible to developers, because loadjava and dropjava keep the table synchronized with schema object additions, changes, and deletions. For this reason, always use dropjava to delete a schema object that was created with loadjava, even if you know how to drop a schema object using DDL. If the digest table becomes corrupted (loadjava does not update a schema object whose file has changed), use loadjava's -force option to bypass the digest table lookup or delete all rows from the table, which is named JAVA$CLASS$MD5$TABLE.

Compilation

Loading a source file creates or updates a Java source schema object and invalidates the class schema object(s) previously derived from the source. If the class schema objects do not exist, loadjava creates them. The loadjava tool invalidates the old class schema objects because they were not compiled from the newly loaded source. Compilation of a newly loaded source, called for instance A, is automatically triggered by any of the following conditions:

To force compilation when you load a source file, use loadjava -resolve.

The compiler writes error messages to the predefined USER_ERRORS view; loadjava retrieves and displays the messages produced by its compiler invocations.

The compiler recognizes some options. There are two ways to specify options to the compiler. If you run loadjava with the -resolve option (which may trigger compilation), you can specify compiler options on the command line.

You can additionally specify persistent compiler options in a per-schema database table known as JAVA$OPTIONS, which you create as described shortly. You can use the JAVA$OPTIONS table for default compiler options, which you can override selectively with a loadjava command-line option.


Note:

A command-line option both overrides and clears the matching entry in the JAVA$OPTIONS table.


A JAVA$OPTIONS row contains the names of source schema objects to which an option setting applies; you can use multiple rows to set the options differently for different source schema objects. The compiler looks up options in the JAVA$OPTIONS table when it has been invoked without a command line--that is, by the class loader--or when the command line does not specify an option. When compiling a source schema object for which there is neither a JAVA$OPTIONS entry nor a command-line value for an option, the compiler assumes a default value as follows:

You can set JAVA$OPTIONS entries by means of the following functions and procedures, which are defined in the database package DBMS_JAVA:

The name parameter is a Java package name, or a fully qualified class name, or the empty string. When the compiler searches the JAVA$OPTIONS table for the options to use for compiling a Java source schema object, it uses the row whose name most closely matches the schema object's fully qualified class name. A name whose value is the empty string matches any schema object name.

The option parameter is either 'online' or 'encoding'.

A schema does not initially have a JAVA$OPTIONS table. To create a JAVA$OPTIONS table, use the DBMS_JAVA package's java.set_compiler_option procedure to set a value; the procedure will create the table if it does not exist. Specify parameters in single quotes. For example:

SQL> execute dbms_java.set_compiler_option('x.y', 'online', 'false');

Table 11-1 represents a hypothetical JAVA$OPTIONS database table. Because the table has no entry for the encoding option, the compiler will use the default or the value specified on the command line. The online options shown in the table match schema object names as follows:

loadjava

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:

You can execute the loadjava tool either through the command line (as described below) or through the loadjava method contained within the DBMS_JAVA class. To execute within your Java application, do the following:

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

where the options are the same as specified below. Separate each option with a blank. Do not separate the options with a comma. The only exception for this is the -resolver option, which contains blanks. For -resolver, specify all other options in the first input parameter, and the -resolver options in the second parameter. This is demonstrated below:

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

Do not specify the following options, because they relate to the database connection for the loadjava command-line tool: -thin, -oci, -user, -password. 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 subdirectory under $ORACLE_HOME.


Just before the loadjava tool exits, it checks whether the execution 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 loadjava to terminate prematurely. There errors are printed with the following syntax:

exiting: <error_reason>

Syntax

loadjava {-user | -u} <user>/<password>[@<database>] [options] 
<file>.java | <file>.class | <file>.jar | <file>.zip |
<file>.sqlj | <resourcefile> ... 
  [-action]
  [-andresolve]
  [-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]
  [-nocasesensitivepub]
  [-nocleargrants]
  [-nodefiner]
  [-nogrant]
  [-norecursivejars]
  [-noschema]
  [-noserverside]
  [-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] 
  [-time]
  [-unresolvedok]
  [-v | -verbose]

Argument Summary

Table 11-2 summarizes the loadjava arguments. If you execute loadjava multiple times specifying the same files and different options, the options specified in the most recent invocation hold. There are two exceptions:

  1. If loadjava does not load a file because it matches a digest table entry, most options on the command line have no effect on the schema object. The exceptions are -grant and -resolve, which are always obeyed. Use the -force option to direct loadjava to skip the digest table lookup.
  2. The -grant option is cumulative; every user specified in every loadjava invocation for a given class in a given schema has the EXECUTE privilege.

    Table 11-2 loadjava Argument Summary  
    Argument Description

    <filenames>

    You can specify any number and combination of .java, .class, .ser, .jar .zip, and resource file name arguments, in any order.

    -action

    Perform all actions. This is the default behavior. This option can be used to override a -noaction option, which may be specified in an option file.

    -andresolve

    To be used in place of -resolve. This option causes files to be compiled or resolved at the time that they are loaded--rather than in a separate pass (as -resolve does). Resolving at the time of loading the class will not invalidate dependent classes.

    This option should be used only to replace classes that were previously loaded. If you changed only the code for existing methods within the class, you should use this option instead of the -resolve option.

    -casesensitivepub

    Publishing will create case sensitive names. Unless the names are already all upper case, it will usually require quoting the names in PL/SQL.

    -cleargrants

    The -grant option causes loadjava to grant execute privileges to classes, sources, and resources. However, it does not cause it to revoke any privileges. If -cleargrants is specified, loadjava will revoke any existing grants of execute privilege before it grants execute privilege to the users and roles specified by the -grant operand. For example, if the intent is to have execute privilege granted to SCOTT and only SCOTT, then the proper options are the following: -grant SCOTT -cleargrants.

    -debug

    Turns on SQL logging.

    -definer

    By default, class schema objects run with the privileges of their invoker. This option confers definer (the developer who invokes loadjava) privileges upon classes instead. (This option is conceptually similar to the UNIX setuid facility.)

    -dirprefix <prefix>

    For any files or JAR entries that start with <prefix>, this prefix will be deleted from the name before the name of the schema object is determined. For classes and sources, the name of the schema object is determined by their contents, so this option will only have an effect for resources.

    -encoding

    Identifies the source file encoding for the compiler, overriding the matching value, if any, in the JAVA$OPTIONS table. Values are the same as for the javac -encoding option. If you do not specify an encoding on the command line or in a JAVA$OPTIONS table, the encoding is assumed to be "System.getProperty("file.encoding");". The -encoding option is relevant only when loading a source file.

    -fileout <file>

    Prints all message to the designated file.

    -force

    Forces files to be loaded, even if they match digest table entries.

    -genmissing

    Determines what classes and methods are referred to by the classes that loadjava is asked to process. Any classes not found in the database or file arguments are called "missing" classes. This option generates dummy definitions for missing classes containing all referred to methods. It then loads the generated classes into the database. This processing happens before the class resolution.

    Because detecting references from source is more difficult than detecting references from class files, and because source is not generally used for distributing libraries, loadjava will not attempt to do this processing for source files.

    The schema in which the missing classes are loaded will be the one specified by the -user command-line option, even when referring classes are created in some other schema. The created classes will be flagged as such so that tools can recognize them. In particular, this is needed, so that the verifier can recognize generated classes.

    -genmissingjar <jar_file>

    This option performs the same actions as -genmissing. In addition, it creates a JAR file, named <jar_file>, that contains the definitions of any generated classes.

    -grant

    Grants the EXECUTE privilege on loaded classes to the listed users. (To call the methods of a class, users must have the EXECUTE privilege.) Any number and combination of user names can be specified, separated by commas but not spaces (-grant Bob,Betty not -grant Bob, Betty). Note: -grant is a "cumulative" option; users are added to the list of those with the EXECUTE privilege. To remove privileges, use the -cleargrants option.

    To grant the EXECUTE privilege on an object in someone else's schema requires that the original CREATE PROCEDURE privilege was granted with WITH GRANT options.

    Note: You must uppercase the schema name.

    -help

    Prints the usage message on how to use the loadjava tool and its options.

    -jarasresource

    Instead of unpacking the JAR file and loading each class within it, loads the whole JAR file into the schema as a resource.

    -noaction

    Take no action on the files. Actions include creating the schema objects, granting execute permissions, and so on. The normal 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 loadjava to ignore all files. Except that JAR files will still be examined to determine if they contain a META-INF/loadjava-options entry. If so, then the option file is processed. An -action option contained in the option file will override a -noaction option specified on the command-line.

    -nocasesensitivepub

    All lower case characters are converted to upper case. Transitions from lower to upper case characters will cause an underscore (_) to be inserted. For example, the method name IsXCharView becomes IS_XCHAR_VIEW. This command only modifies the -publish option.

    -nocleargrants

    Causes loadjava to omit revoking of execute privileges. This option can be used to override a -cleargrants option.

    -nodefiner

    Make the loaded classes (or classes derived from loaded sources) invoker's rights classes. This is the default behavior. This option can be used to override a -definer option.

    -nogrant

    Do not grant any execute privileges to the loaded classes. This is the default behavior. This option is used to override a -grant option.

    -norecursivejars

    Treat JARs contained in other JARs as resources. This is the default behavior. This option can be used to override a -recursivejars option.

    -noschema

    Place the loaded classes, sources, and resources into the schema associated with the user specified in a -user option. This is the default behavior. It can be used to override a -schema option.

    -nosynonym

    Do not create a public synonym for the classes. This is the default behavior. This overrides a -synonym option.

    -noserverside

    Changes the behavior of dbms_java.loadjava to use a JDBC driver to access objects.Normally, server-side loadjava has a performance enhancement that it will modify the object directly--without using a JDBC driver to access the schemas. However, if you want the server-side to use a JDBC driver, use this option.

    -nousage

    Suppresses the usage message that is given if either no option is specified or if the -help option is specified.

    -noverify

    Causes the classes to be loaded without bytecode verification. You must be granted oracle.aurora.security.JServerPermission
    ("Verifier") to execute this option. To be effective, this option must be used in conjunction with -resolve.

    -oci | -oci8

    Directs loadjava to communicate with the database using the OCI JDBC driver. -oci and -thin are mutually exclusive; if neither is specified, -oci is used by default. Choosing -oci implies the syntax of the -user value. You do not need to provide the URL.

    -optionfile <file>

    A file can be provided with loadjava options. See optionfile discussion below for full information.

    -optiontable <tablename>

    This option works like -optionfile except that the source for the patterns and options is a SQL table rather than a file. It is intended to allow people to specify the properties of classes persistently. No mechanism is provided for loading the table. The table name must contain three character columns named 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 specify a command-line option (including the dash) and for options that take an operand, the value of the operand. For options that do not take an operand, the VALUE column should be null. The rows are processed just like lines of an option file would be. To determine the options for a given schema object, the rows are examined (shortest pattern first) and for any that 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, it is unspecified which will prevail. If two rows have the same pattern and option columns, it is unspecified which VALUE will prevail.

    -publish <package>

    The <package> is created (or replaced) by loadjava. Wrappers for the eligible methods will be defined in this package. Through the use of option files, a single invocation of loadjava can be instructed to create more than one package. Each package will undergo the same name transformations as the methods. See the publish section below for more information.

    -pubmain <number>

    A special case applied to methods with a single argument, which is of type java.lang.String. Multiple variants of the SQL procedure or function will be created, each of which takes a different number of arguments of type VARCHAR. In particular, variants are created taking all numbers of arguments up to and including <number>. The default value is three. This option applies to main, as well as any method that has exactly one argument of type java.lang.String.

    -recursivejars

    Normally, if loadjava encounters an entry in a JAR with a .jar extension, it will load the entry as a resource. If this option is specified, then loadjava will process contained JARs as if they were top-level JARs. That is, it will read their entries and load classes, sources, and resources.

    -resolve

    Compiles (if necessary) and resolves external references in classes after all classes on the command line have been loaded. If you do not specify -resolve, loadjava loads files but does not compile or resolve them.

    -resolver

    Specifies an explicit resolver spec, which is bound to the newly loaded classes. If -resolver is not specified, the default resolver spec, which includes current user's schema and PUBLIC, is used. See "resolver" for details.

    -resolveonly

    Causes loadjava to skip the initial creation step. It will still perform grants, resolves, create synonyms, and so on.

    -schema

    Designates the schema where schema objects are created. If not specified, the -user schema is used. To create a schema object in a schema that is not your own, you must have the CREATE PROCEDURE or CREATE ANY PROCEDURE privilege. You must have CREATE TABLE or CREATE ANY TABLE privilege. Finally, you must have the JServerPermission loadLibraryInClass for the class.

    -stdout

    Causes the output to be directed to stdout, rather than to stderr.

    -stoponerror

    Normally, if an error occurs while loadjava is processing files, it will issue a message and continue to process other classes. This option stops when an error occurs. In addition, it reports all errors that apply to Java objects and are contained in the USER_ERROR table of the schema in which classes are being loaded. Except that is does not report ORA-29524 errors. These are errors that are generated when a class cannot be resolved because a referred to class could not be resolved. Thus, these errors are a secondary effect of whatever caused a referred to class to be unresolved. This usually makes it easy to pinpoint the underlying cause of the failure.

    -synonym

    Creates a PUBLIC synonym for loaded classes making them accessible outside the schema into which they are loaded. To specify this option, you must have the CREATE PUBLIC SYNONYM privilege. If -synonym is specified for source files, classes compiled from the source files are treated as if they had been loaded with -synonym.

    -tableschema <schema>

    Creates the loadjava internal tables within this specified schema, rather than in the Java file destination schema.

    -thin

    Directs loadjava to communicate with the database using the thin JDBC driver. -oci and -thin are mutually exclusive; if neither is specified, then -oci is used by default. Choosing -thin implies the syntax of the -user value. You do need to specify the appropriate URL through the -user option.

    -time

    Prints a timestamp on every message.

    -unresolvedok

    When combined with -resolve, will ignore unresolved errors.

    -user

    Specifies a user, password, and database connect string; the files will be loaded into this database instance. The argument has the form <username>/<password>[@<database>].

    -verbose

    Directs loadjava to print detailed status messages while running. Use -verbose to learn when loadjava does not load a file because it matches a digest table entry.

Argument Details

This section describes the details of loadjava arguments whose behavior is more complex than the summary descriptions contained in Table 11-2.

File Names

You can specify as many .class, .java, .jar, .zip, and resource files as you like, in any order. If you specify a JAR or ZIP file, then loadjava processes the files in the JAR or ZIP; there is no JAR or ZIP schema object. If a JAR or ZIP contains a JAR or ZIP, loadjava 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 described later in this section. If you have a JAR or ZIP that works with the JDK, then you can be sure that loading it with loadjava will also work, without having to learn anything about resource schema object naming.

Schema object names are slightly different from file names, and loadjava names different types of schema objects differently. Because class files are self-identifying (they contain their names), loadjava's mapping of class file names to schema object names is invisible to developers. Source file name mapping is also invisible to developers; loadjava 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. loadjava generates Java resource schema object names from the literal names you supply as arguments (or the literal names in a JAR or ZIP file). Because running classes use resource schema objects, it is important that you specify resource file names correctly on the command line, and the correct specification is not always intuitive. The surefire way to load individual resource files correctly is:

Run loadjava from the top of the package tree and specify resource file names relative to that directory. (The "top of the package tree" is the directory you would name in a Java CLASSPATH list.)

If you do not want to follow this rule, observe the details of resource file naming that follow. When you load a resource file, loadjava generates the resource schema object name from the resource file name as literally specified on the command line. Suppose, for example you type:

% cd /home/scott/javastuff
% loadjava options alpha/beta/x.properties
% loadjava options /home/scott/javastuff/alpha/beta/x.properties

Although you have specified the same file with a relative and an absolute path name, loadjava creates two schema objects, one called alpha/beta/x.properties, the other ROOT/home/scott/javastuff/alpha/beta/x.properties. (loadjava inserts ROOT because schema object names cannot begin with the "/" character; however, that is an implementation detail that is unimportant to developers.) The important point is that a resource schema object's name is generated from the file name as entered.

Classes can refer to resource files relatively (for example, b.properties) or absolutely (for example, /a/b.properties). To ensure that loadjava and the class loader use the same name for a schema object, follow this rule when loading resource files:

Enter the name on the command line that 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/scott/javastuff
% jar -cf alpharesources.jar alpha/*.properties
% loadjava options alpharesources.jar

Or, to simplify further, put both the class and resource files in a JAR, which makes the following invocations equivalent:

% loadjava options alpha.jar 
% loadjava options /home/scott/javastuff/alpha.jar

The two loadjava commands in this example make the point that you can use any path name to load the contents of a JAR file. Even if you did execute the redundant commands shown above, loadjava would realize from the digest table that it did not need to load the files twice. That means that reloading JAR files is not as time-consuming as it might seem, even when few files have changed between loadjava invocations.

definer
{-definer | -d}

The -definer option is identical to definer's rights in stored procedures and is conceptually similar to the UNIX setuid facility; however, whereas setuid applies to a complete program, you can apply -definer class by class. Moreover, different definers may have different privileges. Because an application may consist of many classes, you must apply -definer with care to achieve the results desired, namely classes that run with the privileges they need,0 but no more. For more information on definer's rights, see "Controlling the Current User".

noverify
[-noverify]

Causes the classes to be loaded without bytecode verification. You must be granted oracle.aurora.security.JServerPermission(Verifier) to execute this option. In addition, this option must be used in conjunction with -r.

The verifier ensures that incorrectly formed Java binaries cannot be loaded for execution in the server. If you know that the JAR or classes you are loading are valid, use of this option will speed up the loadjava process. Some Oracle Database-specific optimizations for interpreted performance are put in place during the verification process. Thus, interpreted performance of your application may be adversely affected by using this option.

optionfile
[-optionfile <file>]

A file can be provided with loadjava options. This <file> is read and processed by loadjava before any other loadjava options are processed. This <file> may 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 loadjava, the long name of the schema object that is going to be created (typically, the name of the class with a dot "." replaced by a slash "/") is checked against the patterns. Patterns can end in a wildcard (*) to indicate an arbitrary sequence of characters; otherwise, 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, loadjava 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.

Java comments (both /* */ and //) are allowed. A line comment begins with a #. Empty lines are ignored. The quote character is a double quote ("). That is, options containing spaces (common in -resolver options, for example) should be surrounded by double quotes. Certain options, such as -user or -verbose, affect the overall processing of loadjava and not the actions performed for individual Java schema objects. Such options are ignored if they appear in an option file.

As an aid in packaging applications, loadjava looks for an entry named META-INF/loadjava-options in each JAR it processes. If it finds such an entry, it treats it as an options file that is applied for all other entries in the option file. However, loadjava does some processing on entries in the order in which they occur in the JAR.

In case it has partially processed entities before it processes the META-INF/loadjava-options, the loadjava tool will attempt to patch up the schema object to conform to the applicable options. For example, by altering classes that were created with invoker's rights when they should have been created with definer's rights. The fix for -noaction will be to drop the created schema object. This will yield the correct effect except that if a schema object existed before loadjava started, it will have been dropped.

publish
[-publish <package>]
[-pubmain <number>]

The publishing options cause loadjava 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:

  1. The method must be a member of a public class.
  2. The method must itself be declared public and static.
  3. The method signature must be "mappable", which is defined in the following rules:
    • Java arithmetic types (byte, int, long, float, double) as arguments and return types 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 -pubstring option description.
    • If the return type is void, then a procedure is created.
    • If the return type is arithmetic, char, or java.lang.String, then a function is created and its return type is as specified in an earlier rule.

Methods that take arguments or return types that are not covered by the above rules are not eligible. No provision is made for OUT, IN-OUT SQL arguments, OBJECT types, or for many other SQL features.

resolve
{-resolve | -r}

Use -resolve to force loadjava to compile (if necessary) and resolve a class that has previously been loaded. It is not necessary to specify -force, because resolution is performed after, and independently of, loading.

resolver
{-resolver | -R} "resolver spec"

This option associates an explicit resolver spec with the class schema objects that loadjava creates or replaces.

A resolver spec consists of one or more items, each of which consists of a name spec and a schema spec expressed in the following syntax:

"((name_spec schema_spec) [(name_spec schema_spec)] ...)"

The resolution operation interprets a resolver spec item as follows:

When looking for a schema object whose name matches the name spec, look in the schema named by the partner schema spec.

The resolution operation searches schemas in the order in which the resolver spec lists them. For example,

-resolver '((* SCOTT) (* PUBLIC))' 

means the following:

Search for any reference first in SCOTT and then in PUBLIC. If a reference is not resolved, then mark the referring class invalid and display an error message; in other words, call attention to missing classes.

The following example:

-resolver "((* SCOTT) (* PUBLIC) (my/gui/* -))" 

means the following:

Search for any reference first in SCOTT and then in PUBLIC. If the reference is not found, and is to a class in the package my.gui then mark the referring class valid, and do not display an error; in other words, ignore missing classes in this package. If the reference is not found and is not to a class in my.gui, then mark the referring class invalid and produce an error message.

user
{-user | -u} <user>/<password>[@<database>]

By default, loadjava loads into the login schema specified by the -user option. Use the -schema option to specify a different schema to load into. This does not involve a login into that schema, but does require that you have sufficient permissions to alter it.

The permissible forms of @<database> depend on whether you specify -oci or -thin; -oci is the default.

Here are examples of loadjava commands:

dropjava

The dropjava tool is the converse of loadjava. It transforms command-line file names and JAR or ZIP file contents to schema object names, then drops the schema objects and deletes their corresponding digest table rows. You can enter .java, .class, .ser, .zip, .jar, and resource file names on the command line in any order.

Alternatively, you can specify a schema object name (full name, not short name) directly to dropjava. A command-line argument that does not end in .jar, .zip, .class, .java is presumed to be a schema object name. If you specify a schema object name that applies to multiple schema objects (such as a source schema object Foo and a class schema object Foo), all will be removed.

Dropping a class invalidates classes that depend on it, recursively cascading upwards. Dropping a source drops classes derived from it.


Note:

You must remove Java schema objects in the same way that you first loaded them. If you translate on a client and load classes and resources directly, run dropjava on the same classes and resources.


You can execute the dropjava tool either through the command line (as described below) or through the dropjava method contained within the DBMS_JAVA class. To execute within your Java application, do the following:

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

where the options are the same as specified below. Separate each option with a blank. Do not separate the options with a comma. The only exception for this is the -user option. The connection is always made to the current session, so you cannot specify another user name through the -user option.

For -resolver, you should specify all other options first, a comma, then the -resolver option with its definition. Do not specify the following options, because they relate to the database connection for the loadjava command-line tool: -thin, -oci, -user, -password. The output is directed to stderr. Set serveroutput on and call dbms_java.set_output as appropriate.

Syntax

dropjava [options] {<file>.java | <file>.class | file.sqlj | 
<file>.jar | <file.zip> | <resourcefile>} ...
  -u | -user <user>/<password>[@<database>]
  [-genmissingjar <JARfile>]
  [-jarasresource]
  [-noserverside]
  [-o | -oci | -oci8]  
  [-optionfile <file>]
  [-optiontable <table_name>]
  [-S | -schema <schema>] 
  [ -stdout ]
  [-s | -synonym]
  [-t | -thin] 
  [-time]
  [-v | -verbose]

Argument Summary

Table 11-3 summarizes the dropjava arguments.

Table 11-3 dropjava Argument Summary  
Argument Description

-user

Specifies a user, password, and optional database connect string; the files will be dropped from this database instance.

<filenames>

You can specify any number and combination of .java, .class, .sqlj, .ser, .jar.zip, and resource file names, in any order.

-genmissingjar <file>

dropjava treats the operand of this option as a file to be processed.

-jarasresource

Drops the whole JAR file, which was previously loaded as a resource.

-noserverside

Changes the behavior of the server-side dropjava tool to use a JDBC driver to access shemas.Normally, server-side dropjava has a performance enhancement that it will modify the schema directly--without using a JDBC driver to access the schemas. However, if you want the server-side to use a JDBC driver, use this option.

-oci | -oci8

Directs dropjava to connect with the database using the OCI JDBC driver. -oci and -thin are mutually exclusive; if neither is specified, then -oci is used by default. Choosing -oci implies the form of the -user value.

-optionfile <file>

This has the same usage as for loadjava.

-optiontable <table>

This has the same usage as for loadjava.

-schema

Designates the schema from which schema objects are dropped. If not specified, the logon schema is used. To drop a schema object from a schema that is not your own, you need the DROP ANY PROCEDURE and UPDATE ANY TABLE privileges.

-stdout

Causes the output to be directed to stdout, rather than to stderr.

-synonym

Drops a PUBLIC synonym that was created with loadjava.

-thin

Directs dropjava to communicate with the database using the thin JDBC driver. -oci and -thin are mutually exclusive; if neither is specified, then -oci is used by default. Choosing -thin implies the form of the -user value.

-time

Prints a timestamp on every message.

-verbose

Directs dropjava to emit detailed status messages while running.

Argument Details

File Names

dropjava interprets most file names as loadjava does:

If a file name has another extension or no extension, then dropjava interprets the file name as a schema object name and drops all source, class, and resource objects that match the name. For example, the hypothetical file name alpha drops whichever of the following exists: the source schema object named alpha, the class schema object named alpha, and the resource schema object named alpha. If the file name begins with the "/" character, then dropjava inserts ROOT to the schema object name.

If dropjava encounters a file name that does not match a schema object, it displays a message and processes the remaining file names.

user
{-user | -u} <user>/<password>[@<database>]

The permissible forms of @<database> depend on whether you specify -oci or -thin; -oci is the default.

Here are some dropjava examples.

Dropping Resources

Care must be taken if you are removing a resource that was loaded directly into the server. This includes profiles if you translated on the client without using the -ser2class option. When dropping source or class schema objects, or resource schema objects that were generated by the server-side SQLJ translator, the schema objects will be found according to the package specification in the applicable .sqlj source file. However, the fully qualified schema object name of a resource that was generated on the client and loaded directly into the server depends on path information in the .jar file or on the command line at the time you loaded it. If you use a .jar file to load resources and use the same .jar file to remove resources, there will be no problem. If, however, you use the command line to load resources, then you must be careful to specify the same path information when you run dropjava to remove the resources.

ojvmjava

The ojvmjava tool is an interactive interface to a database instance's session namespace. You specify database connection arguments when you start ojvmjava. It then presents you with a prompt to indicate that it is ready for commands.

The shell can launch an executable, that is, a class with a static main() method. Executables must have been loaded with loadjava.

Syntax

ojvmjava {-user <user>[/<password>@database] [options] 
  [@<filename>]
  [-batch]
  [-c | -command <command> <args>]
  [-debug]
  [-d | -database <conn_string>]
  [-fileout <filename>]
  [-o | -oci | -oci8]
  [-oschema <schema>]
  [-t | -thin]
  [-version | -v]

Argument Summary

Table 11-4 summarizes the ojvmjava command-line arguments.

Table 11-4 ojvmjava Argument Summary  
Option Description

-user | -u

Specifies user's name for connecting to the database. This name is case insensitive; the name will always be converted to upper case. If you provide the database information, the default syntax used is OCI. You can also specify the default database by the following option:
-user <user>/<password>@

-password | -p

Specifies user's password for connecting to the database. This name case insensitive; the name will always be converted to upper case.

@<filename>

Specifies a script file that contains ojvmjava commands to be executed. See "Scripting ojvmjava Commands in the @<filename> Option" for structure of the indicated file.

-batch

Disables all messages printed to the screen. No help messages or prompts will be printed. Only responses to entered commands are printed.

-command

Executes the desired command. If you do not want to run ojvmjava in interpretive mode, but only want to execute a single command, execute ojvmjava with the -command option followed by a string that contains the command and the arguments. Once the command executes, ojvmjava exits. The following executes the "ls -lR" command on the designated host:

ojvmjava -user/TIGER -command "java foo"

-debug

Prints debugging information.

-d | -database <conn_string>

Provide a database connection string.

-fileout <file>

Redirect output to the provided file.

-o | -oci | -oci8

Use the JDBC OCI driver. The OCI driver is the default. This flag specifies the syntax used in either the @database or -database option.

-oschema <schema>

Use this schema for class lookup.

-t | -thin

Specifies that the database syntax used is for the JDBC Thin driver. The database connection string must be of the form <host>:<port>:<SID> or an Oracle Net Services Name-Value list.

-verbose

Print the connection information.

-version

Shows the version.

Example

Here is a ojvmjava example.

Open a shell on the session namespace of the database orcl on listener port 2481 on host dbserver.

ojvmjava -thin -user SCOTT/TIGER@dbserver:2481:orcl

The ojvmjava commands span several different types of functionality, which are grouped as follows:

ojvmjava Options

ojvmjava Tool Output Redirection

You can specify that any output generated by the ojvmjava tool is put into a file by appending the "&><filename>" at the end of the command options. The following pipes all output to the listDir file:

ls -lR &>/tmp/listDir
Scripting ojvmjava Commands in the @<filename> Option

This option designates a script file that contains one or more ojvmjava commands. The script file specified is located on the client. The ojvmjava tool reads in the file and then executes all commands on the designated server. Also, because the script file is executed on the server, any interaction with the operating system in the script file--such as redirecting output to a file or executing another script--will occur on the server. If you direct ojvmjava to execute another script file, this file must exist within $ORACLE_HOME directory on the server.

Type in the ojvmjava command followed by any options and any expected input arguments.

The script file contains any ojvmjava command followed by options and input parameters. The input parameters can be passed in on the ojvmjava command-line. The ojvmjava command processes all known ojvmjava options and then passes on any other options and arguments to the script file.

To access arguments within the commands in the script file, place &1...&n to denote the arguments. If all input parameters are passed into a single command, you can supply a the string "&*" to denote that all input parameters are to be passed to this command.

The following shows the contents of the script file, execShell:

chmod +x SCOTT nancy /alpha/beta/gamma
chown SCOTT /alpha/beta/gamma
java testhello &*

Because only two input arguments are expected, you can implement the java command input parameters as follows:

java testhello &1 &2

Note:

You can also supply arguments to the -command option in the same manner. The following shows an example:

ojvmjava ... -command "cd &1" contexts

After processing all other options, the ojvmjava tool passes "contexts" in as the argument to the "cd" command.


To execute this file, do the following:

ojvmjava -user SCOTT -password TIGER -thin -database dbserver:2481:orcl \
        @execShell alpha beta

The ojvmjava processes all options that it knows about and passes along any other input parameters to be used by the commands that exist within the script file. In this example, the parameters, alpha and beta, are passed to the java command in the script file. Thus, the actual command executed is as follows:

java testhello alpha beta

You can add any comments in your script file with the hash symbol (#). The "#" symbol makes anything to the end of the line a comment, which is ignored by ojvmjava. For example:

#this whole line is ignored by ojvmjava 

Shell Commands

The following shell commands behave similarly to their UNIX counterparts:

Shell Commands

echo

exit Command

help Command

java Command

version Command

whoami

Each of these shell commands contains the following common options:

Table 11-5 ojvmjava Command Common Options  
Option Description

-describe | -d

Summarizes the tool's operation.

-help | -h

Summarizes the tool's syntax.

-version

Shows the version.

echo

Prints to stdout exactly what is indicated. This is used mostly in script files.

The syntax is as follows:

echo [<echo_string>] [<args>]

where <echo_string> is a string that contains the text you want written to the screen during the shell script invocation and <args> are input arguments from the user. For example, the following prints out a notification:

echo "Adding an owner to the schema" &1

If the input argument is "SCOTT", the output would be "Adding an owner to the schema SCOTT"

exit Command

The exit command terminates ojvmjava.

Syntax
exit

Here is an example:

Leave the shell:

$ exit
% 

help Command

The help command summarizes the syntax of the shell commands. You can also use the help command to summarize the options for a particular command.

Syntax
help [<command>]

java Command

The java command is analogous to the JDK java command; it invokes a class's static main() method. The class must have been loaded with loadjava. (There is no point to publishing a class that will be invoked with the java command.) The java command provides a convenient way to test Java code that runs in the database. In particular, the command catches exceptions and redirects the class's standard output and standard error to the shell, which displays them as with any other command output. (The usual destination of standard out and standard error for Java classes executed in the database is one or more database server process trace files, which are inconvenient and may require DBA privileges to read.)

Syntax
java [-schema <schema>] <class> [arg1 ... argn]
Argument Summary

Table 11-6 summarizes the java arguments.

Table 11-6 java Argument Summary  
Option Description

class

Names the Java class schema object that is to be executed.

-schema

Names the schema containing the class to be executed; the default is the invoker's schema. The schema name is case sensitive.

arg1 ... argn

Arguments to the class's main() method.

Here is a java command example.

Say hello and display arguments:

package hello;
public class World {
    public World() {
        super();
    }
    public static void main(String[] argv) {
        System.out.println("Hello from the Oracle Database");
        if (argv.length != 0)
            System.out.println("You supplied " + argv.length + " arguments: ");
            for (int i = 0; i < argv.length; i++)
                System.out.println(" arg[" + i + "] : " + argv[i]);
    }
}

Compile, load, publish, and run the executable as follows, substituting your user ID, host, and port information as appropriate:

% javac hello/World.java
% loadjava -r -user SCOTT/TIGER@localhost:2481:orcl hello/World.class
% ojvmjava -user SCOTT -password TIGER -database localhost:2481:orcl
$ java testhello alpha beta
Hello from the Oracle Database
You supplied 2 arguments:
arg[0] : alpha
arg[1] : beta

version Command

The version command shows the version of the ojvmjava tool. You can also show the version of a specified command.

Syntax
version [options] [<command>]

Here is an example of the version command.

Display the shell's version:

$ version
1.0

whoami

Prints out the current user that logged into this session.