7
JSP Translation and Deployment

This chapter discusses operation of the OC4J 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 JSP Translator

• The ojspc Pre-Translation Utility

• JSP Deployment Considerations

Functionality of the 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 JSP translator, focusing on its behavior in on-demand translation scenarios such as in OC4J in the Oracle9i Application Server. The following topics are covered:

• Features of Generated Code

• General Conventions for Output Names

• Generated Package and Class Names

• Generated Files and Locations

• Oracle JSP Global Includes

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 exact details are subject to change from release to release.

Features of Generated Code

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

Features of Page Implementation Class Code

When the 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 provided by the 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, expressions, and JSP tags 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" in a page directive.

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

Inner Class for Static Text

The service method, _jspService(), of the page implementation class includes print statements--out.print() or equivalent calls on the implicit out object--to print any static text in the JSP page. The 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.

Note: The OC4J JSP 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 JSP external_resource configuration parameter for on-demand translation, or the ojspc -extres flag for pre-translation. When static text is placed in a resource file, the inner class is still produced and its .class file must be deployed. (This is noteworthy only if you are in a client-side pre-translation scenario.)

General Conventions for Output Names

The 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, however, 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 Oracle9iAS release 2, the base name is preceded by an underscore ("_"). Translating MyPage123.jsp results in the page implementation class _MyPage123 in the 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 a directory such as webapp/test, the JSP translator by default will create a directory such as webappdeployment/_pages/_test for the page implementation class source. All output directories are created under the standard _pages directory, as described in "Generated Files and Locations".

If you include special characters in a JSP page name or path name, the JSP translator takes steps to ensure that no illegal Java characters 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 chapter.

Generated Package and Class Names

Although the Sun Microsystems JavaServer Pages Specification, Version 1.2 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 OC4J JSP translator creates package and class names when it generates code during translation.

Note: For information about general conventions that the OC4J JSP translator uses in naming output classes, packages, and files, 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 the current OC4J JSP implementation, this results in the following package specification in the generated code:

package _hr._expenses;

(Implementation details are subject to change in future releases.)

No package name is generated if the JSP page is at the 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 the current OC4J JSP implementation, this yields the following class name in the generated code:

public class _UserLogin extends ...

(Implementation details are subject to change in future releases.)

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.

Currently, the translator determines the case of the class name according to the case of the file name. For example:

• UserLogin.jsp results in the class _UserLogin.

• Userlogin.jsp results in the class _Userlogin.

• userlogin.jsp results in the 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

This section describes files that are generated by the 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".

Wherever JSP configuration parameters are mentioned, see "JSP Configuration Parameters" for more information.

Note: For information about general conventions used in naming output classes, packages, and files, see "General Conventions for Output Names".

Files Generated by the JSP Translator

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

Source files:

• A.sqlj file (for example, _Foo.sqlj) is produced by the OC4J JSP translator if the page is a SQLJ JSP page.

• A .java file (for example, _Foo.java) is produced for the page implementation class and inner class. It is produced either directly by the 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 by using the sqljcmd JSP configuration parameter.

Binary files:

• In the case of a SQLJ JSP page with ISO code generation, 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 sqljcmd configuration parameter. The resource file or .class file has "Foo" as part of its name. (The default SQLJ code generation is -codegen=oracle, for Oracle-specific code. No profiles are generated for Oracle-specific code. For ISO code, use -codegen=iso.)

• A .class file is produced by the Java compiler for the page implementation class. The Java compiler is the JDK 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; in the current implementation it would be _Foo$__jsp_StaticText.class.

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

Note: The exact names of generated files for the page implementation class might 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 variations beyond that.

JSP Translator Output File Locations

The JSP translator places generated output files under a base temp/_pages directory, as in the following example:

[Oracle_Home]/j2ee/home/app-deployment/app-name/web-app-name/temp/_pages/...

Note the following, and refer to "Key OC4J Configuration Files" for related information about the noted configuration files:

• The app-deployment directory is the OC4J deployment directory, specified in the OC4J server.xml file. It is typically the application-deployments directory.

• Also, app-name is the application name, according to an <application> element in server.xml.

• And web-app-name is the corresponding "Web application name", mapped to the application name in a <web-app> element in the OC4J default-web-site.xml file (or http-web-site.xml for OC4J standalone, or other Web site XML file as appropriate).

The path under the _pages directory depends on the path of the .jsp file under the application root directory.

As an example, consider the page welcome.jsp in the examples/jsp subdirectory under the OC4J standalone default Web application directory. The path would be as follows:

[Oracle_Home]/j2ee/home/default-web-app/examples/jsp/welcome.jsp

Assuming the default application deployment directory, the JSP translator would place the output files ( _welcome.java, _welcome.class, and _welcome$__jsp_StaticText.class for the page implementation class inner class) in the following directory:

[Oracle_Home]/j2ee/home/application-deployments/default/defaultWebApp/temp/_pages/_examples/_jsp

Note the following for OC4J standalone. (Directories are configurable through Oracle Enterprise Manager in an Oracle9iAS environment.)

• The application-deployments directory is the OC4J default deployment directory.

• Also, default is the OC4J default application name and defaultWebApp is the default Web application name, both used for JSP pages placed in the default-web-app directory.

• Because the .jsp source file is in an examples/jsp subdirectory under the application root directory, the JSP translator generates _examples._jsp as the package name, and places the output files into an _examples/_jsp subdirectory under the _pages directory.

Important: Implementation details, such as the location of generated output files and use of "_" in output file names, are subject to change in future releases.

Oracle JSP Global Includes

The OC4J JSP container provides a feature called global includes. You can use this feature to specify one or more files to statically include into JSP pages in (or under) a specified directory, through virtual JSP include directives. During translation, the JSP container looks for a configuration file, /WEB-INF/ojsp-global-include.xml, that specifies the included files and the directories for the pages.

This enhancement is particularly convenient for migrating applications that used globals.jsa or translate_params functionality in previous Oracle JSP releases.

Globally included files can be used for the following, for example:

• global bean declarations (formerly supported through globals.jsa)

• common page headers or footers

• translate_params equivalent code (typically for a JServ environment)

The ojsp-global-include.xml File

The ojsp-global-include.xml file specifies the names of files to include, whether they should be included at the tops or bottoms of JSP pages, and the locations of JSP pages to which the global includes should apply. This section describes the elements of ojsp-global-include.xml.

<ojsp-global-include>

This is the root element of the ojsp-global-include.xml file. It has no attributes.

Subelements:

<include>

<include ... >

Use this subelement of <ojsp-global-include> to specify a file to be included, and whether it should be included at the top or bottom of JSP pages.

Subelements:

<into>

Attributes:

• file: Specify the file to be included, such as "/header.html" or "/WEB-INF/globalbeandeclarations.jsph". The file name setting must start with a slash ("/"). In other words, it must be context-relative, not page-relative.

• position: Specify whether the file is to be included at the top or bottom of JSP pages. Supported values are "top" (default) and "bottom".

<into ... >

Use this subelement of <include> to specify a location (a directory, and possibly subdirectories) of JSP pages into which the specified file is to be included. This element has no subelements.

Attributes:

• directory: Specify a directory. Any JSP pages in this directory, and optionally its subdirectories, will statically include the file specified in the file attribute of the <include> element. The directory setting must start with a slash ("/"), such as "/dir1". The setting can also include a slash after the directory name, such as "/dir1/", or a slash will be appended internally during translation.

• subdir: Use this to specify whether JSP pages in all subdirectories of the directory should also have the file statically include. Supported values are "true" (default) and "false".

Global Include Examples

This section provides examples of global includes.

Example: Header/Footer

Assume the following ojsp-global-include.xml file:

<?xml version="1.0" standalone='yes'?>
<!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'>

<ojsp-global-include>
  <include file="/header.html">
     <into directory="/dir1" />
  </include>
  <include file="/footer1.html" position="bottom">
     <into directory="/dir1" subdir="false" />
     <into directory="/dir1/part1/" subdir="false" />
  </include>
  <include file="/footer2.html" position="bottom">
     <into directory="/dir1/part2/" subdir="false" />
  </include>
</ojsp-global-include>

This example accomplishes three objectives:

• The header.html file is included at the top of any JSP page in or under the dir1 directory. The result would be the same as if each .jsp file in or under this directory had the following include directive at the top of the page:

  <%@ include file="/header.html" %>
  
  

• The footer1.html file is included at the bottom of any JSP page in the dir1 directory or its part1 subdirectory. The result would be the same as if each .jsp file in those directories had the following include directive at the bottom of the page:

  <%@ include file="/footer1.html" %>
  
  

• The footer2.html file is included at the bottom of any JSP page in the part2 subdirectory of dir1. The result would be the same as if each .jsp file in that directory had the following include directive at the bottom of the page:

  <%@ include file="/footer2.html" %>
  
  

Note: If multiple header or multiple footer files are included into a single JSP page, the order of inclusion is according to the order of <include> elements in the ojsp-global-include.xml file.

Example: translate_params Equivalent Code

Assume the following ojsp-global-include.xml file:

<?xml version="1.0" standalone='yes'?>
<!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'>

<ojsp-global-include>
  <include file="/WEB-INF/nls/params.jsf">
     <into directory="/" />
  </include>   
</ojsp-global-include>

And assume params.jsf contains the following:

<% request.setCharacterEncoding(response.getCharacterEncoding()); %>

