3
Getting Started

This chapter covers basic issues in your JSP environment, including key support files, key OC4J configuration files, configuration of the JSP container, and other initial considerations such as application root and classpath functionality.

Before getting started, it is assumed that you can do the following on your system:

run Java
run a Java compiler (typically the standard javac)
run an HTTP servlet

The following topics are covered here:

Key Support Files Provided with OC4J
JSP Configuration in OC4J
Key OC4J Configuration Files

Some Initial Considerations

Notes:

JSP pages will run with any standard browser supporting HTTP 1.0 or higher. The JDK or other Java environment in the end-user's Web browser is irrelevant, because all the Java code in a JSP page is executed in the Web server.

Key Support Files Provided with OC4J

This section summarizes JAR and ZIP files that are used by the JSP container or JSP applications. These files are installed on your system and into your classpath with OC4J:

ojsp.jar--classes for the JSP container
ojsputil.jar--classes for tag libraries and utilities provided with OC4J
xmlparserv2.jar--for XML parsing; required for the web.xml deployment descriptor and any tag library descriptor files and XML-related tag functionality
xsu12.jar / xsu111.jar--for XML functionality on the client (for JDK 1.2.x or higher, or 1.1.x, respectively)
classes12.zip / classes111.zip--for the Oracle JDBC drivers (for JDK 1.2.x or higher, or 1.1.x, respectively)
translator.zip--for the Oracle SQLJ translator
runtime12.zip / runtime12ee.zip / runtime11.zip / runtime.zip / runtime-nonoracle.zip--for the Oracle SQLJ runtime (respectively: for JDK 1.2.x or higher with Oracle9i JDBC, JDK 1.2.x or higher enterprise edition with Oracle9i JDBC, JDK 1.1.x with Oracle9i JDBC, any 1.1.x or higher JDK with any Oracle JDBC version, or any JDK environment with non-Oracle JDBC drivers)
jndi.jar--for JNDI service for lookup of resources such as JDBC data sources and Enterprise JavaBeans
jta.jar--for the Java Transaction API

There are also files relating to particular areas, such as particular tag libraries. These include the following:

mail.jar--for e-mail functionality within applications (standard javax.mail package)
activation.jar--Java activation files for e-mail functionality
cache.jar--for the Oracle9i Application Server Java Object Cache (which can be used by the OC4J Web Object Cache as the back-end repository)

Note:
The .zip files are also provided as .jar files.

JSP Configuration in OC4J

This section covers the following topics regarding configuration of the JSP environment:

JSP Container Setup

JSP Configuration Parameters

Note:

For non-OC4J environments, including JServ, use the old oracle.jsp.JspServlet front-end servlet instead of the oracle.jsp.runtimev2.JspServlet version. See "Getting Started in a JServ Environment".

JSP Container Setup

The JSP container is appropriately pre-configured in OC4J. The following settings appear in the OC4J global-web-application.xml file to map the name of the front-end JSP servlet, and to map the appropriate file name extensions for JSP pages:

<orion-web-app ... >
   ...
   <web-app>
       ...
      <servlet>
         <servlet-name>jsp</servlet-name>
         <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class>
         ...
            init params
         ...
      </servlet>
      ...
      <servlet-mapping>
         <servlet-name>jsp</servlet-name>
         <url-pattern>/*.jsp</url-pattern>
      </servlet-mapping>
      <servlet-mapping>
          <servlet-name>jsp</servlet-name>
          <url-pattern>/*.JSP</url-pattern>
       </servlet-mapping>
       <servlet-mapping>
           <servlet-name>jsp</servlet-name>
           <url-pattern>/*.sqljsp</url-pattern>
       </servlet-mapping>
      <servlet-mapping>
           <servlet-name>jsp</servlet-name>
           <url-pattern>/*.SQLJSP</url-pattern>
      </servlet-mapping>

      ...
   </web-app>
   ...
</orion-web-app>

See the Oracle9iAS Containers for J2EE Servlet Developer's Guide for more information about the global-web-application.xml file.

JSP Configuration Parameters

The JSP front-end servlet in OC4J, oracle.jsp.runtimev2.JspServlet, supports a number of configuration parameters to control JSP operation. This section describes those parameters, starting with a summary table and then providing more complete descriptions.

Configuration Parameter Summary Table

Table 3-1 summarizes the configuration parameters supported by JspServlet. For each parameter, the table notes any equivalent ojspc translation options for pages you are pre-translating, and whether the parameter is for runtime or compile-time use.

Notes:

See "The ojspc Pre-Translation Utility" for a description of the ojspc options.

Table 3-1 JSP Configuration Parameters, OC4J Environment

Parameter	Related ojspc Options	Description	Default	Runtime / Compile- Time
debug_mode	(n/a)	Set this boolean to `true` to print the stack trace when a runtime exception occurs.	true	runtime
emit_debuginfo	-debug	Set this boolean to `true` to generate a line map to the original `.jsp` file for debugging (for development).	false	compile-time
external_resource	-extres	Set this boolean to `true` to place all static content of the page into a separate Java resource file during translation.	false	compile-time
javaccmd	-noCompile	Use this if you want to specify a `javac` command line, or if you want to specify an alternative Java compiler, optionally with command-line settings (for development). If you specify an alternative compiler, it will be spawned in a separate JVM (`javac` runs in the same JVM). A `null` setting means use the JDK `javac` with default settings.	null	compile-time
main_mode	(n/a)	This determines whether classes are automatically reloaded or JSP pages are automatically recompiled, in case of changes. Possible settings are `justrun`, `reload`, and `recompile`.	recompile	runtime
old_include_from_top	-oldIncludeFromTop	Set this boolean to `true` for page locations in nested `include` directives to be relative to the top-level page, for backward compatibility with behavior prior to Oracle9iAS release 2.	false	compile-time
precompile_check	(n/a)	Set this boolean to `true` to check the HTTP request for a standard `jsp_precompile` setting.	false	runtime
reduce_tag_code	-reduceTagCode	Set this boolean to `true` for further reduction in the size of generated code for custom tag usage.	false	compile-time
req_time_introspection	-reqTimeIntrospection	Set this boolean to `true` to enable request-time JavaBean introspection whenever compile-time introspection is not possible.	false	compile-time
sqljcmd	-S	Use this if you want to specify a SQLJ command line, or if you want to specify an alternative SQLJ translator, optionally with command-line settings (for development). If you specify an alternative translator, it will be spawned in a separate JVM. A `null` setting means use the Oracle SQLJ version provided with Oracle9iAS, with its default option settings.	null	compile-time
static_text_in_chars	-staticTextInChars	Set this boolean to `true` to instruct the JSP translator to generate static text in JSP pages as characters instead of bytes.	false	compile-time
tags_reuse_default	(n/a)	This specifies a default setting for JSP tag handler pooling (`true` to enable by default; `false` to disable by default). You can override this default setting for any particular JSP page.	true	runtime
xml_validate	-xmlValidate	This specifies whether XML validation is performed on the `web.xml` file and TLD files.	false	compile-time

Configuration Parameter Descriptions

This section describes the JSP configuration parameters for OC4J in more detail.

debug_mode

(boolean; default: true)

Use the default true setting to print a stack trace whenever a runtime exception occurs. Set it to false to disable this feature.

Note:

When debug_mode is false and a file is not found, the full path of the missing file is not displayed.

emit_debuginfo

(boolean; default: false)

During development, set this flag to true to instruct the JSP translator to generate a line map to the original .jsp file for debugging. Otherwise, lines will be mapped to the generated page implementation class .java file.

Notes:

Oracle9i JDeveloper enables emit_debuginfo.
For pre-translating pages, the ojspc -debug option is equivalent.

external_resource

(boolean; default: false)

Set this flag to true to instruct the JSP translator to place generated static content (the Java print commands that output static HTML code) into a Java resource file, instead of into the service method of the generated page implementation class.

The resource file name is based on the JSP page name, with the .res suffix. With Oracle9iAS 9.0.2, translation of MyPage.jsp, for example, would create _MyPage.res in addition to normal output. The exact implementation may change in future releases, however.

The translator places the resource file into the same directory as generated 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".

Note:

For pre-translating pages, the ojspc -extres option is equivalent.

javaccmd

(compiler executable; default: null)

This parameter is useful in either of the following circumstances:

if you want to set javac command-line options (although default settings are typically sufficient)
if you want to use a compiler other than javac (optionally including command-line options)
if you want to run the Java compiler in a separate process from the JSP container

Specifying an alternative compiler results in that executable being spawned as a separate process in a separate JVM, instead of within the same JVM as the JSP container. You can fully specify the path for the executable, or specify only the executable and let the JSP container look for it in the system path.

For example, set javaccmd to the value javac -verbose to run the compiler in verbose mode.

Notes:

The specified Java compiler must be installed in the classpath and any front-end utility (if applicable) must be installed in the system path.
For pre-translating pages, the ojspc -noCompile option allows similar functionality. It results in no compilation by javac, so you can compile the translated classes manually, using any desired compiler.

main_mode

(mode switch for reloading or recompilation; default: recompile)

This is a flag to direct the mode of operation of the JSP container, particularly for automatic recompilation of JSP pages and reloading of Java classes that have changed.

Here are the supported settings:

justrun--The runtime dispatcher will not perform any timestamp checking, so there is no recompilation of JSP pages or reloading of Java classes. This mode is the most efficient mode for a deployment environment, where code will not change.
reload--The dispatcher will check if any classes have been modified since loading, including translated JSP pages, JavaBeans invoked from pages, and any other dependency classes.
recompile (default)--The dispatcher will check the timestamp of the JSP page, retranslate it and reload it if has been modified since loading, and execute all reload functionality as well.

old_include_from_top

(backward compatibility for include; default: false)

This is for backward compatibility with Oracle JSP versions prior to Oracle9iAS release 2, for functionality of include directives. If set to true, page locations in nested include directives are relative to the top-level page. If set to false, page locations are relative to the immediate parent page, as per the JSP 1.2 specification.

Note:

For pre-translating pages, the ojspc -oldIncludeFromTop option is equivalent.

precompile_check

(jsp_precompile checking; default: false)

Set this to true to check the HTTP request for a standard jsp_precompile setting. If precompile_check is true and the request enables jsp_precompile, then the JSP page will be pre-translated only, without execution. Setting precompile_check to false improves performance and ignores any jsp_precompile setting in the request.

For more information about jsp_precompile, see "Standard JSP Pre-Translation Without Execution", and the Sun Microsystems JavaServer Pages Specification, Version 1.1.

reduce_tag_code

(flag for size reduction of custom tag code; default: false)

The Oracle9iAS release 2 implementation reduces the size of generated code for custom tag usage, but setting reduce_tag_code to true results in even further size reduction. There may be performance consequences regarding tag handler reuse, however. See "Tag Handler Code Generation".

Note:

For pre-translating pages, the ojspc -reduceTagCode option is equivalent.

req_time_introspection

(flag for request-time introspection; default: false)

A true setting enables 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 an example of a scenario for use of request-time introspection, assume a tag handler returns a generic java.lang.Object instance in VariableInfo 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 and Tag-Extra-Info Classes" for information about use of VariableInfo.)

Note:

For pre-translating pages, the ojspc -reqTimeIntrospection option is equivalent.

sqljcmd

(SQLJ translator executable and options; default: null)

This parameter is useful in any of the following circumstances:

if you want to set one or more SQLJ command-line options
if you want to use a different SQLJ translator, or at least a different version, than the one provided with OC4J
if you want to run SQLJ in a separate process from the JSP container

Specifying a SQLJ translator executable results in its being spawned as a separate process in a separate JVM, instead of within the same JVM as the JSP container.

You can fully specify the path for the executable, or specify only the executable and let the JSP container look for it in the system path.

For example, to run SQLJ with online semantics checking as user scott/tiger and with the -ser2class option enabled, set sqljcmd to the following value:

sqlj -user=scott/tiger -ser2class=true

Appropriate SQLJ libraries must be in the classpath, and any front-end utility (such as sqlj in the example) must be in the system path. For Oracle SQLJ, the translator ZIP or JAR file and the appropriate SQLJ runtime ZIP or JAR file must be in the classpath. See "Key Support Files Provided with OC4J".

Notes:

For pre-translating pages, the ojspc -S option provides related functionality.

static_text_in_chars

(flag to generate static text as characters; default: false)

A true setting directs the JSP translator to generate static text in JSP pages as characters, instead of bytes. 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"); %>

Place this statement as close to the beginning of the page as possible.

The false default setting improves performance in outputting static text blocks.

Note:

For pre-translating pages, the ojspc -staticTextInChars option is equivalent.

tags_reuse_default

(default setting for tag handler pooling; default: true)

You can specify whether JSP tag handler instances are pooled by setting an attribute in the JSP page context. See "Disabling or Enabling Tag Handler Instance Pooling" for information about this.

If there is no setting in the page context, then the behavior is determined by the tags_reuse_default setting, or is according to a setting of true (the "default default") if tags_reuse_default is not specified.

xml_validate

(XML validation of web.xml and TLD files; default: false)

This flag specifies whether XML validation is performed on the application web.xml file and any tag library description (TLD) files. Because the Tomcat JSP reference implementation does not perform XML validation, xml_validate is false by default.

Note:

For pre-translating pages, the ojspc -xmlValidate option is equivalent.

Setting JSP Configuration Parameters in OC4J

In the OC4J environment, you can set JSP configuration parameters in the global-web-application.xml file, inside the servlet tag for the JSP front-end servlet. In the portion of this file shown in "JSP Container Setup", the settings would go where the init params place holder appears.

The following example lists servlet tag and subtag settings for the JSP front-end servlet. This sample enables the precompile_check flag, sets the main_mode flag to run without checking timestamps, and runs the Java compiler in verbose mode.

<servlet>
   <servlet-name>jsp</servlet-name>
   <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class>
   <init-param>
      <param-name>precompile_check</param-name>
      <param-value>true</param-value>
   </init-param>
   <init-param>
      <param-name>main_mode</param-name>
      <param-value>justrun</param-value>
   </init-param>
   <init-param>
      <param-name>javaccmd</param-name>
      <param-value>javac -verbose</param-value>
   </init-param>
</servlet>

You can override any settings in the global-web-application.xml file with settings in the web.xml file for a particular application.

Key OC4J Configuration Files

Be aware of the following key configuration files in the OC4J environment.

Global files for all OC4J applications, in the OC4J /j2ee/home/config directory:

server.xml--This has an overall <application-server> element, with an <application> subelement for each J2EE application. Each <application> subelement specifies the name of the application and the name and location of its EAR deployment file. The <application-server> element specifies the name of the general application source directory, where EAR files are placed for deployment and extracted, and the application deployment directory, where OC4J-specific configuration files are generated. Additionally, there is a <web-site> element for the default Web site, and you can add a <web-site> element for each additional Web site you want to have on the server.
default-web-site.xml--This includes a <web-app> element for each Web application for the default Web site, mapping the application name to the "Web application name". The Web application name corresponds to the WAR deployment file name. Additional Web site XML files, as specified for additional Web sites in the server.xml file, have the same functionality.
global-web-application.xml--This is a global configuration file for OC4J Web applications. It establishes default configurations and includes setup and configuration of the JSP front-end servlet, JspServlet.
application.xml--This is another parent configuration file for OC4J applications.
data-sources.xml--This specifies data sources for database connections.

In addition to the global application.xml file, there is a standard application.xml file, and optionally an orion-application.xml file, for each application. These files are in the application EAR file.

Also, in an application WAR file, which is inside the application EAR file, there is a standard web.xml file and optionally an orion-web.xml file. These are for application-specific and deployment-specific configuration settings, overriding global-web-application.xml settings or providing additional settings as appropriate. The global-web-application.xml and orion-web.xml files support the same elements, which is a superset of those supported by the web.xml file.

If the orion-application.xml and orion-web.xml files are not present in the archive files, they will be generated during initial deployment, according to settings in the global-web-application.xml file.

For information about the use of these files, see the Oracle9iAS Containers for J2EE User's Guide and the Oracle9iAS Containers for J2EE Servlet Developer's Guide. For additional information, see "Overview of EAR/WAR Deployment".

Some Initial Considerations

This section discusses some initial considerations you should be aware of before running or deploying JSP pages:

Application Root Functionality

The servlet 2.2 and 2.3 specifications provide for each Web application to have its own servlet context. Each servlet context is associated with a directory path in the server file system, which is the base path for modules of the Web application. This is the application root. Each Web application has its own application root. For a Web application in a servlet 2.2 or 2.3 environment, servlets, JSP pages, and static files such as HTML files are all based out of this application root. (By contrast, in servlet 2.0 environments the application root for servlets and JSP pages is distinct from the doc root for static files.)

Note that a servlet URL has the following general form:

http://host[:port]/contextpath/servletpath

When a servlet context is created, a mapping is specified between the application root and the context path portion of a URL. The servlet path is defined in the application web.xml file. The <servlet> element within web.xml associates a servlet class with a servlet name. The <servlet-mapping> element within web.xml associates a URL pattern with a named servlet. When a servlet is executed, the servlet container will compare a specified URL pattern with known servlet paths, and pick the servlet path that matches. See the Oracle9iAS Containers for J2EE Servlet Developer's Guide for more information.

For example, consider an application with the application root /home/dir/mybankapp/mybankwebapp, which is mapped to the context path /mybank. Further assume the application includes a servlet whose servlet path is loginservlet. You can invoke this servlet as follows:

http://host[:port]/mybank/loginservlet

The application root directory name itself is not visible to the end-user.

To continue this example for an HTML page in this application, the following URL points to the file /home/dir/mybankapp/mybankwebapp/dir1/abc.html:

http://host[:port]/mybank/dir1/abc.html

For each servlet environment there is also a default servlet context. For this context, the context path is simply "/", which is mapped to the default servlet context application root. For example, assume the application root for the default context is /home/dir/defaultapp/defaultwebapp, and a servlet with the servlet path myservlet uses the default context. Its URL would be as follows:

http://host[:port]/myservlet

The default context is also used if there is no match for the context path specified in a URL.

Continuing this example for an HTML file, the following URL points to the file /home/dir/defaultapp/defaultwebapp/dir2/def.html:

http://host[:port]/dir2/def.html

Classpath Functionality

The JSP container uses standard locations on the Web server to look for translated JSP pages, as well as.class files and .jar files for any required classes (such as JavaBeans). The container will find files in these locations without any Web server classpath configuration, and has the ability to automatically reload classes in these locations, depending on configuration settings.

The locations for dependency classes are as follows and are relative to the application root:

/WEB-INF/classes/...
/WEB-INF/lib

The location for JSP page implementation classes (translated pages) is as follows:

.../_pages/...

The /WEB-INF/classes directory is for individual Java .class files. You should store these classes in subdirectories under the classes directory, according to Java package naming conventions. For example, consider a JavaBean called LottoBean whose code defines it to be in the oracle.jsp.sample.lottery package. The JSP container will look for LottoBean.class in the following location relative to the application root:

/WEB-INF/classes/oracle/jsp/sample/lottery/LottoBean.class

The lib directory is for .jar files. Because Java package structure is specified in the .jar file structure, the .jar files are all directly in the lib directory (not in subdirectories). As an example, LottoBean.class might be stored in lottery.jar, located as follows relative to the application root:

/WEB-INF/lib/lottery.jar

The _pages directory is under the following directory in OC4J:

/j2ee/home/application-deployments/app-name/web-app-name/temp

The app-name is determined through an <application> element in the OC4J server.xml file; the web-app-name, which corresponds to the WAR file name, is mapped to the app-name through a <web-app> element in the OC4J default-web-site.xml file. See the Oracle9iAS Containers for J2EE User's Guide and the Oracle9iAS Containers for J2EE Servlet Developer's Guide for more information.

Generated page implementation classes for translated JSP pages are placed in subdirectories under the _pages directory according to the locations of the original .jsp files. See "Generated Files and Locations" for information.

Important:

Implementation details, such as the location of the _pages directory, are subject to change in future releases.

3Getting Started

Key Support Files Provided with OC4J

JSP Configuration in OC4J

JSP Container Setup

JSP Configuration Parameters

Configuration Parameter Summary Table

Table 3-1 JSP Configuration Parameters, OC4J Environment

Configuration Parameter Descriptions

debug_mode

emit_debuginfo

external_resource

javaccmd

main_mode

old_include_from_top

precompile_check

reduce_tag_code

req_time_introspection

sqljcmd

static_text_in_chars

tags_reuse_default

xml_validate

Setting JSP Configuration Parameters in OC4J

Key OC4J Configuration Files

Some Initial Considerations

Application Root Functionality

Classpath Functionality

3
Getting Started