6
JSP Translation and Deployment

This chapter primarily discusses considerations and procedures for deploying JSP applications to the Oracle9i database or middle-tier database cache to run in the Oracle9i Servlet Engine. It also describes general OracleJSP translation features and briefly discusses deployment in other environments, particularly the Apache/JServ environment used by the Oracle9i Application Server.

The following topics are covered:

Functionality of the OracleJSP Translator

JSP translators generate standard Java code for a JSP page implementation class. This class is essentially a servlet class wrapped with features for JSP functionality.

This section discusses general functionality of the OracleJSP translator, focusing on its behavior in on-demand translation environments such as Apache/JServ, which is included with the Oracle9i Application Server. The following topics are covered:

Generated Code Features
Generated Package and Class Names (On-Demand Translation)
Generated Files and Locations (On-Demand Translation)

Sample Page Implementation Class Source

Important:

Implementation details in this section regarding package and class naming, file and directory naming, output file locations, and generated code are for illustrative purposes. The precise details apply to OracleJSP 1.1.x releases only and are subject to change from release to release.

You must pre-translate JSP pages targeted for the Oracle9i Servlet Engine, either as a result of running the session shell publishjsp command (for deployment with server-side translation), by running the ojspc pre-translation tool directly (for deployment with client-side translation), or by using Oracle WAR deployment. In any case, there are some differences in functionality compared with the discussion in this section, such as in placement of output files. See "Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)" and "The ojspc Pre-Translation Tool" for information about the first two scenarios. For information about Oracle WAR deployment, see the Oracle9i Servlet Engine Developer's Guide.

Generated Code Features

This section discusses general features of the page implementation class code that is produced by the OracleJSP translator in translating JSP source (.jsp and .sqljsp files).

Features of Page Implementation Class Code

When the OracleJSP translator generates servlet code in the page implementation class, it automatically handles some of the standard programming overhead. For both the on-demand translation model and the pre-translation model, generated code automatically includes the following features:

It extends a wrapper class (oracle.jsp.runtime.HttpJsp) provided by the OracleJSP container that implements the standard javax.servlet.jsp.HttpJspPage interface (which extends the more generic javax.servlet.jsp.JspPage interface, which in turn extends the standard javax.servlet.Servlet interface).
It implements the _jspService() method specified by the HttpJspPage interface. This method, often referred to generically as the "service" method, is the central method of the page implementation class. Code from any Java scriptlets and expressions in the JSP page is incorporated into this method implementation.
It includes code to request an HTTP session, unless your JSP source code specifically sets session=false (which can be done in a page directive).

For introductory information about key JSP and servlet classes and interfaces, see Appendix B, "Servlet and JSP Technical Background".

Inner Class for Static Text

The service method, _jspService(), of the page implementation class includes print commands--out.print() calls on the implicit out object--to print any static text in the JSP page. The OracleJSP translator, however, places the static text itself in an inner class within the page implementation class. The service method out.print() statements reference attributes of the inner class to print the text.

This inner class implementation results in an additional .class file when the page is translated and compiled. In a client-side pre-translation scenario (usually for deployment to Oracle9i), be aware this means there is an extra .class file to deploy.

The name of the inner class will always be based on the base name of the .jsp file or .sqljsp file. For mypage.jsp, for example, the inner class (and its .class file) will always include "mypage" in its name.

Note:

The OracleJSP translator can optionally place the static text in a Java resource file, which is advantageous for pages with large amounts of static text. (See "Workarounds for Large Static Content in JSP Pages".) You can request this feature through the OracleJSP external_resource configuration parameter for on-demand translation, or the ojspc -extres option for pre-translation. Enabling hotloading, in deployment to Oracle9i, also results in the static text going into a resource file.

Even when static text is placed in a resource file, the inner class is still produced, and its .class file must be deployed. (This is only noteworthy if you are in a client-side pre-translation scenario.)

General Conventions for Output Names

The OracleJSP translator follows a consistent set of conventions in naming output classes, packages, files and directories (and, in the case of deployment to the Oracle9i database or database cache, in naming schema paths). However, this set of conventions and other implementation details may change from release to release.

One fact that is not subject to change is that the base name of a JSP page will be included intact in output class and file names as long as it does not include special characters. For example, translating MyPage123.jsp will always result in the string "MyPage123" being part of the page implementation class name, Java source file name, and class file name.

In OracleJSP release 1.1.2.x (as well as some previous releases), the base name is preceded by an underscore ("_"). Translating MyPage123.jsp results in page implementation class _MyPage123 in source file _MyPage123.java, which is compiled into _MyPage123.class.

Similarly, where path names are used in creating Java package names (and schema path names for Oracle9i), each component of the path is preceded by an underscore. Translating /jspdir/myapp/MyPage123.jsp, for example, results in class _MyPage123 being in the following package:

_jspdir._myapp

The package name is used in creating directories for output .java and .class files, so the underscores are also evident in output directory names. For example, in translating a JSP page in the directory htdocs/test, the OracleJSP translator by default will create directory htdocs/_pages/_test for the page implementation class source.

Note:

All output directories are created under the standard _pages directory by default, as described in"Generated Files and Locations (On-Demand Translation)". You can change this behavior, however, through the page_repository_root configuration parameter, described in "OracleJSP Configuration Parameters (Non-OSE)", or the ojspc -d and -srcdir options, described in "Option Descriptions for ojspc".

If special characters are included in a JSP page name or path name, the OracleJSP translator takes steps to ensure that no characters that would be illegal in Java appear in the output class, package, and file names. For example, translating My-name_foo12.jsp results in _My_2d_name__foo12 being the class name, in source file _My_2d_name__foo12.java. The hyphen is converted to a string of alpha-numeric characters. (An extra underscore is also inserted before "foo12".) In this case, you can only be assured that alphanumeric components of the JSP page name will be included intact in the output class and file names. For example, you could search for "My", "name", or "foo12".

These conventions are demonstrated in examples provided later in this section and later in this chapter.

Generated Package and Class Names (On-Demand Translation)

Although the Sun Microsystems JavaServer Pages Specification, Version 1.1 defines a uniform process for parsing and translating JSP text, it does not describe how the generated classes should be named--that is up to each JSP implementation.

This section describes how OracleJSP creates package and class names when it generates code during translation.

Note:

For information about general conventions used by OracleJSP in naming output classes, packages, files, and schema paths, see "General Conventions for Output Names"

Package Naming

In an on-demand translation scenario, the URL path that is specified when the user requests a JSP page--specifically, the path relative to the doc root or application root--determines the package name for the generated page implementation class. Each directory in the URL path represents a level of the package hierarchy.

It is important to note, however, that generated package names are always lowercase, regardless of the case in the URL.

Consider the following URL as an example:

http://host[:port]/HR/expenses/login.jsp

In OracleJSP release 1.1.2.x, this results in the following package specification in the generated code (implementation details are subject to change in future releases):

package _hr._expenses;

No package name is generated if the JSP page is at the doc root or application root directory, where the URL is as follows:

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

Class Naming

The base name of the .jsp file (or .sqljsp file) determines the class name in the generated code.

Consider the following URL example:

http://host[:port]/HR/expenses/UserLogin.jsp

In OracleJSP 1.1.2.x, this yields the following class name in the generated code (implementation details are subject to change in future releases):

public class _UserLogin extends ...

Be aware that the case (lowercase/uppercase) that end users type in the URL must match the case of the actual .jsp or .sqljsp file name. For example, they can specify UserLogin.jsp if that is the actual file name, or userlogin.jsp if that is the actual file name, but not userlogin.jsp if UserLogin.jsp is the actual file name.

In OracleJSP release 1.1.2.x, the translator determines the case of the class name according to the case of the file name. For example:

UserLogin.jsp results in class _UserLogin.
Userlogin.jsp results in class _Userlogin.
userlogin.jsp results in class _userlogin.

If you care about the case of the class name, then you must name the .jsp file or .sqljsp file accordingly. However, because the page implementation class is invisible to the end user, this is usually not a concern.

Generated Files and Locations (On-Demand Translation)

This section describes files that are generated by the OracleJSP translator and where they are placed. For pre-translation scenarios, ojspc places files differently and has its own set of relevant options--see "Summary of ojspc Output Files, Locations, and Related Options".

The following subsections mention several OracleJSP configuration parameters. For more information about them, see "OracleJSP Configuration Parameters (Non-OSE)" and "OracleJSP Configuration Parameter Settings".

Note:

For information about general conventions used by OracleJSP in naming output classes, packages, files, and schema paths, see "General Conventions for Output Names"

Files Generated by OracleJSP

This section considers both regular JSP pages (.jsp files) and SQLJ JSP pages (.sqljsp files) in listing files that are generated by the OracleJSP translator. For the file name examples, presume a file Foo.jsp or Foo.sqljsp is being translated.

