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

## Deployment to Oracle8i with Server-Side Translation

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

The steps are as follows:

1. Use `loadjava` to load untranslated JSP page or SQLJ JSP page source files into Oracle8i.

2. Use the session shell `publishjsp` command to translate and publish the pages.

The `publishjsp` step automatically handles translation, compilation, hotloading (if applicable), and publishing.

### Loading Untranslated JSP Pages into Oracle8i (loadjava)

As the first step for deployment with server-side translation, use the Oracle `loadjava` tool to load untranslated `.jsp` or `.sqljsp` files into Oracle8i as Java resource files.

If you are loading 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 server. For an overview, see "Overview of the loadjava Tool". For further information, see the Oracle8i Java Tools Reference.

Following is an example of loading an untranslated page:

    % loadjava -u scott/tiger Foo.jsp

This loads `Foo.jsp` into the `SCOTT` schema (password `TIGER`) as a Java resource object. There is no need to specify the `loadjava -resolve` (`-r`) option.

This will result in the following resource schema object being created in the database:

- `SCOTT:Foo.jsp`

Note that any path information you specify for the `.jsp` file, either in a JAR file or on the `loadjava` command line, determines placement of the resource schema object. Consider the following modification of the previous example:

    % loadjava -u scott/tiger xxx/yyy/Foo.jsp

This will result in the following resource schema object being created in the database:

- `SCOTT:xxx/yyy/Foo.jsp`

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

You can also load a `.sqljsp` file:

    % loadjava -u scott/tiger Foo.sqljsp

This loads `Foo.sqljsp` into the `SCOTT` schema and will result in the following resource schema object being created in the database:

- `SCOTT:Foo.sqljsp`

If you want to load multiple `.jsp` (or `.sqljsp`) files, you can use a wildcard character (depending on your operating environment; assume `%` is a UNIX prompt):

    % loadjava -u scott/tiger *.jsp

Or presume you had put the `.jsp` files into a JAR file:

    % loadjava -u scott/tiger myjspapp.jar

### Translating and Publishing JSP Pages in Oracle8i (Session Shell publishjsp)

Translation, compilation, hotloading (if enabled), and publishing all occur automatically in the scenario of deployment with server-side translation, as the result of executing the JServer session shell `publishjsp` command. See "Overview of the sess_sh Session Shell Tool" for how to start the session shell and connect to the database.

Run `publishjsp` after you have loaded a `.jsp` (or `.sqljsp`) file into Oracle8i as a resource schema object. (This section includes separate discussion for running `publishjsp` on a `.sqljsp` file because there are some logistical differences in the results.)

Note: JSP pages that are published with `publishjsp` can be "unpublished" (removed from the JServer JNDI namespace) with the session shell `unpublishjsp` command. See "Unpublishing JSP Pages with unpublishjsp".

#### Overview of publishjsp Syntax and Options

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

The `publishjsp` command uses the following general syntax:

    $ publishjsp [options] path/name.jsp

The options can be any of the following:

    [-schema schemaname] [-virtualpath path] [-servletName name] [-packageName name]
    [-context context] [-hotload] [-stateless] [-verbose] [-resolver resolver]
    [-extend class] [-implement interface]

Important: Enable boolean options, such as `-hotload`, by typing only the option name in the command line (not setting it to `true`). For options where you specify a value, the value does not have to be in quotes.

The file `name``.jsp` (or `name``.sqljsp` for a SQLJ JSP page) is the JSP page resource schema object that you loaded with `loadjava` and is the only required parameter, along with any relevant schema `path` information.

By default, if no `-virtualpath` option is specified, `path/name``.jsp` becomes the servlet path. For example, running `publishjsp` on `dir1/foo.jsp` (the path within the current schema or specified schema) results in `dir1/foo.jsp` as the servlet path.

By default, if no `-context` option is specified, the OSE default servlet context is used and "/" is the context path.

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

The following informative options are also available:

- Use `-showVersion` by itself to display the OracleJSP version number and exit.

- Use `-usage` by itself to display a `publishjsp` option list and exit.