The params.jsf file (essentially, the setCharacterEncoding() method call) is included at the top of any JSP page in or under the application root directory. In other words, it is included in any JSP page in the application. The result would be the same as if each .jsp file in or under this directory had the following include directive at the top of the page:

<%@ include file="/WEB-INF/nls/parms.jsf" %>

Also see "Migration Away from translate_params".

The ojspc Pre-Translation Utility

This section describes the ojspc utility, provided with OC4J for pre-translation of JSP pages. For consideration of pre-translation scenarios, see "JSP Pre-Translation" and "Deployment of Binary Files Only".

The following topics are covered here:

• Overview of Basic ojspc Functionality

• Overview of ojspc Batch Pre-Translation

• Option Summary Table for ojspc

• Command-Line Syntax for ojspc

• Option Descriptions for ojspc

• Summary of ojspc Output Files, Locations, and Related Options

Important: To use ojspc, you must be using a Sun Microsystems JDK (version 1.1.8 or higher) and you must have tools.jar (for JDK 2.0 or higher) or classes.zip (for JDK 1.1.8) in your classpath.

Overview of Basic ojspc Functionality

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

• It takes a JSP file (typically .jsp), either directly as an argument or from an archive file taken as an argument.

• It invokes the 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.

Following is the default ojspc functionality for a SQLJ JSP page:

• It takes a SQLJ JSP file (a .sqljsp file or a JSP file with language="sqlj" in a page directive), either directly as an argument or from an archive file taken as an argument.

• It invokes the JSP translator to translate the SQLJ JSP page 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, for ISO code generation, translation produces a SQLJ "profile" file that is, by default, a .ser Java resource file.

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

Note: The default SQLJ code generation setting is -codegen=oracle, for Oracle-specific code (with no profiles). For ISO code generation, specify -codegen=iso.

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

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

Overview of ojspc Batch Pre-Translation

Prior to Oracle9iAS release 2 (9.0.3), ojspc accepted only JSP files (or SQLJ JSP files) for translation. Now, however, it can also accept archive files--JAR, WAR, EAR, or ZIP files--for batch pre-translation.

Note: The ojspc utility does not depend on the file name extension to determine whether a file is an archive file. It makes the determination by examining the internal file structure.

When the name of an archive file appears on the ojspc command line, ojspc by default executes the following steps:

1. Opens the archive file.

2. Translates and compiles all .jsp and .sqljsp files in the archive file.

3. Adds the resulting .class files, and any Java resource files, into the archive file (and discards .java and .sqlj files that were created in the process). The .class and resource files are added with directory paths such that upon extraction, they will be located in the same directory as would be the case if the original JSP files were translated after extraction.

   Note: The actual mechanics are that the original archive file is extracted into a temporary storage area (recursively if there are nested archive files), a temporary archive file is created, contents of the original archive file are copied into the temporary file, output .class and resource files from pre-translation are added to the temporary file, the original archive file is deleted, and the temporary file is given the name of the original file. (The original archive file is extracted in its entirety to ensure successful compilation of the translated pages.)

There are ojspc settings for additional functionality, as follows:

• You can use the -batchMask option to specify file name extensions for pre-translation. Whatever you specify is in addition to the defaults, which are *.jsp and *.sqljsp.

• You can use the -output option to specify a new archive file name. In this case, all contents of the original archive file are copied into the specified archive file, then the output .class files (and any resource files) from pre-translation are added to the specified file. The original archive file is unaltered, and you would use the new file instead of the original file for deployment.

• You can use the -deleteSource option if you do not want the JSP source files to appear in the resulting archive file. If you use -deleteSource without using the -output option, then the contents of the original archive file are overwritten so that no pre-translated JSP source files are included. If you use both -deleteSource and -output, then the new archive file is created without any pre-translated JSP source files. The -deleteSource option applies to all JSP files that are pre-translated--*.jsp and *.sqljsp files plus files with extensions specified in the -batchMask setting.

For examples of these options, see the descriptions of those options under "Option Descriptions for ojspc".

Option Summary Table for ojspc

Table 7-1 summarizes 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 OC4J.

Note: For a JServ environment, use the ojspc_jserv command instead of the ojspc command. See "Using ojspc for JServ". Be aware that the -staticTextInChars option is not relevant for JServ, so is not supported by ojspc_jserv.

Table 7-1 Options for ojspc Pre-Translation Utility  

