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

## Oracle-Specific Programming Extensions

The OracleJSP extensions documented in this section are not portable to other JSP environments. This includes the following:

- event-handling through the Oracle `JspScopeListener` mechanism

- support for SQLJ, a standard syntax for embedding SQL statements directly into Java code

- use of JDBC performance enhancement features

  Notes: For servlet 2.0 environments, OracleJSP provides non-portable extensions through a mechanism called `globals.jsa` to support a Web application framework. "OracleJSP Application and Session Support for Servlet 2.0" describes this mechanism. OracleJSP also provides extended (and non-portable) NLS support, which is described in "OracleJSP Extended Support for Multibyte Parameter Encoding".

### OracleJSP Event Handling--JspScopeListener

In standard servlet and JSP technology, only session-based events are supported. OracleJSP extends this support through the `JspScopeListener` interface and `JspScopeEvent` class in the `oracle.jsp.event` package. The OracleJSP mechanism supports the four standard JSP scopes for event-handling for any Java objects used in a JSP application:

- `page`

- `request`

- `session`

- `application`

For Java objects that are used in your application, implement the `JspScopeListener` interface in the appropriate class, then attach objects of that class to a JSP scope using tags such as `jsp:useBean`.

When the end of a scope is reached, objects that implement `JspScopeListener` and have been attached to the scope will be so notified. The OracleJSP container accomplishes this by sending a `JspScopeEvent` instance to such objects through the `outOfScope()` method specified in the `JspScopeListener` interface.

Properties of the `JspScopeEvent` object include the following:

- the scope that is ending (one of the constants `PAGE_SCOPE`, `REQUEST_SCOPE`, `SESSION_SCOPE`, or `APPLICATION_SCOPE`)

- the container object that is the repository for objects at this scope (one of the implicit objects `page`, `request`, `session`, or `application`)

- the name of the object that the notification pertains to (the name of the instance of the class that implements `JspScopeListener`)

- the JSP implicit `application` object

The OracleJSP event listener mechanism significantly benefits developers who want to always free object resources that are of `page` or `request` scope, regardless of error conditions. It frees these developers from having to surround their page implementations with Java `try`/`catch`/`finally` blocks.

For a complete sample, see "Page Using JspScopeListener--scope.jsp".

### OracleJSP Support for Oracle SQLJ

SQLJ is a standard syntax for embedding static SQL instructions directly in Java code, greatly simplifying database access programming. OracleJSP and the OracleJSP translator support Oracle SQLJ, allowing you to use SQLJ syntax in JSP scriptlets. SQLJ statements are indicated by the `#sql` token.

#### SQLJ JSP Code Example

Following is a sample SQLJ JSP page. (The `page` directive imports classes that are typically required by SQLJ.)

    <%@ page language="sqlj"
        import="sqlj.runtime.ref.DefaultContext,oracle.sqlj.runtime.Oracle" %>
    <HTML>
    <HEAD> <TITLE> The SQLJQuery JSP </TITLE> </HEAD>
    <BODY BGCOLOR="white">
    <% String empno = request.getParameter("empno");
    if (empno != null) { %>
    <H3> Employee # <%=empno %> Details: </H3>
    <%= runQuery(empno) %>
    <HR><BR>
    <% } %>
    <B>Enter an employee number:</B>
    <FORM METHOD="get">
    <INPUT TYPE="text" NAME="empno" SIZE=10>
    <INPUT TYPE="submit" VALUE="Ask Oracle");
    </FORM>
    </BODY>
    </HTML>
    <%!

    private String runQuery(String empno) throws java.sql.SQLException {
       DefaultContext dctx = null;
       String ename = null; double sal = 0.0; String hireDate = null;
       StringBuffer sb = new StringBuffer();
       try {
           dctx = Oracle.getConnection("jdbc:oracle:oci8:@", "scott", "tiger");
           #sql [dctx] {
           select ename, sal, TO_CHAR(hiredate,'DD-MON-YYYY')
           INTO :ename, :sal, :hireDate
           FROM scott.emp WHERE UPPER(empno) = UPPER(:empno)
         };
         sb.append("<BLOCKQUOTE><BIG><B><PRE>\n");
         sb.append("Name : " + ename + "\n");
         sb.append("Salary : " + sal + "\n");
         sb.append("Date hired : " + hireDate);
         sb.append("</PRE></B></BIG></BLOCKQUOTE>");
         } catch (java.sql.SQLException e) {
           sb.append("<P> SQL error: <PRE> " + e + " </PRE> </P>\n");
         } finally {
         if (dctx!= null) dctx.close();
         }
      return sb.toString();
    }

    %>

This example uses the JDBC OCI driver, which requires an Oracle client installation. The `Oracle` class used in getting the connection is provided with Oracle SQLJ.

Entering employee number 7788 results in the following output:

Notes: In case a JSP page is invoked multiple times in the same JVM, it is recommended that you always use an explicit connection context, such as `dctx` in the example, instead of the default connection context. (Note that `dctx` is a local method variable.) OracleJSP requires Oracle SQLJ release 8.1.6.1 or higher. In the future, OracleJSP will support `language="sqlj"` in a `page` directive to trigger the Oracle SQLJ translator during JSP translation. For forward compatibility, it is recommended as a good programming practice that you begin using this directive immediately.

For further examples of using SQLJ in JSP pages, see "SQLJ Queries--SQLJSelectInto.sqljsp and SQLJIterator.sqljsp".

For general information about Oracle SQLJ programming features and syntax, see the Oracle8i SQLJ Developer's Guide and Reference.

#### Triggering the SQLJ Translator

You can trigger the OracleJSP translator to invoke the Oracle SQLJ translator by using the file name extension `.sqljsp` for the JSP source file.

This results in the OracleJSP translator generating a `.sqlj` file instead of a `.java` file; the Oracle SQLJ translator is then invoked to translate the `.sqlj` file into a `.java` file.

Using SQLJ results in additional output files; see "Generated Files and Locations (On-Demand Translation)".

Important: To use Oracle SQLJ, you will have to install appropriate SQLJ ZIP files (depending on your environment) and add them to your classpath. See "Required and Optional Files for OracleJSP". Do not use the same base file name for a `.jsp` file and a `.sqljsp` file in the same application, because they would result in the same generated class name and `.java` file name.

#### Setting Oracle SQLJ Options

When you execute or pre-translate a SQLJ JSP page, you can specify desired Oracle SQLJ option settings. This is true both in on-demand translation scenarios and pre-translation scenarios, as follows:

- For on-demand translation, use the OracleJSP `sqljcmd` configuration parameter. This parameter, in addition to allowing you to specify a particular SQLJ translator executable, allows you to set SQLJ command-line options. (The `sqljcmd` parameter is not available prior to OracleJSP release 1.1.0.0.0.)

  For information, see the `sqljcmd` description in "OracleJSP Configuration Parameters (Non-OSE)". For how to set configuration parameters, see "OracleJSP Configuration Parameter Settings".

- For pre-translation with the `ojspc` pre-translation tool, use the `ojspc -S` option. This option allows you to set SQLJ command-line options.

  For information, see "Command-Line Syntax for ojspc" and "Option Descriptions for ojspc".

For general information about Oracle SQLJ options, see the Oracle8i SQLJ Developer's Guide and Reference.

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