Oracle JSP - Developers Guide Release 1.0

Contents Index

2
Installing and Configuring Oracle JSP

This chapter describes the system requirements and guides you through the process of installing and configuring Oracle JSP.

• "System Requirements" for Oracle JSP.
• "Installing Oracle JSP" contains instructions for installing Oracle JSP into an existing web server environment.
• "Configuring Oracle JSP" contains instructions for configuring Oracle JSP.
• "Upgrading Oracle JSP" contains instructions for upgrading an existing Oracle JSP installation.
   

2.1 System Requirements

These are the following minimum requirements for Oracle JSP:
 

Operating Systems:	Any platform that Java 1.1 or greater runs on Note:  Oracle JSP is pure Java.
Java:	Java 1.1 or Java 1.2/2.0 Oracle recommends that you use the latest of either versions that is available on your platform.
Java Compiler:	javac compiler from a Java 1.1 or 1.2 JDK You are required to use the JDK 1.2 javac compiler if you want support for multibyte encoded JSP pages.
Webservers:	Server must support Java Servlets running version 2.0 or greater.
Libraries:	JSWDK 1.0 or greater servlet.jar.  Notes:  Your server may already include this in its installation.  If using SQLJ, the SQLJ translation and JDBC libraries are required: translator.zip, classes111.zip If using XSL, the Oracle XML parser is required: xmlparsev2.jar

2.2 Installing Oracle JSP

Oracle JSP is implemented as a Java Servlet. It conforms to the Servlet 2.0 API so that it can run in any Servlet 2.0 or greater servlet runner. Oracle JSP emulates the Servlet 2.1 APIs required by the JSP specification for the JSP pages it hosts running in a Servlet 2.0 runner.

2.2.1 Installation Steps

Installing Oracle JSP is similar to installing servlets in your server.

Note: If your web server is an Oracle product, Oracle JSP may already be installed. Check your server documentation to be sure. If it is and you want to upgrade to a newer version see section 1.4: "Upgrading Oracle JSP."
 
1. If not already installed, install the web server that will host Oracle JSP. Make sure you can run servlets successfully in the server. Most web servers provide simple or sample servlets as part of their installation.
    
2. Update, if necessary, the Java Software provided implementation independent Servlet/JSP class files. See the subsection "Determining if your server needs updating " for more information.
   To update your server:
   • Download and install the (free) JSWDK 1.0 from the Java Software web site.
      
   • Copy lib\servlet.jar to a location relative to your server installation. We do not recommend overwriting the existing serlvet.jar (if any) in your installation.
      
   • Configure your web server to add the new lib/servlet.jar to its classpath. Consult your server documentation for instructions on how to do this.
      
   • Add the new lib/servlet.jar after the existing one (its called jsdk.jar in Servlet 2.0 environments such as Apache). Do not remove the configuration for the existing servlet.jar as your server has been tested with it. By configuring your server to locate the new servlet.jar after the existing one, only those classes that aren't in the original servlet.jar will be loaded from the new jar file. These are the JSP classes.
      
   • Bounce the server and then rerun your servlet test to make sure the server is still working correctly.
   
    
3. Download Oracle JSP from the Oracle Technology Network at http://technet.oracle.com. The download is a single JAR file called ojsp.jar. Copy this file into a preferred/suitable location on your server.
    
4. Configure your server to recognize Oracle JSP as a servlet. Consult your server's documentation for details on configuring servlets. This usually involves:
    
   • Configuring your server so ojsp.jar is in its classpath.
      
   • Registering the servlet by its Java class name. The Java class name for Oracle JSP is oracle.jsp.JspServlet.
   
    
5. Configure your server to map requests whose targets have a .jsp extension to the newly registered Oracle JSP servlet. Again, consult your server documentation for details.

   
   Note: If you are setting up your server to support JSPs with embedded SQLJ statements, consider also providing an extension map for the .sqljsp extension convention described in Chapter 6. You can map multiple extensions to the Oracle JSP Servlet.
    

