Key Considerations

Considerations for the Oracle Servlet Engine

The Oracle Servlet Engine (OSE) is integrated with the Oracle8i JServer environment. To run in OSE, a JSP page must be loaded and published in the database. The details of deploying JSP pages into Oracle8i are discussed in Chapter 6, "JSP Translation and Deployment". This section discusses special programming considerations for the OSE environment and provides an overview of key OSE characteristics.

A JSP application can run in OSE by using the Oracle HTTP Server, powered by Apache, as a front-end Web server (generally recommended), or by using OSE as the Web server directly. See "Oracle Web Application Database Access Strategies". When installing Oracle8i release 8.1.7, Oracle HTTP Server is set as the default Web server. Refer to your installation instructions if you want to change this setting.

It is assumed that JSP pages running in the Oracle Servlet Engine are intended for database access, so some background is provided on database connections in JServer.

JSP code is generally completely portable between OSE and other environments where OracleJSP is used. The exception is that connecting in JServer through the JDBC server-side internal driver is different (for example, does not require a connect string), as mentioned in "JServer Connections".

Aside from the use of any JServer database connection code or other JServer-specific features, JSP pages written for OSE are portable to other environments running OracleJSP. The original code has to be modified and re-translated only if JServer-specific features were used.

The following topics are covered here:

Equivalent Code for OracleJSP Runtime Configuration Parameters

Notes:
This section discusses development considerations in targeting OSE. For deployment considerations, including hotloaded classes and client-side versus server-side translation, see "Overview of Features and Logistics in Deployment to Oracle8i".

Introduction to the JServer JVM and JDBC Server-Side Internal Driver

Each Oracle8i JServer database session invokes its own dedicated Java virtual machine. This one-to-one correspondence between sessions and JVMs is important to keep in mind.

Any Java program running inside JServer in the target Oracle8i database typically uses the JDBC server-side internal driver to access the local SQL engine. This driver is intrinsically tied to the Oracle8i database and to the JVM. The driver runs as part of the same process as the database. It also runs within a default database session--the same session in which the JVM was invoked.

The server-side internal driver is optimized to run within the database server and provide direct access to SQL data and PL/SQL subprograms on the local database. The entire JVM operates in the same address space as the database and the SQL engine. Access to the SQL engine is a function call--there is no network. This enhances the performance of your JDBC programs and is much faster than executing a remote Net8 call to access the SQL engine.

JServer Connections

Because the JDBC server-side internal driver runs within a default database session, you are already "connected" to the database implicitly. There are two JDBC methods you can use to access the default connection:

Use the Oracle-specific defaultConnection() method of the OracleDriver class. (This returns the same connection object each time it is called.)
Use the static DriverManager.getConnection() method, with either jdbc:oracle:kprb or jdbc:default:connection as the URL string. (This returns a different connection object each time it is called.)

Using the defaultConnection() method is generally recommended.

It is also possible to use the server-side Thin driver for an internal connection (a connection to the database in which your Java code is running), but this is not typical.

Notes:

Alternatively, you can connect using custom JavaBeans provided with OracleJSP. See "Oracle Database-Access JavaBeans".

You are not required to register the OracleDriver class for connecting with the server-side internal driver, although there is no harm in doing so. This is true whether you are using getConnection() or defaultConnection() to make the connection.

For more information about server-side connections through Oracle JDBC, see the Oracle8i JDBC Developer's Guide and Reference.

Connecting with the OracleDriver Class defaultConnection() Method

The oracle.jdbc.driver.OracleDriver class defaultConnection() method is an Oracle extension you can use to make an internal database connection. This method always returns the same connection object. Even if you invoke this method multiple times, assigning the resulting connection object to different variable names, a single connection object is reused.

The defaultConnection() method does not take a connect string. For example:

import java.sql.*; 
import oracle.jdbc.driver.*; 
  
class JDBCConnection 
{ 
  public static Connection connect() throws SQLException 
  { 
    Connection conn = null; 
    try {  
      // connect with the server-side internal driver
         OracleDriver ora = new OracleDriver(); 
         conn = ora.defaultConnection(); 
      } 
 
    } catch (SQLException e) {...}
    return conn; 
  } 
}

