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

## Overview of Features and Logistics in Deployment to Oracle8i

This section is an overview of considerations and logistics in deploying a JSP application into Oracle8i to run in the Oracle Servlet Engine. The following topics are covered:

- Database Schema Objects for Java

- Oracle HTTP Server as a Front-End Web Server

- URLs for the Oracle Servlet Engine

- Static Files for JSP Applications in the Oracle Servlet Engine

- Server-Side Versus Client-Side Translation

- Overview of Hotloaded Classes in Oracle8i

### Database Schema Objects for Java

Java code that executes in the Oracle Servlet Engine uses an Oracle8i JVM inside the database. The code must be loaded into a particular database schema as one or more schema objects.

The three kinds of schema objects for Java are:

- source schema objects (corresponding to Java source files)

- class schema objects (corresponding to Java class files)

- resource schema objects (corresponding to Java resource files)

Each schema object is an individual library unit in the database. When you query the `ALL_OBJECTS` table of the schema, Java schema objects are seen as type `JAVA SOURCE`, `JAVA CLASS`, or `JAVA RESOURCE`, respectively.

See the Oracle8i Java Developer's Guide for more information.

#### Loading Java Files to Create Schema Objects

The JServer `loadjava` tool is used to load Java files into the database as schema objects. (See "Overview of the loadjava Tool".)

When you compile on the client and load the `.class` file directly, `loadjava` stores the `.class` file as a class schema object in the database.

When you load a resource file (such as a `.res` file for static JSP content or `.ser` profile file for SQLJ), `loadjava` stores the resource file as a resource schema object in the database.

When you load a `.java` (or `.sqlj`) source file, `loadjava` stores the source file as a source schema object in the database and optionally compiles it inside the database to create one or more class schema objects.

When you load a `.jsp` or `.sqljsp` page source file (for server-side translation), `loadjava` stores the page source as a resource schema object. During server-side translation (through the JServer session shell `publishjsp` command), server-side `loadjava` is invoked automatically to create source schema objects, class schema objects, and resource schema objects during translation and compilation.

(See "Tools and Commands for Translation and Deployment to Oracle8i" for an overview of the `loadjava` and session shell tools.)

#### Schema Object Full Names and Short Names

The two forms of schema object names in Oracle8i are full names and short names.

Full names are fully qualified and are used as the schema object names wherever possible. If any full name contains more than 31 characters, however, or contains characters that are illegal or cannot be converted to characters in the database character set, then the Oracle8i server converts the full name to a short name to employ as the name of the schema object, keeping track of both names and how to convert between them. If the full name contains 31 characters or less and has no illegal or inconvertible characters, then the full name is used as the schema object name.

For more information about these and about other file naming considerations, including `DBMS_JAVA` procedures to retrieve a full name from a short name and a short name from a full name, see the Oracle8i Java Developer's Guide.

#### Java Schema Object Package Determination During Loading

During loading of Java files into the database, the `loadjava` tool uses the following logic to determine the package for Java schema objects it creates:

- For source schema objects (created from`.java` and `.sqlj` files) and class schema objects (created from `.class` files or by compiling `.java` files), the schema package is determined by any package information in the Java code.

  For example, a class `Foo` that specifies the package `dir1.dir2` and is being loaded into the `SCOTT` schema will be stored in the schema as follows:

      SCOTT:dir1/dir2/Foo

  Note: When pre-translating a JSP page with the `ojspc` tool (for deployment to Oracle8i with client-side translation), you can specify the package of the generated `.java` file through the `ojspc -packageName` option.

- For resource schema objects (created from `.res` and `.ser` Java resource files, for example), the schema package is determined by any path information in the `loadjava` command line (if the Java resource file is being loaded directly) or the JAR file (if the Java resource file is being loaded as part of a JAR file).

  For example, a `.res` file being loaded into the `SCOTT` schema as `dir3/dir4/abcd.res` will be stored in a schema object as follows:

      SCOTT:dir3/dir4/abcd.res

#### Publishing Schema Objects

Any JSP page (or servlet) that will run in the Oracle Servlet Engine must be "published", a process that makes its executable Java code (the class schema objects) accessible through entries in the JServer JNDI namespace.