6. Download, if necessary, and configure your server to locate Oracle JSP dependent libraries (add these libraries to your server's classpath).
    
   • Java compiler (javac):
     Oracle JSP requires the Java compiler (javac) to compile translated pages. The Java compiler is part of the Java Development Kit (JDK). For Solaris and NT platforms the JDK can be downloaded from the Java Software web site. Customers running on other platforms should consult their platform provider. It is recommended you run with the javac compiler included with JDK 1.2 as this compiler supports the -encoding switch that the Oracle JSP engine relies on to translate/compile NLS encoded JSP pages. Oracle JSP will run correctly using the javac compiler included with JDK 1.1 if your JSP pages are written exclusively in U.S. english (and this is your Java VMs default character encoding).
     Note: In JDK 1.1, the Java compiler is included in the JDKs main runtime library classes.zip. In JDK 1.2, the Java compiler has been separated into tools.jar. In either case, the files are typically found in the lib directory of your JDK.
      
   • SQLJ translator:
     Note: You only need to do the following if you intend to develop or deploy JSPs containing SQLJ. Oracle JSP will run correctly without these libraries being installed (unless a JSP containing SQLJ is encountered).
     Oracle JSP requires a special re-entrant version of SQLJ. This version is currently included in the Oracle JSP download. It is called translator.zip and is in the lib directory. Add the library translator.zip (in the lib directory) to your server's classpath. Additionally, SQLJ requires JDBC drivers to be installed. Oracle JDBC drivers can be downloaded from http://www.oracle.com/java/jdbc/. Add the driver library (classes111.zip) to your server's classpath.

   • XSL transformation engine:

     Note: You only need to do the following if you intend to develop or deploy JSPs that generate its response by first generating XML and then tranforming this XML into the final response via an XSL stylesheet. If this isn't applicable you may still want to install the XML engine so the included XMl sample runs.

     To do XSL transformation of a JSP page you need the Oracle XML parser. This can be downloaded from http://technet.oracle.com/tech/xml/parser_java2/ Add the libaray xmlparserv2.jar (in the lib directory) to your server's classpath.

   
    
7. The Oracle JSP engine should now be configured. Add a test JSP page somewhere in your server's document tree, restart the server, and try to access the page.

2.2.2 Determining if Your Server Needs Updating

Oracle JSP relies on Java Software defined JSP classes to run. Unfortunately, for licensing reasons we cannot include these classes in the ojsp.jar. In addition, Java Software has chosen to distribute these classes together with their servlet classes. This is done, because in theory JSPs can't run in an environment that predates their release. But Oracle JSPs can. It can run in Servlet 2.0 or greater environments. In such environments, you will need to upgrade the server's configuration to include these new classes. To determine if you need an upgrade:

• Check when the server was installed. If the server was installed before May 1999, you need to upgrade. The JSP classes were released in the summer of 1999.
• Check when the server was released. Even if you installed the server after May 1999, if the server was released prior to then, you need to upgrade as the server's release date occurs before the classes existed.
• Check what version of the servlet engine your server supports. If the server supports 2.0 you need to upgrade. The Apache/JServ server for example is a 2.0 server.
  Note: In your server documentation, search the installation section for either servlet.jar or jsdk.jar. If you find your server is configured to use jsdk.jar, your server supports Servlet 2.0. If the server uses servlet.jar it supports Servlet 2.1 or greater.
• If your server supports Servlet 2.1, locate the servlet.jar. Either open the servlet.jar in a program like WinZip or use the JDK jar utility to unjar the TOC. If there aren't any class files in the directory /javax/servlet/jsp then you need to upgrade.
  Note: If you cannot locate servlet.jar, then the classes are likely built into your server. In this case, refer to your server's documentation to find out if the JSP classes are included.
• After following the above, if you are unable to determine if you need to upgrade, do the upgrade. Upgrading does not overwrite the existing classes. Instead, the JSP dependent servlet.jar is added to your server's classpath after its current servlet configuration. If the classes are already configured for your server, adding this additional jar file will be a no-op.

2.3 Configuring Oracle JSP

Oracle JSP does not require additional configuring to run. However, it does provide a number of configuration parameters you can set to adjust its behavior. These configuration parameters are controlled by setting their values as servlet initialization parameters on the Oracle JSP Servlet. Consult your server's documentation to determine the mechanism or syntax for doing this.

2.3.1 Common Settings

Note: The following examples depict the syntax used when running in an Apache/JServ 1.0 environment.

These are the common configurations settings for Oracle JSP:

developer_mode: This flag controls the runtime behavior of the Oracle JSP engine. The values are true or false. The default is true. If set to true, the Oracle JSP engine will check whether to retranslate/reload the requested page or application on every request.  If set to false, the Oracle JSP engine will only check whether to translate when the initial request for the page or application is received. Oracle recommends that deployment environments set developer_mode to false to maximize performance. For example:

servlet.oracle.jsp.JspServlet.initArgs=developer_mode=false

translate_params: This flag lets you override servlet engines that don't encode mulitbyte (NLS) request (form) parameters. The values are true or false. The default is false. If set to true, the Oracle JSP engine will encode the request parameters itself. If false, the Oracle JSP engine will return the parameters from the servlet engine unchanged. When developing multibyte JSPs, it is important that you determine if the servlet environment you are running in supports multibyte request parameters or not.  Setting translate_params to true in an environment that correctly handles parameter encoding will yield incorrect results. For example:

servlet.oracle.jsp.JspServlet.initArgs=translate_params=true

page_repository_root: By default, the Oracle JSP Servlet uses the web server's document repository to generate or load translated JSPs. The generated .java/.class files are written into a special directory named _pages in the root directory of the application this page is contained in. If the page is not contained in an application that it is written into the _pages subdirectory in the server's docroot directory. If you want the Oracle JSP engine to generate pages to a location outside the server's docroot set the page_repository_root initArg. The value of this argument should be a fully qualified path to the root directory into which pages will be generated or run. This directory does not need to exist. For example:

servlet.oracle.jsp.JspServlet.initArgs=page_repository_root=c:\jsps

classpath: By default, Oracle JSP loads classes from either the system classpath, the page repository, or predefined locations relative to the JSP's application root directory (see Chapter 4). If additional class dependencies exist they can be specified using the classpath initArgs. The form for specifying a classpath follows the conventions that the platform uses for specifying a regular Java classpath. For example:

servlet.oracle.jsp.JspServlet.initArgs=classpath=c:\somedir\myapp.jar

Since this version currently has some class loader issues, Oracle recommends that all dependent classes be included in the regular JServ classpath rather than via the classpath setting.

2.3.2 Uncommon Settings

The following settings are rarely used and tend to be server specific. Often, a supplemental document released with your server will detail if or how to use these settings. Currently none of the following settings are in use.

page_provider_root: By default, Oracle JSP uses the web server's document repository to locate the .jsp file that corresponds to the incoming request. page_provider_root lets Oracle JSP copy these files from an alternative repository or location. This setting is primarily provided to support servers that don't use the file systems as their repository.

page_provider: By default, the JspServlet assumes pages are being delivered from or to a file system. This is not universally true for all Oracle implementations. This setting lets you specify an alternative class to be used as a page provider for the JspServlet. Currently, there are no alternatives implemented.

page_repository: By default, the JspServlet assumes generated pages are being delivered from or to a file system. This is not universally true for all Oracle implementations. This setting lets you specify an alternative class to be used to manage a page repository for Oracle JSP engine. Currently, there are no alternatives implemented.

classloader: By default, the JspServlet assumes classes are being loaded from a file system. This is not universally true for all Oracle implementations. This setting lets you specify an alternative class to be used to implement a classloader for the JspServlet. Currently, there are no alternatives implemented.

jspcompiler: By default, the JspServlet uses the built-in Java compiler (javac). Pages are read directly from the file system. In the future, Oracle plans to support in memory compilation as well as compiling out of different repository types. This setting names the class that implements the JspCompiler interface. Currently, there are no alternatives implemented.

2.4 Upgrading Oracle JSP

Typically, an existing Oracle JSP installation is easily upgraded. Normally, all you need to do is overwrite the existing ojsp.jar and restart the server. More specifically:

1. Download the new version of ojsp.jar.
2. Check the Release Notes associated with this version. The Release Notes should clearly state whether this version contains changes that require more than the simple upgrade. A simple upgrade overwrites the existing ojsp.jar and restarts the server. If you need more than a simple upgrade, follow the information in the release notes.
3. Stop your server.
4. Copy or rename the existing ojsp.jar. As Oracle JSP is designed to run on many servlet runtimes, it is not possible to test every configuration. It is always possible that the new version will run less reliably then your current version. Keep your existing ojsp.jar until you are satisfied with the new version.
5. Overwrite the existing ojsp.jar with the new one version.
6. Restart the server.