JSP Translation and Deployment

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

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:

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

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.
Run the Oracle8i loadjava utility to load the class files and any resource files into Oracle8i as class schema objects and resource schema objects.
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.
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.