Source files:

A.sqlj file is produced by the OracleJSP translator if the page is a SQLJ JSP page (for example, _Foo.sqlj).
A .java file is produced for the page implementation class and inner class (for example, _Foo.java). It is produced either directly by the OracleJSP translator from the.jsp file, or by the SQLJ translator from the.sqlj file if the page is a SQLJ JSP page. (The currently installed Oracle SQLJ translator is used by default, but you can specify an alternative translator or an alternative release of the Oracle SQLJ translator by using the OracleJSP sqljcmd configuration parameter.)

Binary files:

In the case of a SQLJ JSP page, one or more binary files are produced during SQLJ translation for SQLJ profiles. By default these are .ser Java resource files, but they will be .class files if you enable the SQLJ -ser2class option (through the OracleJSP sqljcmd configuration parameter). The resource file or .class file has "Foo" as part of its name.

Note:

Discussion of SQLJ profiles assumes standard SQLJ code generation. Oracle9i SQLJ provides an option, -codegen=oracle, for Oracle-specific code generation, in which case no profiles are produced.

A .class file is produced by the Java compiler for the page implementation class. (The Java compiler is javac by default, but you can specify an alternative compiler using the OracleJSP javaccmd configuration parameter.)
An additional .class file is produced for the inner class of the page implementation class. This file will have "Foo" as part of its name.

A .res Java resource file is optionally produced for the static page content (for example, _Foo.res) if the OracleJSP external_resource configuration parameter is enabled.

Note:

The exact names of generated files for the page implementation class 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.

OracleJSP Translator Output File Locations

OracleJSP uses the Web server document repository to generate or load translated JSP pages.

By default, the root directory is the Web server doc root directory (for Apache/JServ) or the servlet context root directory of the application the page belongs to.

You can specify an alternative root directory through the OracleJSP page_repository_root configuration parameter.

In OracleJSP release 1.1.2.x, generated files are placed as follows (implementation details may change in future releases):

If the .jsp (or .sqljsp) file is directly in the root directory, then OracleJSP will place generated files into a default _pages subdirectory directly under the root directory.
If the .jsp (or .sqljsp) file is in a subdirectory under the root directory, then a parallel directory structure is created under the _pages subdirectory for the generated files. Subdirectory names under the _pages directory are based on subdirectory names under the root directory.

As an example, consider an Apache/JServ environment with an htdocs doc root directory. If a .jsp file is in the following directory:
```
htdocs/subdir/test
```
then generated files will be placed in the following directory:
```
htdocs/_pages/_subdir/_test
```

Sample Page Implementation Class Source

This section uses an example to illustrate the information in the preceding sections.

Consider the following scenario:

JSP page code is in the file hello.jsp.
The page is executed in an Apache/JServ environment.

The hello.jsp file is located in the following directory:

htdocs/test

Important:

Code generation details discussed here are according to Oracle's implementation of the JSP 1.1 specification. Details may change in the future, as the result of either changes in the specification or changes in how Oracle implements aspects that are not specified.

Sample Page Source: hello.jsp

Following is the JSP code in hello.jsp:

<HTML>
<HEAD><TITLE>The Hello User JSP</TITLE></HEAD>
<BODY>
<% String user=request.getParameter("user"); %>
<H3>Welcome <%= (user==null) ? "" : user %>!</H3>
<P><B> Today is <%= new java.util.Date() %>. Have a nice day! :-)</B></P>
<B>Enter name:</B>
<FORM METHOD=get>
<INPUT TYPE="text" NAME="user" SIZE=15>
<INPUT TYPE="submit" VALUE="Submit name">
</FORM>
</BODY>
</HTML>

Sample: Generated Package and Class

Because hello.jsp is in the test subdirectory of the root directory (htdocs), OracleJSP release 1.1.2.x generates the following package name in the page implementation code:

package _test;

The Java class name is determined by the base name of the .jsp file (including case), so the following class definition is generated in the page implementation code:

public class _hello extends oracle.jsp.runtime.HttpJsp
{
   ...
}

(Because the page implementation class is invisible to the end user, the fact that its name does not adhere to Java capitalization conventions is generally not a concern.)

Sample: Generated Files

Because hello.jsp is located as follows:

htdocs/test/hello.jsp

OracleJSP release 1.1.2.x generates output files as follows (the page implementation class .java file and .class file, and the inner class .class file, respectively):

htdocs/_pages/_test/_hello.java
htdocs/_pages/_test/_hello.class
htdocs/_pages/_test/_hello$__jsp_StaticText.class

Note:

These file names are based specifically on the OracleJSP 1.1.2.x implementation; the exact details may change in future releases. All file names will always include the base "hello", however.

Sample Page Implementation Code: _hello.java

Following is the generated page implementation class Java code (_hello.java), as generated by OracleJSP release 1.1.2.x:

package _test;

import oracle.jsp.runtime.*;
import javax.servlet.*;
import javax.servlet.http.*;
import javax.servlet.jsp.*;
import java.io.*;
import java.util.*;
import java.lang.reflect.*;
import java.beans.*;


public class _hello extends oracle.jsp.runtime.HttpJsp {

  public final String _globalsClassName = null;

  // ** Begin Declarations


  // ** End Declarations

  public void _jspService(HttpServletRequest request, HttpServletResponse 
response) throws IOException, ServletException {

    /* set up the intrinsic variables using the pageContext goober:
    ** session = HttpSession
    ** application = ServletContext
    ** out = JspWriter
    ** page = this
    ** config = ServletConfig
    ** all session/app beans declared in globals.jsa
    */
    JspFactory factory = JspFactory.getDefaultFactory();
    PageContext pageContext = factory.getPageContext( this, request, response, 
null, true, JspWriter.DEFAULT_BUFFER, true);
    // Note: this is not emitted if the session directive == false
    HttpSession session = pageContext.getSession();
    if (pageContext.getAttribute(OracleJspRuntime.JSP_REQUEST_REDIRECTED, 
PageContext.REQUEST_SCOPE) != null) {
      pageContext.setAttribute(OracleJspRuntime.JSP_PAGE_DONTNOTIFY, "true", 
PageContext.PAGE_SCOPE);
      factory.releasePageContext(pageContext);
      return;
}
    ServletContext application = pageContext.getServletContext();
    JspWriter out = pageContext.getOut();
    hello page = this;
    ServletConfig config = pageContext.getServletConfig();

    try {
      // global beans
      // end global beans


      out.print(__jsp_StaticText.text[0]);
      String user=request.getParameter("user"); 
      out.print(__jsp_StaticText.text[1]);
      out.print(  (user==null) ? "" : user );
      out.print(__jsp_StaticText.text[2]);
      out.print(  new java.util.Date() );
      out.print(__jsp_StaticText.text[3]);

      out.flush();

    }
    catch( Exception e) {
      try {
        if (out != null) out.clear();
      }
      catch( Exception clearException) {
      }
      pageContext.handlePageException( e);
    }
    finally {
      if (out != null) out.close();
      factory.releasePageContext(pageContext);
    }

  }
  private static class __jsp_StaticText {
    private static final char text[][]=new char[4][];
    static {
      text[0] = 
      "<HTML>\r\n<HEAD><TITLE>The Welcome User 
JSP</TITLE></HEAD>\r\n<BODY>\r\n".toCharArray();
      text[1] = 
      "\r\n<H3>Welcome ".toCharArray();
      text[2] = 
      "!</H3>\r\n<P><B> Today is ".toCharArray();
      text[3] = 
      ". Have a nice day! :-)</B></P>\r\n<B>Enter name:</B>\r\n<FORM 
METHOD=get>\r\n<INPUT TYPE=\"text\" NAME=\"user\" SIZE=15>\r\n<INPUT 
TYPE=\"submit\" VALUE=\"Submit 
name\">\r\n</FORM>\r\n</BODY>\r\n</HTML>".toCharArray();
    }
  }
}

Overview of Features and Logistics in Deployment to Oracle9i

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

Database Schema Objects for Java

Java code that executes in the Oracle9i Servlet Engine in the Oracle9i database or database cache uses the Oracle JVM. The code must be loaded into a particular Oracle9i 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. 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 Oracle9i Java Developer's Guide for more information.

Loading Java Files to Create Schema Objects

The Oracle9i loadjava tool is used to load Java files into Oracle9i 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 Oracle9i.

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

When you load a .java (or .sqlj) source file, loadjava stores the source file as a source schema object in Oracle9i and compiles it inside the database (or database cache) 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 Oracle9i 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 Oracle9i" 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 Oracle9i 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 Oracle9i 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 Oracle9i Java Developer's Guide.

Java Schema Object Package Determination During Loading

During loading of Java files into Oracle9i, 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 pkg1.pkg2 and is being loaded into the SCOTT schema will be stored in the schema as follows:

SCOTT:pkg1/pkg2/Foo