Publishing the JSP page links its page implementation class schema object to a servlet path (and optionally to a non-default servlet context path). The servlet path (and context path, if applicable) becomes part of the URL that an end-user would specify to access and execute the page. See "URLs for the Oracle Servlet Engine" for more information.

To publish a JSP page, use the Oracle8i session shell `publishjsp` command for the "deployment with server-side translation" scenario, or the session shell `publishservlet` command for the "deployment with client-side translation" scenario. See "Translating and Publishing JSP Pages in Oracle8i (Session Shell publishjsp)" or "Publishing Translated JSP Pages in Oracle8i (Session Shell publishservlet)".

### Oracle HTTP Server as a Front-End Web Server

JSP pages and servlets running in the Oracle Servlet Engine are typically accessed through the Oracle HTTP Server (powered by Apache) and its `mod_ose` module, although it is possible to use OSE itself as the Web server.

For more information about the role of the Oracle HTTP Server and `mod_ose`, see "Role of the Oracle HTTP Server, Powered by Apache".

### URLs for the Oracle Servlet Engine

As with servlet URLs in general, URLs to invoke JSP pages running in the Oracle Servlet Engine are formed by a combination of two components (in addition to the hostname and port):

- the context path of the servlet context in OSE, as determined when the servlet context was created

- the servlet path of the JSP page in OSE (often referred to as the "virtual path"), as determined when the JSP page was published

The context path for the OSE default context, `/webdomains/contexts/default`, is simply:

    /

The context path for any other OSE servlet context you create, which you accomplish using the Oracle8i session shell `createcontext` command, is whatever you specify in the `createcontext -virtualpath` option. (It is conventional, but not required, to specify that the context path be the same as the context name.)

Note: The `-virtualpath` option is required whenever you execute the `createcontext` command.

For general information about the session shell `createcontext` command, see the Oracle8i Java Tools Reference. For an overview of the Oracle8i session shell, see "Overview of the sess_sh Session Shell Tool".

The servlet path (JSP page "virtual path") is determined by how you publish the JSP page, as follows:

- If you use the session shell `publishjsp` command (for server-side translation), then it is determined by the `publishjsp -virtualpath` option, or else is the same as the specified schema path by default.

- If you use the session shell `publishservlet` command (after client-side translation), then it is determined by the `publishservlet -virtualpath` option (which you must specify when you use `publishservlet` for a JSP page).

See "Translating and Publishing JSP Pages in Oracle8i (Session Shell publishjsp)" or "Publishing Translated JSP Pages in Oracle8i (Session Shell publishservlet)".

##### Example 1

As an example, consider a JSP page that is published to the OSE default context with a servlet path (virtual path), as follows:

    mydir/mypage.jsp

This page is accessed as follows:

    http://host[:port]/mydir/mypage.jsp

You can access it from another page in the application, say `mydir/mypage2.jsp`, in either of the following ways (the first is a page-relative path; the second is an application-relative path):

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

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

##### Example 2

Now consider a servlet context that is created as follows (`$` is the session shell prompt):

    $ createcontext -virtualpath mycontext /webdomains mycontext

This does the following:

- It creates the servlet context `/webdomains/contexts/mycontext` (all servlet contexts in the `/webdomains` domain go under `/webdomains/contexts`).

- It specifies the context path to be the same as the context name (`mycontext`).

If `mydir/mypage.jsp` is published to the `mycontext` servlet context, it is accessed as follows:

    http://host[:port]/mycontext/mydir/mypage.jsp

You can access it from another page in the application, say `mydir/mypage2.jsp`, in either of the following ways (the first is a page-relative path; the second is an application-relative path):

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

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

The syntax for the dynamic `jsp:include` statements is the same as in Example 1. Even though a different servlet context is used, the path of the pages relative to the context is unchanged.

##### Example 3

Now consider a servlet context that is created as follows (`$` is the session shell prompt):

    $ createcontext -virtualpath mywebapp /webdomains mycontext

This does the following:

- It creates the servlet context `/webdomains/contexts/mycontext` as in Example 2.

- However, it defines a context path, `mywebapp`, that is different from the context name. It is this context path, not the context name, that is used in the URL.

