Oracle JavaServer Pages Developer's Guide and Reference Release 8.1.7 Part Number A83726-01 |
Library | Service | Contents | Index

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

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index