Note:

When pre-translating a JSP page with the ojspc tool (for deployment to Oracle9i 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 pkg3/pkg4/abcd.res will be stored in a schema object as follows:
```
SCOTT:pkg3/pkg4/abcd.res
```

Publishing Schema Objects

Any JSP page (or servlet) that will run in the Oracle9i Servlet Engine must be "published", a process that makes its executable Java code (the class schema objects) accessible through entries in the Oracle9i 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 Oracle9i Servlet Engine" for more information.

To publish a JSP page, use the Oracle9i 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 Oracle9i (Session Shell publishjsp)" or "Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)".

Oracle HTTP Server as a Front-End Web Server

JSP pages and servlets running in the Oracle9i Servlet Engine are typically accessed through the Oracle HTTP Server, powered by Apache, and its mod_ose module. It is possible, however, 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 Oracle9i Servlet Engine

This section describes how URLs are formed for servlets and JSP pages that will run in the Oracle9i Servlet Engine.

Context Path and Servlet Path

As with servlet URLs in general, URLs to invoke JSP pages running in the Oracle9i 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, as determined when the JSP page was published

The servlet path is often referred to as the "virtual path" and is determined by the -virtualpath option when you publish a servlet or JSP page. Be aware, however, that it is the context path that is determined through the -virtualpath option when a servlet context is created. Do not confuse the servlet path "virtual path" and the context path "virtual path".

For every OSE Web domain there is a default context, /domain_name/contexts/default (where domain_name represents the name of the particular domain). The context path for any OSE default context is simply:

The context path for any other OSE servlet context you create, which you accomplish using the Oracle9i 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. (The -virtualpath option is required whenever you execute the createcontext command.)

Notes:

For purposes of the discussion here and elsewhere in this chapter, assume OSE single-domain mode. In this case, there is just one domain per Web service. For information about single-domain mode versus multi-domain mode and how this would affect the URL, see the Oracle9i Servlet Engine Developer's Guide.

For general information about the session shell createcontext command, see the Oracle9i Java Tools Reference. For an overview of the Oracle9i 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 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 Oracle9i (Session Shell publishjsp)" or "Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)".

OSE Ports

Each OSE Web service has a port associated with it, which an end user must specify as part of the URL if the OSE default Web service (admin) is not being used:

http://host[:port]/path

In this syntax, path is the combination of the context path and servlet path.

The port for the default admin Web service is 8080. The port for any other Web service is determined using the session shell tool addendpoint command. (See "Overview of the sess_sh Session Shell Tool" for general information about the tool. See the Oracle9i Java Tools Reference for information about the addendpoint command.)

OSE scottService

A Makefile is provided with Oracle9i to create an OSE Web service called scottService. The domain is /scottRoot, the default context is /scottRoot/contexts/default, and an additional context, /scottRoot/contexts/scottContext, is also created automatically. (Note that these are JNDI names only and are not directly related to URLs.)

The context path for the default context is:

The context path for scottContext is:

/ose

The scottService port number is 8088.

The scottRoot servlet contexts will be used in the examples in the next section and elsewhere in this chapter.

URL Examples

This section provides examples of OSE URLs, using servlet contexts of scottService as described immediately above.

Example 1

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

mydir/mypage.jsp

This page is accessed as follows:

http://host:8088/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 the scottContext servlet context, created as follows ($ is the session shell prompt):

$ createcontext -virtualpath /ose /scottRoot scottContext

This does the following:

It specifies the domain /scottRoot.
It creates the servlet context /scottRoot/contexts/scottContext (all servlet contexts in OSE go under /domain_name/contexts).
It specifies /ose as the context path.

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

http://host:8088/ose/mydir/mypage.jsp

(Note that /scottRoot and /scottRoot/contexts/scottContext are JNDI names only and are not related to the URL. It is the context path that is relevant to the URL.)

You can access the page 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.

Static Files for JSP Applications in the Oracle9i 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 Oracle9i Servlet Engine (with OSE being used as its own Web server).

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 Oracle9i 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 Oracle9i JNDI namespace. (For more information about the session shell createcontext command, see the Oracle9i Java Tools Reference.)

OSE doc root directories are outside the database (or database cache). The JNDI lookup mechanism for static files is a front-end for the file system of the server on which the database resides.

Notes:

If you are migrating your JSP application from Apache to OSE, any static files that will be dynamic include or forward targets should be copied 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.
The OSE default service, admin, has the following default servlet context:
```
/system/admin/contexts/default
```
The default servlet context has the following doc root:
```
$ORACLE_HOME/jis/public_html
```

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 three translation scenarios:

server-side translation

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

In this case, static files must be loaded 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 Oracle9i.

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".)
Oracle WAR deployment

See the Oracle9i Servlet Engine Developer's Guide for information, or "WAR Deployment" for an overview.

Server-Side Versus Client-Side Translation

Developers who are deploying their JSP pages to Oracle9i to run in the Oracle9i 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 Oracle9i 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 as a servlet for execution in Oracle9i.
  
  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 Oracle9i 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 Oracle9i loadjava utility to load the class files and any resource files into Oracle9i as class schema objects and resource schema objects.
Optionally hotload the classes (if you enabled the ojspc -hotload option during translation) by using the Oracle9i 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 Oracle9i.

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

Note:

Another possible scenario is to use Oracle WAR deployment. See the Oracle9i Servlet Engine Developer's Guide for information, or "WAR Deployment" for an overview.

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 Oracle9i

Oracle9i 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 Oracle9i session created in Java. 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 Oracle9i".

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 class and static resources into Oracle9i, and before invoking publishservlet to publish 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 Oracle9i 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 Oracle9i.

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

Tools and Commands for Translation and Deployment to Oracle9i

Oracle provides the following tools to use, as applicable, in translating JSP pages and deploying them to Oracle9i. How they are implemented depends on your operating system (such as shell scripts for Solaris or .bat files for Windows NT):

ojspc (OracleJSP pre-translation tool)
loadjava (tool for loading JSP pages or Java files into the Oracle9i database or database cache)
sess_sh (Oracle9i session shell tool)

Deployment with client-side translation requires all three tools. Pre-translate JSP pages on the client using ojspc, load the translated pages into Oracle9i using loadjava, and publish them using the session shell publishservlet command.

Deployment with server-side translation does not require ojspc. Load the untranslated JSP pages into Oracle9i using loadjava, then translate and publish them using the session shell publishjsp command.

The loadjava and sess_sh tools are general-purpose tools for the Oracle9i Java environment; ojspc is for JSP pages only.

Notes:

Another tool, the Oracle9i Accelerator, is relevant if you want to natively compile your application to run in Oracle9i. This tool, invoked as ncomp, is documented in the Oracle9i Java Tools Reference.
The tools discussed in this section are located in the [ORACLE_HOME]/bin directory.

The ojspc Pre-Translation Tool

The first step in deploying a JSP application to Oracle9i with client-side translation is to run the OracleJSP pre-translation tool, ojspc.

You will then use loadjava, introduced in the next section, to load the resulting .class files and resource files (if any) into Oracle9i as class schema objects and resource schema objects, respectively.

The following topics are covered here:

Summary of ojspc Output Files, Locations, and Related Options

Notes:

There are other possible scenarios, such as in a middle-tier environment, for using ojspc to pre-translate JSP pages. See "Use of ojspc for Pre-Translation for Non-OSE Environments".

Overview of ojspc Functionality

For a simple JSP (not SQLJ JSP) page, default functionality for ojspc is as follows:

It takes a .jsp file as an argument.
It invokes the OracleJSP translator to translate the .jsp file into Java page implementation class code, producing a .java file. The page implementation class includes an inner class for static page content.
It invokes the Java compiler to compile the .java file, producing two .class files (one for the page implementation class itself and one for the inner class).

And following is the default ojspc functionality for a SQLJ JSP page:

It takes a .sqljsp file as an argument instead of a .jsp file.
It invokes the OracleJSP translator to translate the .sqljsp file into a .sqlj file for the page implementation class (and inner class).

It invokes the Oracle SQLJ translator to translate the .sqlj file. This produces a .java file for the page implementation class (and inner class) and a SQLJ "profile" file that is, by default, a .ser Java resource file.

Note:

Discussion of SQLJ profiles assumes standard SQLJ code generation. Oracle9i SQLJ provides an option, -codegen=oracle, for Oracle-specific code generation, in which case no profiles are produced.

For information about SQLJ profiles and Oracle-specific code generation, see the Oracle9i SQLJ Developer's Guide and Reference.

It invokes the Java compiler to compile the .java file, producing two .class files (one for the page implementation class itself and one for the inner class).

Under some circumstances (see the -hotload and -extres option descriptions below), ojspc options direct the OracleJSP translator to produce a .res Java resource file for static page content instead of putting this content into the inner class of the page implementation class. However, the inner class is still created and must still be deployed with the page implementation class.

