OracleJSP Installation and Web Server Configuration

This section discusses OracleJSP installation and related Web server configuration for various JSP environments. The following environments are considered:

• Apache/JServ

• Sun Microsystems JSWDK

• Tomcat

• Oracle Servlet Engine (OSE)

• other Oracle environments

This discussion assumes that your target system, which might be either a development environment or a deployment environment, meets the requirements specified in "System Requirements". It also assumes that you have verified you can do the following:

• run Java

• run a Java compiler (typically the standard javac)

• run an HTTP servlet

  Note: Examples here are for a UNIX environment, but the basic information (such as directory names and file names) applies to other environments as well. Web server configuration information focuses on prevalent non-Oracle environments. For Oracle environments, refer to documentation for the particular product (such as Oracle Internet Application Server or Web-to-go).

Required and Optional Files for OracleJSP

This section summarizes JAR and ZIP files required for OracleJSP, as well as optional JAR and ZIP files to use Oracle JDBC and SQLJ functionality, JML or SQL custom tags, or custom data-access JavaBeans. The summary of files is followed by a discussion of how to install OracleJSP files on non-Oracle environments, and a list of Oracle environments that already provide OracleJSP.

Required files must also be added to your classpath. (See "Add OracleJSP-Related JAR and ZIP Files to Web Server Classpath".)

Summary of Files

Note: Refer to the Oracle8i Java Developer's Guide for the locations of these files on the Oracle8i product CD.

The following files are provided with OracleJSP and must be installed on your system:

• ojsp.jar (OracleJSP)

• xmlparserv2.jar (for XML parsing--required for the web.xml deployment descriptor and any tag library descriptors)

• servlet.jar (standard servlet library, servlet 2.2 version)

In addition, if your JSP pages will use Oracle JSP Markup Language (JML) tags, SQL tags, or database-access JavaBeans, you will need the following files:

• ojsputil.jar

• xsu12.jar (for JDK 1.2.x) or xsu111.jar (for JDK 1.1.x) (in OSE, or for XML functionality on the client)

To run in the Oracle Servlet Engine, xsu12.jar or xsu111.jar must be installed prior to or simultaneously with ojsputil.jar. (This should be handled automatically in a normal Oracle8i installation.) To run in a client environment, however, xsu12.jar or xsu111.jar is required only if you will use XML functionality in the database-access JavaBeans (such as getting a result set as an XML string). The xsu12.jar and xsu111.jar files are included with Oracle8i release 8.1.7.

Servlet Library Notes

Note that OracleJSP 8.1.7 requires and supplies the 2.2 version of the servlet library, which is where the standard javax.servlet.* packages are located. Your Web server environment likely requires and supplies a different servlet library version. You must be careful in your classpath to have the version for your Web server precede the version for OracleJSP. "Add OracleJSP-Related JAR and ZIP Files to Web Server Classpath" further discusses this.

Table A-1 summarizes the servlet library versions. Do not confuse the Sun Microsystems JSWDK (JavaServer Web Developer's Kit) with the Sun Microsystems JSDK (Java Servlet Developer's Kit).

Table A-1 Servlet Library Versions

Servlet Library Version	Library File Name	Provided with:
servlet 2.2	servlet.jar	OracleJSP, Tomcat 3.1
servlet 2.1	servlet.jar	Sun JSWDK 1.0
servlet 2.0	jsdk.jar	Sun JSDK 2.0; also used with Apache/JServ

(For Apache/JServ, jsdk.jar must be downloaded separately.)

The remainder of this section discusses files that are necessary only if you use certain optional or extended features.

Files for JDBC (optional)

The following files are required if you will use Oracle JDBC. (Be aware that Oracle SQLJ uses Oracle JDBC.)

• classes12.zip (for JDK 1.2.x environments)

or:

• classes111.zip (for JDK 1.1.x environments)

Files for SQLJ (optional)

The following files are necessary if your JSP pages use Oracle SQLJ for their Oracle8i access:

• translator.zip (for the SQLJ translator, for JDK 1.2.x or 1.1.x)

as well as the appropriate SQLJ runtime:

• runtime12.zip (for JDK 1.2.x with Oracle JDBC 8.1.7)

or:

• runtime12ee.zip (for JDK 1.2.x enterprise edition with Oracle JDBC 8.1.7)

or:

• runtime11.zip (for JDK 1.1.x with Oracle JDBC 8.1.7)

