6
JSP Translation and Deployment

This chapter discusses operation of the Oracle JSP translator, then discusses the ojspc utility and situations where pre-translation is useful, followed by general discussion of a number of additional JSP deployment considerations.

The chapter is organized as follows:

• Functionality of the Oracle JSP Translator
• JSP Pre-Translation and the ojspc Utility
• Additional JSP Deployment Considerations

Functionality of the Oracle JSP 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 Oracle JSP translator, focusing on its behavior in on-demand translation scenarios. 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 Oracle JSP 1.1.x.x releases only and are subject to change from release to release.

Generated Code Features

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

Features of Page Implementation Class Code

When the Oracle JSP 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 Oracle JSP 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).

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 Oracle JSP 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, 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.

General Conventions for Output Names

The Oracle JSP translator follows a consistent set of conventions in naming output classes, packages, files and directories. 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 Oracle JSP 1.1.x.x releases (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, 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 Oracle JSP translator by default will create directory htdocs/_pages/_test for the page implementation class source.

If special characters are included in a JSP page name or path name, the Oracle JSP 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 the Oracle JSP container creates package and class names when it generates code during translation.

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 Oracle JSP 1.1.x.x releases, 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 Oracle JSP 1.1.x.x releases, 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 Oracle JSP 1.1.x.x releases, 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 Oracle JSP 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 JSP configuration parameters. For more information about them, and about how to set them in a JServ environment, see "Oracle JSP Configuration Parameters" and "Setting JSP Parameters in JServ".

Files Generated by the Oracle JSP Container

This section considers both regular JSP pages (.jsp files) and SQLJ JSP pages (.sqljsp files) in listing files that are generated by the Oracle JSP 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 Oracle JSP 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 Oracle JSP 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 JSP sqljcmd configuration parameter.)

Binary files:

• In the case of a SQLJ JSP page, if you use ISO standard SQLJ code generation (SQLJ -codegen=iso setting), 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 JSP sqljcmd configuration parameter). The resource file or .class file has "Foo" as part of its name.

  Note: No profiles are produced if you use Oracle-specific code generation in SQLJ (-codegen=oracle). As of Oracle9i release 2, this is the SQLJ default mode.

• 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 JSP 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 JSP 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 beyond that.

Oracle JSP Translator Output File Locations

The Oracle JSP container 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 JServ) or the servlet context root directory of the application the page belongs to.

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

In Oracle JSP 1.1.x.x releases, 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 the Oracle JSP container 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 a 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 a JServ environment.
• The hello.jsp file is located in the following directory:

  htdocs/test
  
  

  Important: Code generation details discussed here are according to the Oracle 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), Oracle JSP 1.1.x.x releases generate 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

Oracle JSP 1.1.x.x releases generate 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

Sample Page Implementation Code: _hello.java

Following is the generated page implementation class Java code (_hello.java), as generated by Oracle JSP 1.1.x.x releases:

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();
    }
  }
}

JSP Pre-Translation and the ojspc Utility

This section describes the ojspc utility, provided with Oracle9i for pre-translation, and is organized as follows:

• General Use of ojspc for Pre-Translation
• Details of the ojspc Pre-Translation Tool

General Use of ojspc for Pre-Translation

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 a 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 Oracle JSP 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 Oracle JSP 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 Oracle JSP 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.)

Details of the ojspc Pre-Translation Tool

The following topics are covered here:

• Overview of ojspc Functionality
• Option Summary Table for ojspc
• Command-Line Syntax for ojspc
• Option Descriptions for ojspc
• 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 "General Use of ojspc for Pre-Translation".

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 Oracle JSP 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 Oracle JSP 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). Also, if you use ISO standard SQLJ code generation (SQLJ -codegen=iso setting), a SQLJ "profile" file is produced that is, by default, a .ser Java resource file.

  Note: No profiles are produced if you use Oracle-specific SQLJ code generation (SQLJ -codegen=oracle setting). As of Oracle9i release 2, this is the default mode.

  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 -extres option description below), ojspc settings direct the Oracle JSP 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 Oracle JSP translator, ojspc output conventions are the same as for the Oracle JSP container in general, as applicable. For general information about Oracle JSP 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 Oracle JSP Translator".

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 JSP configuration parameters for on-demand translation environments (such as JServ).

Table 6-1 Options for ojspc Pre-Translation Utility  

Option	Related JSP 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
-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 Oracle JSP 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 simply entering the option name on the command line. For example, type -extres, not -extres true.)

Following is an example:

% ojspc -d /myapp/mybindir -srcdir /myapp/mysrcdir -extres 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.

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

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

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

-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 Oracle JSP 1.1.x.x releases, 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".

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

-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, Oracle JSP 1.1.x.x releases 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-codegen iso -d /myapproot/mybindir MyPage.jsp

This directs SQLJ to generate ISO standard code instead of the default Oracle-specific code.

Here is another example:

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

This again directs SQLJ to generate ISO standard code, and also enables the -ser2class option to convert the profile to a .class file.

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.

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

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 source files into a clean directory so that you conveniently know what files have been produced.

-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 Oracle JSP 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 Oracle JSP 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 Oracle JSP 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
• -S-ser2class (SQLJ -ser2class option, for SQLJ JSP pages only, and for ISO standard SQLJ code generation 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.

Additional JSP Deployment Considerations

This section covers a variety of general deployment considerations and scenarios, mostly independent of your target environment.

The following topics are covered:

• General JSP Pre-Translation Without Execution
• Deployment of Binary Files Only
• Deployment of JSP Pages with Oracle9i JDeveloper
• Doc Root for JServ

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 Oracle JSP container. There are two aspects to this scenario:

• You must deploy the binary files appropriately.
• In the target environment, the Oracle JSP container 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 a 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 a JServ environment.

Configuring the Oracle JSP Container for Execution with Binary Files Only

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

• bypass_source to true
• developer_mode to false

Without these settings, the Oracle JSP container 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 a 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 in a JServ environment, see "Setting JSP Parameters in JServ".

Deployment of JSP Pages with Oracle9i JDeveloper

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

Doc Root for JServ

JSP pages and servlets running in the JServ environment supplied with Oracle9i, 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.