Oracle8i SQLJ Developer's Guide and Reference Release 8.1.5 A64684-01 |
|
One approach to developing SQLJ code for the server is to first run the SQLJ translator on a client machine to take care of translation, compilation, and profile customization. Then load the resulting class and resource files into the server, typically using a Java archive (.jar
) file.
If you are developing your source on a client machine, as is usually the case, and have a SQLJ translator available there, this approach is advisable. It allows the most flexibility in running the translator because option-setting and error-processing are not as convenient in the server.
It may also be advisable to use the SQLJ -ser2class
option during translation when you intend to load an application into the server. This results in SQLJ profiles being converted from .ser
serialized resource files to .class
files and simplifies their naming. Be aware, however, that profiles converted to .class
files cannot be further customized. To further customize, you would have to rerun the translator and regenerate the profiles. For information about the -ser2class
option, see "Conversion of .ser File to .class File (-ser2class)".
When you load .class
files and .ser
resource files (if any) into the server, either directly or using a .jar
file, the resulting database library units are referred to as Java class schema objects (for Java classes) and Java resource schema objects (for Java resources). A separate schema object is created for each class and for each resource.
Once you run the translator on the client, use the Oracle loadjava
client-side utility to load class and resource files into schema objects in the server.
Either specify the class and resource files individually on the loadjava
command line, or put them into a .jar
file and specify the .jar
file on the command line. A separate schema object is created for each .class
or .ser
file that is in the .jar
file or on the command line.
The loadjava
utility does not support compressed files. If you create a .jar
file, specify the files it contains to be uncompressed, as in the following example (the "0" specifies no compression):
jar -cvf0 demo.jar *.class *.ser
The loadjava
utility defaults to the JDBC OCI 8 driver (which does not require a URL as part of the loadjava
-user
option setting). Alternatively, you can use the Thin driver by using the -thin
option and specifying an appropriate URL through the -user
option, as shown in one of the examples below.
Consider an example where you: 1) translate and compile Foo.sqlj
, which includes an iterator declaration for MyIter
; 2) enable the -ser2class
option when you translate Foo.sqlj
; and 3) archive the resulting files (Foo.class
, MyIter.class
, Foo_SJProfileKeys.class
, and Foo_SJProfile0.class
) into Foo.jar
. Then run loadjava
with the following command line (plus any options you want to specify):
loadjava -user scott/tiger Foo.jar
Or, to use the Thin driver for loading (specifying the -thin
option and an appropriate URL):
loadjava -thin -user scott/tiger@localhost:1521:ORCL Foo.jar
Or, alternatively, use the original files (again with the OCI driver):
loadjava -user scott/tiger Foo.class MyIter.class Foo_SJProfileKeys.class Foo_SJProfile0.class
or:
loadjava -user scott/tiger Foo*.class MyIter.class
The loadjava
script, which runs the actual utility, is in the bin
subdirectory under your Oracle Home directory. This directory should already be in your path once Oracle has been installed.
For more information about the loadjava
utility, see the Oracle8i Enterprise JavaBeans and CORBA Developer's Guide. For information about files generated by the SQLJ translator, see "Code Generation" and "Java Compilation".
Notes:
|
Although the loadjava
utility is recommended for loading your SQLJ and Java applications into the server, you can also use Oracle SQL CREATE JAVA
commands such as the following:
CREATE OR REPLACE <AND RESOLVE> JAVA CLASS <NAMED name>; CREATE OR REPLACE JAVA RESOURCE <NAMED name>;
See the Oracle8i SQL Reference for more information about the CREATE JAVA
commands.
This section discusses how schema objects for classes and profiles are named when you load classes and profiles into the server.
If the SQLJ -ser2class
option was enabled when you translated your application on the client, then profiles were converted to .class
files and will be loaded into class schema objects in the server. If -ser2class
was not enabled, then profiles were generated as .ser
serialized resource files and will be loaded into resource schema objects in the server.
In the following discussion, it is assumed that you use only the default connection context class for any application that will run in the server; therefore, there will only be one profile.
Notes: There are two forms of schema object names in the server: full names and short names. For information about these and about other file naming considerations, see "Full Names vs. Short Names in the Server". |
The full name of the class schema object that is produced when you load a .class
file into the server is determined by the package and class name in the original source code. Any path information you supply on the command line (so loadjava
can find it, for example) or in the .jar
file is irrelevant in determining the name of the schema object. For example, if Foo.class
consists of a class Foo
which was specified in the source code as being in package x.y
, then the full name of the resulting class schema object is as follows:
x/y/Foo
Note that ".class" is dropped.
If Foo.sqlj
declares an iterator MyIter
, then the full name of its class schema object is:
x/y/MyIter
(Unless it is a nested class, in which case it will not have its own schema object.)
The related profile-keys class file, generated by SQLJ when you translate Foo.sqlj
, is Foo_SJProfileKeys.class
; therefore, the full name of its class schema object is:
x/y/Foo_SJProfileKeys
If the -ser2class
option was enabled when you translated your application, then any resulting profile or profiles were generated in file Foo_SJProfile0.class
(and Foo_SJProfile1.class
, and so on); therefore, the full name of class schema objects are of the form:
x/y/Foo_SJProfile0
This discussion is relevant only if you did not enable the -ser2class
option when you translated your application, or if you use other Java serialized resource (.ser
) files in your application.
The naming of resource schema objects is handled differently than for class schema objects--their names are not determined from the contents of the resources. Instead, their full names are identical to the names that appear in a .jar
file or on the loadjava
command line, including path information. Also note that the .ser
extension is not dropped.
It is important to note that because resource names are used to locate the resources at runtime, their names must include the correct path information. In the server, the correct full name of a resource is the same as the relative path and file name that Java would use to look it up on the client.
In the case of a SQLJ profile, this is a subdirectory under the -d
option directory, according to the package name. If the translator -d
option (used to specify the top-level output directory for generated .class
and .ser
files) is set to /mydir
and the application is in package abc.def
, then .class
and .ser
files generated during translation will be placed in the /mydir/abc/def
directory.
At runtime, /mydir
would presumably be in your CLASSPATH
and Java will look for your application components in the abc/def
directory underneath it.
Therefore, when you load this application into the server, you must run loadjava
or jar
from the -d
directory, so that the path you specify on the command line to find the files also indicates the package name, as follows:
cd /mydir loadjava <...options...> abc/def/*.class abc/def/*.ser
Or, if you use a .jar
file:
cd /mydir jar -cvf0 myjar.jar abc/def/*.class abc/def/*.ser loadjava <...options...> myjar.jar
If your application is App
and your profile is App_SJProfile0.ser
, then either of the above examples will correctly result in the following full name of the created resource schema object:
abc/def/App_SJProfile0.ser
Note that if you set -d
to a directory whose hierarchy has no other contents (which is advisable), you can simply run jar
as follows to recursively get your application components:
cd /mydir jar -cvf0 myjar.jar * loadjava <...options...> myjar.jar
For more information about the SQLJ -d
option (including default value), see "Output Directory for Generated .ser and .class Files (-d)".
You can access the USER_OBJECTS
view in your database schema to verify that your classes and resources are loaded properly. For more information, see "Checking Java Uploads".
Before using your SQLJ code in the server, you must publish the top-level methods, as is true of any Java code you use in the server. Publishing involves writing call descriptors, mapping datatypes, and setting parameter modes. For information, see the Oracle8i Java Stored Procedures Developer's Guide.
This section takes you through typical steps of running a client application in the server. As an example, it uses the NamedIterDemo
sample application that is provided in "Named Iterator--NamedIterDemo.sqlj".
Use the connect.properties
file for your connection settings.
connect.properties
to use the server-side (KPRB) JDBC driver.
For example, if you previously used the OCI 8 driver, update connect.properties
as follows.
old:
sqlj.url=jdbc:oracle:oci8:@
new:
sqlj.url=jdbc:oracle:kprb:@
.jar
file for your application components and connect.properties
file. For NamedIterDemo
, the components include SalesRec.class
as well as the application class and profile.
You can create a .jar
file niter-server.jar
as follows (the 0 is to specify no compression, as required by loadjava
):
jar cvf0 niter-server.jar Named*.class Named*.ser SalesRec.class connect.properties
.jar
file into the server.
Use loadjava
, as follows. This instructs loadjava
to use the OCI 8 driver in loading the files. The -resolve
option results in the class files being resolved.
loadjava -oci8 -resolve -force -user scott/tiger niter-server.jar
For example, run a SQL*Plus script that executes the following:
set echo on set serveroutput on set termout on set flush on execute dbms_java.set_output(10000); create or replace procedure SQLJ_NAMED_ITER_DEMO as language java name 'NamedIterDemo.main (java.lang.String[])'; /
The DBMS_JAVA.SET_OUTPUT()
routine reroutes default output to your screen instead of a trace file; the input parameter is the buffer size in bytes.
For example:
sqlplus> call SQLJ_NAMED_ITER_DEMO();