Skip Headers

Oracle® Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide 10g Release 3 (10.1.3) Part No. B14430-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 2 The Oracle JSP Implementation

This chapter provides details on the functionality implemented by the Web container provided with Oracle Containers for J2EE (OC4J), a component of the Oracle Application Server. Overviews of the Oracle Application Server, OC4J, the OC4J JSP implementation and features, and custom tag libraries and utilities that are also supplied (documented in the Oracle Containers for J2EE JSP Tag Libraries and Utilities Reference).

The following sections are included:

- Introduction to OC4J

- JSP Support in Oracle JDeveloper

- Oracle Value-Added Features for JSP

## 2.1 Introduction to OC4J

Oracle Containers for J2EE 10g Release 3 (10.1.3), or OC4J, provides a complete Java 2 Enterprise Edition (J2EE) 1.4-compliant environment. OC4J Standalone is for use in development environments and in small-to-medium scale production environments.

OC4J is written entirely in Java and executes on the Java Virtual Machine (JVM) of the standard Java Development Kit (JDK). You can run OC4J on the standard JDK that exists on your operating system.

The OC4J documentation assumes that you have a basic understanding of Java programming, J2EE technology, and Web and EJB application technology. This includes deployment conventions such as the `/WEB-INF` and `/META-INF` directories.

### 2.1.1 What's New in OC4J

Release 3 (10.1.3) of Oracle Containers for J2EE includes a number of new features and enhancements, described below.

#### 2.1.1.1 Support for Web Services

OC4J provides full support for Web Services in accordance with the J2EE 1.4 standard, including JAX-RPC 1.1. Web Services interoperability is also supported.

- EJB 2.1 Web services end point model

- JSR 109 client and server deployment model

- CORBA Web services: Support for wrapping existing basic CORBA Servants as Web services and auto-generating WSDL from IDL

- Support for source code annotations to customize Web services behavior such as invocation and ending styles (RPC/literal, RPC/encoded, Doc/literal); customizing the Java to XML mapping; enforcing security.

- Database and JMS Web services

#### 2.1.1.2 Support for New J2EE 1.4 Application Management and Deployment Specifications

OC4J supports the following specifications defining new standards for deploying and managing applications in a J2EE environment.

- The Java Management Extensions (JMX) 1.2 specification, which allows standard interfaces to be created for managing resources, such as services and applications, in a J2EE environment. The OC4J implementation of JMX provides a JMX client that can be used to completely manage an OC4J server and applications running within it.

- The J2EE Management Specification (JSR-77), a sub-set of JMX that allows standard interfaces to be created for managing applications in a J2EE environment.

- The J2EE Application Deployment API (JSR-88), which defines a standard API for configuring and deploying J2EE applications and modules into a J2EE-compatible environment. The OC4J implementation includes the ability to create and/or edit a deployment plan containing the OC4J-specific configuration data needed to deploy a component into OC4J.

#### 2.1.1.3 Support for Oracle Application Server TopLink

Oracle Application Server TopLink is an advanced, object persistence framework for use with a wide range of Java 2 Enterprise Edition (J2EE) and Java application architectures. OracleAS TopLink includes support for the OC4J Container Managed Persistence (CMP) container and base classes that simplify Bean Managed Persistence (BMP) development.

#### 2.1.1.4 OracleAS Job Scheduler

The OracleAS Job Scheduler provides asynchronous scheduling services for J2EE applications. Its key features include capabilities for submitting, controlling and monitoring jobs, defined as a unit of work that executes when the work is performed.

#### 2.1.1.5 New Two-Phase Commit Transaction Coordinator Functionality

The new Distributed Transaction Manager in OC4J can coordinate two-phase transactions between any type of XA resource, including databases from Oracle as well as other vendors and JMS providers such as IBM WebsphereMQ. Automatic transaction recovery in the event of a failure is also supported.

#### 2.1.1.6 Generic JMS Resource Adapter Enhancements

The Generic JMS Resource Adapter can now be used as an OC4J plug-in for OracleAS JMS that ships with the current version of OC4J as well as for IBM Websphere MQ JMS version 5.3.

Support for lazy transaction enlistment has been added so that JMS connections can be cached and still be able to correctly participate in global transactions.

Finally, the Generic JMS Resource Adapter now has better error handling. Endpoints now automatically retry after provider or system failures, and `onMessage()` errors are handled correctly.