or:

• runtime.zip (generic: for JDK 1.2.x or 1.1.x with any Oracle JDBC version)

(The JDK 1.2.x enterprise edition allows datasource support, in compliance with the SQLJ ISO specification.)

File Installation for Non-Oracle Environments

To run OracleJSP in a non-Oracle environment--typically Apache/JServ, the Sun Microsystems JSWDK, or Tomcat--download the OracleJSP files from the Oracle Technology Network (OTN) at the following URL:

http://technet.oracle.com/tech/java/servlets/index.htm

Click on "Software" in the button bar near the top of this page.

You will need an OTN account, but membership is free of charge. Click on "Membership" in the bar at the top of the page if you do not already have an account.

For the OTN download, OracleJSP files are contained within ojsp.zip, which includes files mentioned in this section as well as configuration files discussed later in this appendix, release notes, documentation files, and sample applications.

Installation and configuration instructions are included in ojsp.zip--see install.htm for top-level information and links. However, you can use this appendix for detailed information about configuring the predominant non-Oracle Web server environments--Apache/JServ, the Sun Microsystems JSWDK, and Tomcat--to use OracleJSP.

You can choose any desired root directory for OracleJSP, as long as the location you choose is reflected in your Web server classpath settings (discussed in "Add OracleJSP-Related JAR and ZIP Files to Web Server Classpath").

Oracle JDBC and SQLJ files are also available from OTN separately at the following URL:

http://technet.oracle.com/tech/java/sqlj_jdbc/index.htm

Click on "Software" in the button bar near the top of this page.

Note: Oracle Internet Application Server uses an Apache/JServ environment, but you should use application server installation and configuration instructions instead of the Apache/JServ instructions in this appendix.

Oracle Environments Providing OracleJSP

The following Oracle environments provide OracleJSP and a Web server or Web listener, starting with the version numbers noted:

• Oracle Servlet Engine (OSE) 8.1.7

• Oracle Internet Application Server 1.0.0

• Oracle Application Server 4.0.8.2

• Oracle Web-to-go 1.3 (can be used with Oracle8i Lite)

• Oracle JDeveloper 3.0

In any of these environments, OracleJSP components are included with the product installation.

If you are targeting OSE you will need a client-side development and testing environment--probably Oracle JDeveloper or perhaps a non-Oracle development tool. When you have completed preliminary testing in your development environment, you can deploy JSP pages to the Oracle8i database, as described in Chapter 6, "JSP Translation and Deployment".

Configuration of Web Server and Servlet Environment to Run OracleJSP

Configuring your Web server to run OracleJSP pages requires the following general steps:

1. Add OracleJSP-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 OracleJSP container.

These steps apply to any Web server environment, but the information in this section focuses on the most prevalent non-Oracle environments-- Apache/JServ, the Sun Microsystems JSWDK, and Tomcat.

The Oracle Servlet Engine, provided with the Oracle8i JServer environment, is automatically configured upon installation to run OracleJSP. For other Oracle environments, refer to the documentation for those products, because procedures vary. (Much of the installation and configuration may be automatic.)

Add OracleJSP-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 OracleJSP, and 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 OracleJSP is identical to the servlet.jar provided with Tomcat 3.1.)

• ojsputil.jar (optional, for JML tags, SQL tags, and database-access JavaBeans)

• xsu12.jar (for JDK 1.2.x) or xsu111.jar (for JDK 1.1.x) (optional, for JML tags, SQL tags, and database-access JavaBeans; see "Summary of Files")

• additional optional ZIP and JAR files, as necessary, for JDBC and SQLJ (see "Summary of Files")

  Important: You must also ensure that OracleJSP can find javac (or an alternative Java compiler, according to your javaccmd configuration parameter setting). For javac in a JDK 1.1.x environment, the JDK classes.zip file must be in the Web server classpath. For javac in a JDK 1.2.x environment, the JDK tools.jar file must be in the Web server classpath.

Apache/JServ Environment

In an Apache/JServ environment, add appropriate wrapper.classpath commands to the jserv.properties file in the JServ conf directory. Note that jsdk.jar should already be in the classpath. This file is from the Sun Microsystems JSDK 2.0 and provides servlet 2.0 versions of the javax.servlet.* packages that are required by Apache/JServ. Additionally, files for your JDK environment should already be in the classpath.

