A
Getting Started in Alternative Environments

This appendix provides information about configuring the Web server to run Oracle JSP and configuring Oracle JSP in alternative environments. The technical information focuses on the following environments:

• JSWDK (the Sun Microsystems JavaServer Web Developer's Kit)
• Tomcat (from Apache, in cooperation with Sun Microsystems)

This appendix includes the following topics:

• Configuration of Web Server and Servlet Environment for Oracle JSP
• Oracle JSP Configuration Parameter Settings

  Note: For installation and configuration information for the JServ environment, provided with Oracle9i release 2, as well as for general configuration information and required files, see "Getting Started in a JServ Environment". For information for an OC4J environment, refer to the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference.

Configuration of Web Server and Servlet Environment for Oracle JSP

Configuring your Web server to run the Oracle JSP container requires the following general steps:

1. Add JSP-related JAR and ZIP files to the Web server classpath.
2. Configure the Web server to map JSP file name extensions (.jsp and .JSP and, optionally, .sqljsp and .SQLJSP) to the Oracle JspServlet, which is the front-end of the Oracle JSP container.

These steps apply to any Web server environment, but the information in this section focuses on the Sun Microsystems JSWDK and Tomcat.

Adding Oracle JSP-Related JAR and ZIP Files to Web Server Classpath

You must update the Web server classpath to add JAR and ZIP files that are required by the Oracle JSP container, being careful to add them in the proper order. (In particular, you must be careful as to where you place the servlet 2.2 version of servlet.jar in the classpath, as described below.) This includes the following:

• ojsp.jar
• xmlparserv2.jar
• servlet.jar (servlet 2.2 version)

  Note that the servlet.jar supplied with Oracle9i release 2 is identical to the servlet.jar provided with Tomcat 3.1.

• ojsputil.jar (optional, for JML tags, SQL tags, and data-access JavaBeans)
• xsu12.jar, for JDK 1.2.x, or xsu111.jar, for JDK 1.1.x (optional, for XML functionality for JML tags, SQL tags, and data-access JavaBeans)
• additional optional ZIP and JAR files, as necessary, for JDBC and SQLJ

See "Required and Optional Files for Oracle JSP" for additional information.

Add Files to Classpath for the JSWDK Environment

Update the startserver script in the jswdk-1.0 root directory to add files required by the Oracle JSP container to the jspJars environment variable. Append them to the last .jar file listed, using the appropriate directory syntax and separator character for your operating system, such as a colon (":") for UNIX or a semi-colon (";") for Windows NT. Here is an example:

jspJars=./lib/jspengine.jar:./lib/ojsp.jar:./lib/ojsputil.jar

This example (with UNIX syntax) assumes that the JAR files are in the lib subdirectory under the jswdk-1.0 root directory.

Similarly, update the startserver script to specify any additional required files in the miscJars environment variable, such as in the following example:

miscJars=./lib/xml.jar:./lib/xmlparserv2.jar:./lib/servlet.jar

This example (with UNIX syntax) also assumes that the files are in the lib subdirectory under the jswdk-1.0 root directory.

Add Files to Classpath for the Tomcat Environment

For Tomcat, the procedure for adding files to the classpath is more operating-system dependent than for the other servlet environments discussed here.

For a UNIX operating system, copy the JSP-related JAR and ZIP files to your [TOMCAT_HOME]/lib directory. This directory is automatically included in the Tomcat classpath.

For a Windows NT operating system, update the tomcat.bat file in the [TOMCAT_HOME]\bin directory to individually add each file to the CLASSPATH environment variable. The following example presumes that you have copied the files to the [TOMCAT_HOME]\lib directory:

set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\ojsp.jar;%TOMCAT_HOME%\lib\ojsputil.jar

The servlet 2.2 version of servlet.jar (the same version that is provided with Oracle9i release 2) is already included with Tomcat, so it needs no consideration.

Mapping JSP File Name Extensions to Oracle JspServlet

You must configure the Web server to be able to do the following:

• It must recognize appropriate file name extensions as JSP pages.

  Map .jsp and .JSP. Also map .sqljsp and .SQLJSP if your JSP pages use Oracle SQLJ.

• It must find and execute the servlet that begins processing JSP pages.

  For the Oracle JSP container, this is oracle.jsp.JspServlet, which you can think of as the front-end of the JSP container.

  Important: With the above configurations, the Oracle JSP container will support page references that use either a .jsp file name extension or a .JSP file name extension, but the case in the reference must match the actual file name in a case-sensitive environment. If the file name is file.jsp, you can reference it that way, but not as file.JSP. If the file name is file.JSP, you can reference it that way, but not as file.jsp. (The same holds true for .sqljsp versus .SQLJSP.)

Map File Name Extensions for the JSWDK Environment

In a JSWDK environment, mapping each JSP file name extension to the Oracle JspServlet requires two steps.

1. The first step is to update the mappings.properties file in the WEB-INF directory of each servlet context to define JSP file name extensions. Do this with the following commands:

   # Map JSP file name extensions (.sqljsp and .SQLJSP are optional).
   .jsp=jsp
   .JSP=jsp
   .sqljsp=jsp
   .SQLJSP=jsp
   
   

2. The second step is to update the servlet.properties file in the WEB-INF directory of each servlet context to define the Oracle JspServlet as the servlet that begins JSP processing. In addition, be sure to comment out the previously defined mapping for the JSP reference implementation. Do this as follows:

   #jsp.code=com.sun.jsp.runtime.JspServlet (replacing this with Oracle)
   jsp.code=oracle.jsp.JspServlet
   
   

Map File Name Extensions for the Tomcat Environment

In a Tomcat environment, mapping each JSP file name extension to the Oracle JspServlet requires a single step. Update the servlet mapping section of the web.xml file as shown below.

# Map file name extensions (.sqljsp and .SQLJSP are optional).

<servlet-mapping>
   <servlet-name>
      oracle.jsp.JspServlet
   </servlet-name>
   <url-pattern>
      *.jsp
   </url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>
      oracle.jsp.JspServlet
   </servlet-name>
   <url-pattern>
      *.JSP
   </url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>
      oracle.jsp.JspServlet
   </servlet-name>
   <url-pattern>
      *.sqljsp
   </url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>
      oracle.jsp.JspServlet
   </servlet-name>
   <url-pattern>
      *.SQLJSP
   </url-pattern>
</servlet-mapping>

You can optionally set an alias for the oracle.jsp.JspServlet class name, as follows:

<servlet>
   <servlet-name>
      ojsp
   </servlet-name>
   <servlet-class>
      oracle.jsp.JspServlet
   </servlet-class>
   ...
</servlet>

Setting this alias allows you to use "ojsp" instead of the class name for your other settings, as follows:

<servlet-mapping>
   <servlet-name>
      ojsp
   </servlet-name>
   <url-pattern>
      *.jsp
   </url-pattern>
</servlet-mapping>

Oracle JSP Configuration Parameter Settings

The Oracle JSP front-end servlet, JspServlet, supports a number of configuration parameters to control operation of the JSP container. These are described in "Oracle JSP Configuration Parameters". They are set as servlet initialization parameters for JspServlet. How you accomplish this depends on the Web server and servlet environment you are using.

This section describes how to set them in the JSWDK and Tomcat servlet environments.

Setting Oracle JSP Parameters in JSWDK

To set JSP configuration parameters in a JSWDK environment, set the jsp.initparams property in the servlet.properties file in the WEB-INF directory of the application servlet context, as in the following example (which happens to use UNIX syntax):

jsp.initparams=developer_mode=false,classpath=/mydir/myapp.jar

Setting Oracle JSP Parameters in Tomcat

To set JSP configuration parameters in a Tomcat environment, add init-param entries in the web.xml file as shown below.

<servlet>
   <init-param>
      <param-name>
         developer_mode
      </param-name>
      <param-value>
         true
      </param-value>
   </init-param>
   <init-param>
      <param-name>
         external_resource
      </param-name>
      <param-value>
         true
      </param-value>
   </init-param>
   <init-param>
      <param-name>
         javaccmd
      </param-name>
      <param-value>
         javac -verbose
      </param-value>
   </init-param>
</servlet>