12 Schema Objects and Oracle JVM Utilities

Syntax

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]

Argument Summary

Table 12-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.

loadjava –u HR –r –v –proxy proxy_server:1020 http://my.server.com/this/is /the/path/my.jar
Password: password

-grant HR -cleargrants

System.getProperty("file.encoding");

^Footnote 1 If you load a JAR file in this manner, then you cannot use it for resolution or execution.

^Footnote 2 If you load a JAR file in this manner, then you can use it for resolution or execution.

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 Table 12-2.

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.

Syntax

The syntax of the dropjava tool command is:

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

Argument Summary

Table 12-3 summarizes the dropjava tool arguments.

Argument Details

This section describes a few of the dropjava tool arguments, which are complex.

File Names

The dropjava tool interprets most file names as the loadjava tool does:

• .class files

  Finds the class name in the file and drops the corresponding schema object.

• .java and .sqlj files

  Finds the first class name in the file and drops the corresponding schema object.

• .jar and .zip files

  Processes the archived file names as if they had been entered on the command line.

If a file name has another extension or no extension, then the dropjava tool interprets the file name as a schema object name and drops all source, class, and resource objects that match the name.

If the dropjava tool encounters a file name that does not match a schema object, then 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:@database is optional. If you do not specify, then the dropjava tool uses the user's default database. If specified, then database can be a TNS name or an Oracle Net Services name-value list.

• -thin:@database 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 dropjava tool command:

• Drop all schema objects in the TEST schema in the default database that were loaded from ServerObjects.jar:

  dropjava -u HR -schema TEST ServerObjects.jar
  Password: password
  

• Connect with the JDBC Thin driver, then drop a class and a resource file from the user's schema:

  dropjava -thin -u HR@dbhost:5521:orcl alpha.class beta.props
  Password: password
  

List Based Deletion

Earlier versions of the dropjava tool required that the classes, JARs, source, and resources be present on the machine, where the client or server side utility is running. The current version of dropjava has an option that enables you to drop classes, resources, or sources based on a list of classes, which may not exist on the client machine or the server machine. This list can be either on the command line or in a text file. For example:

dropjava –list –u HR –v this.is.my.class this.is.your.class
Password: password

The preceding command drops the classes this.is.my.class and this.is.your.class listed on the command line without them being present on the client machine or server machine.

dropjava –listfile my.list –u HR –s –v
Password: password

The preceding command drops classes, resources, or sources and their synonyms based on a list of classes listed in my.list and displays verbosely.

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 them 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 that specified 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, then there will be no problem. However, if you use the command line to load resources, then you must be careful to specify the same path information when you run the dropjava tool to remove the resources.

Syntax

The syntax of the ojvmjava tool command is:

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]
 -runjava [server_file_system]
 -jdwp port [host]
 -verbose

Argument Summary

Table 12-4 summarizes the ojvmjava tool arguments.

Example

Open a shell on the session namespace of the database orcl on listener port 2481 on the host dbserver, as follows:

ojvmjava -thin -user HR@dbserver:2481:orcl
Password: password

Functionality

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

• ojvmjava Tool Command-Line Options

• Shell Commands

java myclass a b c

ojvmjava -user HR -thin -database dbserver:2481:orcl @commands
Password: password

#this whole line is ignored by ojvmjava

echo [echo_string] [args]

echo "Adding an owner to the schema" &1

Adding an owner to the schema HR

exit

$ exit
%

help [command]

java [-schema schema] class [arg1 ... argn]

java [command-line options] class [arg1 ... argn]

package hello;
public class World
{
  public World()
  {
    super();
  }

  public static void main(String[] argv)
  {
    System.out.println("Hello from 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]);
  }
}

% javac hello/World.java

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

version [options] [command]

$ version
1.0

whoami

connect [-service service] [-user user][-password password]

connect -s thin@locahost:5521:orcl -u HR/<password>
connect -s oci@locahost:5521:orcl -u HR -p <password>