### 2.1.2 Features of OC4J

The following features are provided with the latest release of OC4J.

#### 2.1.2.1 J2EE Support

OC4J supports and is certified for the standard J2EE APIs, as listed in Table 2-1

Table 2-1 J2EE APIs Supported by OC4J

J2EE Standard APIs | Version Supported By OC4J
--- | ---
JavaServer Pages (JSP) | 2.0
Servlets | 2.4
Enterprise JavaBeans (EJB) | 2.1
Java Transaction API (JTA) | 1.0
Java Message Service (JMS) | 1.1
Java Naming and Directory Interface (JNDI) | 1.2
Java Mail | 1.1.2
Java Database Connectivity (JDBC) | 2.0 Extension
Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider | 1.0
J2EE Connector Architecture | 1.5
Java API for XML-Based RPC (JAX-RPC) | 1.1
SOAP with Attachments API for Java (SAAJ) | 1.2
Java API for XML Registries (JAXR) | 1.0.5

#### 2.1.2.2 OC4J Web Communication

OC4J supports HTTP and HTTPS communications natively without the use of the Oracle HTTP Server.

The default Web site is defined in the `http-web-site.xml` file, which specifies the default HTTP listener on port `8888`. Additional Web sites may be defined on different ports using variations of this file. See the Oracle Containers for J2EE Configuration and Administration Guide for instructions on creating additional Web sites in OC4J.

#### 2.1.2.3 Clustering

OC4J provides support for HTTP session and stateful session Enterprise JavaBean replication and load balancing across a cluster of OC4J instances. However, cluster configuration and management is completely manual in this release, through editing of the OC4J-specific application configuration file. See the Oracle Containers for J2EE Configuration and Administration Guide for details.

## 2.2 Oracle Value-Added Features for JSP

OC4J value-added features for JSP pages can be grouped into three major categories:

- Features that are Oracle-specific

- Features implemented through custom tag libraries, custom JavaBeans, or custom classes that are generally portable to other JSP environments

- Features supporting caching technologies

The rest of this section provides feature summaries and overviews in these areas, plus a brief summary of Oracle support for the JavaServer Pages Standard Tag Library (JSTL). JSTL support is summarized more fully in the Oracle Containers for J2EE JSP Tag Libraries and Utilities Reference .

### 2.2.1 Supported Specifications

The JSP container provided with OC4J is in full compliance with the following specifications published by Sun Microsystems:

- JavaServer Pages Specification, Version 2.0

- Java Servlet Specification, Version 2.4

- JSR-045: Debugging Support for Other Languages

Feel free to consult these specifications for more details.

### 2.2.2 Oracle-Specific Features

This section provides an overview of Oracle-specific programming extensions supported by the OC4J Web container.

#### 2.2.2.1 Configurable JSP Extensions in OC4J

In addition to JSP 2.0 compliance, the OC4J Web container includes the following notable features.

Also see "Oracle Value-Added Features for JSP".

- Separate mode switches for XML validation of `web.xml` file and TLD files

  Validation of `web.xml` is disabled by default but can be enabled. Validation of TLD files is disabled by default.

- Mode flag for extra imports

  Use this to automatically import certain Java packages beyond the JSP defaults.

- "Well-known" location for sharing tag libraries

  You can specify a directory where tag library JAR files can be placed for sharing across multiple Web applications.

- Configurable JSP timeout

  You can specify a timeout value for JSP pages, after which a page is removed from memory if it has not been requested again.

The following features are also supported:

- Mode switch for automatic page retranslation and reloading

  You have a choice of: 1) running JSP pages without any automatic reloading or retranslation of JSP pages; 2) automatically reloading any page implementation classes (but not JavaBeans or other dependency classes); or 3) automatically retranslating any JSP pages that have changed.

- Tag handler instance pooling

  To save time in tag handler creation and garbage collection, you can optionally enable pooling of tag handler instances. They are pooled in `application` scope. You can use different settings in different pages, or even in different sections of the same page. See "Disabling or Enabling Tag Handler Reuse (Tag Pooling)".

- Output mode for null output

  You can print an empty string instead of the default "null" string for null output from a JSP page.

#### 2.2.2.2 Global Includes

The OC4J Web container provides a feature called global includes. You can use this feature to specify one or more files to statically include into JSP pages in or under a specified directory, through virtual JSP `include` directives. During translation, the Web container looks for a configuration file, `/WEB-INF/ojsp-global-include.xml`, that specifies the included files and the directories for the pages.

