5
Oracle-Specific Programming Extensions

This chapter discusses extended JSP functionality offered by Oracle that is not portable to other JSP environments. This consists of event-handling through the Oracle JspScopeListener mechanism and support for SQLJ, a standard syntax for embedding SQL statements directly into Java code. The chapter is organized as follows:

Oracle JSP Event Handling with JspScopeListener

Oracle JSP Support for Oracle SQLJ

Notes:

For servlet 2.0 environments, the Oracle JSP container supports non-portable extensions through a mechanism called globals.jsa to support a Web application framework. "Oracle JSP Application and Session Support for JServ" describes this mechanism.
The Oracle JSP container also has extended (and non-portable) globalization support, which is described in "Oracle JSP Extended Support for Multibyte Parameter Encoding".

Oracle JSP Event Handling with JspScopeListener

In standard servlet and JSP technology, only session-based events are supported. The Oracle JSP container extends this support through the JspScopeListener interface and JspScopeEvent class in the oracle.jsp.event package. This 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 Oracle JSP 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 Oracle JSP 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.

Oracle JSP Support for Oracle SQLJ

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

For general information about Oracle SQLJ programming features, syntax, and command-line options, see the Oracle9i SQLJ Developer's Guide and Reference.

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>\n");
     sb.append("Name : " + ename + "\n");
     sb.append("Salary : " + sal + "\n");
     sb.append("Date hired : " + hireDate);
     sb.append("</B></BIG></BLOCKQUOTE>");
     } catch (java.sql.SQLException e) {
       sb.append("<P> SQL error:  " + e + "  </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.

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.)
The Oracle JSP container requires Oracle SQLJ release 8.1.6.1 or higher.
In future releases (and in Oracle9i Application Server release 2), the Oracle JSP container 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.

Entering employee number 7788 for the schema used in the example results in the following output:

Text description of testsqlj.gif follows.

Text description of the illustration testsqlj.gif

Triggering the SQLJ Translator

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

This results in the JSP 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 JAR or ZIP files, depending on your environment, and add them to your classpath. See "Required and Optional Files for Oracle JSP".
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:

In an on-demand translation scenario, use the JSP 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.

For information, see the sqljcmd description in "Oracle JSP Configuration Parameters". For how to set configuration parameters in a JServ environment, see "Setting JSP Parameters in JServ".
In a pre-translation scenario 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".

5 Oracle-Specific Programming Extensions

Oracle JSP Event Handling with JspScopeListener

Oracle JSP Support for Oracle SQLJ

SQLJ JSP Code Example

Triggering the SQLJ Translator

Setting Oracle SQLJ Options

5
Oracle-Specific Programming Extensions