Note that there is no conn.close() call in the example. When JDBC code is running inside the target server, the connection is an implicit data channel, not an explicit connection instance as from a client. It should typically not be closed.

If you do call the close() method, be aware of the following:

All connection instances obtained through the defaultConnection() method, which actually all reference the same connection object, will be closed and unavailable for further use, with state and resource cleanup as appropriate. Executing defaultConnection() afterward would result in a new connection object and, therefore, a new transaction.
Even though the connection object is closed, the implicit connection to the database will not be closed.

Connecting with the DriverManager.getConnection() Method

Instead of using the defaultConnection() method to make an internal database connection, you can use the static DriverManager.getConnection() method with either of the following connect strings:

Connection conn = DriverManager.getConnection("jdbc:oracle:kprb:");

or:

Connection conn = DriverManager.getConnection("jdbc:default:connection:");

Any user name or password you include in the URL string is ignored in connecting to the server default connection.

The DriverManager.getConnection() method returns a new Java Connection object every time you call it. Note that although the method is not creating a new physical connection (only a single implicit connection is used), it is returning a new object.

The fact that DriverManager.getConnection() returns a new connection object every time you call it is significant if you are working with object maps, known as "type maps". A type map, for mapping Oracle SQL object types to Java classes, is associated with a specific Connection object and with any state that is part of the object. If you want to use multiple type maps as part of your program, then you can call getConnection() to create a new Connection object for each type map. For general information about type maps, see the Oracle8i JDBC Developer's Guide and Reference.

Connecting with the Server-Side Thin Driver

The Oracle JDBC server-side Thin driver is generally intended for connecting to one database from within another database. It is possible, however, to use the server-side Thin driver for an internal connection. Specify a connect string as you would for any usage of the Oracle JDBC Thin driver.

This feature offers the possible advantage of code portability between the Oracle Servlet Engine and other servlet environments; however, the server-side internal driver offers more efficient performance.

No Auto-Commit in Server-Side Internal Driver

The JDBC auto-commit feature is disabled in the server-side internal driver. You must commit or roll back changes manually.

No Connection Pooling or Caching with Server-Side Internal Driver

Connection pooling and caching is not applicable when using the server-side internal driver, because it uses a single implicit database connection. Attempts to use these features through the internal driver may actually degrade performance.

Use of JNDI by the Oracle Servlet Engine

The Oracle Servlet Engine uses a JNDI mechanism to look up "published" JSP pages and servlets, although this mechanism is generally invisible to the JSP developer or user. Publishing a JSP page, which you accomplish during deployment to OSE, involves either running the Oracle session-shell publishjsp command (for deployment with server-side translation) or running the session-shell publishservlet command (for deployment with client-side translation).

The publishservlet command requires you to specify a virtual path name and a servlet name for the page implementation class. The virtual path name is then used to invoke the page through a URL, or to include or forward to the page from any other page running in OSE.

The publishjsp command can either take a virtual path name and servlet name on the command line, or will infer them from the JSP source file name and directory path that you specify.

Both the servlet name and the virtual path name are entered into the JServer JNDI namespace, but the JSP developer or user need only be aware of the virtual path name.

For more information about publishing a JSP page for OSE, see "Translating and Publishing JSP Pages in Oracle8i (Session Shell publishjsp)" (for deployment with server-side translation) or "Publishing Translated JSP Pages in Oracle8i (Session Shell publishservlet)" (for deployment with client-side translation).

For general information about how the Oracle Servlet Engine uses JNDI, see the Oracle8i Oracle Servlet Engine User's Guide.

Equivalent Code for OracleJSP Runtime Configuration Parameters

Some OracleJSP configuration parameters take effect during translation; others take effect during runtime. When you deploy JSP pages to the Oracle8i database to run in the Oracle Servlet Engine, you can make appropriate translation-time settings through command-line options of the OracleJSP pre-translation tool.

At runtime, however, the Oracle Servlet Engine does not support execution-time configuration parameters. The most significant runtime parameter is translate_params, which relates to NLS. For a discussion of equivalent code, see "Code Equivalent to the translate_params Configuration Parameter".