Tools and Commands for Translation and Deployment to Oracle8i

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: Another tool, the JServer Accelerator, is relevant if you want to natively compile your application to run in Oracle8i. This tool, invoked as ncomp, is documented in the Oracle8i Java Tools Reference. The tools discussed in this section are located in the [ORACLE_HOME]/bin directory.

The ojspc Pre-Translation Tool

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:

• Overview of ojspc Functionality

• Option Summary Table for ojspc

• Command-Line Syntax for ojspc

• Option Descriptions for ojspc

• Summary of ojspc Output Files, Locations, and Related Options

  Notes: There are other possible scenarios, such as in a middle-tier environment, for using ojspc to pre-translate JSP page. See "Use of ojspc for Pre-Translation for Non-OSE Environments".

Overview of ojspc Functionality

For a simple JSP (not SQLJ JSP) page, default functionality for ojspc is as follows:

• It takes a .jsp file as an argument.

• It invokes the OracleJSP translator to translate the .jsp file into Java page implementation class code, producing a .java file. The page implementation class includes an inner class for static page content.

• It invokes the Java compiler to compile the .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:

• It takes a .sqljsp file as an argument instead of a .jsp file.

• It invokes the OracleJSP translator to translate the .sqljsp file into a .sqlj file for the page implementation class (and inner class).

• It invokes the Oracle SQLJ translator to translate the .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.

• It invokes the Java compiler to compile the .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)".

Note: The ojspc command-line tool is a front-end utility that invokes the oracle.jsp.tool.Jspc class.

Option Summary Table for ojspc

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).

Note: A boolean ojspc option is enabled by typing only the option name, not by setting it to true. Setting it to true will cause an error.

Table 6-1 Options for ojspc Pre-Translation Utility

Option	Related OracleJSP Configuration Parameters	Description	Default
-addclasspath	classpath (related, but with different functionality)	additional classpath entries for javac	empty (no additional path entries)
-appRoot	n/a	application root directory for application-relative static include directives from the page	current directory
-debug	emit_debuginfo	boolean to direct ojspc to generate a line map to the original .jsp file for debugging	false
-d	page_repository_root	location where ojspc should place generated binary files (.class and resource)	current directory
-extend	n/a	class for the generated page implementation class to extend	empty
-extres	external_resource	boolean to direct ojspc to generate an external resource file for static text from the .jsp file	false
-hotload (for OSE only)	n/a	boolean to direct ojspc to implement code in the page implementation class to allow hotloading	false
-implement	n/a	interface for the generated page implementation class to implement	empty
-noCompile	javaccmd	boolean to direct ojspc not to compile the generated page implementation class	false
-packageName	n/a	package name for the generated page implementation class	empty (generate package names per .jsp file location)
-S-<sqlj option>	sqljcmd	-S prefix followed by an Oracle SQLJ option (for .sqljsp files)	empty
-srcdir	page_repository_root	location where ojspc should place generated source files (.java and .sqlj)	current directory
-verbose	n/a	boolean to direct ojspc to print status information as it executes	false
-version	n/a	boolean to direct ojspc to display the OracleJSP version number	false

Command-Line Syntax for ojspc

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:

• If multiple .jsp files are translated, they all must use the same character set (either by default or through page directive contentType settings).

• Use spaces between file names in the file list.

• Use spaces as separators between option names and option values.

• Option names are not case sensitive, but option values usually are (such as package names, directory paths, class names, and interface names).

• Enable boolean options, which are disabled by default, by typing only the option name. For example, type -hotload, not -hotload true.)

Following is an example:

% ojspc -d /myapp/mybindir -srcdir /myapp/mysrcdir -hotload MyPage.sqljsp MyPage2.jsp

Option Descriptions for ojspc

This section describes the ojspc options in more detail.

-addclasspath

(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 classpath configuration parameter provides related, although different, functionality. See "OracleJSP Configuration Parameters (Non-OSE)".

-appRoot

(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:

• It is used for static 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.

• It is used in determining the package of the page implementation class. The package will be based on the location of the file being translated relative to the application root directory. The package, in turn, determines the placement of output files. (See "Summary of ojspc Output Files, Locations, and Related Options".)

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:

• You want to translate the following file:

  /abc/def/ghi/test.jsp
  
  

• You run ojspc from the current directory, /abc, as follows (assume % is a UNIX prompt):

  % cd /abc
  % ojspc def/ghi/test.jsp
  
  

• The test.jsp page has the following include directive:

  <%@ include file="/test2.jsp" %> 
  
  

• The 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.

Note: It is typical for the specified application root directory to be some level of parent directory of the directory where the translated JSP page is located.

-d

(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 page_repository_root configuration parameter provides related functionality. See "OracleJSP Configuration Parameters (Non-OSE)".

-debug

(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 emit_debuginfo configuration parameter provides the same functionality. See "OracleJSP Configuration Parameters (Non-OSE)".

-extend

(fully qualified Java class name; ojspc default: empty)

Use this option to specify a Java class that the generated page implementation class will extend.

-extres

(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: The inner class is still created and must still be deployed. In an on-demand translation scenario, the OracleJSP external_resource configuration parameter provides the same functionality. See "OracleJSP Configuration Parameters (Non-OSE)".

-hotload

(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:

1. Perform -extres functionality, writing static output to a Java resource file (see the -extres description above).

2. Create a 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".

Note: To write static content to a resource file without enabling hotloading (if the page will not be running in OSE, for example), use the -extres option.

-implement

(fully qualified Java interface name; ojspc default: empty)

Use this option to specify a Java interface that the generated page implementation class will implement.

-noCompile

(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: In an on-demand translation scenario, the OracleJSP javaccmd configuration parameter provides related functionality, allowing you to specify an alternative Java compiler directly. See "OracleJSP Configuration Parameters (Non-OSE)". For a SQLJ JSP page, enabling -noCompile does not prevent SQLJ translation, just Java compilation.

-packageName

(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-<sqlj option> <value>

(-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:

• Do not use the SQLJ -encoding option; instead, use the contentType parameter in a page directive in the JSP page.

• Do not use the SQLJ -classpath option if you use the ojspc -addclasspath option.

• Do not use the SQLJ -compile option if you use the ojspc -noCompile option.

• Do not use the SQLJ -d option if you use the ojspc -d option.

• Do not use the SQLJ -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.

-srcdir

(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 page_repository_root configuration parameter provides related functionality. See "OracleJSP Configuration Parameters (Non-OSE)".

-verbose

(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

-version

(boolean; ojspc default: false)

Enable this option for ojspc to display the OracleJSP version number and then exit.

Summary of ojspc Output Files, Locations, and Related Options

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:

• a .sqlj source file (SQLJ JSP pages only)

• a.java source file

• a .class file for the page implementation class

• a .class file for the inner class

• a Java resource file or, optionally, a .class file for the SQLJ profile (SQLJ JSP pages only)

• optionally, a Java resource file for the static text of the page

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.

Notes: It is advisable that you run ojspc once for each directory of your JSP application, so files in different directories can be given different package names, as appropriate.

Overview of the loadjava Tool

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:

• For client-side translation, you will have already translated your JSP pages using 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.

• For server-side translation, use 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

Overview of the sess_sh Session Shell Tool

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:sid
  jdbc:oracle:type:spec
  http://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 sess_sh syntax and options. It presents only the simplest invocation and usage of the tool. Beyond what is presented here, for example, commands can be specified within quotes on the sess_sh command line instead of at the $ prompt. 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 sess_sh tool, see the Oracle8i Java Tools Reference.

---