The following example (which happens to use UNIX directory paths) includes files for OracleJSP, JDBC, and SQLJ. (Replace [Oracle_Home] with your Oracle Home path.)

# servlet 2.0 APIs (required by Apache/JServ, from Sun JSDK 2.0):
wrapper.classpath=jsdk2.0/lib/jsdk.jar
#
# servlet 2.2 APIs (required and provided by OracleJSP):
wrapper.classpath=[Oracle_Home]/ojsp/lib/servlet.jar
# OracleJSP packages:
wrapper.classpath=[Oracle_Home]/ojsp/lib/ojsp.jar
wrapper.classpath=[Oracle_Home]/ojsp/lib/ojsputil.jar
# XML parser (used for servlet 2.2 web deployment descriptor):
wrapper.classpath=[Oracle_Home]/ojsp/lib/xmlparserv2.jar
# JDBC libraries for Oracle database access (JDK 1.2.x environment):
wrapper.classpath=[Oracle_Home]/ojsp/lib/classes12.zip
# SQLJ translator (optional):
wrapper.classpath=[Oracle_Home]/ojsp/lib/translator.zip
# SQLJ runtime (optional) (for JDK 1.2.x enterprise edition):
wrapper.classpath=[Oracle_Home]/ojsp/lib/runtime12.zip

Important: In an Apache/JServ environment, jsdk.jar must precede servlet.jar in the classpath.

Now consider an example where you have the following useBean command:

<jsp:useBean id="queryBean" class="mybeans.JDBCQueryBean" scope="session" />

You can add the following wrapper.classpath command to the jserv.properties file. (This example happens to be for a Windows NT environment.)

wrapper.classpath=D:\Apache\Apache1.3.9\beans\

And then JDBCQueryBean.class should be located as follows:

D:\Apache\Apache1.3.9\beans\mybeans\JDBCQueryBean.class

JSWDK Environment

Update the startserver script in the jswdk-1.0 root directory to add OracleJSP files 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.

Important: In a JSWDK environment, the servlet 2.1 version of servlet.jar (provided with Sun JSWDK 1.0) must precede the servlet 2.2 version of servlet.jar (provided with OracleJSP) in your classpath. The servlet 2.1 version is typically in the jsdkJars environment variable. The overall classpath is formed through a combination of various xxxJars environment variables, including jsdkJars, jspJars, and miscJars. Examine the startserver script to verify that miscJars is added to the classpath after jsdkJars.

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 OracleJSP 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 OracleJSP 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 OracleJSP) is already included with Tomcat, so it needs no consideration.

Map JSP File Name Extensions to Oracle JspServlet

You must configure the Web server for the following:

• to recognize appropriate file name extensions as JSP pages

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

• to find and execute the servlet that begins processing JSP pages

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

  Important: With the above configurations, OracleJSP 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.)

Apache/JServ Environment

In an Apache/JServ environment, mapping each JSP file name extension to the Oracle JspServlet requires just a single step. In the JServ conf directory, update the configuration file--jserv.conf or mod_jserv.conf--to add ApJServAction commands to perform the mappings.

(In older versions, you must instead update the httpd.conf file in the Apache conf directory. In newer versions, the jserv.conf or mod_jserv.conf file is "included" into httpd.conf during execution--look at the httpd.conf file to see which one it includes.)

Following is an example (which happens to use UNIX syntax):

# Map file name extensions (.sqljsp and .SQLJSP are optional).
ApJServAction .jsp /servlets/oracle.jsp.JspServlet
ApJServAction .JSP /servlets/oracle.jsp.JspServlet
ApJServAction .sqljsp /servlets/oracle.jsp.JspServlet
ApJServAction .SQLJSP /servlets/oracle.jsp.JspServlet

The path you use in this command for oracle.jsp.JspServlet is not a literal directory path in the file system. The path to specify depends on your Apache/JServ servlet configuration--how the servlet zone is mounted, the name of the zone properties file, and the file system directory that is specified as the repository for the servlet. ("Servlet zone" is an Apache/JServ term that is similar conceptually to "servlet context".) Consult your Apache/JServ documentation for more information.

JSWDK Environment

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

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

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

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.

Note: There is a global web.xml file in the [TOMCAT_HOME]/conf directory. To override any settings in this file for a particular application, update the web.xml file in the WEB-INF directory under the particular application root.

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

---