Option	Related JSP Configuration Parameters	Description	Default
-addclasspath	(none)	Specify additional classpath entries for javac.	empty (no additional path entries)
-appRoot	(none)	Specify the application root directory for application-relative static include directives from the page.	current directory
-batchMask	(none)	For batch pre-translation, optionally specify additional file name extensions for pre-translation.	*.jsp, *.sqljsp
-d	(none)	Specify the location where ojspc should place generated binary files (.class and resource). Do not use this option for batch pre-translation.	current directory
-debug	emit_debuginfo	Enabling this flag directs ojspc to generate a line map to the original .jsp file for debugging.	false
-deleteSource	(none)	For batch pre-translation, enabling this flag directs that JSP source files should be removed from (or not copied to) the resulting archive file.	false
-extend	(none)	Specify the class for the generated page implementation class to extend. Do not use this option for batch pre-translation.	empty
-extraImports	extra_imports	Use this to add imports beyond the JSP defaults.	empty
-extres	external_resource	Enabling this flag directs ojspc to generate an external resource file for static text from the .jsp file.	false
-forgiveDupDirAttr	forgive_dup_dir_attr	Enable this flag in order to avoid JSP 1.2 translation errors if you have duplicate settings for the same directive attribute within a single JSP translation unit.	false
-help (or -h)	(none)	Enabling this flag directs ojspc to display usage information.	false
-implement	(none)	Specify an interface for the generated page implementation class to implement. Do not use this option for batch pre-translation.	empty
-noCompile	javaccmd	Enabling this flag directs ojspc to not compile the generated page implementation class.	false
-noTldXmlValidate	no_tld_xml_validate	Enable this flag in order to disable XML validation of TLD files. By default, validation of TLD files is performed.	false
-oldIncludeFromTop	old_include_from_top	Enable this flag in order to specify that page locations in nested include directives are relative to the top-level page, for backward compatibility with Oracle JSP behavior prior to Oracle9iAS release 2.	false
-output	(none)	For batch pre-translation, optionally specify the name of the output archive file.	original archive file
-packageName	(none)	Specify the package name for the generated page implementation class.	empty (generate package names according to .jsp file location)
-reduceTagCode	reduce_tag_code	Enable this flag in order to specify further reduction in the size of generated code for custom tag usage.	false
-reqTimeIntrospection	req_time_introspection	Enable this flag in order to allow request-time JavaBean introspection whenever compile-time introspection is not possible.	false
-S-<sqlj_option>	sqljcmd	Use the -S prefix followed by an Oracle SQLJ option (for SQLJ JSP pages).	empty
-srcdir	(none)	Specify the location where ojspc should place generated source files (.java and .sqlj). Do not use this option for batch pre-translation.	current directory
-staticTextInChars	static_text_in_chars	Enable this flag in order to instruct the JSP translator to generate static text in JSP pages as characters instead of bytes.	false
-verbose	(none)	Enabling this flag directs ojspc to print status information as it executes.	false
-version	(none)	Enabling this flag directs ojspc to display the JSP version number.	false
-xmlValidate	xml_validate	Enable this flag in order to perform XML validation of the web.xml file. By default, validation of web.xml is not performed.	false

Command-Line Syntax for ojspc

Following is the general ojspc command-line syntax (where % is the system prompt):

% ojspc file_list [option_settings]

The file list can include JSP files, including SQLJ JSP files, or archive files (JAR, WAR, EAR, or ZIP 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 settings).

• Use spaces between file names in the file list.

• Use spaces as delimiters 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 (flags), which are disabled by default, by simply typing the option name in the command line. For example, type -extres, not -extres true.

Here are two examples:

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

% ojspc myapp.war -deleteSource

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.

Note: 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 your current directory when you ran ojspc.

The specified application root directory path is used as follows:

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

• 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 that 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 (where % 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 example 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 when you ran ojspc. (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 /abc/def/ghi/test.jsp -appRoot /abc

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.

-batchMask

(additional file name extensions; ojspc default: "*.jsp,*.sqljsp")

For batch pre-translation, you can use this option to specify file name extensions for pre-translation. By default, .jsp and .sqljsp files are pre-translated. Extensions specified through the -batchMask option are in addition to the default extensions.

Place quotes around the list of file name extensions, and use commas or semicolons as delimiters within the list. White space before or after a file name extension is ignored.

The following examples (where % is the system prompt) result in the same action, given that .jsp and .sqljsp files are pre-translated anyway, and that commas are equivalent to semicolons as delimiters):

% ojspc myapp.war -batchMask "*.jspf,*.jsph,*.jsp,*.sqljsp"

% ojspc myapp.zip -batchMask "*.jspf; *.jsph"

Notes: File name extensions specified in this option are not case-sensitive. There is no support for specifying directory paths or Java packages in the -batchMask setting.

-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 with SQLJ ISO code generation.)

The specified path is taken 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: Do not use -d for batch pre-translation. In environments such as Windows NT that allow spaces in directory names, enclose the directory name in quotes.

-debug

(boolean; ojspc default: false)

Enabling this flag instructs 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 flag is useful for source-level JSP debugging, such as when you use Oracle9i JDeveloper.

Note: In an on-demand translation scenario, the JSP emit_debuginfo configuration parameter provides the same functionality.

