| Oracle® Database Java Developer's Guide 10g Release 2 (10.2) Part Number B14187-01 |
|
|
View PDF |
| Oracle® Database Java Developer's Guide 10g Release 2 (10.2) Part Number B14187-01 |
|
|
View PDF |
This chapter describes the schema objects that you use in the Oracle Database Java environment and the Oracle JVM utilities. You run these utilities from a UNIX shell or from the Microsoft Windows DOS prompt.
Note:
All names supplied to these tools are case-sensitive. As a result, the schema, user name, and password should not be changed to uppercase.This chapter contains the following sections:
Unlike a conventional Java virtual machine (JVM), which compiles and loads Java files, the Oracle JVM compiles and loads schema objects. The following kinds of Java schema objects are loaded:
Java class schema objects, which correspond to Java class files.
Java source schema objects, which correspond to Java source files.
Java resource schema objects, which correspond to Java resource files.
To ensure that a class file can be run by the Oracle JVM, you must 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 Oracle JVM, you must use loadjava to create and load a Java resource schema object from the resource file.
The dropjava tool 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 schema objects using SQL data definition language (DDL) commands will not update auxiliary data maintained by loadjava and dropjava.
You must load resource files using 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 Oracle Database 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 the corresponding .java file, but not both.
The loadjava tool accepts Java Archive (JAR) files that contain either source and resource files or class and resource files. When you pass a JAR or ZIP file to loadjava, it 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. As a result, there is little performance penalty for loading JAR files. Loading JAR files is a simple, fool-proof way to use loadjava.
It is illegal for two schema objects in the same schema to define the same class. For example, assume that 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. Instead, do either of the following:
Drop a.java, load b.java, and then load the new a.java, which does not define x.
Load the new a.java, which does not define x, and then load b.java.
All Java classes contain references to other classes. A conventional JVM searches for classes in the directories, ZIP files, and JAR files named in the CLASSPATH. In contrast, the Oracle JVM searches schemas for class schema objects. Each class in the database has a resolver specification, which is the Oracle Database counterpart to CLASSPATH. For example, the resolver specification of a class, alpha, lists the schemas to search for classes that alpha uses. Notice that resolver specifications are per-class, whereas in a classic JVM, CLASSPATH is global to all classes.
In addition to a resolver specification, 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:
The name of the class schema object to call when the class uses the reference
A code indicating whether the reference is unsatisfied, that is, whether the referent schema object is known
An Oracle Database facility known as resolver maintains reference lists. For each interclass reference in a class, the resolver searches the schemas specified by the resolver specification of the class for a valid class schema object that satisfies the reference. If all references are resolved, then 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 these classes, 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 resolve classes that are marked valid.
A 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 ClassNotFound exception. Furthermore, run-time resolution can fail for the following reasons:
Lack of database resources, if the tree of classes is very large
Deadlocks due to circular dependencies
The loadjava tool has two resolution modes:
Load-and-resolve
The -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 while the command is being carried out.
Load-then-resolve
This mode resolves each class at run time. The -resolve option is not specified.
Note:
As with a Java compiler,
loadjava resolves references to classes but not to resources. Ensure that you correctly load the resource files that your classes need.If you can, defer resolution until all classes have been loaded. This avoids a situation in which the resolver marks a class invalid because a class it uses has not yet been loaded.
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 call loadjava for collections of files, 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 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, loadjava 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 loadjava does not load the file, because a corresponding schema object exists and is up to date. If you call 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, then use the loadjava -force option to bypass the digest table lookup or delete all rows from the table JAVA$CLASS$MD5$TABLE.
Loading a source file creates or updates a Java source schema object and invalidates the class schema objects previously derived from the source. If the class schema objects do not exist, then 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, for example, class A, is automatically triggered by any of the following conditions:
The resolver, while working on class B, finds that class B refers to class A, but class A is invalid.
The compiler, while compiling the source of class B, finds that class B refers to class A, but class A is invalid.
The class loader, while trying to load class A for running it, finds that class A is invalid.
To force compilation when you load a source file, use loadjava -resolve.
The compiler writes error messages to the predefined USER_ERRORS view. The loadjava tool 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, then you can specify compiler options on the command line. You can additionally specify persistent compiler options in a per-schema database table, JAVA$OPTIONS. You can use the JAVA$OPTIONS table for default compiler options, which you can override selectively using a loadjava command-line option.
Note:
A command-line option overrides and clears the matching entry in theJAVA$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 JAVA$OPTIONS when it has been called by the class loader or when called from the command line without specifying any options. 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:
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. loadjava can also create schema objects from SQLJ files.
You must have the following SQL database privileges to load classes:
CREATE PROCEDURE and CREATE TABLE privileges to load into your schema.
CREATE ANY PROCEDURE and CREATE ANY TABLE privileges to load into another schema.
oracle.aurora.security.JServerPermission.loadLibraryInClass.classname.
You can run the loadjava tool either from the command line or by using the loadjava method contained in the DBMS_JAVA class. To run the tool from within your Java application, do the following:
call dbms_java.loadjava('... options...');
The options are the same as those that can be specified on the command line with the loadjava tool. Separate each option with a space. Do not separate the options with a comma. The only exception for this is the -resolver option, which contains spaces. For -resolver, specify all other options in the first input parameter and the -resolver options in the second parameter, as follows:
call dbms_java.loadjava('..options...', 'resolver_options');
Do not specify the -thin, -oci, -user, and -password options, because they relate to the database connection for the loadjava command-line tool. The output is directed to stderr. Set serveroutput on, and call dbms_java.set_output, as appropriate.
Note:
Theloadjava tool is located in the bin directory under $ORACLE_HOME.Just before the loadjava tool exits, it checks whether the processing was successful. All failures are summarized preceded by the following header:
The following operations failed
Some conditions, such as losing the connection to the database, cause loadjava to terminate prematurely. These errors are printed with the following syntax:
exiting: error_reason
This section covers the following:
The syntax of the loadjava command is as follows:
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]
Table 11-1 summarizes the loadjava arguments. If you run loadjava 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 loadjava 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 loadjava to skip the digest table lookup.
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-1 loadjava Argument Summary
This section describes the details of some of the loadjava arguments whose behavior is more complex than the summary descriptions contained in Table 11-1.
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 loadjava 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, 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. If you have a JAR or ZIP that works with the Java Development Kit (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 different from file names, and loadjava 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 loadjava 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. 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 loadjava from the top of the package tree and specify resource file names relative to that directory.
Note:
The top of the package tree is the directory you would name in aCLASSPATH.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, loadjava 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, loadjava 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 loadjava 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 commands imply that you can use any path name to load the contents of a JAR file. Even if you run the redundant commands, loadjava 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 loadjava invocations.
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.
See Also:
"Controlling the Current User"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 loadjava process. 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 loadjava options. This file is read and processed by loadjava before any other loadjava 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 loadjava, 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, 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.
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 loadjava 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, loadjava 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, loadjava does some processing on entries in the order in which they occur in the JAR.
If loadjava has partially processed entities before it processes META-INF/loadjava-options, then loadjava will attempt to patch up the schema object to conform to the applicable options. For example, loadjava alters classes that were created with invoker rights when they should have been created with definer 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, then 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:
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 loadjava 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 loadjava 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, loadjava 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 loadjava 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 loadjava 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/shmoe -resolve -schema TEST ServerObjects.jar
Connect with the JDBC Thin driver, load a class and a resource file, and resolve each class:
loadjava -thin -u SCOTT/TIGER@dbhost:5521:orcl \ -resolve alpha.class beta.props
Add Betty and Bob to the users who can run alpha.class:
loadjava -thin -schema test -u SCOTT/TIGER@localhost:5521:orcl \ -grant BETTY,BOB alpha.class
The dropjava tool is the converse of loadjava. It transforms command-line file names and JAR or ZIP file contents to schema object names, drops the schema objects, and deletes their corresponding digest table rows. You can enter .java, .class, .sqlj, .ser, .zip, .jar, and resource file names on the command line and in any order.
Alternatively, you can specify a schema object name directly to dropjava. A command-line argument that does not end in .jar, .zip, .class, .java, or .sqlj is presumed to be a schema object name. If you specify a schema object name that applies to multiple schema objects, then 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 load a.sqlj source file and translate it in the server, then you must run dropjava on the same source file. If you translate on a client and load classes and resources directly, then run dropjava on the same classes and resources.You can run dropjava either from the command line or by using the dropjava method in the DBMS_JAVA class. To run dropjava from within your Java application, use the following command:
call dbms_java.dropjava('... options...');
The options are the same as specified on the command line. Separate each option with a space. Do not separate the options using commas. The only exception to this is the -resolver option. The connection is always made to the current session. Therefore, 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 -thin, -oci, -user, and -password options, because they relate to the database connection for loadjava. The output is directed to stderr. Set serveroutput on and call dbms_java.set_output, as appropriate.
This section covers the following topics:
The syntax of the dropjava command is:
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]
Table 11-2 summarizes the dropjava arguments.
Table 11-2 dropjava Argument Summary
| Argument | Description |
|---|---|
|
|
Specifies a user name, password, and optional database connect string. The files will be dropped from this database instance. |
|
|
Specifies any number and combination of |
|
|
Treats the operand of this option as a file to be processed. |
|
|
Drops the whole JAR file, which was previously loaded as a resource. |
|
|
Changes the behavior of the server-side |
|
|
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. |
|
|
Has the same usage as for |
|
|
Has the same usage as for |
|
|
Designates the schema from which schema objects are dropped. If not specified, then the logon schema is used. To drop a schema object from a schema that is not your own, you need the |
|
|
Causes the output to be directed to |
|
|
Drops a |
|
|
Directs |
|
|
Prints a timestamp on every message. |
|
|
Directs |
This section describes few of the dropjava argument, which are complex
dropjava interprets most file names as loadjava 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 dropjava interprets the file name as a schema object name and drops all source, class, and resource objects that match the name.
If dropjava 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 dropjava 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 dropjava.
Drop all schema objects in the TEST schema in the default database that were loaded from ServerObjects.jar:
dropjava -u SCOTT/TIGER -schema TEST ServerObjects.jar
Connect with the JDBC Thin driver, then drop a class and a resource file from the user's schema:
dropjava -thin -u SCOTT/TIGER@dbhost:5521:orcl alpha.class beta.props
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 dropjava to remove the resources.
The ojvmjava tool is an interactive interface to the session namespace of a database instance. 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.
This section covers the following topics:
The syntax of the ojvmjava 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]
Table 11-3 summarizes the ojvmjava arguments.
Table 11-3 ojvmjava Argument Summary
| Argument | Description |
|---|---|
|
|
Specifies user name for connecting to the database. This name is not case-sensitive. The name will always be converted to uppercase. If you provide the database information, then the default syntax used is OCI. You can also specify the default database. |
|
|
Specifies the password for connecting to the database. This is not case-sensitive and will always be converted to uppercase. |
|
|
Specifies a script file that contains the |
|
|
Disables all messages printed to the screen. No help messages or prompts will be printed. Only responses to commands entered are printed. |
|
|
Runs the desired command. If you do not want to run |
|
|
Prints debugging information. |
|
|
Provide a database connection string. |
|
|
Redirect output to the provided file. |
|
|
Use the JDBC OCI driver. The OCI driver is the default. This flag specifies the syntax used in either the |
|
|
Use this schema for class lookup. |
|
|
Specifies that the database syntax used is for the JDBC Thin driver. The database connection string must be of the form |
|
|
Print the connection information. |
|
|
Shows the version. |
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/TIGER@dbserver:2481:orcl
The ojvmjava commands span several different types of functionality, which are grouped as follows:
This section describes the options for the ojvmjava command-line tool
The ojvmjava Tool Output Redirection
You can direct any output generated by the ojvmjava tool to a file by appending &>filename at the end of the command options. The following command directs all output to the listDir file:
ls -lR &>/tmp/listDir
Scripting ojvmjava Commands in the @filename Option
This @filename 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 the file and runs all commands on the designated server. In addition, because the script file is run on the server, any interaction with the operating system in the script file, such as redirecting output to a file or running another script, will occur on the server. If you direct ojvmjava to run another script file, then this file must exist in $ORACLE_HOME on the server.
Enter the ojvmjava command followed by any options and any expected input arguments.
The script file contains the ojvmjava command followed by options and input parameters. The input parameters can be passed to ojvmjava on the command line. ojvmjava processes all known options and passes on any other options and arguments to the script file.
To access arguments within the commands in the script file, use &1...&n to denote the arguments. If all input parameters are passed to a single command, then you can type &* 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, ojvmjava passes contexts as argument to the cd command.
To run this file, do the following:
ojvmjava -user SCOTT -password TIGER -thin -database dbserver:2481:orcl \ @execShell alpha beta
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. The actual command is run as follows:
java testhello alpha beta
You can add any comments in your script file using hash (#). Comments are ignored by ojvmjava. For example:
#this whole line is ignored by ojvmjava
Running sess_sh Within Applications
You can run sess_sh commands from within a Java or PL/SQL application using the following commands:
| Application Type | Command and Description |
|---|---|
| PL/SQL applications |
dbms_namespace.shell(in command VARCHAR2)Your application can run individual commands on a unique session instance. The state of the shell is preserved between different calls of sess_sh within the same session. The following examples run the cd command of the sess_sh tool within a PL/SQL application:
dbms_namespace.shell('cd /webdomains');
dbms_namespace.shell('ls &> /tmp/test');
To reset the state of the shell instance, run the dbms_namespace.shell('exit');
|
| Java applications | Instantiate oracle.aurora.namespace.shell.Shell within a Java server object. After creation, you must initialize the Shell object using its initialize method. Once initialized, you can run sess_sh commands, as follows:
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
}
|
This section describes the commands used for manipulating and viewing contexts and objects in the namespace.
The following shell commands function similar to their UNIX counterparts:
Each of these shell commands have some options in common, which are summarized in Table 11-4:
Table 11-4 ojvmjava Command Common Options
| Option | Description |
|---|---|
|
|
Summarizes the operation of the tool. |
|
|
Summarizes the syntax of the tool. |
|
|
Shows the version. |
This commnad prints to stdout exactly what is indicated. This is used mostly in script files.
The syntax is as follows:
echo [echo_string] [args]
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 command prints out a notification:
echo "Adding an owner to the schema" &1
If the input argument is SCOTT, then the output would be:
Adding an owner to the schema SCOTT
This command terminates ojvmjava. The syntax is as follows:
exit
For example, to leave a shell, use the following command:
$ exit %
This command summarizes the syntax of the shell commands. You can also use the help command to summarize the options for a particular command. The syntax is as follows:
help [command]
This command is analogous to the JDK java command. It calls the static main() method of the class. The class must be loaded with loadjava. The command provides a convenient way to test Java code that runs in the database. In particular, the command catches exceptions and redirects the standard output and standard error of the class to the shell, which displays them as with any other command output. The destination of standard out and standard error for Java classes that run in the database is one or more database server process trace files, which are inconvenient and may require DBA privileges to read.
The syntax of this command is:
java [-schema schema] class [arg1 ... argn]
Table 11-5 summarizes the arguments of this command.
Table 11-5 java Argument Summary
| Argument | Description |
|---|---|
|
|
Names the Java class schema object that is to be run. |
|
|
Names the schema containing the class to be run. The default is the invoker's schema. The schema name is case-sensitive. |
|
|
Arguments to the |
Consider the following Java file, World.java:
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]);
}
}
You can compile, load, publish, and run the class, as follows:
% 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
This command shows the version of the ojvmjava tool. You can also show the version of a specified command. The syntax of this command is:
version [options] [command]
For example, you can display the version of the shell, as follows:
$ version 1.0
This command prints the user name of the user who logged in to the current session. The syntax of the command is:
whoami
