JSP Translation and Deployment

Deployment to Oracle8i with Client-Side Translation

This section describes the steps for deployment to Oracle8i with client-side translation.

The steps are as follows:

Use ojspc to pre-translate JSP pages or SQLJ JSP pages on the client.
Use loadjava to load files into Oracle8i--.class files (or, optionally, .java or .sqlj files instead) and any Java resource files resulting from the page translation.
(Optional) "Hotload" the pages into Oracle8i (if hotloading was enabled during translation). See "Overview of Hotloaded Classes in Oracle8i" for background information about hotloading.
Use the session shell publishservlet command to publish the pages.

Note:
For simplicity and convenience, deployment with server-side translation is generally recommended. See "Deployment to Oracle8i with Server-Side Translation".

Pre-Translating JSP Pages (ojspc)

To pre-translate JSP pages on a client (typically for pages that will run in the Oracle Servlet Engine), use the ojspc command-line tool to invoke the OracleJSP translator.

For general information about ojspc and description of its options, see "The ojspc Pre-Translation Tool".

The rest of this section covers the following topics:

Simplest ojspc Usage
ojspc for SQLJ JSP Pages
Enabling Hotloading with ojspc
Other Key ojspc Features and Options for Deployment to Oracle8i

ojspc Examples

Note:
The exact names of generated files may change in future releases, but will still have the same general form. The names would always include the base name (such as "Foo" in these examples), but may include slight variations, such as _Foo.java or _Foo.class.

Simplest ojspc Usage

The following example shows the simplest usage of ojspc:

% ojspc Foo.jsp

With this invocation, the following files are produced:

Foo.java
Foo.class
a.class file for the inner class for static content (with "Foo" in the name)

By default, all output goes to the current directory, from which ojspc was run.

ojspc for SQLJ JSP Pages

The ojspc tool also accepts .sqljsp files for JSP pages that use SQLJ code:

% ojspc Foo.sqljsp

For .sqljsp files, ojspc automatically invokes the SQLJ translator as well as the JSP translator.

With this invocation, the following files are produced:

Foo.sqlj (produced from Foo.sqljsp by the JSP translator)
Foo.java (produced from Foo.sqlj by the SQLJ translator)
Foo.class
a.class file for the inner class for static content (with "Foo" in the name)
a Java resource file (.ser) or class file (.class), depending on the setting of the SQLJ -ser2class option, for the SQLJ "profile" (with "Foo" in the name)

For information about SQLJ profiles, see the Oracle8i SQLJ Developer's Guide and Reference.

By default, all output goes to the current directory, from which ojspc was run.

Enabling Hotloading with ojspc

Use the ojspc -hotload option to enable hotloading, which (among other things) results in static page content going into a Java resource file instead of into the inner class of the page implementation class.

The following example translates the page and directs the OracleJSP translator to enable hotloading:

% ojspc -hotload Foo.jsp

With this command, the translator will generate the following output:

Foo.java (as usual)
Foo.class (as usual)
Foo.res, a Java resource file to contain the static page content
a.class file for the inner class (as usual, with "Foo" in the name, although the static content goes into Foo.res instead of going into the inner class)

Be aware that the ojspc -hotload option merely enables hotloading; it does not actually hotload the page. Hotloading requires an additional deployment step, as described in "Hotloading Page Implementation Classes in Oracle8i".

For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle8i".

Other Key ojspc Features and Options for Deployment to Oracle8i

The following ojspc options, fully described in "Option Descriptions for ojspc", are especially useful:

-appRoot--Set an application root directory if you do not want the default (the current directory, from which ojspc was run).
-noCompile--Enable this flag if you do not want to compile during translation. You would do this, for example, if you want to load the translated page into Oracle8i as a .java file and have compilation performed by the server-side compiler.
-d--Specify the directory where ojspc will place the generated binary files (.class files and Java resource files). This makes it easier to know what was generated, and therefore what needs to be loaded into Oracle8i.
-srcdir--Specify the directory where ojspc will place the generated source files. For example, this would be useful instead of -d if you are enabling -noCompile and will load your translated page into Oracle8i as .java source.
-extres--Direct the OracleJSP translator to put static content into a Java resource file instead of into the inner class of the page implementation class.
-hotload--Direct the OracleJSP translator to put static content into a Java resource file instead of into the inner class of the page implementation class, and generate code in the page implementation class to enable hotloading.
-S--For SQLJ JSP pages, use the -S prefix to specify Oracle SQLJ options; ojspc will pass these option settings to the Oracle SQLJ translator.