-deleteSource

(boolean; ojspc default: false)

For batch pre-translation, enable this flag if you do not want JSP source files that were pre-translated to appear in the resulting archive file. This is all .jsp and .sqljsp files by default, plus files with name extensions specified in the -batchMask option.

If you do not use the -output option--that is, if the original archive file is being updated and is also the output archive file--this means that the contents of the archive file are overwritten to remove any JSP files that are pre-translated. If you do use the -output option, this means that any JSP files that are pre-translated will not be copied to the specified output archive file. (The original archive file is unaltered.)

Note: As in any situation where JSP source files are not deployed, after you have used -deleteSource the target JSP runtime environment must be configured to operate properly without having source files available. See "Configuring the OC4J JSP Container for Execution with Binary Files Only".

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

Note: Do not use -extend for batch pre-translation.

-extraImports

(import list; ojspc default: empty)

As described in "Default Package Imports", as of Oracle9iAS release 2 (9.0.3) the OC4J JSP container has a smaller default list of packages that are imported into each JSP page. This is in accordance with the JSP specification. You can avoid updating your code, however, by specifying package names or fully qualified class names for any additional imports through the -extraImports option. Be aware that the names must be comma-delimited, with no spaces, as in the following example:

% ojspc foo.jsp -extraImports java.util.*,java.io.*

Note: In an on-demand translation scenario, the JSP extra_imports configuration parameter provides the same functionality. As an alternative to using -extraImports, you can use global includes. See "Oracle JSP Global Includes".

-extres

(boolean; ojspc default: false)

Enabling this flag instructs 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. In the current OC4J JSP implementation, 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 might 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 JSP external_resource configuration parameter provides the same functionality.

-forgiveDupDirAttr

(boolean; ojspc default: false)

Enabling this flag avoids translation errors in JSP 1.2 (or higher) if you have duplicate settings for the same directive attribute within a single JSP translation unit (a JSP page plus anything it includes through include directives).

The JSP 1.2 specification directs that a JSP container must verify that directive attributes, with the exception of the page directive import attribute, are not set more than once each within a single JSP translation unit. See "Duplicate Settings of Page Directive Attributes Are Disallowed" for more information.

The JSP 1.1 specification does not specify such a limitation. OC4J offers the -forgiveDupDirAttr option for backward compatibility.

Note: In an on-demand translation scenario, the JSP forgive_dup_dir_attr configuration parameter provides the same functionality.

-help

(boolean; ojspc default: false)

Use this option to have ojspc display usage information and then exit. As a shortcut, -h is also accepted.

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

Note: Do not use -implement for batch pre-translation.

-noCompile

(boolean; ojspc default: false)

Enabling this flag directs ojspc to not compile the generated page implementation class Java source. This is in case you want to compile it later for some reason, such as with an alternative Java compiler.

Notes: In an on-demand translation scenario, the JSP javaccmd configuration parameter provides related functionality. It enables you to specify a complete Java compiler command line, optionally using an alternative compiler. For a SQLJ JSP page, enabling -noCompile does not prevent SQLJ translation, just Java compilation.

-noTldXmlValidate

(boolean; ojspc default: false)

Enable this flag if you do not want XML validation of tag library descriptor (TLD) files of the application. By default, validation of TLD files is performed.

See "Overview of TLD File Validation and Features" for related information.

Note: In an on-demand translation scenario, the JSP no_tld_xml_validate configuration parameter provides the same functionality.

-oldIncludeFromTop

(boolean; ojspc default: false)

This is for backward compatibility with Oracle JSP versions prior to Oracle9iAS release 2, for functionality of include directives. If you enable this flag, page locations in nested include directives are relative to the top-level page. Otherwise, page locations are relative to the immediate parent page. This complies with the JSP 1.2 specification.

Note: In an on-demand translation scenario, the JSP old_include_from_top configuration parameter provides the same functionality.

-output

(archive file name; ojspc default: none)

For batch pre-translation, use the -output option if you want to specify a new archive file for output. In this case, all contents of the original archive file are copied into the specified archive file, then the output .class files (and any resource files) from pre-translation are added to the specified file. The original archive file is unaltered, and you would use the new file instead of the original file for deployment.

Without the -output option, the original archive file is updated to add output .class (and resource) files; no new archive file is created.

Here is an example of -output usage:

% ojspc myapp.war -output myappout.war

-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 your current directory when 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 (where % is a UNIX prompt):

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

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

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

-reduceTagCode

(boolean; ojspc default: false)

The Oracle JSP implementation reduces the size of generated code for custom tag usage, but enabling this flag results in even further size reduction. There may be performance consequences regarding tag handler reuse, however. See "Tag Handler Code Generation".

Note: In an on-demand translation scenario, the JSP reduce_tag_code configuration parameter provides the same functionality.

