Release 8.1.7
Part Number A83726-01
 Library |
 Product |
 Contents |
 Index |
| Oracle JavaServer Pages Developer's Guide and Reference Release 8.1.7 Part Number A83726-01 |
|
Oracle provides the following tools to use, as applicable, in translating JSP pages and deploying them into Oracle8i. How they are implemented depends on your operating system (such as shell scripts for Solaris or .bat files for Windows NT):
ojspc (OracleJSP pre-translation tool)
loadjava (tool for loading JSP pages or Java files into the database)
sess_sh (Oracle8i session shell tool)
Deployment with client-side translation requires all three tools. Pre-translate JSP pages on the client using ojspc, load the translated pages into Oracle8i using loadjava, and publish them using the session shell publishservlet command.
Deployment with server-side translation does not require ojspc. Load the untranslated JSP pages into Oracle8i using loadjava, then translate and publish them using the session shell publishjsp command.
The loadjava and sess_sh tools are general-purpose tools for the Oracle8i JServer environment; ojspc is for JSP pages only.
|
Notes:
|
The first step in deploying a JSP application to Oracle8i with client-side translation is to run the OracleJSP pre-translation tool, ojspc.
You will then use loadjava, introduced in the next section, to load the resulting .class files and resource files (if any) into the database as class schema objects and resource schema objects, respectively.
The following topics are covered here:
There are other possible scenarios, such as in a middle-tier environment, for using
Notes:
ojspc to pre-translate JSP page. See "Use of ojspc for Pre-Translation for Non-OSE Environments".
For a simple JSP (not SQLJ JSP) page, default functionality for ojspc is as follows:
.jsp file as an argument.
.jsp file into Java page implementation class code, producing a .java file. The page implementation class includes an inner class for static page content.
.java file, producing two .class files (one for the page implementation class itself and one for the inner class).
And following is the default ojspc functionality for a SQLJ JSP page:
.sqljsp file as an argument instead of a .jsp file.
.sqljsp file into a .sqlj file for the page implementation class (and inner class).
.sqlj file. This produces a .java file for the page implementation class (and inner class) and a SQLJ "profile" file that is, by default, a .ser Java resource file.
For information about SQLJ profiles, see the Oracle8i SQLJ Developer's Guide and Reference.
.java file, producing two .class files (one for the page implementation class itself and one for the inner class).
Under some circumstances (see the -hotload and -extres option descriptions below), ojspc options direct the OracleJSP translator to produce a .res Java resource file for static page content instead of putting this content into the inner class of the page implementation class. However, the inner class is still created and must still be deployed with the page implementation class.
For general information about OracleJSP translator output (particularly in the on-demand translation scenario), see "Generated Files and Locations (On-Demand Translation)".
Table 6-1 describes the options supported by the ojspc pre-translation utility. These options are further discussed in "Option Descriptions for ojspc".
The second column notes comparable or related OracleJSP configuration parameters for on-demand translation environments (such as Apache/JServ).
Following is the general ojspc command-line syntax (assume % is a UNIX prompt):
% ojspc [option_settings] file_list
The file list can include .jsp files or .sqljsp files.
Be aware of the following syntax notes:
.jsp files are translated, they all must use the same character set (either by default or through page directive contentType settings).
-hotload, not -hotload true.)
Following is an example:
% ojspc -d /myapp/mybindir -srcdir /myapp/mysrcdir -hotload MyPage.sqljsp MyPage2.jsp
This section describes the ojspc options in more detail.
(fully qualified path; ojspc default: empty)
Use this option to specify additional classpath entries for javac to use when compiling generated page implementation class source. Otherwise, javac uses only the system classpath.
(The -addclasspath setting is also used by the SQLJ translator for SQLJ JSP pages.)
|
Notes:
In an on-demand translation scenario, the OracleJSP |
(fully qualified path; ojspc default: current directory)
Use this option to specify an application root directory. The default is the current directory, from which ojspc was run.
The specified application root directory path is used as follows:
include directives in the page being translated. The specified directory path is prepended to any application-relative (context-relative) paths in the include directives of the translated page.
This option is necessary, for example, so included files can still be found if you run ojspc from some other directory.
Consider the following example:
/abc/def/ghi/test.jsp
ojspc from the current directory, /abc, as follows (assume % is a UNIX prompt):
% cd /abc % ojspc def/ghi/test.jsp
test.jsp page has the following include directive:
<%@ include file="/test2.jsp" %>
test2.jsp page is in the /abc directory, as follows:
/abc/test2.jsp
This requires no -appRoot setting, because the default application root setting is the current directory, which is the /abc directory. The include directive uses the application-relative /test2.jsp syntax (note the opening "/"), so the included page will be found as /abc/test2.jsp.
The package in this case is def.ghi, based simply on the location of test.jsp relative to the current directory, from which ojspc was run (the current directory is the default application root). Output files are placed accordingly.
If, however, you run ojspc from some other directory, suppose /home/mydir, then you would need an -appRoot setting as in the following example:
% cd /home/mydir % ojspc -appRoot /abc /abc/def/ghi/test.jsp
The package is still def.ghi, based on the location of test.jsp relative to the specified application root directory.
(fully qualified path; ojspc default: current directory)
Use this option to specify a base directory for ojspc placement of generated binary files--.class files and Java resource files. (The .res files produced for static content by the -extres and -hotload options are Java resource files, as are .ser profile files produced by the SQLJ translator for SQLJ JSP pages.)
The specified path is taken simply as a file system path (not an application-relative or page-relative path).
In environments such as Windows NT that allow spaces in directory names, enclose the directory name in quotes.
Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. See "Summary of ojspc Output Files, Locations, and Related Options" for more information.
The default is to use the current directory (your current directory when you executed ojspc).
It is recommended that you use this option to place generated binary files into a clean directory so that you easily know what files have been produced.
|
Notes:
In an on-demand translation scenario, the OracleJSP |
(boolean; ojspc default: false)
Enable this flag to instruct ojspc to generate a line map to the original .jsp file for debugging. Otherwise, line-mapping will be to the generated page implementation class.
This is useful for source-level JSP debugging, such as when using Oracle JDeveloper.
|
Note:
In an on-demand translation scenario, the OracleJSP |
(fully qualified Java class name; ojspc default: empty)
Use this option to specify a Java class that the generated page implementation class will extend.
(boolean; ojspc default: false)
Enable this flag to instruct ojspc to place generated static content (the Java print commands that output static HTML code) into a Java resource file instead of into an inner class of the generated page implementation class.
The resource file name is based on the JSP page name. For release 8.1.7 it will be the same name as the JSP name, but with the .res suffix (translation of MyPage.jsp, for example, would create MyPage.res in addition to normal output). The exact implementation may change in future releases, however.
The resource file is placed in the same directory as .class files.
If there is a lot of static content in a page, this technique will speed translation and may speed execution of the page. For more information, see "Workarounds for Large Static Content in JSP Pages".
|
Notes:
|
(boolean; ojspc default: false) (for OSE only)
Enable this flag to allow hotloading. This is relevant only if you will be loading the translated pages into Oracle8i to run in the Oracle Servlet Engine.
The -hotload flag directs ojspc to do the following:
-extres functionality, writing static output to a Java resource file (see the -extres description above).
main() method and a hotloading method in the generated page implementation class to allow hotloading.
For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle8i". For how to accomplish the hotloading step (once hotloading has been enabled), see "Hotloading Page Implementation Classes in Oracle8i".
(fully qualified Java interface name; ojspc default: empty)
Use this option to specify a Java interface that the generated page implementation class will implement.
(boolean; ojspc default: false)
Enable this flag to direct ojspc not to compile the generated page implementation class source. This allows you to compile it later with an alternative Java compiler.
|
Notes:
|
(fully qualified package name; ojspc default: per .jsp file location)
Use this option to specify a package name for the generated page implementation class, using Java "dot" syntax.
Without setting this option, the package name is determined according to the location of the .jsp file relative to the current directory (from which you ran ojspc).
Consider an example where you run ojspc from the /myapproot directory, while the .jsp file is in the /myapproot/src/jspsrc directory (assume % is a UNIX prompt):
% cd /myapproot % ojspc -packageName myroot.mypackage src/jspsrc/Foo.jsp
This results in myroot.mypackage being used as the package name.
If this example did not use the -packageName option, OracleJSP release 8.1.7 (1.1.0.0.0) would use src.jspsrc as the package name, by default. (Be aware that such implementation details are subject to change in future releases.)
(-S followed by SQLJ option setting; ojspc default: empty)
For SQLJ JSP pages, use the ojspc -S option to pass Oracle SQLJ options to the SQLJ translator.
Unlike when you run the SQLJ translator directly, use a space between a SQLJ option and its value (this is for consistency with other ojspc options).
For example (from a UNIX prompt):
% ojspc -S-default-customizer mypkg.MyCust -d /myapproot/mybindir MyPage.jsp
This invokes the Oracle SQLJ -default-customizer option to choose an alternative profile customizer, as well as setting the ojspc -d option.
Note the following for particular Oracle SQLJ options:
-encoding option; instead, use the contentType parameter in a page directive in the JSP page.
-classpath option if you use the ojspc -addclasspath option.
-compile option if you use the ojspc -noCompile option.
-d option if you use the ojspc -d option.
-dir option if you use the ojspc -srcdir option.
For information about Oracle SQLJ translator options, see the Oracle8i SQLJ Developer's Guide and Reference.
(fully qualified path; ojspc default: current directory)
Use this option to specify a base directory location for ojspc placement of generated source files--.sqlj files (for SQLJ JSP pages) and .java files.
The specified path is taken simply as a file system path (not an application-relative or page-relative path).
In environments such as Windows NT that allow spaces in directory names, enclose the directory name in quotes.
Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. See "Summary of ojspc Output Files, Locations, and Related Options" for more information.
The default is to use the current directory (your current directory when you executed ojspc).
It is recommended that you use this option to place generated source files into a clean directory so that you easily know what files have been produced.
|
Notes:
In an on-demand translation scenario, the OracleJSP |
(boolean; ojspc default: false)
Enable this option to direct ojspc to report its translation steps as it executes.
The following example shows -verbose output for the translation of myerror.jsp (in this example, ojspc is run from the directory where myerror.jsp is located; assume % is a UNIX prompt):
% ojspc -verbose myerror.jsp Translating file: myerror.jsp 1 JSP files translated successfully. Compiling Java file: ./myerror.java
(boolean; ojspc default: false)
Enable this option for ojspc to display the OracleJSP version number and then exit.
By default, ojspc generates the same set of files that are generated by the OracleJSP translator in an on-demand translation scenario and places them in or under the current directory (from which ojspc was executed).
Here are the files:
.sqlj source file (SQLJ JSP pages only)
.java source file
.class file for the page implementation class
.class file for the inner class
.class file for the SQLJ profile (SQLJ JSP pages only)
For more information about files that are generated by the OracleJSP translator, see "Generated Files and Locations (On-Demand Translation)".
To summarize some of the commonly used options described in "Option Descriptions for ojspc", you can use the following ojspc options to affect file generation and placement:
-appRoot to specify an application root directory
-srcdir to place source files in a specified alternative location
-d to place binary files (.class files and Java resource files) in a specified alternative location
-noCompile to not compile the generated page implementation class source (as a result of this, no .class files are produced)
-extres to put static text into a Java resource file
-hotload to put static text into a Java resource file and to enable hotloading (relevant only for pages targeting the Oracle Servlet Engine)
-S-ser2class (SQLJ -ser2class option, for SQLJ JSP pages only) to generate the SQLJ profile in a .class file instead of a .ser Java resource file
For output file placement, the directory structure underneath the current directory (or directories specified by the -d and -srcdir options, as applicable) is based on the package. The package is determined by the location of the file being translated relative to the application root, which is either the current directory or the directory specified in the -appRoot option.
For example, presume you run ojspc as follows (presume % is a UNIX prompt):
% cd /abc % ojspc def/ghi/test.jsp
Then the package is def.ghi and output files will be placed in the directory /abc/def/ghi.
If you specify alternate output locations through the -d and -srcdir options, a def/ghi subdirectory structure is created under the specified directories.
Now presume ojspc is run from some other directory, as follows:
% cd /home/mydir % ojspc -appRoot /abc /abc/def/ghi/test.jsp
The package is still def.ghi, according to the location of test.jsp relative to the specified application root. Output files will be placed in /home/mydir/def/ghi, or in a def/ghi subdirectory under locations specified through the -d and -srcdir options.
The loadjava command-line tool is supplied with Oracle8i to create schema objects from Java files and load them into a specified database schema.
For information beyond what is provided here, and for information about the associated dropjava tool (for removing Java source, class, and resource schema objects from the database), see the Oracle8i Java Tools Reference.
Generally speaking (not for JSP applications in particular), a Java developer can compile Java source on the client and then load the resulting class files, or can load Java source and have it compiled in Oracle8i automatically by the server-side compiler. In the first case, only class schema objects are created. In the second case, both source schema objects and class schema objects are created. In either case, the developer can also load Java resource files, creating resource schema objects.
The loadjava tool accepts source files, class files, resource files, JAR files, and ZIP files on the command line. Source files and class files cannot be loaded simultaneously, however. A JAR file, ZIP file, or loadjava command line can contain source files or class files, but not both. (In either case, resource files can be included.)
A JAR or ZIP file is opened and processed, with each file within the JAR or ZIP file resulting in one or more schema objects.
For OracleJSP, use loadjava as follows:
ojspc, which, by default, also compiles the translated Java source. Then use loadjava to load the resulting .class files and any resource files (the ojspc -hotload option, for example, produces a resource file), typically all bundled into a JAR file.
Alternatively, you can load the translated .java file instead of the compiled .class files. You can have the server-side compiler compile the .java file as it is being loaded.
loadjava to load untranslated .jsp files, typically bundled into a JAR file, as resource schema objects. (They will be translated and published later, in the server, as a result of the session shell publishjsp command.)
Following is the complete loadjava option syntax. Brackets, {...}, are not part of the syntax. They are used to surround two possible option formats that are followed by option input.
loadjava {-user | -u} user/password[@database] [options] file.java | file.class | file.jar | file.zip | file.sqlj | resourcefile [-debug] [-d | -definer] [{-e | -encoding} encoding_scheme] [-f | -force] [{-g | -grant} user [, user]...] [-o | -oci8] [ -order ] [-noverify] [-r | -resolve] [{-R | -resolver} "resolver_spec"] [{-S | -schema} schema] [ -stdout ] [-s | -synonym] [-t | -thin] [-v | -verbose]
Of particular significance are the -user and -resolve options (which can be abbreviated to -u and -r, respectively). Use the -user option to specify the schema name and password. Use the -resolve option to specify whether loadjava is to compile (if applicable) and resolve external references in the classes you are loading, after all classes on the command line have been loaded.
If you are loading a .java source file that you want compiled by the server-side compiler during loading, you must enable the -resolve option.
Following is an example for a client-side translation scenario where the JSP page has already been translated and compiled, producing file HelloWorld.class and another .class file for the page implementation inner class (with a name that starts with "HelloWorld"). Assume % is a UNIX prompt:
% loadjava -u scott/tiger -r HelloWorld*.class
Or you can bundle the files into a JAR file:
% loadjava -v -u scott/tiger -r HelloWorld.jar
The loadjava -v (-verbose) option, which provides detailed status reporting as loading progresses, is especially useful when you are loading a number of files or compiling in the server.
The following example is also for a client-side translation scenario (HelloWorld.java is the JSP translator output), but where you have elected to skip the compilation step on the client (using the ojspc -noCompile option) and instead have the server-side compiler handle the compilation:
% loadjava -v -u scott/tiger -r HelloWorld.java
The following example is for a server-side translation scenario:
% loadjava -u scott/tiger -r HelloWorld.jsp
The sess_sh (session shell) tool is provided with Oracle8i as an interactive interface to the session namespace of a database instance. You specify database connection arguments when you start sess_sh. It then presents you with its $ prompt to indicate that it is ready for commands.
The session shell tool has many top-level commands you can run from the $ prompt, each of which may have its own set of options. For OracleJSP developers, the publishservlet and unpublishservlet commands (for deployment with client-side translation), publishjsp and unpublishjsp commands (for deployment with server-side translation), and createcontext command (for creating OSE servlet contexts) are of primary interest.
Following are the key sess_sh syntax elements for starting the tool:
sess_sh -user user -password password -service serviceURL
-user specifies the user name of the schema.
-password specifies the password for the specified user name.
-service specifies the URL of the database whose session namespace is to be "opened" by sess_sh. The serviceURL parameter should have one of the three following forms:
sess_iiop://host:port:sidjdbc:oracle:type:spechttp://host[:port]
Following are some general examples:
sess_iiop://localhost:2481:orcl
jdbc:oracle:thin:@myhost:1521:orcl
http://localhost:8000
Here is an example of a sess_sh command line:
% sess_sh -user SCOTT -password TIGER -service jdbc:oracle:thin:@myhost:5521:orcl
After starting sess_sh, you will see its command prompt:
$
In addition to publish object commands, such as publishservlet and publishjsp, the session shell tool offers shell commands that give the session namespace much of the "look and feel" of a UNIX file system as seen from one of the UNIX shells (such as the C shell). For example, the following sess_sh command displays the published objects and publishing contexts in the /alpha/beta/gamma publishing context (publishing contexts are nodes in the session namespace, analogous to directories in a file system):
$ ls /alpha/beta/gamma
As mentioned previously, key sess_sh commands for OracleJSP developers include the following:
$ publishjsp ... $ unpublishjsp ... $ publishservlet ... $ unpublishservlet ... $ createcontext ...
For information about the publishservlet and unpublishservlet commands, see "Publishing Translated JSP Pages in Oracle8i (Session Shell publishservlet)". For information about the publishjsp and unpublishjsp commands, see "Translating and Publishing JSP Pages in Oracle8i (Session Shell publishjsp)".
Each session shell command has a -describe option to describe its operation, a -help option to summarize its syntax, and a -version option to show its version number.
|
Note:
This document provides only abbreviated discussion of
Beyond what is presented here, for example, commands can be specified within quotes on the There are also top-level options to connect with plain IIOP instead of the default session IIOP, to specify a role, to connect to the database with SSL server authentication, and to use a service name instead of an SID in the URL.
For complete information about the |
|
 Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|