In this case, if `mydir/mypage.jsp` is published to the `mycontext` servlet context, it is accessed as follows:

    http://host[:port]/mywebapp/mydir/mypage.jsp

You can access it from another page in the application, say `mydir/mypage2.jsp`, in either of the following ways (the first is a page-relative path; the second is an application-relative path):

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

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

### Static Files for JSP Applications in the Oracle Servlet Engine

This section describes the required placement of static files, such as HTML files, that are used in a JSP application that runs in the Oracle Servlet Engine.

The information in this section is independent of whether the Oracle HTTP Server (powered by Apache) is used as a front-end Web server for OSE, or OSE is used directly.

#### Files for Dynamic Includes and Forwards

Static files that are dynamic `include` or `forward` targets (`jsp:include` or `jsp:forward`) in a JSP application running in the Oracle Servlet Engine must be manually moved or copied to the OSE doc root directory corresponding to the servlet context of the application. When you create an OSE servlet context (using the session shell `createcontext` command), you specify a doc root directory through the `createcontext -docroot` option. Each OSE doc root directory is linked to the JServer JNDI namespace.

OSE doc root directories are outside the database. The JNDI lookup mechanism for static files is a front-end for the file system of the server where the database resides.

The doc root for the OSE default servlet context, `/webdomains/contexts/default`, is the following:

    $ORACLE_HOME/jis/public_html

Whenever you create an additional servlet context with the session shell `createcontext` command, you can use the `createcontext -docroot` option to specify a doc root directory. (For more information about the session shell `createcontext` command, see the Oracle8i Java Tools Reference.)

Note: If you are migrating your JSP application from Apache to OSE, it is advisable to copy static files from the Apache doc root to the OSE servlet context doc root, as opposed to mapping the OSE servlet context doc root to the Apache doc root. Mapping the doc roots may ultimately cause confusion.

#### Files for Static Includes

Any file that is statically included (through an `include` directive) by a JSP page, whether it is another JSP page or a static file such as an HTML file, must be accessible by the OracleJSP translator during translation.

In the case of a JSP application targeted for OSE, there are two translation scenarios:

- server-side translation

  This is where you load a `.jsp` file into the database as a Java resource, then use `publishjsp` to invoke the OracleJSP translator in the server. (See "Deployment to Oracle8i with Server-Side Translation".)

  In this case, static files must be loaded into the database beforehand, using `loadjava`, as resource schema objects.

- client-side translation

  This is where you translate a `.jsp` file on the client using `ojspc` and load the generated components into the database.

  In this case, static files do not have to be in the server at all. They only have to be accessible by `ojspc` on the client during translation. (For application-relative static `include` directives, see the discussion of the `ojspc -appRoot` option under "Option Descriptions for ojspc".)

### Server-Side Versus Client-Side Translation

Developers who are deploying their JSP pages to Oracle8i to run in the Oracle Servlet Engine can translate either in the server or on the client.

Deployment with server-side translation requires two steps:

1. Run `loadjava` to load the JSP page source (`.jsp` or `.sqljsp` file) into Oracle8i as a resource schema object. (You must also load any required Java classes or other required JSP pages.)

2. Run the session shell `publishjsp` command. This will automatically accomplish the following:

   - The JSP page source is translated into Java code for the page implementation class (first producing a SQLJ source file and invoking the SQLJ translator in the case of a SQLJ JSP page).

   - The Java code is compiled into one or more class files.

   - The page implementation class is optionally hotloaded (if you specified the `publishjsp -hotload` option).

   - The page implementation class is published for execution in the database.

     This step also produces source schema objects, class schema objects, and resource schema objects for all generated `.java` files (and `.sqlj` files for `.sqljsp` pages), `.class` files, and resource files, respectively.

See "Deployment to Oracle8i with Server-Side Translation" for more information.

Deployment with client-side translation requires three or, optionally, four steps:

1. Run the OracleJSP pre-translation tool, `ojspc`. This accomplishes the following:

   - The JSP page source is translated into Java code for the page implementation class. (In the case of a SQLJ JSP page, `ojspc` first produces a SQLJ source file then invokes the SQLJ translator to produce Java code.)

   - A Java resource file is optionally produced for static text, depending on the `ojspc -extres` and `-hotload` options.

   - The Java code is compiled into its class files.