-reqTimeIntrospection

(boolean; ojspc default: false)

Enabling this flag allows request-time JavaBean introspection whenever compile-time introspection is not possible. When compile-time introspection is possible and succeeds, this parameter is ignored and there is no request-time introspection.

As a sample scenario for request-time introspection, assume a tag handler returns a generic java.lang.Object instance in the VariableInfo instance of the tag-extra-info class during translation and compilation, but actually generates more specific objects during request-time (runtime). In this case, if req_time_introspection is enabled, the JSP container will delay introspection until request-time. (See "Scripting Variables, Declarations, and Tag-Extra-Info Classes" for information about use of VariableInfo.)

Note: In an on-demand translation scenario, the JSP req_time_introspection configuration parameter provides the same functionality.

-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, where each specifies one SQLJ option setting.

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 (where % is a UNIX prompt):

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

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

Here is another example:

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

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

Note: As the preceding example shows, you must 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 or pageEncoding attribute 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 JSP sqljcmd configuration parameter provides related functionality. It enables you to enter a complete SQLJ command line, with desired option settings and optionally an alternative SQLJ compiler.

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

Notes: Do not use -srcdir for batch pre-translation. In environments such as Windows NT that allow spaces in directory names, enclose the directory name in quotes.

-staticTextInChars

(boolean; ojspc default: false)

Enabling this flag directs the JSP translator to generate static text in JSP pages as characters instead of bytes. The default setting is false, which improves performance in outputting static text blocks.

Enable this flag if your application requires the ability to change the character encoding dynamically during runtime, such as in the following example:

<% response.setContentType("text/html; charset=UTF-8"); %>

Note: In an on-demand translation scenario, the JSP static_text_in_chars configuration parameter provides the same functionality.

-verbose

(boolean; ojspc default: false)

Enabling this flag directs 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 myerror.jsp -verbose
Translating file: myerror.jsp
1 JSP files translated successfully.
Compiling Java file: ./_myerror.java

-version

(boolean; ojspc default: false)

Use this option to have ojspc display the JSP version number and then exit.

-xmlValidate

(boolean; ojspc default: false)

Enable this flag if you want XML validation of the application web.xml file. Because the Tomcat JSP reference implementation does not perform XML validation, this flag is disabled by default.

Note: In an on-demand translation scenario, the JSP xml_validate configuration parameter provides the same functionality.

Summary of ojspc Output Files, Locations, and Related Options

By default, ojspc generates the same set of files that are generated by the JSP translator in an on-demand translation scenario, and (not considering batch pre-translation) places them in or under your current directory when you ran ojspc.

Here are the files:

• for SQLJ JSP pages--a .sqlj source file (for batch pre-translation, discarded after compilation)

• a .java source file (for batch pre-translation, discarded after compilation)

• a .class file for the page implementation class

• a .class file for the inner class for static text

• for SQLJ JSP pages using ISO code generation--a Java resource file (.ser), or optionally a .class file, for the SQLJ profile

• optionally, a Java resource file (.res) for the static text of the page

For more information about files that are generated by the JSP translator, see "Generated Files and Locations".

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 location (not relevant for batch pre-translation)

• -d to place binary files (.class files and Java resource files) in a specified location (not relevant for batch pre-translation)

