11 Schema Objects and Oracle JVM Utilities

Schema Object Digest Table

The schema object digest table is an optimization that is usually invisible to developers. The digest table enables the loadjava tool to skip files that have not changed since they were last loaded. This feature improves the performance of makefiles and scripts that call the loadjava tool for collections of files, some of which must 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 or a hash, of the content of the file. Comparing digests computed for the same file at different times is a fast way to detect a change in the content of the file. This is much faster than comparing every byte in the file. For each file it processes, the loadjava tool computes a digest of the content of the file and then looks up the file name in the digest table. If the digest table contains an entry for the file name that has an identical digest, then the loadjava tool does not load the file, because a corresponding schema object exists and is up to date. If you call the loadjava tool with the -verbose option, then it will show you the results of its digest table lookups.

Typically, the digest table is invisible to developers, because the loadjava tool and the dropjava tool keep the table synchronized with schema object additions, changes, and deletions. For this reason, always use the dropjava tool to delete a schema object that was created with the loadjava tool, even if you know how to drop a schema object using DDL.

Syntax

The syntax of the loadjava tool command is as follows:

loadjava {-user | -u} user/[password][@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]
  [-norecursivejars]
  [-nosynonym]
  [-nousage]
  [-noverify]
  [-o | -oci | oci8]
  [-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 11-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 scott –r –v –proxy proxy_server:1020 http://my.server.com/this/is /the/path/my.jar
Password: password

-grant SCOTT -cleargrants

System.getProperty("file.encoding");

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 11-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/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, the loadjava tool creates two schema objects, alpha/beta/x.properties and ROOT/home/scott/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/scott/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/scott/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 option 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.

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 '((* SCOTT) (* PUBLIC))'

This implies that 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.

Consider the following example:

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

This implies that search for any reference first in SCOTT 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 SCOTT@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 SCOTT@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]
  [-S | -schema schema]
  [-stdout]
  [-s | -synonym]
  [-t | -thin]
  [-v | -verbose]

Argument Summary

Table 11-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 SCOTT -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 SCOTT@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 scott –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 scott –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 11-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 SCOTT@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

ls -lR &>/tmp/listDir

chmod +x SCOTT nancy /alpha/beta/gamma
chown SCOTT /alpha/beta/gamma
java hello.World &*

java hello.World &1 &2

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

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

java hello.World alpha beta

#this whole line is ignored by ojvmjava

dbms_namespace.shell(in command VARCHAR2)

dbms_namespace.shell('cd /webdomains');

dbms_namespace.shell('ls &> /tmp/test');

dbms_namespace.shell('exit');

String commands="cd /webdomains\nls -l";
 StringReader commandReader = new StringReader(commands);
 Shell sh = new oracle.aurora.namespace.shell.Shell();

 try
 {
   sh.initialize();
   sh.invoke(new BufferedReader(commandReader), false);
 }
 catch (ToolsException te)
 {
   //Error executing the commands
 }

echo [echo_string] [args]

echo "Adding an owner to the schema" &1

Adding an owner to the schema SCOTT

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 SCOTT@localhost:2481:orcl hello/World.class
Password: password
% ojvmjava -user SCOTT -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 scott/tiger
connect -s oci@locahost:5521:orcl -u scott -p tiger