Because ojspc invokes the OracleJSP translator, ojspc output conventions are the same as for OracleJSP in general, as applicable. For general information about OracleJSP translator output, including generated code features, general conventions for output names, generated package and class names, and generated files and locations, see "Functionality of the OracleJSP Translator".

Note:

The ojspc command-line tool is a front-end utility that invokes the oracle.jsp.tool.Jspc class.

Option Summary Table for ojspc

Table 6-1 describes the options supported by the ojspc pre-translation utility. These options are further discussed in "Option Descriptions for ojspc".

The second column notes comparable or related OracleJSP configuration parameters for on-demand translation environments (such as Apache/JServ).

Note:

A boolean ojspc option is enabled by typing only the option name, not by setting it to true. Setting it to true will cause an error.

Table 6-1 Options for ojspc Pre-Translation Utility

Option	Related OracleJSP Configuration Parameters	Description	Default
-addclasspath	classpath (related, but with different functionality)	additional classpath entries for `javac`	empty (no additional path entries)
-appRoot	n/a	application root directory for application-relative static `include` directives from the page	current directory
-debug	emit_debuginfo	boolean to direct `ojspc` to generate a line map to the original `.jsp` file for debugging	false
-d	page_repository_root	location where `ojspc` should place generated binary files (`.class` and resource)	current directory
-extend	n/a	class for the generated page implementation class to extend	empty
-extres	external_resource	boolean to direct `ojspc` to generate an external resource file for static text from the `.jsp` file	false
-hotload (for OSE only)	n/a	boolean to direct `ojspc` to implement code in the page implementation class to allow hotloading	false
-implement	n/a	interface for the generated page implementation class to implement	empty
-noCompile	javaccmd	boolean to direct `ojspc` not to compile the generated page implementation class	false
-packageName	n/a	package name for the generated page implementation class	empty (generate package names per `.jsp` file location)
-S-<sqlj option>	sqljcmd	`-S` prefix followed by an Oracle SQLJ option (for `.sqljsp` files)	empty
-srcdir	page_repository_root	location where `ojspc` should place generated source files (`.java` and `.sqlj`)	current directory
-verbose	n/a	boolean to direct `ojspc` to print status information as it executes	false
-version	n/a	boolean to direct `ojspc` to display the OracleJSP version number	false

Command-Line Syntax for ojspc

Following is the general ojspc command-line syntax (assume % is a UNIX prompt):

% ojspc [option_settings] file_list

The file list can include .jsp files or .sqljsp files.

Be aware of the following syntax notes:

If multiple .jsp files are translated, they all must use the same character set (either by default or through page directive contentType settings).
Use spaces between file names in the file list.
Use spaces as separators between option names and option values in the option list.
Option names are not case sensitive, but option values usually are (such as package names, directory paths, class names, and interface names).
Enable boolean options, which are disabled by default, by typing only the option name. For example, type -hotload, not -hotload true.)

Following is an example:

% ojspc -d /myapp/mybindir -srcdir /myapp/mysrcdir -hotload MyPage.sqljsp MyPage2.jsp

Option Descriptions for ojspc

This section describes the ojspc options in more detail.

-addclasspath

(fully qualified path; ojspc default: empty)

Use this option to specify additional classpath entries for javac to use when compiling generated page implementation class source. Otherwise, javac uses only the system classpath.

Notes:

In an on-demand translation scenario, the OracleJSP classpath configuration parameter provides related, although different, functionality. See "OracleJSP Configuration Parameters (Non-OSE)".
The -addclasspath setting is also used by the SQLJ translator for SQLJ JSP pages.

-appRoot

(fully qualified path; ojspc default: current directory)

Use this option to specify an application root directory. The default is the current directory, from which ojspc was run.

The specified application root directory path is used as follows:

It is used for static include directives in the page being translated. The specified directory path is prepended to any application-relative (context-relative) paths in the include directives of the translated page.
It is used in determining the package of the page implementation class. The package will be based on the location of the file being translated relative to the application root directory. The package, in turn, determines the placement of output files. (See "Summary of ojspc Output Files, Locations, and Related Options".)

This option is necessary, for example, so included files can still be found if you run ojspc from some other directory.

Consider the following example:

You want to translate the following file:
```
/abc/def/ghi/test.jsp
```
You run ojspc from the current directory, /abc, as follows (assume % is a UNIX prompt):
```
% cd /abc
% ojspc def/ghi/test.jsp
```
The test.jsp page has the following include directive:
```
<%@ include file="/test2.jsp" %> 
```
The test2.jsp page is in the /abc directory, as follows:
```
/abc/test2.jsp 
```

This requires no -appRoot setting, because the default application root setting is the current directory, which is the /abc directory. The include directive uses the application-relative /test2.jsp syntax (note the beginning "/"), so the included page will be found as /abc/test2.jsp.

The package in this case is _def._ghi, based simply on the location of test.jsp relative to the current directory, from which ojspc was run (the current directory is the default application root). Output files are placed accordingly.

If, however, you run ojspc from some other directory, suppose /home/mydir, then you would need an -appRoot setting as in the following example:

% cd /home/mydir
% ojspc -appRoot /abc /abc/def/ghi/test.jsp

The package is still _def._ghi, based on the location of test.jsp relative to the specified application root directory.

Note:

It is typical for the specified application root directory to be some level of parent directory of the directory where the translated JSP page is located.

-d

(fully qualified path; ojspc default: current directory)

Use this option to specify a base directory for ojspc placement of generated binary files--.class files and Java resource files. (The .res files produced for static content by the -extres and -hotload options are Java resource files, as are .ser profile files produced by the SQLJ translator for SQLJ JSP pages.)

The specified path is taken simply as a file system path (not an application-relative or page-relative path).

Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. See "Summary of ojspc Output Files, Locations, and Related Options" for more information.

The default is to use the current directory (your current directory when you executed ojspc).

It is recommended that you use this option to place generated binary files into a clean directory so that you easily know what files have been produced.

Notes:

In environments such as Windows NT that allow spaces in directory names, enclose the directory name in quotes.
In an on-demand translation scenario, the OracleJSP page_repository_root configuration parameter provides related functionality. See "OracleJSP Configuration Parameters (Non-OSE)".

-debug

(boolean; ojspc default: false)

Enable this flag to instruct ojspc to generate a line map to the original .jsp file for debugging. Otherwise, line-mapping will be to the generated page implementation class.

This is useful for source-level JSP debugging, such as when using Oracle JDeveloper.

Note:

In an on-demand translation scenario, the OracleJSP emit_debuginfo configuration parameter provides the same functionality. See "OracleJSP Configuration Parameters (Non-OSE)".

-extend

(fully qualified Java class name; ojspc default: empty)

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

-extres

(boolean; ojspc default: false)

Enable this flag to instruct ojspc to place generated static content (the Java print commands that output static HTML code) into a Java resource file instead of into an inner class of the generated page implementation class.

The resource file name is based on the JSP page name. For release 1.1.2.x it will be the same core name as the JSP name (unless special characters are included in the JSP name), but with an underscore ("_") prefix and .res suffix. Translation of MyPage.jsp, for example, would create _MyPage.res in addition to normal output. The exact implementation for name generation may change in future releases, however.

The resource file is placed in the same directory as .class files.

If there is a lot of static content in a page, this technique will speed translation and may speed execution of the page. For more information, see "Workarounds for Large Static Content in JSP Pages".

Notes:

The inner class is still created and must still be deployed.
In an on-demand translation scenario, the OracleJSP external_resource configuration parameter provides the same functionality. See "OracleJSP Configuration Parameters (Non-OSE)".

-hotload

(boolean; ojspc default: false) (for OSE only)

Enable this flag to allow hotloading. This is relevant only if you will be loading the translated pages into Oracle9i to run in the Oracle9i Servlet Engine.

The -hotload flag directs ojspc to do the following:

Perform -extres functionality, writing static output to a Java resource file (see the -extres description above).
Create a main() method and a hotloading method in the generated page implementation class to allow hotloading.

For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle9i". For how to accomplish the hotloading step (once hotloading has been enabled), see "Hotloading Page Implementation Classes in Oracle9i".

Note:

To write static content to a resource file without enabling hotloading (if the page will not be running in OSE, for example), use the -extres option.

-implement

(fully qualified Java interface name; ojspc default: empty)

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

-noCompile

(boolean; ojspc default: false)

Enable this flag to direct ojspc not to compile the generated page implementation class Java source. This allows you to compile it later with an alternative Java compiler.

Notes:

In an on-demand translation scenario, the OracleJSP javaccmd configuration parameter provides related functionality, allowing you to specify an alternative Java compiler directly. See "OracleJSP Configuration Parameters (Non-OSE)".
For a SQLJ JSP page, enabling -noCompile does not prevent SQLJ translation, just Java compilation.