ojspc Examples

The following examples show the use of key ojspc options.

% ojspc -appRoot /myroot/pagesrc -d /myroot/bin -hotload /myroot/pagesrc/Foo.jsp

The preceding example accomplishes the following:

Specifies an application root for application-relative static include directives in the translated page.
Enables hotloading and produces the Java resource file Foo.res for static content.
Places Foo.java into the current directory, by default. There is no package, because Foo.jsp is in the specified application root directory.

Places Foo.class, Foo.res, and the .class file for the inner class into the /myroot/bin directory.

% ojspc -appRoot /myroot/pagesrc -srcdir /myroot/gensrc -noCompile -extres /myroot/pagesrc/Foo.jsp

The preceding example accomplishes the following:

Specifies an application root for application-relative static include directives in the translated page.
Produces the Java resource file Foo.res for static content (without enabling hotloading).
Places Foo.java into the /myroot/gensrc directory. There is no package, because Foo.jsp is in the specified application root directory.
Does not compile Foo.java (no .class files are produced).

Places Foo.res into the current directory, by default.

% ojspc -appRoot /myroot/pagesrc -d /myroot/bin -extres -S-ser2class true /myroot/pagesrc/Foo.sqljsp

The preceding example accomplishes the following:

Specifies an application root for application-relative static include directives in the translated page.
Produces the Java resource file Foo.res for static content (without enabling hotloading).
Places Foo.sqlj and Foo.java into the current directory, by default. There is no package, because Foo.jsp is in the specified application root directory.
Places Foo.class, Foo.res, a .class file for the inner class, and a .class file for the SQLJ profile into the /myroot/bin directory. (Without the SQLJ -ser2class option setting, the profile would be generated in a .ser Java resource file instead of a .class file.)

Loading Translated JSP Pages into Oracle8i (loadjava)

After client-side pre-translation, use the Oracle loadjava tool to load generated files into Oracle8i. You can use either of the following scenarios:

Load .class files and Java resource files (if any).
Use the ojspc -noCompile option during translation, then load the translated .java file and resource files (if any). The .java file can be compiled by the Oracle8i server-side compiler during loading.

In either case, whenever you have multiple files it is recommended that you put the files into a JAR file for loading.

The loadjava tool is provided with Oracle8i as a general-purpose tool for loading Java files into the database. For an overview, see "Overview of the loadjava Tool". For further information, see the Oracle8i Java Tools Reference.

Important:
In the next two subsections ("Loading Class Files with loadjava" and "Loading Source Files with loadjava"), be aware of the following important considerations.

Even when you enable the -extres or -hotload option to place static text into a resource file, the page implementation inner class is still produced and must still be loaded.

Like a Java compiler, loadjava resolves references to classes, but not to resources; be sure to correctly load the resource files your classes need--they must be in the same package as the .java file.

Loading Class Files with loadjava

Assume you translated a JSP page Foo.jsp with the ojspc -extres or -hotload option enabled, producing the following files:

Foo.java
Foo.class
Foo$__jsp__StaticText.class

Foo.res

Note:
Generated names used here are provided as examples only. Such implementation details are subject to change in future releases, although the base name (such as "Foo" here) will always be part of the generated names.

You can ignore Foo.java, but the binary files (.class and .res) must all be loaded into Oracle8i. Typically, you would put Foo.class, Foo$__jsp__StaticText.class, and Foo.res into a JAR file, suppose Foo.jar, and load it as follows (assume % is a UNIX prompt):

% loadjava -v -u scott/tiger -r Foo.jar

The -u (-user) option specifies the user name and password for the database schema; the -r (-resolve) option resolves the classes as they are loaded. Optionally use the -v (-verbose) option for detailed status output.

Alternatively, you can load the files individually, as follows. (The syntax depends on your operating environment. In these examples, assume % is a UNIX prompt.)

% loadjava -v -u scott/tiger -r Foo*.class Foo.res

or:

% loadjava -v -u scott/tiger -r Foo*.*

All these examples result in the following schema objects being created in the database (you typically need to know only the name of the page implementation class schema object):

SCOTT:Foo page implementation class schema object

