3 Getting Started

Application Root Functionality

The servlet specification (since servlet 2.2) provides 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 standard servlet 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 document 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 Oracle Application Server 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 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.

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 (.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 J2EE home directory in OC4J and depends on the value of the jsp-cache-directory configuration parameter. See "JSP Translator Output File Locations" for information.

Runtime Retranslation or Reloading

During runtime, any retranslation of JSP pages or reloading of JSP page implementation classes is controlled by the JSP main_mode configuration parameter. Possible settings are recompile (default) to retranslate JSP pages that have changed, reload to reload classes that were generated by the JSP container and have changed (such as page implementation classes), or justrun to run without any timestamp-checking, for optimal performance in production environments. See "JSP Configuration Parameter Descriptions" for additional information.

For information about classloading behavior at the servlet layer, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

JSP Compilation Considerations

Java compilation can be either in-process, running in the same process as OC4J, or out-of-process, running in a separate process.

By default, OC4J as a whole uses out-of-process compilation, and the compiler is invoked as a separate executable. The default compiler executable is javac from the Sun Microsystems JDK; however, you can configure OC4J to use a different compiler. In OC4J standalone, you can accomplish this by adding a <java-compiler> element, with desired settings, to the OC4J server.xml file. In an Oracle Application Server environment, use Oracle Enterprise Manager 10g to change this configuration.

For improved JSP performance, however, the OC4J JSP container uses in-process compilation by default, assuming that the tools.jar file of the Sun Microsystems JDK is installed and in the classpath. With in-process compilation, the compiler class is invoked directly. You can use a <library> element in the server.xml file to ensure that tools.jar is in the classpath.

There are also two related JSP configuration parameters: use_old_compiler and javaccmd:

• You can set use_old_compiler to false to force the JSP container to use the same compiler as the rest of OC4J—out-of-process compilation with javac by default, or compilation according to a <java-compiler> element in server.xml. The use_old_compiler flag is set to true by default if tools.jar is in the classpath, resulting in in-process compilation unless javaccmd is set.

• If you want to use an out-of-process compiler, but not the compiler that the rest of OC4J uses, then set use_old_compiler to true and use the javaccmd parameter to specify the desired compiler. (The javaccmd parameter is ignored if use_old_compiler is set to false.)

  
  

  Notes: If tools.jar is not in the classpath, then use_old_compiler is forced to a false setting. The use_old_compiler and javaccmd parameters are further discussed under "JSP Configuration Parameter Descriptions". See the Oracle Application Server Containers for J2EE User's Guide for information about elements of the server.xml file.

  
  

JSP Security Considerations

With respect to application security, be aware that you should verify that the debug_mode parameter has its default false setting if you want to suppress the display of the physical file path when nonexistent JSP files are requested. This parameter is described in "JSP Configuration Parameter Descriptions".

JSP Performance Considerations

The following sections summarize JSP, OC4J, and Oracle Application Server features for performance optimization and monitoring:

• Programmatic Considerations for Optimization

• Configuration Optimizations

• The ojspc Utility for Pretranslation

• Additional OC4J and Oracle Application Server Performance Features

Default Package Imports

Beginning with Oracle9iAS Release 2 (9.0.3), the OC4J JSP container by default imports the following packages into any JSP page, in accordance with the JSP specification. No page directive import settings are required:

javax.servlet.*
javax.servlet.http.*
javax.servlet.jsp.*

In earlier releases, the following packages were also imported by default:

java.io.*
java.util.*
java.lang.reflect.*
java.beans.*

The default list of packages to import was reduced to minimize the chance of a conflict between any unqualified class name you might use and a class by the same name in any of the imported packages.

However, this might result in migration problems for applications you have used with previous versions of OC4J. Such applications might no longer compile successfully. If you need imports beyond the default list, you have two choices:

• Specify additional package names or fully qualified class names in one or more page directive import settings. For more information, see the page directive under "Directives", and see "Page Directive import Settings Are Cumulative".

  For multiple pages, you can accomplish this through global includes functionality. See "Oracle JSP Global Includes".

• Specify additional package names or fully qualified class names through the JSP extra_imports configuration parameter, or by using the ojspc -extraImports option for pretranslation. Syntax varies between OC4J configuration parameter settings and ojspc option settings, so refer to the following sections as appropriate:

  • "JSP Configuration Parameter Descriptions"

  • "Option Descriptions for ojspc"

JSP File Naming Conventions

The file name extension .jsp for JSP pages is required by the servlet specification. The servlet 2.3 specification does not, however, distinguish between complete pages that are independently translatable and page segments that are not (such as files brought in through an include directive).

The JSP 1.2 specification recommends the following:

• Use the .jsp extension for top-level pages, dynamically included pages, and pages that are forwarded to—pages that are translatable on their own.

• Do not use .jsp for page segments brought in through include directives—files that are not translatable on their own. No particular extension is mandated for such files, but .jsph, .jspf, or .jsf is recommended.

Removal of tools.jar from OC4J Standalone

The OC4J 9.0.3 standalone implementation provided the tools.jar file from the Sun Microsystems JDK 1.3.1. This file includes the java front-end executable and javac compiler executable, for example, among many other components.

The OC4J 10.1.2 standalone implementation no longer provides the tools.jar file. Therefore, you must install a JDK that OC4J supports before installing OC4J itself. The JDK versions that OC4J supports for the OC4J 10.1.2 implementation are JDK 1.3.1 (for OC4J standalone only) and JDK 1.4. Oracle Application Server 10g Release 2 (10.1.2) includes JDK 1.4, so you should typically use this JDK version for OC4J standalone as well. However, there are migration issues to consider, particularly the JDK 1.4 requirement that all invoked classes must be in packages. See "JDK 1.4 Considerations: Cannot Invoke Classes Not in Packages" below.

JDK 1.4 Considerations: Cannot Invoke Classes Not in Packages

Among the migration considerations in moving to a Sun Microsystems JDK 1.4 environment, which is the environment that is shipped with Oracle Application Server 10g Release 2 (10.1.2), there is one of particular importance to servlet and JSP developers.

As stated by Sun Microsystems, "The compiler now rejects import statements that import a type from the unnamed namespace." This was to address security concerns and ambiguities with previous JDK versions. Essentially, this means that you cannot invoke a class (a method of a class) that is not within a package. Any attempt to do so will result in a fatal error at compilation time.

This especially affects JSP developers who invoke JavaBeans from their JSP pages, as such beans are often outside of any package (although the JSP 2.0 specification now requires beans to be within packages, in order to satisfy the new compiler requirements). Where JavaBeans outside of packages are invoked, JSP applications that were built and executed in an OC4J 9.0.3 / JDK 1.3.1 environment will no longer work in an OC4J 10.1.2 / JDK 1.4 environment.

Until you update your application so that all JavaBeans and other invoked classes are within packages, you can avoid this issue by reverting back to a JDK 1.3.1 environment for OC4J standalone. Note that JDK 1.3.x is not supported in a full Oracle Application Server 10.1.2 environment.

For more information about the "classes not in packages" issue and other JDK 1.4 compatibility issues, refer to the following Web site:

http://java.sun.com/j2se/1.4/compatibility.html

In particular, click the link "Incompatibilities Between Java 2 Platform, Standard Edition, v1.4.0 and v1.3".

JSP Container Setup

The JSP container is appropriately preconfigured 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>

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

See the Oracle Application Server 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. The following subsections provide a summary table, detailed descriptions, and documentation of how to set them in the OC4J global-web-application.xml or orion-web.xml file:

• JSP Configuration Parameter Summary Table

• JSP Configuration Parameter Descriptions

• Setting JSP Configuration Parameters in OC4J

   <init-param>
      <param-name>extra_imports</param-name>
      <param-value>java.util.* java.beans.*</param-value>
   </init-param>

   <init-param>
      <param-name>extra_imports</param-name>
      <param-value>java.util.*,java.beans.*</param-value>
   </init-param>

<% if (cond) { %> 
      <jsp:useBean id="foo" class="pkgA.Foo1" /> 
<% } else { %> 
      <jsp:useBean id="foo" class="pkgA.Foo2" /> 
<% } %>

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

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

OC4J Configuration Parameters for JSP

There are also OC4J configuration parameters—as opposed to parameters for the JspServlet front-end servlet of the JSP container—which affect JSP pages. This section documents JSP-related attributes of the root <orion-web-app> element of the OC4J global-web-application.xml file or orion-web.xml file. For more information about these files, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

<orion-web-app ... jsp-print-null="false" ... >
...
</orion-web-app>

Application Server Control Console JSP Properties Page

Figure 3-1 shows the key portion of the Application Server Control Console JSP Properties Page for an OC4J instance.

Figure 3-1 Application Server Control Console JSP Properties Page

Description of "Figure 3-1 Application Server Control Console JSP Properties Page"

When you first access an Oracle Application Server instance through Application Server Control Console in Enterprise Manager, you reach the Oracle Application Server Instance Home Page. You can drill down to the JSP Properties Page as follows:

1. From the Oracle Application Server Instance Home Page, select the name of an OC4J instance in the System Components table. Things brings you to the OC4J Home Page for the OC4J instance.

2. From the OC4J Home Page, click Administration. This brings you to the OC4J Administration Page.

3. From the OC4J Administration Page, click JSP Container Properties under Instance Properties. This brings you to the JSP Properties Page

For further information about using Enterprise Manager, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide for an overview of Web application deployment and configuration or the Oracle Application Server Containers for J2EE User's Guide for information about any OC4J-related deployment and configuration.

Configuration Parameters Supported by the JSP Properties Page

Table 3-2 shows the correspondence between JSP container properties shown in the Application Server Control Console JSP Properties Page in Enterprise Manager, and configuration parameters of the JSP container front-end servlet as described in "JSP Configuration Parameters". See that section for the meanings of the settings.

Possible settings are shown with defaults in bold. Note that Application Server Control Console defaults are appropriate for a production environment, so are not necessarily the same as defaults otherwise, which are appropriate for a development environment.

Configuration Parameters Not Supported by the JSP Properties Page

As of Oracle Application Server 10g Release 2 (10.1.2), the following configuration parameters are not yet supported through the Application Server Control Console JSP Properties Page:

• JSP front-end servlet parameters: check_page_scope, extra_imports, forgive_dup_dir_attr, no_tld_xml_validate, old_include_from_top, req_time_introspection, and well_known_taglib_loc.

• JSP-related attributes of the <orion-web-app> element in global-web-application.xml or orion-web.xml: jsp-print-null and jsp-timeout, jsp-cache-directory, jsp-cache-tlds, jsp-taglib-locations, simple-jsp-mapping, and enable-jsp-dispatcher-shortcut.

Instead, you must update them in orion-web.xml or other appropriate XML file (such as web.xml or global-web-application.xml). Edit orion-web.xml or global-web-application.xml through the Application Server Control Console Web Module Advanced Properties Page, as described in the Oracle Application Server Containers for J2EE Servlet Developer's Guide. Also see "Setting JSP Configuration Parameters in OC4J" and "Setting JSP-Related OC4J Configuration Parameters" for related information.