-packageName

(fully qualified package name; ojspc default: per .jsp file location)

Use this option to specify a package name for the generated page implementation class, using Java "dot" syntax.

Without setting this option, the package name is determined according to the location of the .jsp file relative to the current directory (from which you ran ojspc).

Consider an example where you run ojspc from the /myapproot directory, while the .jsp file is in the /myapproot/src/jspsrc directory (assume % is a UNIX prompt):

% cd /myapproot
% ojspc -packageName myroot.mypackage src/jspsrc/Foo.jsp

This results in myroot.mypackage being used as the package name.

If this example did not use the -packageName option, OracleJSP release 1.1.2.x would use _src._jspsrc as the package name, by default. (Be aware that such implementation details are subject to change in future releases.)

-S-<sqlj option> <value>

(-S followed by SQLJ option setting; ojspc default: empty)

For SQLJ JSP pages, use the ojspc -S option to pass an Oracle SQLJ option to the SQLJ translator. You can use multiple occurrences of -S, with one SQLJ option per occurrence.

Unlike when you run the SQLJ translator directly, use a space between a SQLJ option and its value (this is for consistency with other ojspc options).

For example (from a UNIX prompt):

% ojspc -S-default-customizer mypkg.MyCust -d /myapproot/mybindir MyPage.jsp

This invokes the Oracle SQLJ -default-customizer option to choose an alternative profile customizer, as well as setting the ojspc -d option.

Here is another example:

% ojspc -S-ser2class true -S-status true -d /myapproot/mybindir MyPage.jsp

This enables the SQLJ -ser2class option (to convert the profile to a .class file) and the SQLJ -status option (to display status information as the .sqlj file is translated).

Note:

As the preceding example shows, you can use an explicit true setting in enabling a SQLJ boolean option through the -S option setting. This is in contrast to ojspc boolean options, which do not take an explicit true setting.

Note the following for particular Oracle SQLJ options:

Do not use the SQLJ -encoding option; instead, use the contentType parameter in a page directive in the JSP page.
Do not use the SQLJ -classpath option if you use the ojspc -addclasspath option.
Do not use the SQLJ -compile option if you use the ojspc -noCompile option.
Do not use the SQLJ -d option if you use the ojspc -d option.
Do not use the SQLJ -dir option if you use the ojspc -srcdir option.

For information about Oracle SQLJ translator options, see the Oracle9i SQLJ Developer's Guide and Reference.

Note:

In an on-demand translation scenario, the OracleJSP sqljcmd configuration parameter provides related functionality, allowing you to specify an alternative SQLJ translator or specify SQLJ option settings. See "OracleJSP Configuration Parameters (Non-OSE)".

-srcdir

(fully qualified path; ojspc default: current directory)

Use this option to specify a base directory location for ojspc placement of generated source files--.sqlj files (for SQLJ JSP pages) and .java files.

The specified path is taken simply as a file system path (not an application-relative or page-relative path).

The default is to use the current directory (your current directory when you executed ojspc).

It is recommended that you use this option to place generated source files into a clean directory so that you conveniently know what files have been produced.

Notes:

In environments such as Windows NT that allow spaces in directory names, enclose the directory name in quotes.
In an on-demand translation scenario, the OracleJSP page_repository_root configuration parameter provides related functionality. See "OracleJSP Configuration Parameters (Non-OSE)".

-verbose

(boolean; ojspc default: false)

Enable this option to direct ojspc to report its translation steps as it executes.

The following example shows -verbose output for the translation of myerror.jsp (in this example, ojspc is run from the directory where myerror.jsp is located; assume % is a UNIX prompt):

% ojspc -verbose myerror.jsp
Translating file: myerror.jsp
1 JSP files translated successfully.
Compiling Java file: ./_myerror.java

-version

(boolean; ojspc default: false)

Enable this option for ojspc to display the OracleJSP version number and then exit.

Summary of ojspc Output Files, Locations, and Related Options

By default, ojspc generates the same set of files that are generated by the OracleJSP translator in an on-demand translation scenario and places them in or under the current directory (from which ojspc was executed).

Here are the files:

a .sqlj source file (SQLJ JSP pages only)
a .java source file
a .class file for the page implementation class
a .class file for the inner class for static text
a Java resource file (.ser) or, optionally, a .class file for the SQLJ profile (SQLJ JSP pages only)

This assumes standard SQLJ code generation. Oracle-specific SQLJ code generation produces no profiles.
optionally, a Java resource file (.res) for the static text of the page

For more information about files that are generated by the OracleJSP translator, see "Generated Files and Locations (On-Demand Translation)".

To summarize some of the commonly used options described under "Option Descriptions for ojspc", you can use the following ojspc options to affect file generation and placement:

-appRoot to specify an application root directory
-srcdir to place source files in a specified alternative location
-d to place binary files (.class files and Java resource files) in a specified alternative location
-noCompile to not compile the generated page implementation class source (as a result of this, no .class files are produced)

In the case of SQLJ JSP pages, translated .java files are still produced, but not compiled.
-extres to put static text into a Java resource file
-hotload to put static text into a Java resource file and to enable hotloading (relevant only for pages targeting the Oracle9i Servlet Engine)
-S-ser2class (SQLJ -ser2class option, for SQLJ JSP pages only) to generate the SQLJ profile in a .class file instead of a .ser Java resource file

For output file placement, the directory structure underneath the current directory (or directories specified by the -d and -srcdir options, as applicable) is based on the package. The package is based on the location of the file being translated relative to the application root, which is either the current directory or the directory specified in the -appRoot option.

For example, presume you run ojspc as follows (presume % is a UNIX prompt):

% cd /abc
% ojspc def/ghi/test.jsp

Then the package is _def._ghi and output files will be placed in the directory /abc/_def/_ghi, where the _def/_ghi subdirectory structure is created as part of the process.

If you specify alternate output locations through the -d and -srcdir options, a _def/_ghi subdirectory structure is created under the specified directories.

Now presume ojspc is run from some other directory, as follows:

% cd /home/mydir
% ojspc -appRoot /abc /abc/def/ghi/test.jsp

The package is still _def._ghi, according to the location of test.jsp relative to the specified application root. Output files will be placed in the directory /home/mydir/_def/_ghi or in a _def/_ghi subdirectory under locations specified through the -d and -srcdir options. In either case, the _def/_ghi subdirectory structure is created as part of the process.

Notes:

It is advisable that you run ojspc once for each directory of your JSP application, so files in different directories can be given different package names, as appropriate.

Overview of the loadjava Tool

The loadjava command-line tool is supplied with Oracle9i to create schema objects from Java files and load them into a specified Oracle9i schema.

For information beyond what is provided here, and for information about the associated dropjava tool (for removing Java source, class, and resource schema objects from Oracle9i), see the Oracle9i Java Tools Reference.

Generally speaking (not for JSP applications in particular), a Java developer can compile Java source on the client and then load the resulting class files, or can load Java source and have it compiled in Oracle9i automatically by the server-side compiler. In the first case, only class schema objects are created. In the second case, both source schema objects and class schema objects are created. In either case, the developer can also load Java resource files, creating resource schema objects.

The loadjava tool accepts source files, class files, resource files, JAR files, and ZIP files on the command line. Source files and class files cannot be loaded simultaneously, however. A JAR file, ZIP file, or loadjava command line can contain source files or class files, but not both. (In either case, resource files can be included.)

A JAR or ZIP file is opened and processed, with each file within the JAR or ZIP file resulting in one or more schema objects.

For OracleJSP, use loadjava as follows:

For client-side translation, you will have already translated your JSP pages using ojspc, which, by default, also compiles the translated Java source. Then use loadjava to load the resulting .class files and any resource files (the ojspc -hotload option, for example, produces a resource file), typically all bundled into a JAR file.

Alternatively, you can load the translated .java file instead of the compiled .class files. You can have the server-side compiler compile the .java file as it is being loaded.
For server-side translation, use loadjava to load untranslated .jsp files, typically bundled into a JAR file, as resource schema objects. (They will be translated and published later, in the server, as a result of the session shell publishjsp command.)

Following is the complete loadjava option syntax. Brackets, {...}, are not part of the syntax. They are used to surround two possible option formats that are followed by option input.

loadjava {-user | -u} user/password[@database] [options] 
file.java | file.class | file.jar | file.zip | file.sqlj | resourcefile  
  [-debug]
  [-d | -definer]
  [{-e | -encoding} encoding_scheme]
  [-f | -force]
  [{-g | -grant} user [, user]...]
  [-o | -oci8] 
  [ -order ]
  [-noverify]
  [-r | -resolve] 
  [{-R | -resolver} "resolver_spec"]
  [{-S | -schema} schema] 
  [ -stdout ]
  [-s | -synonym]
  [-t | -thin] 
  [-v | -verbose]