Or there may be an additional package designation, according either to the ojspc -packageName option or the relative location of the .jsp file to the current directory when you ran ojspc. For example, a -packageName setting of "abc.def" results in that being the package of the Foo class, so there would be a SCOTT:abc/def/Foo class schema object.
SCOTT:Foo$__jsp__StaticText class schema object

With the same package designation as the page implementation class.
SCOTT:Foo.res resource schema object

With a package designation according to any path specification, either in a JAR file or on the loadjava command line, when it was loaded.

For an overview of how loadjava names the schema objects it produces, see "Database Schema Objects for Java".

Note:
If you are loading a pre-translated SQLJ JSP page, you must also load the generated profile file--either a .ser Java resource file or a .class file, depending on the SQLJ -ser2class option. If it is a .ser file, schema object naming is comparable to that of a .res Java resource file; if it is a .class file, schema object naming is comparable to that of the other .class files.

Loading Source Files with loadjava

Assume that you translated a JSP page, Foo.jsp, with the ojspc -noCompile and -extres options enabled, producing the following files:

Foo.java (which you want to load into Oracle8i as source to be compiled by the server-side compiler)
Foo.res

Typically, you would put Foo.java and Foo.res into a JAR file, suppose Foo.jar, and load it as follows:

% loadjava -v -u scott/tiger -r Foo.jar

When you enable the loadjava -r (-resolve) option, this results in the source file being compiled automatically by the server-side compiler, producing class schema objects. The -u (-user) option specifies the user name and password for the database schema. Optionally use the -v (-verbose) option for detailed status reporting.

Alternatively, you can load the files individually:

% loadjava -v -u scott/tiger -r Foo.java Foo.res

Or load them using a wildcard character:

% loadjava -v -u scott/tiger -r Foo.*

All these examples result in the following schema objects being created in the database (you typically need to know only the name of the page implementation class schema object):

SCOTT:Foo source schema object

When you load a source file into Oracle8i with loadjava, the source is stored separately as a source schema object, in addition to the class schema objects produced by the server-side compiler.
SCOTT:Foo page implementation class schema object

Or there may be an additional package designation for the Foo class and source schema objects, according either to the ojspc -packageName option or the relative location of the .jsp file to the current directory when you ran ojspc. For example, a -packageName setting of "abc.def" results in that being the package of the Foo class, so you would have a SCOTT:abc/def/Foo class schema object.
SCOTT:Foo$__jsp__StaticText class schema object

With the same package designation as the page implementation class.
SCOTT:Foo.res resource schema object

With a package designation according to any path specification, either in a JAR file or on the loadjava command line, when it was loaded.

For an overview of how loadjava names the schema objects it produces, see "Database Schema Objects for Java".

Notes:

Generated names used here are provided as examples only. Such implementation details are subject to change in future releases, although the base name (such as "Foo" here) will always be part of generated names.

If you are loading translated source (.java) for a SQLJ JSP page, you must also load the generated profile file--either a .ser Java resource file or a .class file, depending on the SQLJ -ser2class option. If it is a .ser file, schema object naming is comparable to that of a .res Java resource file; if it is a .class file, schema object naming is comparable to that of other .class files. (Remember that the ojspc -noCompile option prevents Java compilation, but not SQLJ translation.)

Hotloading Page Implementation Classes in Oracle8i

To optionally "hotload" translated JSP pages in Oracle8i, use the session shell java command to invoke the main() method of the page implementation class schema object. See "Overview of the sess_sh Session Shell Tool" for how to start the tool and connect to the database.

You are required to have previously enabled hotloading through the ojspc -hotload option during translation. The -hotload option results in a main() method and hotloading method being implemented in the page implementation class. Invoking the main() method calls the hotloading method and hotloads the page implementation class.

Here is an example ($ is the sess_sh prompt):

$ java SCOTT:Foo

Assuming Foo is a class that was translated with the -hotload option enabled and was then loaded with loadjava into the SCOTT schema as in earlier examples, this session shell java command will hotload the Foo page implementation class.

For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle8i". For more information about the session shell java command, see the Oracle8i Java Tools Reference.

Publishing Translated JSP Pages in Oracle8i (Session Shell publishservlet)

To publish translated pages as part of the "deployment with client-side translation" scenario, use the session shell publishservlet command. See "Overview of the sess_sh Session Shell Tool" for how to start the tool and connect to the database.

The publishservlet command is for general use in publishing any servlet to run in OSE, but also applies to JSP page implementation classes (which are essentially servlets).