This enhancement is particularly useful in migrating applications that had used `globals.jsa` or `translate_params` functionality in previous Oracle JSP releases. For more information, see "Oracle JSP Global Includes".

#### 2.2.2.3 Support for Dyna mic Monitoring Service

DMS adds performance-monitoring features to a number of Oracle Application Server components, including OC4J. The goal of DMS is to provide information about runtime behavior through built-in performance measurements so that users can diagnose, analyze, and debug any performance problems. DMS provides this information in a package that can be used at any time, including during live deployment. Data are published through HTTP and can be viewed with a browser.

The OC4J Web container supports DMS features, calculating relevant statistics and providing information to DMS servlets such as the spy servlet and monitoring agent. Statistics include the following (using averages, maximums, and minimums, as applicable). Times are in milliseconds.

- Processing time of HTTP request

- Processing time of JSP service method

- Number of JSP instances created or available

Standard configuration for these servlets is in the OC4J `application.xml` and `default-web-site.xml` configuration file. Use the Oracle Enterprise Manager 10g Application Server Control Console to access DMS, display DMS information, and, if appropriate, alter DMS configuration.

See the Oracle Application Server Performance Guide for precise definitions of the JSP metrics and detailed instructions for viewing and analyzing them.

### 2.2.3 JSP Utilities and Tag Libraries Provided with OC4J

This section provides a brief summary of extended OC4J JSP features that are implemented through standards-compliant custom tag libraries, custom JavaBeans, and other classes. These features are documented in the Oracle Containers for J2EE JSP Tag Libraries and Utilities Reference.

- Extended types implemented as JavaBeans that can have a specified scope

- `JspScopeListener` for event-handling

- Integration with XML and XSL

- Data-access tag library (sometimes referred to as "SQL tags") and JavaBeans

- Web services tag library

- Tag libraries and JavaBeans for uploading files, downloading files, and sending e-mail from within an application

- EJB tag library

- Additional utility tags, such as for displaying dates and currency amounts appropriately for a specified locale

### 2.2.4 Tags and API for Caching Support

Faced with Web performance challenges, e-businesses must invest in more cost-effective technologies and services to improve the performance of their Internet sites. Web caching, the caching of both static and dynamic Web content, is a key technology in this area. Benefits of Web caching include performance, scalability, high availability, cost savings, and network traffic reduction.

OC4J provides the following support for Web caching technologies:

- The JESI tag library for Edge Side Includes (ESI), an XML-style markup language that allows dynamic content assembly away from the Web server

  The OracleAS Web Cache provides an ESI engine.

- A tag library and servlet API for the Web Object Cache, an application-level cache that is embedded and maintained within a Java Web application

  The Web Object Cache uses the Oracle Application Server Java Object Cache as its default repository.

These features are documented in the Oracle Containers for J2EE JSP Tag Libraries and Utilities Reference.

### 2.2.5 Support for the JavaServer Pages Standard Tag Library (JSTL)

The OC4J JSP implementation supports the JavaServer Pages Standard Tag Library (JSTL), as specified in the Sun Microsystems JavaServer Pages Standard Tag Library specification.

Note: The JSTL distribution is no longer installed in the `ORACLE_HOME/j2ee/home/jsp/lib/taglib` directory within OC4J. See "Sharing Tag Libraries Across Web Applications" for instructions on sharing tag libraries across deployed Web applications.

JSTL is intended as a convenience for JSP page authors who are not familiar or not comfortable with scripting languages such as Java. Historically, scriptlets have been used in JSP pages to process dynamic data. With JSTL, the intent is for JSTL tag usage to replace the need for scriptlets.

Key JSTL features include the following:

- Core tags for expression language support, conditional logic and flow control, iterator actions, and access to URL-based resources

- Tags for XML processing, flow control, and XSLT transformations

- SQL tags for database access

- Tags for I8N-capable internationalization and formatting

  (The term "I8N" refers to an internationalization standard.)

Tag support is organized into four JSTL sublibraries according to these functional areas.

For a more complete summary of JSTL support, refer to the Oracle Containers for J2EE JSP Tag Libraries and Utilities Reference. For complete information about JSTL, refer to the specification at the following location:

    http://www.jcp.org/aboutJava/communityprocess/first/jsr052/index.html