Following are the option descriptions:

- `-schema` `schemaname`

  Use this option to specify the schema where the JSP page resource schema object is located, if it is not in the same schema you logged in to through `sess_sh`.

  This schema must be accessible from your `sess_sh` login schema. The `publishjsp` command does not offer a way to specify passwords.

- `-virtualpath` `path`

  You can use this option to specify an alternative servlet path for the JSP page; otherwise, the servlet path is simply the specified `.jsp` file name itself along with any specified schema path.

  For example:

      -virtualpath altpath/Foo.jsp

  or perhaps simply:

      -virtualpath mypath.jsp

- `-servletName` `name`

  You can use this option to specify an alternative servlet name (in OSE `named_servlets`) for the JSP page; however, the servlet name has no bearing on how the page is invoked so is rarely needed.

  By default, the servlet name is the base name of the `.jsp` file along with any path you specified. For example, running `publishjsp` on `SCOTT:dir1/Foo.jsp` results in `dir1.Foo` as the servlet name in OracleJSP release 8.1.7 (1.1.0.0.0) (Be aware that implementation details are subject to change in future releases.)

- `-packageName` `name`

  You can use this option to specify a package name for the generated page implementation class; otherwise, it is determined by any path specification for the `.jsp` file when you run `publishjsp`. For example, running `publishjsp` on `SCOTT:dir1/Foo.jsp` results in package `dir1` for the page implementation class.

  The `-packageName` option affects where schema objects are placed in the schema, but does not affect the servlet path of the JSP page.

- `-context` `context`

  You can use this option to specify a servlet context in the Oracle Servlet Engine. The context path of this servlet context becomes part of the URL used to invoke the page.

  If you do not use this option, the JSP page will be in the OSE default context, `/webdomains/contexts/default`, whose context path is simply "/".

  Any specified context should be under `/webdomains/contexts`, such as:

      /webdomains/contexts/mycontext

  Important: Remember that it is the context path of the servlet context, not the context name itself, that is used in URLs to access the page. When a servlet context is created in OSE with the session shell `createcontext` command, both the context path (through the `createcontext -virtualpath` option) and the context name must be specified. It is convenient, and probably typical, to specify the context name and context path to be the same, but it is not required.

- `-hotload`

  Enable this flag to enable and perform hotloading. This results in the following steps being performed by the `publishjsp` command:

  1. Static output is written to a resource schema object instead of to the page implementation class schema object.

  2. A `main()` method and a hotloading method are implemented in the generated page implementation class to allow hotloading.

  3. The `main()` method is executed to perform hotloading.

  To use `-hotload`, you must have permission for the JServer hotloader. This can be granted as follows (from SQL*Plus, for the `SCOTT` schema, for example):

      dbms_java.grant_permission('SCOTT', 'SYS:oracle.aurora.security.JServerPermission', 'HotLoader', null);

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

- `-stateless`

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

  This flag is used for `mod_ose` optimization. For information about the Apache `mod_ose` module, see the Oracle8i Oracle Servlet Engine User's Guide.

- `-verbose`

  Set this option to `true` to direct `publishjsp` to report the translation steps as it executes.

- `-resolver`

  Use this option to specify an alternative Java class resolver. The resolver is used in compiling and resolving Java source through `loadjava`, including locating classes used in JSP pages.

  The default resolver is `((*` `user``) (* PUBLIC))`. For the `SCOTT` schema, for example, this is the following:

      ((* SCOTT) (* PUBLIC))

  For the `-resolver` option, you must specify the value in quotes as in the following example:

      $ publishjsp ... -resolver "((* BILL) (* SCOTT) (* PUBLIC))" ...

- `-extend`

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

- `-implement`

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

#### Examples: Publishing JSP Pages with publishjsp

This section provides examples of using `publishjsp` to translate and publish `.jsp` pages in Oracle8i. The pages will have already been loaded as resource schema objects in a particular schema, such as `SCOTT:Foo.jsp`.

(For information about running `publishjsp` on `.sqljsp` pages, see "Publishing SQLJ JSP Pages with publishjsp".)