Note:
Servlets and JSP pages that are published with publishservlet can be "unpublished" (removed from the JServer JNDI namespace) with the session shell unpublishservlet command. See "Unpublishing JSP Pages with unpublishservlet".

Overview of publishservlet Syntax and Options

Starting sess_sh establishes a connection to the Oracle8i database. Once you start sess_sh, you can run the publishservlet command from the session shell $ prompt.

The publishservlet command uses the following general syntax:

$ publishservlet context servletName className -virtualpath path [-stateless] [-reuse] [-properties props]

When using publishservlet, you must specify the following:

a servlet context (context in the command line above)

This is required by publishservlet. You can use the Oracle Servlet Engine's default servlet context:
```
/webdomains/contexts/default
```
This results in a context path of "/".

If you specify some other servlet context, then the context path of that servlet context will be used.

For example, if you specify a servlet context, mycontext, that was created as follows:
```
$ createcontext -virtualpath mywebapp /webdomains mycontext
```
then mywebapp will be the context path for the published JSP page.
a servlet name (servletName in the command line above)

This is required by publishservlet to specify the name for the JSP page in the named_servlets directory, but has no practical use for the JSP developer or user other than for unpublishing. It can be an arbitrary string.
a class name (className in the command line above)

This is the name of the page implementation class schema object being published.
a servlet path (referred to on the command line as the "virtual path")

Use the -virtualpath option. This is required for a JSP page, although it is optional for publishing servlets in general.

Together, the context path and servlet path (along with the host name and port) determine the URL to invoke the page, as described in "URLs for the Oracle Servlet Engine".

Important:

The servlet context, servlet name, and class name are not preceded by any designating syntax so must appear on the command line in the above order relative to each other. (Any publishservlet options can be intermixed with these parameters, however.)

Enable boolean options, such as -stateless, by typing only the option name in the command line (as opposed to setting it to true).

In addition to the required parameters, you can specify any of the following options:

-stateless

This is a boolean option that tells the Oracle Servlet Engine that the JSP page is to be stateless--it will not have access to the HttpSession object during execution.
-reuse

This is a boolean option to specify a new servlet path (referred to as the "virtual path") for a JSP page. If you enable it, then the specified servlet path will be linked to the specified servlet name in the JNDI namespace without publishservlet going through the complete publishing process.

When you enable the -reuse option, specify a new servlet path, the servlet context, and a previously published servlet name.
-properties props

Use this option to specify properties to be passed to the JSP page as initialization parameters upon execution.

For more information about the publishservlet command, see the Oracle8i Java Tools Reference.

Example: Publishing JSP Pages with publishservlet

The following example publishes a JSP page that has been loaded into Oracle8i ($ is the sess_sh prompt):

$ publishservlet /webdomains/contexts/default -virtualpath Foo.jsp FooServlet SCOTT:Foo

For simplicity, the OSE default servlet context is specified, resulting in "/" as the context path.

Foo.jsp will be the servlet path. (You can specify any name you want for the servlet path, but naming it according to the original source file name is a good convention.)

FooServlet will be the servlet name in the OSE named_servlets directory, but this name generally will not be used, except for unpublishing.

SCOTT:Foo is the page implementation class schema object being published.

After the above publishservlet command, the end-user would invoke the JSP page with a URL as follows:

http://host[:port]/Foo.jsp

Access it dynamically from another JSP page in the application, suppose a page published as Bar.jsp, as follows (using page-relative syntax and then application-relative syntax):

<jsp:include page="Foo.jsp" flush="true" />

or:

<jsp:include page="/Foo.jsp" flush="true" />

Note:
Both the servlet path and the servlet name specified in the publishservlet command are entered into the JServer JNDI namespace, although only the servlet path is generally of interest to JSP users. OSE uses JNDI to look up any published JSP page or servlet.

Unpublishing JSP Pages with unpublishservlet

The sess_sh tool also has an unpublishservlet command that removes a servlet or JSP page from the JServer JNDI namespace. This does not, however, remove the servlet class schema object or page implementation class schema object from the database.

Specify the context, servlet path (referred to on the command line as the "virtual path"), and servlet name. Following is the general syntax to unpublish a JSP page:

$ unpublishservlet -virtualpath path context servletName

For example, to unpublish the page that was published in the previous section:

$ unpublishservlet -virtualpath Foo.jsp /webdomains/contexts/default FooServlet