Note: The custom JML, XML, and data-access (SQL) and other tag libraries provided with OC4J pre-date JSTL and have areas of duplicate functionality. For standards compliance, it is generally advisable to use JSTL instead of the custom libraries. For features in the custom libraries that are not yet available in JSTL, where there seems to be general usefulness, Oracle will try to have the features adopted into the JSTL standard as appropriate.

## 2.3 JSP Support in Oracle J Developer

Visual Java programming tools now typically support JSP coding. In particular, Oracle JDeveloper supports JSP development and includes the following features:

- Integration of the OC4J Web container to support the full application development cycle: editing, debugging, and running JSP pages

- Debugging of deployed JSP pages

- An extensive set of data-enabled and Web-enabled JavaBeans, known as JDeveloper Web beans

- The JSP Element Wizard, which offers a convenient way to add predefined Web beans to a page

- Support for incorporating custom JavaBeans

For debugging, JDeveloper can set breakpoints within JSP page source and can follow calls from JSP pages into JavaBeans. This is much more convenient than manual debugging techniques, such as adding print statements within the JSP page to output state into the response stream (for viewing in your browser) or to the server log (through the `log()` method of the implicit `application` object).

For information about JDeveloper, refer to the JDeveloper online help, or to the following site on the Oracle Technology Network:

    http://otn.oracle.com/products/jdev/content.html

(You will need an Oracle Technology Network membership, which is free of charge.) For an overview of JSP tag libraries provided with JDeveloper, see the Oracle Containers for J2EE JSP Tag Libraries and Utilities Reference.

Note: Other key IDE vendors have built plug-in modules that allow seamless integration with OC4J. This provides developers with the capability to build, deploy, and debug J2EE applications running on OC4J directly from within the IDE.

## 2.4 Oracle JSP Resource Management Features

The following sections discuss standard features and Oracle value-added features for resource management:

- Standard Session Resource Management: HttpSessionBindingListener

- Overview of Oracle Value-Added Features for Resource Management

### 2.4.1 Standard Se ssion Resource Management: HttpSessionBindingListener

A JSP page must appropriately manage resources acquired during its execution, such as JDBC connection, statement, and result set objects. The standard `javax.servlet.http` package provides the `HttpSessionBindingListener` interface and `HttpSessionBindingEvent` class to manage session-scope resources. Through this mechanism, a session-scope query bean could, for example, acquire a database cursor when the bean is instantiated and close it when the HTTP session is terminated.

This section describes use of the `HttpSessionBindingListener` `valueBound()` and `valueUnbound()` methods.

Note: The bean instance must register itself in the event notification list of the HTTP session object, but the `jsp:useBean` statement takes care of this automatically.

#### 2.4.1.1 The valueBound() and valueUnbound() Methods

An object that implements the `HttpSessionBindingListener` interface can implement a `valueBound()` method and a `valueUnbound()` method, each of which takes an `HttpSessionBindingEvent` instance as input. These methods are called by the servlet container—the `valueBound()` method when the object is stored in the session, and the `valueUnbound()` method when the object is removed from the session or when the session reaches a timeout or becomes invalid. Usually, a developer will use `valueUnbound()` to release resources held by the object (in the example below, to release the database connection).

"Oracle Value-Added Features for JSP" below provides a sample JavaBean that implements `HttpSessionBindingListener` and a sample JSP page that calls the bean.

#### 2.4.1.2 JDBCQueryBean JavaBean Code

Following is the sample code for `JDBCQueryBean`, a JavaBean that implements the `HttpSessionBindingListener` interface. It uses the JDBC OCI driver for its database connection; use an appropriate JDBC driver and connection string if you want to run this example yourself.

`JDBCQueryBean` gets a search condition through the HTML request (as described in "UseJDBCQueryBean JSP Page"), executes a dynamic query based on the search condition, and outputs the result.