Of particular significance are the -user and -resolve options (which can be abbreviated to -u and -r, respectively). Use the -user option to specify the schema name and password. Use the -resolve option to specify whether loadjava is to compile (if applicable) and resolve external references in the classes you are loading, after all classes on the command line have been loaded.

If you are loading a .java source file that you want compiled by the server-side compiler during loading, you must enable the -resolve option.

Following is an example for a client-side translation scenario where the JSP page has already been translated and compiled using the ojspc utility, producing file _HelloWorld.class and another .class file for the page implementation inner class (with a name that starts with "_HelloWorld"). Assume % is a UNIX prompt:

% loadjava -u scott/tiger -r _HelloWorld*.class

Or you can bundle the files into a JAR file:

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

The loadjava -v (-verbose) option, which provides detailed status reporting as loading progresses, is especially useful when you are loading a number of files or compiling in the server.

The following example is also for a client-side translation scenario (_HelloWorld.java is the JSP translator output), but where you have elected to skip the compilation step on the client (using the ojspc -noCompile option) and instead have the server-side compiler handle the compilation:

% loadjava -v -u scott/tiger -r _HelloWorld.java

The following example is for a server-side translation scenario:

% loadjava -u scott/tiger -r HelloWorld.jsp

Overview of the sess_sh Session Shell Tool

The sess_sh (session shell) tool is provided with Oracle9i as an interactive interface to the session namespace of an Oracle9i instance. You specify connection arguments when you start sess_sh. It then presents you with its $ prompt to indicate that it is ready for commands.

The session shell tool has many commands you can run from the $ prompt, each of which may have its own set of options. For OracleJSP developers, the publishservlet and unpublishservlet commands (for deployment with client-side translation), publishjsp and unpublishjsp commands (for deployment with server-side translation), and createcontext command (for creating OSE servlet contexts) are of primary interest.

Following are the key sess_sh syntax elements for starting the tool:

sess_sh -user user -password password -service serviceURL

The -user parameter specifies the user name of the schema.
The -password parameter specifies the password for the specified user name.
The -service parameter specifies the URL of the database or database cache whose session namespace is to be "opened" by sess_sh. The serviceURL parameter should have one of the three following forms:
```
sess_iiop://host:port:sid
jdbc:oracle:type:spec
http://host[:port]
```
Following are some general examples:
```
sess_iiop://localhost:2481:orcl
jdbc:oracle:thin:@myhost:1521:orcl
http://localhost:8000
```

Here is an example of a sess_sh command line:

% sess_sh -user SCOTT -password TIGER -service jdbc:oracle:thin:@myhost:5521:orcl

After starting sess_sh, you will see its command prompt:

In addition to publish object commands, such as publishservlet and publishjsp, the session shell tool offers shell commands that give the session namespace much of the "look and feel" of a UNIX file system as seen from one of the UNIX shells (such as the C shell). For example, the following sess_sh command displays the published objects and publishing contexts in the /alpha/beta/gamma publishing context (publishing contexts are nodes in the session namespace, analogous to directories in a file system):

$ ls /alpha/beta/gamma

As mentioned previously, key sess_sh commands for OracleJSP developers include the following:

$ publishjsp ...
$ unpublishjsp ...
$ publishservlet ...
$ unpublishservlet ...
$ createcontext ...

For information about the publishservlet and unpublishservlet commands, see "Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)". For information about the publishjsp and unpublishjsp commands, see "Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)".

Each session shell command has a -describe option to describe its operation, a -help option to summarize its syntax, and a -version option to show its version number.

Note:

This document provides only abbreviated discussion of sess_sh syntax and options. It presents only the simplest invocation and usage of the tool.

Beyond what is presented here, for example, commands can be specified within quotes on the sess_sh command line instead of at the $ prompt.

There are also top-level options to connect with plain IIOP instead of the default session IIOP, to specify a role, to connect to the database or database cache with SSL server authentication, and to use a service name instead of an SID in the URL.

For complete information about the sess_sh tool, see the Oracle9i Java Tools Reference.

Deployment to Oracle9i with Server-Side Translation

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

The steps are as follows:

Use loadjava to load untranslated JSP page or SQLJ JSP page source files into Oracle9i.
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 Oracle9i (loadjava)

As the first step for deployment with server-side translation, use the Oracle loadjava tool to load untranslated .jsp or .sqljsp files into Oracle9i 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 Oracle9i 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 Oracle9i 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 Oracle9i:

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

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

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 Oracle9i (Session Shell publishjsp)

In the scenario of deployment with server-side translation, the translation (.jsp or .sqljsp to .java), compilation (.java to .class), hotloading (if enabled), and publishing all occur as the result of executing the Oracle9i session shell publishjsp command. See "Overview of the sess_sh Session Shell Tool" for how to start the session shell and connect to Oracle9i.

Run publishjsp after you have loaded a .jsp (or .sqljsp) file into Oracle9i 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 Oracle9i 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 Oracle9i. 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:

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

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 a required parameter, along with any relevant schema path information.

In addition, you should always specify a -context setting.

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.

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

Important:

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

Following are the option descriptions:

-context context

Use this option to specify a servlet context in the Oracle9i Servlet Engine. The context path of this servlet context becomes part of the URL used to invoke the page.

Any specified context should be under the appropriate Web domain, as follows:

/domain_name/contexts/context_name

(Where domain_name represents the name of the particular domain.)

Important:

Always specify a -context setting.
Remember 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.

-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 based on 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 1.1.2.x (Be aware that implementation details are subject to change in future releases.)

Important:

If you use the publishjsp -servletName option, you must also use the unpublishjsp -servletName option if you unpublish the page. Therefore, when you publish the page, it is advisable to use the publishjsp -verbose option to verify the resulting servlet name.

-packageName name

You can use this option to specify a package name for the generated page implementation class; otherwise, it is based on 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.

Also be aware that if no -servletName setting is specified, the -packageName setting is also reflected in the servlet name. Consider the following example:

$ publishjsp -packageName mytestpkg -verbose simple1_a.jsp

This results in the following servlet name:

mytestpkg._simple1__a.jsp

However, if a -servletName setting is specified, its effect on the servlet name overrides the effect of the -packageName setting.

Important:

If you use the publishjsp -packageName option, you must use the unpublishjsp -servletName option if you unpublish the page. Therefore, when you publish the page, it is advisable to use the publishjsp -verbose option to verify the resulting servlet name.

-hotload

Enable this flag to enable and perform hotloading. This results in the following steps being performed automatically 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 Oracle9i 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 Oracle9i".
-stateless

This is a boolean option that tells the Oracle9i 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 Oracle9i Servlet Engine Developer's Guide.
-verbose