To review how the servlet path and context path combine in forming the URL to invoke the page, see "URLs for the Oracle Servlet Engine".

Notes: The following examples use the `SCOTT` schema. `SCOTT` must either be the schema specified when starting `sess_sh`, or accessible from the schema specified. Each example lists the schema objects that are created, although this is secondary. All that matters in invoking the JSP page is the servlet path and context path. The page implementation class schema object is automatically mapped during the `publishjsp` publishing step. Application-relative and page-relative syntax for dynamic `jsp:include` and `jsp:forward` statements inside Oracle8i is the same as for any JSP environment. The relative paths are according to how the JSP pages were published (as shown in the examples below). The exact names of generated schema objects 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` instead of `Foo`. `$` is the `sess_sh` prompt.

##### Example 1

    $ publishjsp -schema SCOTT dir1/Foo.jsp

This uses the default servlet context, which has a context path of "/".

The default servlet path is `dir1/Foo.jsp`.

After this command, `Foo.jsp` can be invoked as follows:

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

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

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

or:

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

By default, `dir1` is the Java package for the page implementation class and inner class (because of the specified path in the `SCOTT` schema).

The following schema objects are created:

- `SCOTT:dir1/Foo` source schema object

- `SCOTT:dir1/Foo` class schema object

- a class schema object under `dir1` for the inner class for static text (with "Foo" in the name, such as `SCOTT:dir1/Foo$__jsp__StaticText`)

##### Example 2

    $ publishjsp -schema SCOTT -context /webdomains/contexts/mycontext Foo.jsp

Presume `mycontext` had been created as follows:

    $ createcontext -virtualpath mycontext /webdomains mycontext

The `publishjsp` command publishes the page to the `mycontext` servlet context, which was created with `mycontext` also specified as the context path.

The default servlet path is simply `Foo.jsp`.

After this command, `Foo.jsp` can be invoked as follows:

    http://host[:port]/mycontext/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" />

Even though this example specifies a non-default servlet context, that is not relevant for dynamic `jsp:include` or `jsp:forward` commands. What is relevant is that the published path of the page relative to that context is simply `/Foo.jsp`.

By default, there is no Java package for the page implementation class and inner class (because no path is specified in the `SCOTT` schema).

The following schema objects are created:

- `SCOTT:Foo` source schema object

- `SCOTT:Foo` class schema object

- a class schema object for the inner class for static text (with "Foo" in the name, such as `SCOTT:Foo$__jsp__StaticText`)

##### Example 3

    $ publishjsp -schema SCOTT -context /webdomains/contexts/mycontext dir1/Foo.jsp

Presume `mycontext` had been created as follows:

    $ createcontext -virtualpath mywebapp /webdomains mycontext

The `publishjsp` command publishes the page to the `mycontext` servlet context, which was created with `mywebapp` specified as the context path.

The default servlet path is `dir1/Foo.jsp`.

After this command, `Foo.jsp` can be invoked as follows:

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

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

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

or:

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

Example 1 and Example 3 use different servlet contexts, but in either case what is relevant for the application-relative `include` command is that the published path of the page relative to that context is `/dir1/Foo.jsp`.

By default, `dir1` is the Java package for the page implementation class and inner class.

The following schema objects are created:

- `SCOTT:dir1/Foo` source schema object

- `SCOTT:dir1/Foo` class schema object

- a class schema object for the inner class for static text (with "Foo" in the name, such as `SCOTT:dir1/Foo$__jsp__StaticText`)

##### Example 4

    $ publishjsp -schema SCOTT -hotload -packageName mypkg dir1/Foo.jsp

This performs hotloading, uses the default servlet context, and overrides the default `dir1` package.

The context path is "/".

The `-packageName` option does not affect the servlet path, which, by default, remains `dir1/Foo.jsp`.

After this command, `Foo.jsp` can be invoked as follows:

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

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

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

or:

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

The following schema objects are created:

- `SCOTT:mypkg/Foo` source schema object

- `SCOTT:mypkg/Foo` class schema object

- a class schema object under `mypkg` for the inner class (with "Foo" in the name, such as `SCOTT:mypkg/Foo$__jsp__StaticText`)

- `SCOTT:mypkg/Foo.res` resource schema object for the static text that is normally in the inner class (the resource is hotloaded as part of `publishjsp` functionality)

#### Publishing SQLJ JSP Pages with publishjsp

This section provides an example of using `publishjsp` to translate and publish a `.sqljsp` page in Oracle8i. The page will have already been loaded as a resource schema object in a particular schema, such as `SCOTT:Foo.sqljsp`.

In addition, see "Examples: Publishing JSP Pages with publishjsp".

To review how the servlet path and context path combine in forming the URL to invoke the page, see "URLs for the Oracle Servlet Engine".

Be aware of the following for `.sqljsp` pages:

- Beyond what is created for a `.jsp` page, an additional schema objects is created--a resource schema object for the SQLJ profile. This is always a `.ser` resource schema object, as opposed to a class schema object, because there is no SQLJ `-ser2class` option when translating in the server.

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

- The generated source schema object is SQLJ source instead of Java source.

- SQLJ has very limited option support in the server.

##### Server-Side SQLJ Options

Client-side SQLJ options are not available for translation in the server (this is true in general, not just for JSP pages). Instead, there is a small set of options available through the standard Oracle8i `JAVA$OPTIONS` table as set by the `dbms_java.set_compiler_option()` stored procedure (using SQL*Plus, for example). Of these options, only the following is supported for JSP pages:

- `online`

This is a boolean option that enables online semantics-checking through the default `oracle.sqlj.checker.OracleChecker` front-end.

For more information about server-side SQLJ and semantics-checking, see the Oracle8i SQLJ Developer's Guide and Reference,

##### Example of publishjsp for SQLJ JSP Page

Following is an example of `publishjsp` usage for a `.sqljsp` page (`$` is the `sess_sh` prompt).

Notes: This example uses the `SCOTT` schema. `SCOTT` must either be the schema specified when starting `sess_sh`, or accessible from the schema specified. This example documents the schema objects that are created, although this is secondary. All that matters in invoking the JSP page is the servlet path and context path. The page implementation class schema object is automatically mapped during the `publishjsp` publishing step. The exact names of generated schema objects 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` instead of `Foo`.

    $ publishjsp -schema SCOTT dir1/Foo.sqljsp