• -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 (not considering batch pre-translation), 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, suppose you run ojspc as follows (where % 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 that you run ojspc from some other directory, as follows:

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

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.

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

JSP Deployment Considerations

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

It discusses the following topics:

• Overview of EAR/WAR Deployment

• Application Deployment with Oracle9i JDeveloper

• JSP Pre-Translation

• Deployment of Binary Files Only

Overview of EAR/WAR Deployment

This section provides an overview of OC4J deployment features and standard WAR deployment features.

See Oracle9iAS Containers for J2EE User's Guide for detailed information about deployment to OC4J in an Oracle9iAS environment.

OC4J Deployment Features

In OC4J, deploy each application through a standard EAR (Enterprise archive) file. Specify the name of the application and the name and location of the EAR file through an <application> element in the OC4J server.xml file. (This file is in the OC4J configuration files directory. In Oracle9iAS, directory paths are configurable; in OC4J standalone, the configuration files directory is j2ee/home/config by default.)

For production, use Enterprise Manager for deployment. Enterprise Manager is recommended for managing OC4J and other components of Oracle9iAS in a production environment. Refer to the Oracle9i Application Server Administrator's Guide and Oracle Enterprise Manager Administrator's Guide for information.

OC4J also supports the admin.jar tool for deployment, typically in an OC4J standalone development environment. This modifies server.xml and other configuration files for you, based on settings you specify to the tool. Or you can modify the configuration files manually (not generally recommended). Note that if you modify configuration files in Oracle9iAS without going through Enterprise Manager, you must run the dcmctl tool, using its updateConfig command, to inform Oracle9iAS Distributed Configuration Management (DCM) of the updates. (This does not apply in an OC4J standalone mode, where OC4J is being run apart from Oracle9iAS.)

Here is the dcmctl command:

dcmctl updateConfig -ct oc4j

The dcmctl tool is documented in the Oracle9i Application Server Administrator's Guide.

The EAR file includes the following:

• a standard application.xml configuration file, in /META-INF

• optionally, an orion-application.xml configuration file, in /META-INF

• a standard WAR (Web archive) file

The WAR file includes the following:

• a standard web.xml configuration file, in /WEB-INF

  In the web.xml file for any particular application, you can override global settings for individual configuration parameters or for the definition of the JSP servlet (oracle.jsp.runtimev2.JspServlet by default). Each application uses its own instance of the JSP servlet.

• optionally, an orion-web.xml configuration file, in /WEB-INF

• classes necessary to run the application (servlets, JavaBeans, and so on), under WEB-INF/classes and in JAR files in WEB-INF/lib

• JSP pages and static HTML files

The EAR file goes in the OC4J applications directory, which is specified in the application-directory setting in the <application-server> element of the server.xml file (for example, j2ee/home/applications). This would be the same directory as is specified for the EAR file location in the <application> element in server.xml.

Through the OC4J auto-deployment feature, a new EAR file in the applications directory (as specified in server.xml) is detected automatically and hierarchically extracted.

See the Oracle9iAS Containers for J2EE User's Guide for more information about deployment to Oracle9iAS. See the standalone version of this document for information about admin.jar (which has additional uses as well). Also see "Key OC4J Configuration Files" for a summary of important configuration files in OC4J.

Standard WAR Deployment

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

In typical JSP 1.2 implementations, you can deploy JSP pages through the WAR mechanism, creating WAR files through 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.

According to the servlet specification, versions 2.2 and higher, 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 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 intends.

Deployment configurations in the web.xml deployment descriptor include mappings between servlet paths and the JSP pages and servlets that will be invoked. You can specify many additional features 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.

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

Application Deployment with Oracle9i JDeveloper

Oracle9i JDeveloper supports many types of deployment profiles, including simple archive, J2EE application (EAR file), J2EE EJB module (EJB JAR file), J2EE Web module (WAR file), J2EE client module (client JAR file), tag library for JSP 1.2 (tag library JAR file), business components EJB session bean profile, business components CORBA server for VisiBroker, and business components archive profile.

When creating a Business Components for Java (BC4J) Web application using Oracle9i JDeveloper, a J2EE Web module deployment archive is generated, containing both the BC4J and the Web application files.

The JDeveloper deployment wizards create all the necessary code to deploy business components as a J2EE Web module. Typically, a JSP client accesses the BC4J application in a J2EE Web Module configuration. The JSP client can also use data tags, data Web beans, or UIX tags to access the business components. (See the Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference for an overview of the BC4J and UIX tag libraries.)

A J2EE Web module is packaged as a WAR file that contains one or more Web components (servlets and JSP pages) and web.xml, the deployment descriptor file.

JDeveloper lets you create the deployment profile containing the Web components and the web.xml file, and packages them into a standard J2EE EAR file for deployment. JDeveloper takes the resulting EAR file and deploys it to one or more Oracle9iAS instances.

For information about JDeveloper, refer to the JDeveloper online help, or to the following site on the Oracle Technology Network:

http://otn.oracle.com/products/jdev/content.html

JSP Pre-Translation

JSP pages are typically used in an on-demand scenario, where pages are translated as they are invoked, in a sequence that is invisible to the user. Another approach is to pre-translate JSP pages, which offers at least two advantages:

• It saves end users the translation overhead the first time a page is invoked.

• It ensures that the developer or deployer, instead of end users, will see any translation or compilation errors.

You also might want to pre-translate pages so that you can deploy binary files only, as discussed in "Deployment of Binary Files Only".

OC4J users can employ the Oracle ojspc utility for pre-translation, either specifying individual files, or specifying archive files (JAR, WAR, EAR, or ZIP) for batch pre-translation. There is also a standard jsp_precompile mechanism. These topics are covered in the following subsections:

• Techniques for Page Pre-Translation with ojspc

• Batch Pre-Translation with ojspc

• Standard JSP Pre-Translation without Execution

Also see "The ojspc Pre-Translation Utility" for detailed information about this utility.

Techniques for Page Pre-Translation with ojspc

When you pre-translate with ojspc (not considering batch pre-translation), use the -d option to set an appropriate output base directory for placement of generated binary files.

Consider the example in "JSP Translator Output File Locations", where the JSP page is located in the examples/jsp subdirectory under the OC4J standalone default Web application directory:

[Oracle_Home]/j2ee/home/default-web-app/examples/jsp/welcome.jsp

A user would invoke this with a URL such as the following:

http://host[:port]/examples/jsp/welcome.jsp

(This is just a general example and does not consider OC4J default configuration for the context path.)

In an on-demand translation scenario for this page, as explained in the example, the JSP translator would by default use the following base directory for placement of generated binary files:

[Oracle_Home]/j2ee/home/application-deployments/default/defaultWebApp/temp/_pages

When you pre-translate, set your current directory to the application root directory, then in ojspc set the _pages directory as the output base directory. This results in the appropriate package name and file hierarchy. Continuing the example (where % is a UNIX prompt):

% cd [Oracle_Home]/j2ee/home/default-web-app
% ojspc examples/jsp/welcome.jsp 
-d [Oracle_Home]/j2ee/home/application-deployments/default/defaultWebApp/temp/_pages

(This assumes you specify the appropriate Oracle_Home directory.) The ojspc command is a single wraparound command, translating examples/jsp/welcome.jsp and specifying the _pages directory as the base output directory.

The URL noted above specifies an application-relative path of examples/jsp/welcome.jsp, so at execution time the JSP container looks for the binary files in an _examples/_jsp subdirectory under the _pages directory. This subdirectory would be created automatically by ojspc if it is run as in the above example.

At execution time, the JSP container would find the pre-translated binaries and would not have to perform translation, assuming that either the source file was not altered after pre-translation, or the JSP main_mode flag is set to justrun.

Note: OC4J JSP implementation details, such as use of underscores ("_") in output directory names, are subject to change from release to release. This documentation applies specifically to Oracle9iAS release 2.

Batch Pre-Translation with ojspc

Beginning with the OC4J 9.0.3 implementation, there are ojspc features for batch pre-translation of JSP files in archive files (JAR, WAR, EAR, or ZIP files). When you specify an archive file on the ojspc command line, by default all .jsp and .sqljsp files in the contents will be pre-translated, and the archive file will be updated to include the output .class files and any Java resource files (but not .java or .sqlj files). You would then deploy the resulting archive file.

In addition to this basic functionality, you can use ojspc options to specify any of the following:

• Use the -batchMask option to specify file name extensions for pre-translation in addition to the default extensions *.jsp and *.sqljsp.

• Use the -output option to specify a new archive file for output. After pre-translation, this file will have copies of all the contents of the original archive file, as well as the output .class files (and any resource files) resulting from pre-translation. The original archive file will be unaltered.

• Use the -deleteSource option to specify that pre-translated JSP files will not be included in the resulting archive file. If you use the -output option, the JSP files will not appear in the specified output archive file. If you do not use the -output option, the JSP files will be removed from the original archive file. This applies to whatever JSP files are pre-translated (.jsp and .sqljsp files plus any files according to the -batchMask setting).

Standard JSP Pre-Translation without Execution

It is also possible to specify JSP pre-translation, without execution, when you invoke the page in the normal way. Accomplish this as follows:

1. Enable the JSP precompile_check configuration parameter. (See "JSP Configuration Parameters".)

2. Enable the standard jsp_precompile request parameter when invoking the JSP page from the browser.

Following is an example of using jsp_precompile:

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

or:

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

(The "=true" is optional.)

Refer to the Sun Microsystems JavaServer Pages Specification, Version 1.2, for more information about this mode of operation.

Deployment of Binary Files Only

You can avoid exposing your JSP source, for proprietary or security reasons, by pre-translating the 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 standard J2EE environment. This involves two steps:

1. You must archive and deploy the binary files appropriately.

2. In the target environment, the JSP container must be configured to run pages without the JSP source being available.

Archiving and Deploying the Binary Files

You must take steps to create and archive the binary files in an appropriate hierarchy.

• If you pre-translate with ojspc, you must first set your current directory to the application root directory. After running ojspc, archive the output files using the ojspc output directory as the base directory for the archive. See "The ojspc Pre-Translation Utility" for general information about this utility.

• If you are archiving binary files produced during previous execution in an on-demand translation environment, then archive the output directory structure, typically under the _pages directory.

In the target environment, place the archive JAR file in the /WEB-INF/lib directory; or restore the archived directory structure under the appropriate directory, typically under the _pages directory.

Configuring the OC4J JSP Container for Execution with Binary Files Only

If you have deployed binary files to an OC4J environment, set the JSP configuration parameter main_mode to the value justrun or reload to execute JSP pages without the original source.

Without this setting, the JSP translator will always look for the JSP source file to see if it has been modified more recently than the page implementation .class file, and terminate with a "file not found" error if it cannot find the source file.

With main_mode 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 how to set configuration parameters in the OC4J environment, see "Setting JSP Configuration Parameters in OC4J".