2. Run the Oracle8i `loadjava` utility to load the class files and any resource files into Oracle8i as class schema objects and resource schema objects.

3. Optionally hotload the classes (if you enabled the `ojspc -hotload` option during translation) by using the Oracle8i session shell `java` command to execute the `main()` method of the page implementation class.

4. Run the session shell `publishservlet` command to publish the page implementation classes for execution in the database.

See "Deployment to Oracle8i with Client-Side Translation" for more information.

If you are using Oracle JDeveloper, you may find it more convenient to translate on the client using the OracleJSP translator provided with JDeveloper and then deploy the resulting classes and resources, as in steps 2, 3, and 4.

If you are not using JDeveloper, however, translating in the server is likely to be more convenient, because the session shell `publishjsp` command combines translation, optional hotloading, and publishing into a single step.

In addition, either of the following situations may dictate the need to translate in the server:

- if required libraries are not available on the client

- if you want to compile against the exact set of classes that will be used at runtime

### Overview of Hotloaded Classes in Oracle8i

Oracle8i JServer offers a feature known as hotloading classes, for more efficient use of `static final` variables (constants). This becomes relevant whenever the hotloaded classes might be used by multiple concurrent users.

A separate JVM is invoked for each JServer database session. Normally each session gets its own copy of all `static final` variables in its session space or, in the case of literal strings, in a hashtable known as the intern table in shared memory. Use of literal strings in the intern table is synchronized across sessions.

The processing of literal strings is especially relevant to JSP pages. By default (without hotloading), the static text in a JSP page is ultimately represented as literal strings.

Note: This section refers to the OracleJSP pre-translation tool (`ojspc`), the Oracle session shell tool (`sess_sh`), and the session shell `publishjsp` command. For an overview of these tools, see "Tools and Commands for Translation and Deployment to Oracle8i".

#### Enabling and Accomplishing Hotloading

The ability to hotload a JSP page is enabled during translation, through the `ojspc` `-hotload` option (for client-side translation) or the `publishjsp` `-hotload` option (for server-side translation).

Enabling the `-hotload` option directs the OracleJSP translator to do the following:

- It generates code in the page implementation class to allow hotloading, by creating a hotloading method and a `main()` method that invokes the hotloading method.

- It writes static text to a Java resource file. (Otherwise, static text is written to an inner class of the page implementation class.)

The hotloading itself is accomplished as follows:

- For deployment with client-side translation, you must hotload as an extra deployment step. After translating with the `ojspc -hotload` option enabled and loading the page into the database, and before publishing the page, you must use the session shell `java` command to invoke the `main()` method of the page implementation class. Details of the process are discussed in "Deployment to Oracle8i with Client-Side Translation".

- For deployment with server-side translation, hotloading is accomplished automatically as part of `publishjsp` functionality when you enable the `publishjsp -hotload` option.

The act of hotloading a page implementation class, either directly through the session shell `java` command or indirectly through the `publishjsp` command, actually just makes the inner class static text shareable among multiple JVMs in the database.

#### Features and Advantages of Hotloading

Hotloading classes results in the following logistical features and advantages:

- The translator generates code to read the Java resource containing the static text in static initializers, to initialize the `char` arrays representing static text.

- During hotloading, each hotloaded inner class is initialized only once, and static JSP text is converted into static Java `char` arrays only once.

  These `char` arrays, instead of being stored in the synchronized intern table, are stored elsewhere in a global area that is shared across all sessions without synchronization (which is feasible because of the knowledge that none of the variables will change).

Hotloading, by avoiding synchronization and other costly overhead, can significantly improve the runtime performance and scalability of JSP pages executed in the Oracle Servlet Engine. Furthermore, when a hotloaded class is referenced, the class initializer is not rerun. The session has instant access to the literal strings and other `static final` variables.

In addition to allowing better performance of individual JSP pages, hotloading reduces overall CPU usage of the server.

Note: JSP pages that will not be used by multiple users concurrently, or small JSP pages with few literal strings, may have little or no performance improvement from hotloading.

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