Set this option to true to direct publishjsp to report the translation steps as it executes.
-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.
-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))" ...
```

Examples: Publishing JSP Pages with publishjsp

This section provides examples of using publishjsp to translate and publish .jsp pages in Oracle9i. 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 Oracle9i Servlet Engine".

Example Notes

These notes apply to the examples that follow:

The 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. Note that default package names and output schema object names have underscores in them, even though the original JSP resource schema object name and resulting servlet path do not have underscores. Again, this is secondary and does not impact the user.
Application-relative and page-relative syntax for dynamic jsp:include and jsp:forward statements inside Oracle9i 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.
$ is the sess_sh prompt.

Example 1

$ publishjsp -schema SCOTT dir1/Foo.jsp

This uses the default servlet context of the relevant OSE Web domain, so the context path is "/".

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

$ publishjsp -schema SCOTT -context /scottRoot/contexts/scottContext Foo.jsp

Presume scottContext had been created as follows:

$ createcontext -virtualpath /ose /scottRoot scottContext

The publishjsp command publishes the page to the scottContext servlet context, which was created with /ose specified as the context path.

The default servlet path is simply Foo.jsp.

After this command, Foo.jsp can be invoked as follows (assume port 8088 for the Web service):

http://host:8088/ose/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 /scottRoot/contexts/scottContext dir1/Foo.jsp

Presume scottContext had been created as follows:

$ createcontext -virtualpath /ose /scottRoot scottContext

The publishjsp command publishes the page to the scottContext servlet context, which was created with /ose specified as the context path.

The default servlet path is dir1/Foo.jsp.

After this command, Foo.jsp can be invoked as follows (assume port 8088 for the Web service):

http://host:8088/ose/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 under _dir1 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 of the relevant OSE Web domain, 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 Oracle9i. 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 Oracle9i Servlet Engine".

Be aware of the following for .sqljsp pages:

Beyond what is created for a .jsp page, an additional schema object 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.

Note:

Discussion of SQLJ profiles assumes standard SQLJ code generation. Oracle9i SQLJ provides an option, -codegen=oracle, for Oracle-specific code generation, in which case no profiles are produced.

For information about SQLJ profiles and Oracle-specific code generation, see the Oracle9i 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 Oracle9i JAVA$OPTIONS table. These options can be set through 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 Oracle9i SQLJ Developer's Guide and Reference.

Example of publishjsp for SQLJ JSP Page

This section presents an example of publishjsp usage for a .sqljsp page ($ is the sess_sh prompt). Be aware of the following:

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. Note that default package names and output schema object names have underscores in them, even though the original SQLJSP resource schema object name and resulting servlet path do not have underscores. Again, this is secondary and does not impact the user.
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.

Here is the example:

$ 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, based on 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)
a resource schema object under _dir1 for the SQLJ profile, if applicable (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 Oracle9i JNDI namespace. This does not, however, remove the page implementation class schema object from Oracle9i.

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

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

$ unpublishjsp dir1/Foo.jsp

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, remember the following:

If you used the publishjsp -context option in publishing the page, use the unpublishjsp -context option with the same setting when you unpublish the page.

If you used the publishjsp -servletName or -packageName option in publishing a page, you must use the unpublishjsp -servletName option to specify the resulting servlet name when you unpublish the page. For information about how these publishjsp options affect the servlet name, see the option descriptions in "Overview of publishjsp Syntax and Options".

Note:

If you use the publishjsp -schemaName or -packageName option in publishing a JSP page, it is advisable to also use the -verbose option to verify the servlet name for later use in unpublishjsp.

Deployment to Oracle9i with Client-Side Translation

This section describes the steps for deployment to Oracle9i 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 Oracle9i--.class files (or, optionally, .java or .sqlj files instead) and any Java resource files resulting from the page translation.
Optionally "hotload" the pages in Oracle9i (if hotloading was enabled during translation). See "Overview of Hotloaded Classes in Oracle9i" 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 Oracle9i 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 Oracle9i 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 Oracle9i

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.

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
_Foo$__jsp_StaticText.class for the inner class for static content

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, as follows:

% 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
_Foo$__jsp_StaticText.class for the inner class for static content

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)

Note:

Discussion of SQLJ profiles assumes standard SQLJ code generation. Oracle9i SQLJ provides an option, -codegen=oracle, for Oracle-specific code generation, in which case no profiles are produced.

For information about SQLJ profiles and Oracle-specific code generation, see the Oracle9i 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
_Foo$__jsp_StaticText.class for the inner class, as usual, 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 Oracle9i".

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

Other Key ojspc Features and Options for Deployment to Oracle9i

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 .java or .sqlj files during translation. You would do this, for example, if you want to load the translated page into Oracle9i as a .java file and have compilation performed by the server-side compiler.

In the case of SQLJ JSP pages, translated .java files are still produced, but not compiled.
-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 Oracle9i.
-srcdir--Specify the directory where ojspc will place the generated .java or .sqlj source files. For example, this would be useful instead of -d if you are enabling -noCompile and will load your translated page into Oracle9i 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 set an Oracle SQLJ option; ojspc will pass the option setting to the Oracle SQLJ translator. (You can have multiple -S settings in the ojspc command line.)

ojspc Examples

The following examples show the use of key ojspc options.

Example 1

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

This 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 directly under the specified application root directory.
Places _Foo.class, _Foo.res, and the .class file for the inner class into the /myroot/bin directory.

Example 2

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

This 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 directly under the specified application root directory.
Does not compile _Foo.java (no .class files are produced).
Places _Foo.res into the current directory, by default.

Example 3

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

This 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 directly under 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.)

Note:

As Example 3 shows, you can use an explicit true setting in enabling a SQLJ boolean option through the -S option setting. This is in contrast to ojspc boolean options, such as -extres, which do not take an explicit true setting.

Loading Translated JSP Pages into Oracle9i (loadjava)

After client-side pre-translation, use the Oracle loadjava tool to load generated files into Oracle9i. 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 Oracle9i 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 Oracle9i as a general-purpose tool for loading Java files into the database or database cache. For an overview, see "Overview of the loadjava Tool". For further information, see the Oracle9i Java Tools Reference.

Important:

In the next two subsections, "Loading Class Files with loadjava" and "Loading Java or SQLJ 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 Oracle9i. 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 Oracle9i 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 Oracle9i (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 to either 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:abc/def/_Foo$__jsp_StaticText class schema object

With the same package designation as the page implementation class.
SCOTT:abc/def/_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, if applicable--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 Java or SQLJ 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 Oracle9i 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 Oracle9i 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 Oracle9i (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 Oracle9i 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 the same package designation as the page implementation class.

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, if applicable--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 Oracle9i

To optionally "hotload" translated JSP pages in Oracle9i, 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 or database cache.

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 static text portion of the _Foo page implementation class.

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

Publishing Translated JSP Pages in Oracle9i (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 Oracle9i.

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 Oracle9i 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 Oracle9i. 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 default servlet context of the relevant Web domain:
```
/domain_name/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, created as follows:
```
$ createcontext -virtualpath /ose /scottRoot scottContext
```
Then /ose 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 name.
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 Oracle9i 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 Oracle9i Servlet Engine that the JSP page is to be stateless--it should 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 Oracle9i Java Tools Reference.

Example: Publishing JSP Pages with publishservlet

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

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

For simplicity, the default servlet context (of the /scottRoot domain) 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 Oracle9i 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 Oracle9i JNDI namespace. This does not, however, remove the servlet class schema object or page implementation class schema object from Oracle9i.

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 /scottRoot/contexts/default FooServlet

Additional JSP Deployment Considerations

Most of this chapter focuses on translation and deployment when targeting the Oracle9i Servlet Engine, because running in Oracle9i is a special situation requiring special considerations and logistics.

This section covers a variety of additional deployment considerations and scenarios, mostly for situations where you are not targeting OSE.

The following topics are covered:

Doc Root for Oracle9i Application Server Versus Oracle9i Servlet Engine

Both the Oracle9i Servlet Engine and the Oracle9i Application Server use the Oracle HTTP Server, essentially an Apache environment, as a Web server for HTTP requests. However, each environment uses its own doc root.

JSP pages and servlets running in the Oracle9i Servlet Engine, which are routed through the Apache mod_ose module provided by Oracle, use the OSE doc root of the relevant servlet context. OSE doc root directories are in the file system, but are linked to the Oracle9i JNDI mechanism.

Remember that for JSP pages running in OSE, only static files are located in or under the doc root. JSP pages are in the database or database cache.

The doc root directory for an OSE servlet context is specified using the session shell createcontext command -docroot option when the servlet context is created. For the default servlet context of the OSE default Web service, admin, the doc root is the [ORACLE_HOME]/jis/public_html directory. (It is possible to have a null doc root, although this may lead to undesirable behavior because the default OSE installation uses the doc root for error mapping.)

JSP pages and servlets running in the Apache/JServ environment of the Oracle9i Application Server (release 1.0.x), which are routed through the Apache mod_jserv module provided with JServ, use the Apache doc root. This doc root (typically htdocs) is set in the DocumentRoot command of the Apache httpd.conf configuration file.

For JSP pages running in JServ, JSP pages as well as static files are located in or under the doc root.

If you are migrating between the Apache/JServ environment and the OSE environment, move or copy static files to the appropriate doc root.

Note:

For an overview of the role of the Oracle HTTP Server and its mod_ose and mod_jserv modules, see "Role of the Oracle HTTP Server, Powered by Apache".

Use of ojspc for Pre-Translation for Non-OSE Environments

The Oracle ojspc tool, described in detail in "The ojspc Pre-Translation Tool", is typically used for client-side JSP translation for deployment to Oracle9i. However, you can use ojspc to pre-translate JSP pages in any environment, which may be useful in saving end users the translation overhead the first time a page is executed.

If you are pre-translating in some environment other than the target environment, specify the ojspc -d option to set an appropriate base directory for placement of generated binary files.

As an example, consider an Apache/JServ environment with the following JSP source file:

htdocs/test/foo.jsp

A user would invoke this with the following URL:

http://host[:port]/test/foo.jsp

During on-demand translation at execution time, the OracleJSP translator would use a default base directory of htdocs/_pages for placement of generated binary files. Therefore, if you pre-translate, you should set htdocs/_pages as the base directory for binary output, such as in the following example (assume % is a UNIX prompt):

% cd htdocs
% ojspc -d _pages test/foo.jsp

The URL noted above specifies an application-relative path of test/foo.jsp, so at execution time the OracleJSP container looks for the binary files in a _test subdirectory under the default htdocs/_pages directory. This subdirectory would be created automatically by ojspc if it is run as in the above example. At execution time, the OracleJSP container would find the pre-translated binaries and would not have to perform translation, assuming that the source file was not altered after pre-translation. (By default, the page would be re-translated if the source file timestamp is later than the binary timestamp, assuming the source file is available and the bypass_source configuration parameter is not enabled.)