This class also implements a `valueUnbound()` method, as specified in the `HttpSessionBindingListener` interface, that results in the database connection being closed at the end of the session.

    package mybeans;

    import java.sql.*;
    import javax.servlet.http.*;

    public class JDBCQueryBean implements HttpSessionBindingListener
    {
      String searchCond = "";
      String result = null;

      public void JDBCQueryBean() {
      }

      public synchronized String getResult() {
        if (result != null) return result;
        else return runQuery();
      }

      public synchronized void setSearchCond(String cond) {
        result = null;
        this.searchCond = cond;
      }

      private Connection conn = null;

      private String runQuery() {
        StringBuffer sb = new StringBuffer();
        Statement stmt = null;
        ResultSet rset = null;
        try {
          if (conn == null) {
            DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());
            conn = DriverManager.getConnection("jdbc:oracle:oci8:@",
                                               "scott", "tiger");

          }

          stmt = conn.createStatement();
          rset = stmt.executeQuery ("SELECT ename, sal FROM scott.emp "+
                (searchCond.equals("") ? "" : "WHERE " + searchCond ));
          result = formatResult(rset);
          return result;

        } catch (SQLException e) {
          return ("<P> SQL error: <PRE> " + e + " </PRE> </P>\n");
        }
        finally {
          try {
            if (rset != null) rset.close();
            if (stmt != null) stmt.close();
          }
          catch (SQLException ignored) {}
        }
      }

      private String formatResult(ResultSet rset) throws SQLException  {
        StringBuffer sb = new StringBuffer();
        if (!rset.next())
          sb.append("<P> No matching rows.<P>\n");
        else {
          sb.append("<UL><B>");
          do {  sb.append("<LI>" + rset.getString() +
                " earns $ " + rset.getInt(2) + "</LI>\n");
          } while (rset.next());
          sb.append("</B></UL>");
        }
        return sb.toString();
      }

      public void valueBound(HttpSessionBindingEvent event) {
        // do nothing -- the session-scope bean is already bound
      }

      public synchronized void valueUnbound(HttpSessionBindingEvent event) {
        try {
          if (conn != null) conn.close();
        }
        catch (SQLException ignored) {}
      }
    }

Note: The preceding code serves as a sample only. This is not necessarily an advisable way to handle database connection pooling in a large-scale Web application.

#### 2.4.1.3 UseJDBCQueryBean JSP Page

The following JSP page uses the `JDBCQueryBean` JavaBean defined in "Oracle Value-Added Features for JSP" above, invoking the bean with `session` scope. It uses `JDBCQueryBean` to display employee names that match a search condition entered by the user.

`JDBCQueryBean` gets the search condition through the `jsp:setProperty` tag in this JSP page, which sets the `searchCond` property of the bean according to the value of the `searchCond` request parameter input by the user through the HTML form. The HTML `INPUT` tag specifies that the search condition entered in the form be named `searchCond`.

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

    <HTML>
    <HEAD> <TITLE> The UseJDBCQueryBean JSP  </TITLE> </HEAD>
    <BODY BGCOLOR="white">

    <% String searchCondition = request.getParameter("searchCond");
       if (searchCondition != null) { %>
          <H3> Search results for : <I> <%= searchCondition %> </I> </H3>
          <%= queryBean.getResult() %>
          <HR><BR>
    <% }  %>

    <B>Enter a search condition for the EMP table:</B>

    <FORM METHOD="get">
    <INPUT TYPE="text" NAME="searchCond" VALUE="ename LIKE 'A%' " SIZE="40">
    <INPUT TYPE="submit" VALUE="Ask Oracle">
    </FORM>

    </BODY>
    </HTML>

Following is sample input and output for this page:

Description of the illustration jdbcquer.gif

#### 2.4.1.4 Advantages of HttpSessionBindingListener

In the preceding example, an alternative to the `HttpSessionBindingListener` mechanism would be to close the connection in a `finalize()` method in the JavaBean. The `finalize()` method would be called when the bean is garbage-collected after the session is closed. The `HttpSessionBindingListener` interface, however, has more predictable behavior than a `finalize()` method. Garbage collection frequency depends on the memory consumption pattern of the application. By contrast, the `valueUnbound()` method of the `HttpSessionBindingListener` interface is called reliably at session shutdown.

### 2.4.2 Overview of Oracle Value-Added Features for Resource Management

OC4J JSP provides the `JspScopeListener` interface for managing application-scope, session-scope, request-scope, or page-scope resources in OC4J.

This mechanism adheres to servlet and JSP standards in supporting objects of `page`, `request`, `session`, or `application` scope. To create a class that supports session scope as well as other scopes, you can integrate `JspScopeListener` with `HttpSessionBindingListener` by having the class implement both interfaces. For `page` scope in OC4J or JServ environments, you also have the option of using an Oracle-specific runtime implementation.

For information about configuration and how to integrate with `HttpSessionBindingListener`, see the Oracle Containers for J2EE JSP Tag Libraries and Utilities Reference.