This uses the default OSE servlet context, the context path of which is "/".

The servlet path, by default, is `dir1/Foo.sqljsp`.

After this command, `Foo.sqljsp` can be invoked as follows:

    http://host[:port]/dir1/Foo.sqljsp

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

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

or:

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

By default, `dir1` is the Java package for the page implementation class and inner class (because of the specified path in the `SCOTT` schema).

The following schema objects are created:

- `SCOTT:dir1/Foo` source schema object

- `SCOTT:dir1/Foo` class schema object

- class schema object under `dir1` for the inner class for static text (with "Foo" in the name, such as `SCOTT:dir1/Foo$__jsp__StaticText`)

- resource schema object under `dir1` for the SQLJ profile (with "Foo" in the name, such as `SCOTT:dir1/Foo_SJProfile0.ser`)

#### Unpublishing JSP Pages with unpublishjsp

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

Unlike the `unpublishservlet` command, you do not need to specify a servlet name (unless you specified one when you ran `publishjsp`). Generally, the only required input is the servlet path (sometimes referred to as the "virtual path").

Following is the general syntax:

    $ unpublishjsp [-servletName name] [-context context] [-showVersion] [-usage] [-verbose] servletpath

The `-servletName`, `-context`, `-showVersion`, `-usage`, and `-verbose` options are the same as for `publishjsp`, as described in "Overview of publishjsp Syntax and Options".

In using `unpublishjsp`, specify the values for `-servletName` and `-context` that you specified in using `publishjsp`.

As an example, here is the command to unpublish the page that was published in Example 4:

    $ unpublishjsp dir1/Foo.jsp

(Remember that the `-packageName` option specified in Example 4 has no effect on the servlet path.)

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