Oracle JavaServer Pages Developer's Guide and Reference Release 8.1.7 Part Number A83726-01 |
Library | Service | Contents | Index

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

1. Use `ojspc` to pre-translate JSP pages or SQLJ JSP pages on the client.

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

3. (Optional) "Hotload" the pages into Oracle8i (if hotloading was enabled during translation). See "Overview of Hotloaded Classes in Oracle8i" for background information about hotloading.

4. 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:

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

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

3. a class name (`className` in the command line above)

   This is the name of the page implementation class schema object being published.

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

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index