Note:

OracleJSP implementation details, such as use of an underscore ("_") in output directory names (as for _test above), are subject to change from release to release. This documentation applies specifically to OracleJSP release 1.1.2.x.

General JSP Pre-Translation Without Execution

In an on-demand translation environment, it is possible to specify JSP pre-translation only, without execution, by enabling the standard jsp_precompile request parameter when invoking the JSP page from the end user's browser.

Following is an example:

http://host[:port]/foo.jsp?jsp_precompile

Refer to the Sun Microsystems JavaServer Pages Specification, Version 1.1, for more information.

Deployment of Binary Files Only

If your JSP source is proprietary, you can avoid exposing the source by pre-translating JSP pages and deploying only the translated and compiled binary files. Pages that are pre-translated, either from previous execution in an on-demand translation scenario or by using ojspc, can be deployed to any environment that supports the OracleJSP container. There are two aspects to this scenario:

You must deploy the binary files appropriately.
In the target environment, OracleJSP must be configured properly to run pages when the .jsp (or .sqljsp) source is not available.

Deploying the Binary Files

After JSP pages have been translated, archive the directory structure and contents that are under the binary output directory, then copy the directory structure and contents to the target environment, as appropriate. For example:

If you pre-translate with ojspc, you should specify a binary output directory with the ojspc -d option, then archive the directory structure under that specified directory.
If you are archiving binary files produced during previous execution in an Apache/JServ (on-demand translation) environment, archive the output directory structure, typically under the default htdocs/_pages directory.

In the target environment, restore the archived directory structure under the appropriate directory, such as under the htdocs/_pages directory in an Apache/JServ environment.

Configuring OracleJSP for Execution with Binary Files Only

Set OracleJSP configuration parameters as follows to execute JSP pages when the .jsp or .sqljsp source is unavailable:

bypass_source=true
developer_mode=false

Without these settings, OracleJSP will always look for the .jsp or .sqljsp file to see if it has been modified more recently than the page implementation .class file, and abort with a "file not found" error if it cannot find the .jsp or .sqljsp file.

With these parameters set appropriately, the end user can invoke a page with the same URL that would be used if the source file were in place. For an example, consider an Apache/JServ environment--if the binary files for foo.jsp are in the htdocs/_pages/_test directory, then the page can be invoked with the following URL without foo.jsp being present:

http://host:[port]/test/foo.jsp

For how to set configuration parameters, see "OracleJSP Configuration Parameter Settings".

WAR Deployment

The Sun Microsystems JavaServer Pages Specification, Version 1.1 supports the packaging and deployment of Web applications, including JavaServer Pages, according to the Sun Microsystems Java Servlet Specification, Version 2.2.

In typical JSP 1.1 implementations, JSP pages can be deployed through the WAR (Web archive) mechanism. WAR files are created using the JAR utility. The JSP pages can be delivered in source form and are deployed along with any required support classes and static HTML files.

Oracle9i provides a WAR deployment implementation that adheres to the Sun Microsystems standard.

Standard WAR Features

According to the servlet 2.2 specification, a Web application includes a deployment descriptor file--web.xml--that contains information about the JSP pages and other components of the application. The web.xml file must be included in the WAR file.

The servlet 2.2 specification also defines an XML DTD for web.xml deployment descriptors and specifies exactly how a servlet container must deploy a Web application to conform to the deployment descriptor.

Through these logistics, a WAR file is the best way to ensure that a Web application is deployed into any standard servlet environment exactly as the developer intended.

Deployment configurations in the web.xml deployment descriptor include mappings between servlet paths and the JSP pages and servlets that will be invoked. Many additional features can be specified in web.xml as well, such as timeout values for sessions, mappings of file name extensions to MIME types, and mappings of error codes to JSP error pages.

To summarize, the WAR file includes the following:

web.xml deployment descriptor
JSP pages
required JavaBeans and other support classes
required static HTML files
hierarchical organization (as with any JAR file)

For more information about standard WAR deployment, see the Sun Microsystems Java Servlet Specification, Version 2.2.

Oracle WAR Implementation

Each vendor providing a WAR implementation typically includes the following:

a DTD for an auxiliary descriptor, which is used for vendor-specific features in conjunction with the use of web.xml for standard features
a tool that performs the application deployment in the server

This section provides an overview of the Oracle implementation of these features. For more information about Oracle WAR deployment, see the Oracle9i Servlet Engine Developer's Guide.

Oracle Auxiliary Descriptor

The web.xml file is a vehicle for standard configuration instructions for a Web application and is portable to any standard runtime environment. However, web.xml cannot provide all the information necessary to deploy an application to a particular servlet container, because each vendor extends standard functionality with their own set of features. The servlet 2.2 specification suggests that each vendor provide an additional descriptor file for configuration of features unique to that vendor's runtime environment.

Oracle specifies and supports such an additional descriptor, known as the Oracle auxiliary descriptor. Like the web.xml deployment descriptor, the auxiliary descriptor is in XML format. Oracle provides a DTD to specify supported elements and attributes.

Oracle Deployment Tool

Oracle provides a tool that deploys a Web application to Oracle9i for execution in the Oracle9i Servlet Engine. The deployment tool requires that the application be packaged in a WAR file, and can be invoked in any of the following ways:

from the server, by using an Oracle session shell command (requires you to first manually upload the WAR file and auxiliary descriptor)
from the server, from Java code or a PL/SQL "call spec" (this also requires you to first manually upload the WAR file and auxiliary descriptor)
from any client, by invoking the Oracle deployment servlet (by default, the servlet class is automatically published to the Oracle9i Servlet Engine in advance)
from an Oracle client, through a client-side deployment script
from a non-Oracle client, by executing the deployment tool wrapper directly from Java

Note:
The client-side scripts and client-side wrapper are just convenient front ends that invoke the deployment servlet.

Deployment of JSP Pages with JDeveloper

Oracle JDeveloper release 3.1 and higher includes a deployment option, "Web Application to Web Server", that was added specifically for JSP applications.

This option generates a deployment profile that specifies the following:

a JAR file containing Business Components for Java (BC4J) classes required by the JSP application
static HTML files required by the JSP application
the path to the Web server

The developer can either deploy the application immediately upon creating the profile, or save the profile for later use.

6JSP Translation and Deployment

Functionality of the OracleJSP Translator

Generated Code Features

Features of Page Implementation Class Code

Inner Class for Static Text

General Conventions for Output Names

Generated Package and Class Names (On-Demand Translation)

Package Naming

Class Naming

Generated Files and Locations (On-Demand Translation)

Files Generated by OracleJSP

OracleJSP Translator Output File Locations

Sample Page Implementation Class Source

Sample Page Source: hello.jsp

Sample: Generated Package and Class

Sample: Generated Files

Sample Page Implementation Code: _hello.java

Overview of Features and Logistics in Deployment to Oracle9i

Database Schema Objects for Java

Loading Java Files to Create Schema Objects

Schema Object Full Names and Short Names

Java Schema Object Package Determination During Loading

Publishing Schema Objects

Oracle HTTP Server as a Front-End Web Server

URLs for the Oracle9i Servlet Engine

Context Path and Servlet Path

OSE Ports

OSE scottService

URL Examples

Example 1

Example 2

Static Files for JSP Applications in the Oracle9i Servlet Engine

Files for Dynamic Includes and Forwards

Files for Static Includes

Server-Side Versus Client-Side Translation

Overview of Hotloaded Classes in Oracle9i

Enabling and Accomplishing Hotloading

Features and Advantages of Hotloading

Tools and Commands for Translation and Deployment to Oracle9i

The ojspc Pre-Translation Tool

Overview of ojspc Functionality

Option Summary Table for ojspc

Table 6-1 Options for ojspc Pre-Translation Utility

Command-Line Syntax for ojspc

Option Descriptions for ojspc

-addclasspath

-appRoot

-d

-debug

-extend

-extres

-hotload

-implement

-noCompile

-packageName

-S-<sqlj option> <value>

-srcdir

-verbose

-version

Summary of ojspc Output Files, Locations, and Related Options

Overview of the loadjava Tool

Overview of the sess_sh Session Shell Tool

Deployment to Oracle9i with Server-Side Translation

Loading Untranslated JSP Pages into Oracle9i (loadjava)

Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)

Overview of publishjsp Syntax and Options

Examples: Publishing JSP Pages with publishjsp

Example Notes

Example 1

Example 2

Example 3

Example 4

Publishing SQLJ JSP Pages with publishjsp

Server-Side SQLJ Options

Example of publishjsp for SQLJ JSP Page

Unpublishing JSP Pages with unpublishjsp

Deployment to Oracle9i with Client-Side Translation

Pre-Translating JSP Pages (ojspc)

Simplest ojspc Usage

ojspc for SQLJ JSP Pages

6
JSP Translation and Deployment