[orc-xx] oraclejsp

OracleJSP

Support for JavaServer Pages Developer’s Guide and Reference

Release 1.1.3.1

June 2001

Part No. n/a

OracleJSP Support for JavaServer Pages Developer’s Guide and Reference, Release 1.1.3.1

Part No. n/a

Copyright © 2000, 2001 Oracle Corporation. All rights reserved.

Primary Author: Brian Wright

Contributing Author: Michael Freedman

Contributors: Julie Basu, Alex Yiu, Sunil Kunisetty, Gael Stevens, Ping Guo, YaQing Wang, Song Lin, Hal Hildebrand, Jasen Minton, Matthieu Devin, Jose Alberto Fernandez, Olga Peschansky, Jerry Schwarz, Clement Lai, Shinji Yoshida, Kenneth Tang, Robert Pang, Kannan Muthukkaruppan, Ralph Gordon, Shiva Prasad, Sharon Malek, Jeremy Lizt, Kuassi Mensah, Susan Kraft, Sheryl Maring, Ellen Barnes, Angie Long, Sanjay Singh, Olaf van der Geest

The Programs (which include both the software and documentation) contain proprietary information of Oracle Corporation; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation.

If the Programs are delivered to the U.S. Government or anyone licensing or using the programs on behalf of the U.S. Government, the following notice is applicable:

Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial computer software" and use, duplication, and disclosure of the Programs, including documentation, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR 52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the Programs.

Oracle is a registered trademark, and OracleJSP, JDeveloper, Oracle9i Net, Oracle Objects, Oracle9i, Oracle8i, Oracle8, Oracle7, Oracle9i Lite, PL/SQL, Pro*C, SQL*Net, and SQL*Plus are trademarks or registered trademarks of Oracle Corporation. Other names may be trademarks of their respective owners.

Contents

Send Us Your Comments .................................................................................................................. xiii

Preface........................................................................................................................................................... xv

Intended Audience ............................................................................................................................... xvStructure ................................................................................................................................................ xviRelated Documents............................................................................................................................. xviiAdditional Resources ........................................................................................................................... xxConventions.......................................................................................................................................... xxiDocumentation Accessibility ............................................................................................................ xxii

1 General Overview

Introduction to JavaServer Pages..................................................................................................... 1-2What a JSP Page Looks Like........................................................................................................ 1-2Convenience of JSP Coding Versus Servlet Coding ................................................................ 1-3Separation of Business Logic from Page Presentation—Calling JavaBeans ........................ 1-5JSP Pages and Alternative Markup Languages........................................................................ 1-6

JSP Execution ....................................................................................................................................... 1-7JSP Containers in a Nutshell ....................................................................................................... 1-7JSP Pages and On-Demand Translation.................................................................................... 1-7Requesting a JSP Page.................................................................................................................. 1-8

Overview of JSP Syntax Elements................................................................................................. 1-10Directives ..................................................................................................................................... 1-10Scripting Elements...................................................................................................................... 1-12JSP Objects and Scopes .............................................................................................................. 1-14

iii

JSP Actions and the <jsp: > Tag Set.......................................................................................... 1-18Tag Libraries ................................................................................................................................ 1-23

2 Overview of Oracle’s JSP Implementation

Portability and Functionality Across Servlet Environments ...................................................... 2-2OracleJSP Portability .................................................................................................................... 2-2OracleJSP Extended Functionality for Servlet 2.0 Environments .......................................... 2-2

Support for OracleJSP in Oracle Environments ........................................................................... 2-4Overview of the Oracle9i Servlet Engine (OSE) ....................................................................... 2-4Overview of the Oracle9i Application Server........................................................................... 2-5Role of the Oracle HTTP Server, Powered by Apache............................................................ 2-6Oracle Web Application Data-Access Strategies...................................................................... 2-8Overview of Other Oracle JSP Environments .......................................................................... 2-9

Support for OracleJSP in Non-Oracle Environments ................................................................ 2-11Overview of OracleJSP Programmatic Extensions ..................................................................... 2-12

Overview of Portable OracleJSP Extensions........................................................................... 2-12Overview of Oracle-Specific Extensions.................................................................................. 2-15Use of OracleJSP with Oracle PL/SQL Server Pages ............................................................ 2-16

Overview of Oracle Caching Support for Web Applications................................................... 2-19Oracle9i Application Server and OracleJSP Caching Features ............................................ 2-19Role of the OracleJSP Web Object Cache................................................................................. 2-21

Summary of OracleJSP Releases and Feature Sets..................................................................... 2-23OracleJSP Releases Provided with Oracle Platforms............................................................. 2-23OracleJSP Feature Notes for Previous Releases ..................................................................... 2-24

OracleJSP Execution Models .......................................................................................................... 2-26On-Demand Translation Model ............................................................................................... 2-26Oracle9i Servlet Engine Pre-Translation Model ..................................................................... 2-26

Oracle JDeveloper Support for OracleJSP ................................................................................... 2-28

3 Basics

Preliminary Considerations .............................................................................................................. 3-2Installation and Configuration Overview................................................................................. 3-2Development Environments Versus Deployment Environments ......................................... 3-2Client-Side Considerations.......................................................................................................... 3-3

Application Root and Doc Root Functionality .............................................................................. 3-4

iv

Application Roots in Servlet 2.2 Environments ....................................................................... 3-4OracleJSP Application Root Functionality in Servlet 2.0 Environments .............................. 3-5

Overview of JSP Applications and Sessions ................................................................................. 3-6General OracleJSP Application and Session Support ............................................................. 3-6JSP Default Session Requests ...................................................................................................... 3-6

JSP-Servlet Interaction....................................................................................................................... 3-7Invoking a Servlet from a JSP Page............................................................................................ 3-7Passing Data to a Servlet Invoked from a JSP Page................................................................. 3-8Invoking a JSP Page from a Servlet............................................................................................ 3-8Passing Data Between a JSP Page and a Servlet....................................................................... 3-9JSP-Servlet Interaction Samples................................................................................................ 3-10

JSP Resource Management ............................................................................................................. 3-12Standard Session Resource Management—HttpSessionBindingListener ......................... 3-12Overview of Oracle Extensions for Resource Management................................................. 3-17

JSP Runtime Error Processing ........................................................................................................ 3-18Using JSP Error Pages ................................................................................................................ 3-18JSP Error Page Example............................................................................................................. 3-19

JSP Starter Sample for Data Access............................................................................................... 3-21

4 Key Considerations

General JSP Programming Strategies, Tips, and Traps ............................................................... 4-2JavaBeans Versus Scriptlets......................................................................................................... 4-2Use of Enterprise JavaBeans in JSP Pages ................................................................................. 4-3Use of JDBC Performance Enhancement Features .................................................................. 4-9Static Includes Versus Dynamic Includes ............................................................................... 4-12When to Consider Creating and Using JSP Tag Libraries .................................................... 4-14Use of a Central Checker Page.................................................................................................. 4-15Workarounds for Large Static Content in JSP Pages............................................................. 4-16Method Variable Declarations Versus Member Variable Declarations.............................. 4-18Page Directive Characteristics .................................................................................................. 4-19JSP Preservation of White Space and Use with Binary Data................................................ 4-20

Key OracleJSP Configuration Issues ............................................................................................ 4-24Optimization of JSP Execution ................................................................................................. 4-24Classpath and Class Loader Issues (Non-OSE Only)............................................................ 4-25

OracleJSP Runtime Page and Class Reloading (Non-OSE Only) ........................................... 4-29

v

Dynamic Page Retranslation ..................................................................................................... 4-29Dynamic Page Reloading........................................................................................................... 4-29Dynamic Class Reloading.......................................................................................................... 4-30

Considerations for the Oracle9i Servlet Engine ......................................................................... 4-32Introduction to the Oracle JVM and JDBC Server-Side Internal Driver ............................. 4-33Database Connections Through Java....................................................................................... 4-33Use of JNDI by the Oracle9i Servlet Engine............................................................................ 4-36Equivalent Code for OracleJSP Runtime Configuration Parameters.................................. 4-37

Considerations for Apache/JServ Servlet Environments .......................................................... 4-38Use of Apache/JServ in the Oracle9i Application Server..................................................... 4-38Dynamic Includes and Forwards in Apache/JServ............................................................... 4-39Application Framework for Apache/JServ ............................................................................ 4-41JSP and Servlet Session Sharing................................................................................................ 4-42Directory Alias Translation ....................................................................................................... 4-42

5 OracleJSP Extensions

Portable OracleJSP Programming Extensions ............................................................................... 5-2JML Extended Datatypes ............................................................................................................. 5-2OracleJSP Support for XML and XSL ........................................................................................ 5-9Oracle Data-Access JavaBeans .................................................................................................. 5-13OracleJSP Tag Library for SQL ................................................................................................. 5-24

Oracle-Specific Programming Extensions.................................................................................... 5-33OracleJSP Event Handling—JspScopeListener ...................................................................... 5-33OracleJSP Support for Oracle SQLJ.......................................................................................... 5-34

OracleJSP Application and Session Support for Servlet 2.0 .................................................... 5-38Overview of globals.jsa Functionality ..................................................................................... 5-38Overview of globals.jsa Syntax and Semantics ...................................................................... 5-40The globals.jsa Event Handlers................................................................................................. 5-43Global Declarations and Directives.......................................................................................... 5-47

6 JSP Translation and Deployment

Functionality of the OracleJSP Translator...................................................................................... 6-2Generated Code Features ............................................................................................................ 6-3General Conventions for Output Names .................................................................................. 6-4Generated Package and Class Names (On-Demand Translation)......................................... 6-5

vi

Generated Files and Locations (On-Demand Translation)..................................................... 6-7Sample Page Implementation Class Source.............................................................................. 6-9

Overview of Features and Logistics in Deployment to Oracle9i............................................. 6-14Database Schema Objects for Java............................................................................................ 6-14Oracle HTTP Server as a Front-End Web Server ................................................................... 6-16URLs for the Oracle9i Servlet Engine ...................................................................................... 6-17Static Files for JSP Applications in the Oracle9i Servlet Engine .......................................... 6-20Server-Side Versus Client-Side Translation............................................................................ 6-22Overview of Hotloaded Classes in Oracle9i ........................................................................... 6-24

Tools and Commands for Translation and Deployment to Oracle9i ...................................... 6-26The ojspc Pre-Translation Tool ................................................................................................. 6-26Overview of the loadjava Tool ................................................................................................. 6-40Overview of the sess_sh Session Shell Tool............................................................................ 6-42

Deployment to Oracle9i with Server-Side Translation ............................................................. 6-45Loading Untranslated JSP Pages into Oracle9i (loadjava).................................................... 6-45Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)................... 6-46

Deployment to Oracle9i with Client-Side Translation.............................................................. 6-59Pre-Translating JSP Pages (ojspc) ............................................................................................. 6-59Loading Translated JSP Pages into Oracle9i (loadjava) ........................................................ 6-64Hotloading Page Implementation Classes in Oracle9i.......................................................... 6-68Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet) ..................... 6-69

Additional JSP Deployment Considerations .............................................................................. 6-73Doc Root for Oracle9i Application Server Versus Oracle9i Servlet Engine ....................... 6-73Use of ojspc for Pre-Translation for Non-OSE Environments ............................................. 6-74General JSP Pre-Translation Without Execution.................................................................... 6-75Deployment of Binary Files Only............................................................................................. 6-75WAR Deployment ...................................................................................................................... 6-77Deployment of JSP Pages with JDeveloper ............................................................................ 6-79

7 JSP Tag Libraries and the Oracle JML Tags

Standard Tag Library Framework .................................................................................................... 7-2Overview of a Custom Tag Library Implementation.............................................................. 7-2Tag Handlers ................................................................................................................................. 7-4Scripting Variables and Tag-Extra-Info Classes....................................................................... 7-8Access to Outer Tag Handler Instances .................................................................................. 7-10

vii

Tag Library Description Files.................................................................................................... 7-11Use of web.xml for Tag Libraries ............................................................................................. 7-12The taglib Directive .................................................................................................................... 7-14End-to-End Example: Defining and Using a Custom Tag.................................................... 7-15

Overview of the JSP Markup Language (JML) Sample Tag Library ...................................... 7-20JML Tag Library Philosophy..................................................................................................... 7-21JML Tag Categories .................................................................................................................... 7-21JML Tag Library Description File and taglib Directive......................................................... 7-22

JSP Markup Language (JML) Tag Descriptions .......................................................................... 7-30Syntax Symbology and Notes ................................................................................................... 7-30Bean Binding Tag Descriptions................................................................................................. 7-30Logic and Flow Control Tag Descriptions .............................................................................. 7-34

8 JESI Tags for Edge Side Includes

Overview of Edge Side Includes Technology and Processing ................................................... 8-2Edge Side Includes Technology.................................................................................................. 8-2Oracle Web Cache and ESI Processor ........................................................................................ 8-4

Overview of JESI Functionality ....................................................................................................... 8-6Motivation for JESI Tags .............................................................................................................. 8-6Overview of JESI Tags Implemented by OracleJSP................................................................. 8-7JESI Usage Models ........................................................................................................................ 8-8Page Invalidation ........................................................................................................................ 8-10Page Personalization .................................................................................................................. 8-10

OracleJSP JESI Tag Descriptions ................................................................................................... 8-11Syntax Symbology and Notes ................................................................................................... 8-11Page Setup and Content Tag Descriptions.............................................................................. 8-12Page Invalidation Tag and Subtag Descriptions .................................................................... 8-21Page Personalization Tag Description ..................................................................................... 8-27JESI Tag Handling and JESI-to-ESI Conversion ..................................................................... 8-28OracleJSP JESI Tag Library Description File........................................................................... 8-29

9 Web Object Cache Tags and API

Overview of the Web Object Cache ................................................................................................ 9-2Benefits of the Web Object Cache............................................................................................... 9-2Web Object Cache Components ................................................................................................. 9-4

viii

Cache Policy and Scope ............................................................................................................... 9-6Key Functionality of the Web Object Cache ................................................................................. 9-7

Cache Block Naming—Implicit Versus Explicit ...................................................................... 9-7Cloneable Cache Objects.............................................................................................................. 9-8Cache Block Runtime Functionality......................................................................................... 9-10Data Invalidation and Expiration............................................................................................. 9-10

Attributes for Policy Specification and Use ................................................................................ 9-12Cache Policy Attributes ............................................................................................................. 9-12Expiration Policy Attributes...................................................................................................... 9-18

Web Object Cache Tag Descriptions ............................................................................................. 9-21Syntax Symbology and Notes................................................................................................... 9-21Cache Tag Descriptions ............................................................................................................. 9-21Cache Invalidation Tag Description ........................................................................................ 9-34Web Object Cache Tag Library Description File .................................................................... 9-39

Web Object Cache Servlet API Description ................................................................................ 9-50Cache Policy Object Creation.................................................................................................... 9-50CachePolicy Methods................................................................................................................. 9-51Expiration Policy Object Retrieval ........................................................................................... 9-57ExpirationPolicy Methods ......................................................................................................... 9-57CacheBlock Methods.................................................................................................................. 9-59Sample Servlet Using the Web Object Cache API.................................................................. 9-59

Cache Policy Descriptor................................................................................................................... 9-63Cache Policy Descriptor DTD ................................................................................................... 9-63Sample Cache Policy Descriptor .............................................................................................. 9-64Cache Policy Descriptor Loading and Refreshing................................................................. 9-64

Cache Repository Descriptor .......................................................................................................... 9-66Cache Repository Descriptor DTD........................................................................................... 9-66Sample Cache Repository Descriptor ...................................................................................... 9-67

10 OracleJSP Globalization Support

Content Type Settings in the page Directive............................................................................... 10-2Dynamic Content Type Settings .................................................................................................... 10-4OracleJSP Extended Support for Multibyte Parameter Encoding .......................................... 10-5

The setReqCharacterEncoding() Method................................................................................ 10-5The translate_params Configuration Parameter.................................................................... 10-6

ix

11 Sample Applications

Basic Samples .................................................................................................................................... 11-2Hello Page—hellouser.jsp.......................................................................................................... 11-2Usebean Page—usebean.jsp ...................................................................................................... 11-3Shopping Cart Page—cart.jsp ................................................................................................... 11-5Information Page—info.jsp ..................................................................................................... 11-10

JDBC Samples ................................................................................................................................. 11-12Simple Query—SimpleQuery.jsp ........................................................................................... 11-12User-Specified Query—JDBCQuery.jsp ................................................................................ 11-14Query Using a Query Bean—UseHtmlQueryBean.jsp ....................................................... 11-15Connection Caching—ConnCache3.jsp and ConnCache1.jsp ........................................... 11-18

Data-Access JavaBean Samples .................................................................................................... 11-23Page Using DBBean—DBBeanDemo.jsp ............................................................................... 11-23Page Using ConnBean—ConnBeanDemo.jsp....................................................................... 11-25Page Using CursorBean—CursorBeanDemo.jsp ................................................................. 11-26Page Using ConnCacheBean—ConnCacheBeanDemo.jsp ................................................. 11-28

Custom Tag Samples ...................................................................................................................... 11-31JML Tag Sample—hellouser_jml.jsp...................................................................................... 11-31Pointers to Additional Custom Tag Samples ....................................................................... 11-33

Samples for Oracle-Specific Programming Extensions........................................................... 11-34Page Using JspScopeListener—scope.jsp .............................................................................. 11-34XML Query—XMLQuery.jsp.................................................................................................. 11-38SQLJ Queries—SQLJSelectInto.sqljsp and SQLJIterator.sqljsp.......................................... 11-39

JESI Tag Sample—Portal Demo ................................................................................................... 11-43Portal Demo Explanation......................................................................................................... 11-43Portal Demo Source Code........................................................................................................ 11-45

Samples for the Web Object Cache ............................................................................................. 11-61Web Object Cache—Using Oracle9iAS Object Caching Service for Java ......................... 11-61Web Object Cache—Using a File System Cache .................................................................. 11-65Web Object Cache—Caching XML DOM Objects ............................................................... 11-69Web Object Cache—Caching Generic Java Objects ............................................................. 11-71Web Object Cache—Tag Code Versus API Code................................................................. 11-75

Samples Using globals.jsa for Servlet 2.0 Environments........................................................ 11-81globals.jsa Example for Application Events—lotto.jsp ....................................................... 11-81globals.jsa Example for Application and Session Events—index1.jsp.............................. 11-84

x

globals.jsa Example for Global Declarations—index2.jsp .................................................. 11-87

A General Installation and Configuration

System Requirements ........................................................................................................................ A-2OracleJSP Installation and Web Server Configuration ............................................................... A-3

Required and Optional Files for OracleJSP............................................................................... A-3Configuration of Web Server and Servlet Environment to Run OracleJSP ......................... A-7

OracleJSP Configuration ................................................................................................................. A-15OracleJSP Configuration Parameters (Non-OSE) .................................................................. A-15OracleJSP Configuration Parameter Settings ......................................................................... A-26

B Servlet and JSP Technical Background

Background on Servlets ..................................................................................................................... B-2Review of Servlet Technology .................................................................................................... B-2The Servlet Interface..................................................................................................................... B-3Servlet Containers......................................................................................................................... B-3Servlet Sessions ............................................................................................................................. B-4Servlet Contexts ............................................................................................................................ B-6Application Lifecycle Management Through Event Listeners .............................................. B-7Servlet Invocation ......................................................................................................................... B-8

Web Application Hierarchy .............................................................................................................. B-9Standard JSP Interfaces and Methods .......................................................................................... B-12

C Compile-Time JML Tag Support

JML Compile-Time Versus Runtime Considerations and Logistics ......................................... C-2General Compile-Time Versus Runtime Considerations ....................................................... C-2The taglib Directive for Compile-Time JML Support ............................................................. C-3

JML Compile-Time/1.0.0.6.x Syntax Support ................................................................................ C-4JML Bean References and Expressions, Compile-Time Implementation............................. C-4Attribute Settings with JML Expressions .................................................................................. C-5

JML Compile-Time/1.0.0.6.x Tag Support ...................................................................................... C-7JML Tag Summary, 1.0.0.6.x/Compile-Time Versus 1.1.x.x/Runtime ................................ C-7Descriptions of Additional JML Tags, Compile-Time Implementation ............................... C-8

xi

Send Us Your Comments

OracleJSP Support for JavaServer Pages Developer’s Guide and Reference, Release 1.1.3.1

Part No. n/a

Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of this document. Your input is an important part of the information used for revision.

■ Did you find any errors?■ Is the information clearly presented?■ Do you need more information? If so, where?■ Are the examples correct? Do you need more examples?■ What features did you like most?

If you find any errors or have any other suggestions for improvement, please indicate the document title and part number, and the chapter, section, and page number (if available). You can send com-ments to us in the following ways:

■ Electronic mail: [email protected] ■ FAX: (650) 506-7225 Attn: Java Platform Group, Information Development Manager■ Postal service:

Oracle Corporation Java Platform Group, Information Development Manager500 Oracle Parkway, Mailstop 4op9Redwood Shores, CA 94065USA

If you would like a reply, please give your name, address, telephone number, and (optionally) elec-tronic mail address.

If you have problems with the software, please contact your local Oracle Support Services.

xiii

Preface

This document introduces and explains Oracle’s implementation of JavaServer Pages (JSP) technology, specified by Sun Microsystems. The document summarizes standard features, as specified by Sun, but focuses primarily on Oracle-specific implementations and extensions in the OracleJSP product.

Intended AudienceThis document is intended for developers interested in using OracleJSP to create Web applications based on JavaServer Pages technology. It assumes that working Web and servlet environments already exist, and that readers are already familiar with the following:

■ general Web technology

■ general servlet technology (some technical background is provided in Appendix B)

■ how to configure their Web server and servlet environments

■ HTML

■ Java

■ Oracle JDBC (for JSP applications accessing an Oracle database)

■ Oracle SQLJ (for JSP database applications using SQLJ)

Note: OracleJSP release 1.1.3.x is a complete implementation of the Sun Microsystems JavaServer Pages Specification, Version 1.1.

xv

This document focuses on Oracle JSP extensions, and on features and logistics particular to running JSP pages in the Oracle9i Servlet Engine.

While some information about standard JSP 1.1 technology and syntax is provided in Chapter 1 and elsewhere, there is no attempt at completeness in this area. For additional information about standard JSP 1.1 features, consult the Sun Microsystems JavaServer Pages Specification, Version 1.1 or other appropriate reference materials.

Because the JSP 1.1 specification relies on a servlet 2.2 environment, this document is geared largely toward such environments. OracleJSP has special features for earlier servlet environments, however, and there is special discussion of these features as they relate to servlet 2.0 environments, particularly Apache/JServ, which is included with the Oracle9i Application Server.

StructureThis document includes the following chapters and appendixes:

■ Chapter 1, "General Overview"—This chapter highlights standard JSP 1.1 technology. (It is not intended as a complete reference.)

■ Chapter 2, "Overview of Oracle’s JSP Implementation"—This chapter discusses support for OracleJSP in both Oracle and non-Oracle JSP environments, and introduces Oracle JSP extensions and features.

■ Chapter 3, "Basics"—This chapter introduces basic JSP programming considerations and provides a starter sample for database access.

■ Chapter 4, "Key Considerations"—This chapter discusses a variety of general programming and configuration issues the developer should be aware of. It also covers considerations specific to the OSE and Apache/JServ environments.

■ Chapter 5, "OracleJSP Extensions"—This chapter covers Oracle JSP extensions—both Oracle-specific extensions and extensions that are portable to other JSP environments.

■ Chapter 6, "JSP Translation and Deployment"—This chapter focuses on procedures and logistics in deploying JSP pages to Oracle9i to run in the Oracle9i Servlet Engine, but also covers general JSP translation and deployment features and issues.

■ Chapter 7, "JSP Tag Libraries and the Oracle JML Tags"—This chapter introduces the basic JSP 1.1 framework for custom tag libraries and also

xvi

provides an overview and tag descriptions for the JSP 1.1 (runtime) implementation of the Oracle JML sample tag library.

■ Chapter 8, "JESI Tags for Edge Side Includes"—This chapter describes the OracleJSP implementation of JESI tags to support Edge Side Includes technology for Web caching.

■ Chapter 9, "Web Object Cache Tags and API"—This chapter describes concepts, custom tags, servlet APIs, and XML descriptor files for the Web Object Cache, an application-level Java caching service provided with OracleJSP.

■ Chapter 10, "OracleJSP Globalization Support"—This chapter discusses both standard and Oracle-specific features for globalization support.

■ Chapter 11, "Sample Applications"—This chapter contains a set of sample applications covering both standard JSP technology and Oracle extensions.

■ Appendix A, "General Installation and Configuration"—This appendix covers OracleJSP required and optional files, configuration steps for non-Oracle environments such as Apache/JServ and Tomcat, and OracleJSP configuration parameters for on-demand translation.

■ Appendix B, "Servlet and JSP Technical Background"—This appendix provides a brief background of servlet technology and introduces the standard JSP interfaces for translated pages.

■ Appendix C, "Compile-Time JML Tag Support"—This chapter provides an overview of the compile-time implementation of the Oracle JML sample tag library (as supported in pre-JSP 1.1 releases), and documents tags not supported in the runtime implementation documented in Chapter 7.

Related DocumentsSee the following additional documents available from the Oracle Java Platform group:

■ Oracle9i Java Developer’s Guide

This book introduces the basic concepts of Java in Oracle9i and provides general information about server-side configuration and functionality. Information that pertains to the Oracle Java platform as a whole, rather than to a particular product (such as JDBC, SQLJ, or EJBs) is in this book.

xvii

■ Oracle9i Servlet Engine Developer’s Guide

This book documents use of the Oracle9i Servlet Engine, the servlet container in Oracle9i.

■ Oracle9i Java Tools Reference

This book documents Java-related tools and utilities for use with Oracle9i or in deploying applications to Oracle9i (such as the Oracle9i session shell and loadjava tools).

■ Oracle9i JDBC Developer’s Guide and Reference

This book covers programming syntax and features of Oracle’s implementation of the JDBC standard (for Java Database Connectivity). This includes an overview of the Oracle JDBC drivers, details of Oracle’s implementation of JDBC 1.22 and 2.0 features, and discussion of Oracle JDBC type extensions and performance extensions.

■ Oracle9i JPublisher User’s Guide

This book describes how to use the Oracle JPublisher utility to translate object types and other user-defined types to Java classes. If you are developing SQLJ or JDBC applications that use object types, VARRAY types, nested table types, or object reference types, then JPublisher can generate custom Java classes to map to them.

■ Oracle9i SQLJ Developer’s Guide and Reference

This book covers the use of SQLJ to embed static SQL operations directly into Java code, covering SQLJ language syntax and SQLJ translator options and features. Both standard SQLJ features and Oracle-specific SQLJ features are described.

■ Oracle9i Java Stored Procedures Developer’s Guide

This book discusses Java stored procedures—programs that run directly in the Oracle9i database. With stored procedures (functions, procedures, triggers, and SQL methods), Java developers can implement business logic at the server level, thereby improving application performance, scalability, and security.

■ Oracle9i Enterprise JavaBeans Developer’s Guide and Reference

This book describes Oracle’s Enterprise JavaBeans implementation and extensions.

■ Oracle9i CORBA Developer’s Guide and Reference

This book describes Oracle’s CORBA implementation and extensions.

xviii

The following documentation is for Oracle products that incorporate OracleJSP. You may want to refer to them for JSP information, including installation and configuration, for those products:

■ Oracle9i Application Server Documentation Library

■ Oracle Application Server, Release 4.0.8.2Developer’s Guide: JServlet and JSP Applications

■ Oracle JDeveloper online help

■ Oracle Web-to-go Implementation Guide

The following documents from the Oracle Server Technologies group or other groups may also contain information of interest.

■ Oracle Web Cache Administration and Deployment Guide

This book documents the Oracle Web Cache, which can be used to speed the execution of JSP applications or other Web applications.

■ Oracle9iAS Object Caching Service for Java Developer’s Guide

This book documents the Oracle9i Application Server Object Caching Service for Java, a service designed to cache and manage Java objects within a process, across processes, and on local disk.

■ Oracle9i Application Developer’s Guide - XML

■ Oracle9i XML Reference

These books provides information about the Oracle XML-SQL Utility. Some of this is relevant to XML-related support provided by OracleJSP.

■ Oracle9i Application Developer’s Guide - Fundamentals

This book introduces basic design concepts and programming features in using Oracle9i and creating data-access applications.

■ Oracle9i Supplied PL/SQL Packages and Types Reference

This book documents PL/SQL packages available as part of the Oracle9i database, some of which may be useful to call from JDBC applications.

■ PL/SQL User’s Guide and Reference

PL/This book explains the concepts and features of PL/SQL, Oracle’s procedural language extension to SQL.

xix

■ Oracle9i Globalization Support Guide

This book contains information about Oracle Globalization Support environment variables, character sets, and territory and locale settings. In addition, it contains an overview of common globalization issues, typical scenarios, and related considerations for OCI and SQL programmers.

■ Oracle9i SQL Reference

This book contains a complete description of the content and syntax of the SQL commands and features used to manage information in an Oracle database.

■ Oracle9i Net Services Administrator’s Guide

This book contains information about the Oracle Connection Manager and Oracle9i Net network administration in general.

■ Oracle Advanced Security Administrator’s Guide

This book describes features of the Oracle Advanced Security Option (formerly known as ANO or ASO).

■ Oracle9i Database Reference

This book contains general reference information about the Oracle9i database.

■ Oracle9i Database Error Messages

This book contains information about error messages that can be passed by the Oracle9i database.

Additional ResourcesThe following Oracle Technology Network (OTN) resources are available for further information about JavaServer Pages:

■ OTN Web site for Java servlets and JavaServer Pages:

http://technet.oracle.com/tech/java/servlets/

■ OTN JSP discussion group, accessible through the following address:

http://technet.oracle.com/support/bboard/discussions.htm

The following resources are available from Sun Microsystems:

■ Javasoft Web site for JavaServer Pages:

http://www.javasoft.com/products/jsp/index.html

xx

■ jsp-interest discussion group for JavaServer Pages

To subscribe, send an e-mail to [email protected] with the following line in the body of the message:

subscribe jsp-interest yourlastname yourfirstname

It is recommended, however, that you request only the daily digest of the posted e-mails. To do this add the following line to the message body as well:

set jsp-interest digest

ConventionsThe following conventions are used in this document:

Convention Meaning

italicized regular text Italicized regular text is used for emphasis or to indicate a term that is being defined or will be defined shortly.

. . . Horizontal ellipsis points in sample code indicate the omission of a statement or statements or part of a statement. This is done when you would normally expect additional statements or code to appear, but such statements or code would not be relevant to the example.

code text Code text within regular text indicates commands, option names, parameter names, Java syntax, class names, object names, method names, variable names, Java types, Oracle datatypes, file names, and directory names.

italicized_code_text Italicized code text in a program statement indicates something that must be provided by the user.

[italicized_code_text ] Square brackets enclosing italicized code text in a program statement indicates something that can optionally be provided by the user.

xxi

Documentation AccessibilityOracle’s goal is to make our products, services, and supporting documentation accessible to the disabled community with good usability. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For additional information, visit the Oracle Accessibility Program Web site at:

http://www.oracle.com/accessibility/

JAWS, a Windows screen reader, may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, JAWS may not always read a line of text that consists solely of a bracket or brace.

xxii

General Overv

1
General Overview
This chapter reviews standard features and functionality of JavaServer Pages technology. For further information, consult the Sun Microsystems JavaServer Pages Specification, Version 1.1.

(For an overview of Oracle-specific OracleJSP features, see Chapter 2, "Overview of Oracle’s JSP Implementation". Also note that Appendix B, "Servlet and JSP Technical Background", provides related background on standard servlet and JSP technology.)

The following topics are covered here:

■ Introduction to JavaServer Pages

■ JSP Execution

■ Overview of JSP Syntax Elements

iew 1-1

Introduction to JavaServer Pages

Introduction to JavaServer PagesJavaServer Pages(TM) is a technology specified by Sun Microsystems as a convenient way of generating dynamic content in pages that are output by a Web application (an application running on a Web server).

This technology, which is closely coupled with Java servlet technology, allows you to include Java code snippets and calls to external Java components within the HTML code (or other markup code, such as XML) of your Web pages. JavaServer Pages (JSP) technology works nicely as a front-end for business logic and dynamic functionality in JavaBeans and Enterprise JavaBeans (EJBs).

JSP code is distinct from other Web scripting code, such as JavaScript, in a Web page. Anything that you can include in a normal HTML page can be included in a JSP page as well.

In a typical scenario for a database application, a JSP page will call a component such as a JavaBean or Enterprise JavaBean, and the bean will directly or indirectly access the database, generally through JDBC or perhaps SQLJ.

A JSP page is translated into a Java servlet before being executed (typically on demand, but sometimes in advance), and it processes HTTP requests and generates responses similarly to any other servlet. JSP technology offers a more convenient way to code the servlet.

Furthermore, JSP pages are fully interoperable with servlets—JSP pages can include output from a servlet or forward to a servlet, and servlets can include output from a JSP page or forward to a JSP page.

What a JSP Page Looks LikeHere is an example of a simple JSP page. (For an explanation of JSP syntax elements used here, see "Overview of JSP Syntax Elements" on page 1-10.)

<HTML><HEAD><TITLE>The Welcome User JSP</TITLE></HEAD><BODY><% String user=request.getParameter("user"); %><H3>Welcome <%= (user==null) ? "" : user %>!</H3><P><B> Today is <%= new java.util.Date() %>. Have a nice day! :-)</B></P><B>Enter name:</B><FORM METHOD=get><INPUT TYPE="text" NAME="user" SIZE=15><INPUT TYPE="submit" VALUE="Submit name"></FORM>

1-2 OracleJSP Support for JavaServer Pages Developer’s Guide and Reference


</BODY></HTML>

In a JSP page, Java elements are set off by tags such as <% and %>, as in the preceding example. In this example, Java snippets get the user name from an HTTP request object, print the user name, and get the current date.

This JSP page will produce the following output if the user inputs the name "Amy":

Convenience of JSP Coding Versus Servlet CodingCombining Java code and Java calls into an HTML page is more convenient than using straight Java code in a servlet. JSP syntax gives you a shortcut for coding dynamic Web pages, typically requiring much less code than Java servlet syntax. Following is an example contrasting servlet code and JSP code.

Servlet Code

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

public class Hello extends HttpServlet{ public void doGet(HttpServletRequest rq, HttpServletResponse rsp) { rsp.setContentType("text/html"); try {

General Overview 1-3


PrintWriter out = rsp.getWriter(); out.println("<HTML>"); out.println("<HEAD><TITLE>Welcome</TITLE></HEAD>"); out.println("<BODY>"); out.println("<H3>Welcome!</H3>"); out.println("<P>Today is "+new java.util.Date()+".</P>"); out.println("</BODY>"); out.println("</HTML>"); } catch (IOException ioe) { // (error processing) } }}

(See "The Servlet Interface" on page B-3 for some background information about the standard HttpServlet abstract class, HttpServletRequest interface, and HttpServletResponse interface.)

JSP Code

<HTML><HEAD><TITLE>Welcome</TITLE></HEAD><BODY><H3>Welcome!</H3><P>Today is <%= new java.util.Date() %>.</P></BODY></HTML>

Note how much simpler JSP syntax is. Among other things, it saves Java overhead such as package imports and try...catch blocks.

Additionally, the JSP translator automatically handles a significant amount of servlet coding overhead for you in the .java file that it outputs, such as directly or indirectly implementing the standard javax.servlet.jsp.HttpJspPage interface (see "Standard JSP Interfaces and Methods" on page B-12) and adding code to acquire an HTTP session.

Also note that because the HTML of a JSP page is not embedded within Java print statements as is the case in servlet code, you can use HTML authoring tools to create JSP pages.



Separation of Business Logic from Page Presentation—Calling J avaBeansJSP technology allows separating the development efforts between the HTML code that determines static page presentation, and the Java code that processes business logic and presents dynamic content. It therefore becomes much easier to split maintenance responsibilities between presentation and layout specialists who may be proficient in HTML but not Java, and code specialists who may be proficient in Java but not HTML.

In a typical JSP page, most Java code and business logic will not be within snippets embedded in the JSP page—instead, it will be in JavaBeans or Enterprise JavaBeans that are invoked from the JSP page.

JSP technology offers the following syntax for defining and creating an instance of a JavaBeans class:

<jsp:useBean id="pageBean" class="mybeans.NameBean" scope="page" />

This example creates an instance, pageBean, of the mybeans.NameBean class (the scope parameter will be explained later in this chapter).

Later in the page, you can use this bean instance, as in the following example:

Hello <%= pageBean.getNewName() %> !

(This prints "Hello Julie !", for example, if the name "Julie" is in the newName attribute of pageBean, which might occur through user input.)

The separation of business logic from page presentation allows convenient division of responsibilities between the Java expert who is responsible for the business logic and dynamic content—this developer owns and maintains the code for the NameBean class—and the HTML expert who is responsible for the static presentation and layout of the Web page that the application user sees—this developer owns and maintains the code in the .jsp file for this JSP page.

Tags used with JavaBeans—useBean to declare the JavaBean instance and getProperty and setProperty to access bean properties—are further discussed in "JSP Actions and the <jsp: > Tag Set" on page 1-18.



JSP Pages and Alternative Markup LanguagesJavaServer Pages technology is typically used for dynamic HTML output, but the Sun Microsystems JavaServer Pages Specification, Version 1.1 also supports additional types of structured, text-based document output. A JSP translator does not process text outside of JSP elements, so any text that is appropriate for Web pages in general is typically appropriate for a JSP page as well.

A JSP page takes information from an HTTP request and accesses information from a data server (such as through a SQL database query). It combines and processes this information and incorporates it as appropriate into an HTTP response with dynamic content. The content can be formatted as HTML, DHTML, XHTML, or XML, for example.

For information about XML support, see "OracleJSP Support for XML and XSL" on page 5-9.


JSP Execution

JSP ExecutionThis section provides a top-level look at how a JSP is run, including on-demand translation (the first time a JSP page is run), the role of the JSP container and the servlet container, and error processing.

JSP Containers in a NutshellA JSP container is an entity that translates, executes, and processes JSP pages and delivers requests to them.

The exact make-up of a JSP container varies from implementation to implementation, but it will consist of a servlet or collection of servlets. The JSP container, therefore, is executed by a servlet container. (Servlet containers are summarized in "Servlet Containers" on page B-3.)

A JSP container may be incorporated into a Web server if the Web server is written in Java, or the container may be otherwise associated with and used by the Web server.

JSP Pages and On-Demand TranslationPresuming the typical on-demand translation scenario, a JSP page is usually executed through the following steps:

1. The user requests the JSP page through a URL ending with a .jsp file name.

2. Upon noting the .jsp file name extension in the URL, the servlet container of the Web server invokes the JSP container.

3. The JSP container locates the JSP page and translates it if this is the first time it has been requested. Translation includes producing servlet code in a .java file and then compiling the .java file to produce a servlet .class file.

The servlet class generated by the JSP translator subclasses a class (provided by the JSP container) that implements the javax.servlet.jsp.HttpJspPage interface (described in "Standard JSP Interfaces and Methods" on page B-12). The servlet class is referred to as the page implementation class. This document will refer to instances of page implementation classes as JSP page instances.

Note: The term JSP container is used in the Sun Microsystems JavaServer Pages Specification, Version 1.1, replacing the term JSP engine that was used in earlier specifications. The two terms are synonymous.


JSP Execution

Translating a JSP page into a servlet automatically incorporates standard servlet programming overhead into the generated servlet code, such as implementing the HttpJspPage interface and generating code for its service method.

4. The JSP container triggers instantiation and execution of the page implementation class.

The servlet (JSP page instance) will then process the HTTP request, generate an HTTP response, and pass the response back to the client.

Requesting a JSP PageA JSP page can be requested either directly—through a URL—or indirectly—through another Web page or servlet.

Directly Request a JSP PageAs with a servlet or HTML page, the end-user can request a JSP page directly by URL. For example, assume you have a HelloWorld JSP page that is located under the myapp application root directory in the Web server, as follows:

myapp/dir1/HelloWorld.jsp

If it uses port 8080 of the Web server, you can request it with the following URL:

http://hostname:8080/myapp/dir1/HelloWorld.jsp

(The application root directory is specified in the servlet context of the application. "Servlet Contexts" on page B-6 summarizes servlet contexts.)

The first time the end-user requests HelloWorld.jsp, the JSP container triggers both translation and execution of the page. With subsequent requests, the JSP container triggers page execution only; the translation step is no longer necessary.

Note: The preceding steps are loosely described for purposes of this discussion. As mentioned earlier, each vendor decides how to implement its JSP container, but it will consist of a servlet or collection of servlets. For example, there may be a front-end servlet that locates the JSP page, a translation servlet that handles translation and compilation, and a wrapper servlet class that is subclassed by each page implementation class (because a translated page is not a pure servlet and cannot be run directly by the servlet container). A servlet container is required to run each of these components.


JSP Execution

Indirectly Requesting a JSP PageJSP pages, like servlets, can also be executed indirectly—linked from a regular HTML page or referenced from another JSP page or from a servlet.

When invoking one JSP page from a JSP statement in another JSP page, the path can be either relative to the application root—known as context-relative or application-relative—or relative to the invoking page—known as page-relative. An application-relative path starts with "/"; a page-relative path does not.

Be aware that, typically, neither of these paths is the same path as used in a URL or HTML link. Continuing the example in the preceding section, the path in an HTML link is the same as in the direct URL request, as follows:

<a href="/myapp/dir1/HelloWorld.jsp" /a>

The application-relative path in a JSP statement is:

<jsp:include page="/dir1/HelloWorld.jsp" flush="true" />

The page-relative path to invoke HelloWorld.jsp from a JSP page in the same directory is:

<jsp:forward page="HelloWorld.jsp" />

("JSP Actions and the <jsp: > Tag Set" on page 1-18 discusses the jsp:include and jsp:forward statements.)


Overview of JSP Syntax Elements

Overview of JSP Syntax ElementsYou have seen a simple example of JSP syntax in "What a JSP Page Looks Like" on page 1-2; now here is a top-level list of syntax categories and topics:

■ directives—These convey information regarding the JSP page as a whole.

■ scripting elements—These are Java coding elements such as declarations, expressions, scriptlets, and comments.

■ objects and scopes—JSP objects can be created either explicitly or implicitly and are accessible within a given scope, such as from anywhere in the JSP page or the session.

■ actions—These create objects or affect the output stream in the JSP response (or both).

This section introduces each category, including basic syntax and a few examples. For more information, see the Sun Microsystems JavaServer Pages Specification, Version 1.1.

DirectivesDirectives provide instruction to the JSP container regarding the entire JSP page. This information is used in translating or executing the page. The basic syntax is as follows:

<%@ directive attribute1="value1" attribute2="value2"... %>

The JSP 1.1 specification supports the following directives:

■ page—Use this directive to specify any of a number of page-dependent attributes, such as the scripting language to use, a class to extend, a package to import, an error page to use, or the JSP page output buffer size. For example:

<%@ page language="java" import="packages.mypackage" errorPage="boof.jsp" %>

Or, to set the JSP page output buffer size to 20kb (the default is 8kb):

<%@ page buffer="20kb" %>

Notes: There are XML-compatible alternatives to the syntax for JSP directives, declarations, expressions, and scriptlets. See "XML-Alternative Syntax" on page 5-9.



Or, to unbuffer the page:

<%@ page buffer="none" %>

■ include—Use this directive to specify a resource that contains text or code to be inserted into the JSP page when it is translated. Specify the path of the resource relative to the URL specification of the JSP page.

Example:

<%@ include file="/jsp/userinfopage.jsp" %>

The include directive can specify either a page-relative or context-relative location (see "Requesting a JSP Page" on page 1-8 for related discussion).

■ taglib—Use this directive to specify a library of custom JSP tags that will be used in the JSP page. Vendors can extend JSP functionality with their own sets of tags. This directive indicates the location of a tag library description file and a prefix to distinguish use of tags from that library.

Example:

<%@ taglib uri="/oracustomtags" prefix="oracust" %>

Notes:

■ A JSP page using an error page must be buffered. Forwarding to an error page clears the buffer (not outputting it to the browser).

■ In OracleJSP, java is the default language setting. It is good programming practice to set it explicitly, however.

Notes:

■ The include directive, referred to as a "static include", is comparable in nature to the jsp:include action discussed later in this chapter, but takes effect at JSP translation time instead of request time. See "Static Includes Versus Dynamic Includes" on page 4-12.

■ The include directive can be used only between pages in the same servlet context.



Later in the page, use the oracust prefix whenever you want to use one of the tags in the library (presume this library includes a tag dbaseAccess):

<oracust:dbaseAccess>...</oracust:dbaseAccess>

As you can see, this example uses XML-style start-tag and end-tag syntax.

JSP tag libraries and tag library description files are introduced later in this chapter, in "Tag Libraries" on page 1-23, and discussed in detail in Chapter 7, "JSP Tag Libraries and the Oracle JML Tags".

Scripting ElementsJSP scripting elements include the following categories of snippets of Java code that can appear in a JSP page:

■ declarations—These are statements declaring methods or member variables that will be used in the JSP page.

A JSP declaration uses standard Java syntax within the <%!...%> declaration tags to declare a member variable or method. This will result in a corresponding declaration in the generated servlet code. For example:

<%! double f1=0.0; %>

This example declares a member variable, f1. In the servlet class code generated by the JSP translator, f1 will be declared at the class top level.

■ expressions—These are Java expressions that are evaluated, converted into string values as appropriate, and displayed where they are encountered on the page.

A JSP expression does not end in a semi-colon, and is contained within <%=...%> tags.

Example:

<P><B> Today is <%= new java.util.Date() %>. Have a nice day! </B></P>

Note: Method variables, as opposed to member variables, are declared within JSP scriptlets as described below.



■ scriptlets—These are portions of Java code intermixed within the markup language of the page.

A scriptlet, or code fragment, may consist of anything from a partial line to multiple lines of Java code. You can use them within the HTML code of a JSP page to set up conditional branches or a loop, for example.

A JSP scriptlet is contained within <%...%> scriptlet tags, using normal Java syntax.

Example 1:

<% if (pageBean.getNewName().equals("")) { %> I don’t know you.<% } else { %> Hello <%= pageBean.getNewName() %>.<% } %>

Three one-line JSP scriptlets are intermixed with two lines of HTML (one of which includes a JSP expression, which does not require a semi-colon). Note that JSP syntax allows HTML code to be the code that is conditionally executed within the if and else branches (inside the Java brackets set out in the scriptlets).

The preceding example assumes the use of a JavaBean instance, pageBean.

Example 2:

<% if (pageBean.getNewName().equals("")) { %> I don’t know you. <% empmgr.unknownemployee();} else { %> Hello <%= pageBean.getNewName() %>. <% empmgr.knownemployee(); } %>

This example adds more Java code to the scriptlets. It assumes the use of a JavaBean instance, pageBean, and assumes that some object, empmgr, was previously instantiated and has methods to execute appropriate functionality for a known employee or an unknown employee.

Note: A JSP expression in a request-time attribute, such as in a jsp:setProperty statement, need not be converted to a string value.



■ comments—These are developer comments embedded within the JSP code, similar to comments embedded within any Java code.

Comments are contained within <%--...--%> tags. Unlike HTML comments, these comments are not visible when a user views the page source.

Example:

<%-- Execute the following branch if no user name is entered. --%>

JSP Objects and ScopesIn this document, the term JSP object refers to a Java class instance declared within or accessible to a JSP page. JSP objects can be either:

■ explicit—Explicit objects are declared and created within the code of your JSP page, accessible to that page and other pages according to the scope setting you choose.

or:

■ implicit—Implicit objects are created by the underlying JSP mechanism and accessible to Java scriptlets or expressions in JSP pages according to the inherent scope setting of the particular object type.

Scopes are discussed below, in "Object Scopes".

Note: Use a JSP scriptlet to declare method variables, as opposed to member variables, as in the following example:

<% double f2=0.0; %>

This scriptlet declares a method variable, f2. In the servlet class code generated by the JSP translator, f2 will be declared as a variable within the service method of the servlet.

Member variables are declared in JSP declarations as described above.

For a comparative discussion, see "Method Variable Declarations Versus Member Variable Declarations" on page 4-18.



Explicit ObjectsExplicit objects are typically JavaBean instances declared and created in jsp:useBean action statements. The jsp:useBean statement and other action statements are described in "JSP Actions and the <jsp: > Tag Set" on page 1-18, but an example is also shown here:


This statement defines an instance, pageBean, of the NameBean class that is in the mybeans package. The scope parameter is discussed in "Object Scopes" below.

You can also create objects within Java scriptlets or declarations, just as you would create Java class instances in any Java program.

Object ScopesObjects in a JSP page, whether explicit or implicit, are accessible within a particular scope. In the case of explicit objects, such as a JavaBean instance created in a jsp:useBean action statement, you can explicitly set the scope with the following syntax (as in the example in the preceding section, "Explicit Objects"):

scope="scopevalue"

There are four possible scopes:

■ scope="page"—The object is accessible only from within the JSP page where it was created.

Note that when the user refreshes the page while executing a JSP page, new instances will be created of all page-scope objects.

■ scope="request"—The object is accessible from any JSP page servicing the same HTTP request that is serviced by the JSP page that created the object.

■ scope="session"—The object is accessible from any JSP page sharing the same HTTP session as the JSP page that created the object.

■ scope="application"—The object is accessible from any JSP page used in the same Web application (within any single Java virtual machine) as the JSP page that created the object.

Implicit ObjectsJSP technology makes available to any JSP page a set of implicit objects. These are Java class instances that are created automatically by the JSP mechanism and that allow interaction with the underlying servlet environment.



The following implicit objects are available. For information about methods available with these objects, refer to the Sun Microsystems Javadoc for the noted classes and interfaces at the following location:

http://java.sun.com/products/servlet/2.2/javadoc/index.html

■ page

This is an instance of the JSP page implementation class that was created when the page was translated, and that implements the interface javax.servlet.jsp.HttpJspPage; page is synonymous with this within a JSP page.

■ request

This represents an HTTP request and is an instance of a class that implements the javax.servlet.http.HttpServletRequest interface, which extends the javax.servlet.ServletRequest interface.

■ response

This represents an HTTP response and is an instance of a class that implements the javax.servlet.http.HttpServletResponse interface, which extends the javax.servlet.ServletResponse interface.

The response and request objects for a particular request are associated with each other.

■ pageContext

This represents the page context of a JSP page, which is provided for storage and access of all page scope objects of a JSP page instance. A pageContext object is an instance of the javax.servlet.jsp.PageContext class.

The pageContext object has page scope, making it accessible only to the JSP page instance with which it is associated.

■ session

This represents an HTTP session and is an instance of the javax.servlet.http.HttpSession class.

■ application

This represents the servlet context for the Web application and is an instance of the javax.servlet.ServletContext class.

The application object is accessible from any JSP page instance running as part of any instance of the application within a single JVM. (The programmer



should be aware of the server architecture regarding use of JVMs. For example, in the Oracle9i Servlet Engine architecture, each user runs in his or her own JVM.)

■ out

This is an object that is used to write content to the output stream of a JSP page instance. It is an instance of the javax.servlet.jsp.JspWriter class, which extends the java.io.Writer class.

The out object is associated with the response object for a particular request.

■ config

This represents the servlet configuration for a JSP page and is an instance of a class that implements the javax.servlet.ServletConfig interface. Generally speaking, servlet containers use ServletConfig instances to provide information to servlets during initialization. Part of this information is the appropriate ServletContext instance.

■ exception (JSP error pages only)

This implicit object applies only to JSP error pages—these are pages to which processing is forwarded when an exception is thrown from another JSP page; they must have the page directive isErrorPage attribute set to true.

The implicit exception object is a java.lang.Exception instance that represents the uncaught exception that was thrown from another JSP page and that resulted in the current error page being invoked.

The exception object is accessible only from the JSP error page instance to which processing was forwarded when the exception was encountered.

For an example of JSP error processing and use of the exception object, see "JSP Runtime Error Processing" on page 3-18.

Using an Implicit ObjectAny of the implicit objects discussed in the preceding section may be useful. The following example uses the request object to retrieve and display the value of the username parameter from the HTTP request:

<H3> Welcome <%= request.getParameter("username") %> ! <H3>



JSP Actions and the <jsp: > Tag SetJSP action elements result in some sort of action occurring while the JSP page is being executed, such as instantiating a Java object and making it available to the page. Such actions may include the following:

■ creating a JavaBean instance and accessing its properties

■ forwarding execution to another HTML page, JSP page, or servlet

■ including an external resource in the JSP page

Action elements use a set of standard JSP tags that begin with <jsp: syntax. Although the tags described earlier in this chapter that begin with <% syntax are sufficient to code a JSP page, the <jsp: tags provide additional functionality and convenience.

Action elements also use syntax similar to that of XML statements, with similar "begin" and "end" tags such as in the following example:

<jsp:sampletag attr1="value1" attr2="value2" ... attrN="valueN">...body...</jsp:sampletag>

Or, where there is no body, the action statement is terminated with an empty tag:

<jsp:sampletag attr1="value1", ..., attrN="valueN" />

The JSP specification includes the following standard action tags, which are introduced and briefly discussed here:

■ jsp:useBean

The jsp:useBean action creates an instance of a specified JavaBean class, gives the instance a specified name, and defines the scope within which it is accessible (such as from anywhere within the current JSP page instance).

Example:


This example creates a page-scoped instance pageBean of the mybeans.NameBean class. This instance is accessible only from the JSP page instance that creates it.

■ jsp:setProperty

The jsp:setProperty action sets one or more bean properties. The bean must have been previously specified in a useBean action. You can directly



specify a value for a specified property, or take the value for a specified property from an associated HTTP request parameter, or iterate through a series of properties and values from the HTTP request parameters.

The following example sets the user property of the pageBean instance (defined in the preceding useBean example) to a value of "Smith":

<jsp:setProperty name="pageBean" property="user" value="Smith" />

The following example sets the user property of the pageBean instance according to the value set for a parameter called username in the HTTP request:

<jsp:setProperty name="pageBean" property="user" param="username" />

Or, if the bean property and request parameter have the same name (user), you can simply set the property as follows:

<jsp:setProperty name="pageBean" property="user" />

The following example results in iteration over the HTTP request parameters, matching bean property names with request parameter names and setting bean property values according to the corresponding request parameter values:

<jsp:setProperty name="pageBean" property="*" />

■ jsp:getProperty

The jsp:getProperty action reads a bean property value, converts it to a Java string, and places the string value into the implicit out object so that it can be displayed as output. The bean must have been previously specified in a jsp:useBean action. For the string conversion, primitive types are converted

Important: For property="*", the JSP 1.1 specification does not stipulate the order in which properties are set. If order matters, and if you want to ensure that your JSP page is portable, you should use a separate setProperty statement for each property.

Also, if you use separate setProperty statements, then the OracleJSP translator can generate the corresponding setXXX() methods directly. In this case, introspection only occurs during translation. There will be no need to introspect the bean during runtime, which would be somewhat more costly.



directly and object types are converted using the toString() method specified in the java.lang.Object class.

The following example puts the value of the user property of the pageBean bean into the out object:

<jsp:getProperty name="pageBean" property="user" />

■ jsp:param

You can use the jsp:param action in conjunction with jsp:include, jsp:forward, or jsp:plugin actions (described below).

For jsp:forward and jsp:include statements, a jsp:param action optionally provides key/value pairs for parameter values in the HTTP request object. New parameters and values specified with this action are added to the request object, with new values taking precedence over old.

The following example sets the request object parameter username to a value of Smith:

<jsp:param name="username" value="Smith" />

■ jsp:include

The jsp:include action inserts additional static or dynamic resources into the page at request time as the page is displayed. Specify the resource with a relative URL (either page-relative or application-relative).

As of the Sun Microsystems JavaServer Pages Specification, Version 1.1, you must set flush to true, which results in the buffer being flushed to the browser when a jsp:include action is executed. (The flush attribute is mandatory, but a setting of false is currently invalid.)

You can also have an action body with jsp:param settings, as shown in the second example.

Examples:

<jsp:include page="/templates/userinfopage.jsp" flush="true" />

Note: The jsp:param tag is not supported for jsp:include or jsp:forward in the JSP 1.0 specification.



or:

<jsp:include page="/templates/userinfopage.jsp" flush="true" > <jsp:param name="username" value="Smith" /> <jsp:param name="userempno" value="9876" /></jsp:include>

Note that the following syntax would work as an alternative to the preceding example:

<jsp:include page="/templates/userinfopage.jsp?username=Smith&userempno=9876" flush="true" />

■ jsp:forward

The jsp:forward action effectively terminates execution of the current page, discards its output, and dispatches a new page—either an HTML page, a JSP page, or a servlet.

The JSP page must be buffered to use a jsp:forward action; you cannot set buffer="none". The action will clear the buffer, not outputting contents to the browser.

As with jsp:include, you can also have an action body with jsp:param settings, as shown in the second example.

Examples:

<jsp:forward page="/templates/userinfopage.jsp" />

or:

<jsp:forward page="/templates/userinfopage.jsp" > <jsp:param name="username" value="Smith" /> <jsp:param name="userempno" value="9876" /></jsp:forward>

Notes:

■ The jsp:include action, known as a "dynamic include", is similar in nature to the include directive discussed earlier in this chapter, but takes effect at request time instead of translation time. See "Static Includes Versus Dynamic Includes" on page 4-12.

■ The jsp:include action can be used only between pages in the same servlet context.



■ jsp:plugin

The jsp:plugin action results in the execution of a specified applet or JavaBean in the client browser, preceded by a download of Java plugin software if necessary.

Specify configuration information, such as the applet to run and the codebase, using jsp:plugin attributes. The JSP container might provide a default URL for the download, but you can also specify attribute nspluginurl="url" (for a Netscape browser) or iepluginurl="url" (for an Internet Explorer browser).

Use nested jsp:param actions within <jsp:params> and </jsp:params> start and end tags to specify parameters to the applet or JavaBean. (Note that these jsp:params start and end tags are not necessary when using jsp:param in a jsp:include or jsp:forward action.)

Use <jsp:fallback> and </jsp:fallback> start and end tags to delimit alternative text to execute if the plugin cannot run.

Notes:

■ The difference between the jsp:forward examples here and the jsp:include examples earlier is that the jsp:include examples insert userinfopage.jsp within the output of the current page; the jsp:forward examples stop executing the current page and display userinfopage.jsp instead.

■ The jsp:forward action can be used only between pages in the same servlet context.

■ The jsp:forward action results in the original request object being forwarded to the target page. As an alternative, if you do not want the request object forwarded, you can use the sendRedirect(String) method specified in the standard javax.servlet.http.HttpServletResponse interface. This sends a temporary redirect response to the client using the specified redirect-location URL. You can specify a relative URL; the servlet container will convert the relative URL to an absolute URL.



The following example, from the Sun Microsystems JavaServer Pages Specification, Version 1.1, shows the use of an applet plugin:

<jsp:plugin type=applet code="Molecule.class" codebase="/html" > <jsp:params> <jsp:param name="molecule" value="molecules/benzene.mol" /> </jsp:params> <jsp:fallback> <p> Unable to start the plugin. </p> </jsp:fallback></jsp:plugin>

Many additional parameters—such as ARCHIVE, HEIGHT, NAME, TITLE, and WIDTH—are allowed in the jsp:plugin action statement as well. Use of these parameters is according to the general HTML specification.

Tag LibrariesIn addition to the standard JSP tags discussed previously in this section, the JSP specification lets vendors define their own tag libraries and also lets vendors implement a framework allowing customers to define their own tag libraries.

A tag library defines a collection of custom tags and can be thought of as a JSP sub-language. Developers can use tag libraries directly, in manually coding a JSP page, but they might also be used automatically by Java development tools. A tag library must be portable between different JSP container implementations.

Import a tag library into a JSP page using the taglib directive, introduced in "Directives" on page 1-10.

Key concepts of standard JavaServer Pages support for JSP tag libraries include the following topics:

■ tag handlers

A tag handler describes the semantics of the action that results from use of a custom tag. A tag handler is an instance of a Java class that implements either the Tag or BodyTag interface (depending on whether the tag uses a body between a start tag and an end tag) in the standard javax.servlet.jsp.tagext package.

■ scripting variables

Custom tag actions can create server-side objects available for use by the tag itself or by other scripting elements such as scriptlets. This is accomplished by creating or updating scripting variables.



Details regarding scripting variables that a custom tag defines must be specified in a subclass of the standard javax.servlet.jsp.tagext.TagExtraInfo abstract class. This document refers to such a subclass as a tag-extra-info class. The JSP container uses instances of these classes during translation.

■ tag library description files

A tag library description (TLD) file is an XML document that contains information about a tag library and about individual tags of the library. The file name of a TLD has the .tld extension.

A JSP container uses the TLD file in determining what action to take when it encounters a tag from the library.

■ use of web.xml for tag libraries

The Sun Microsystems Java Servlet Specification, Version 2.2 describes a standard deployment descriptor for servlets—the web.xml file. JSP applications can use this file in specifying the location of a JSP tag library description file.

For JSP tag libraries, the web.xml file can include a taglib element and two subelements: taglib-uri and taglib-location.

For information about these topics, see "Standard Tag Library Framework" on page 7-2.

For information about the sample tag library provided with OracleJSP, see "Overview of the JSP Markup Language (JML) Sample Tag Library" on page 7-20

For further information, see the Sun Microsystems JavaServer Pages Specification, Version 1.1.


Overview of Oracle’s JSP Implemen

2
Overview of Oracle’s JSP Implementation
OracleJSP release 1.1.3.x is a complete implementation of the Sun Microsystems JavaServer Pages Specification, Version 1.1.

This chapter introduces features of OracleJSP as well as discussing support for OracleJSP in various environments, particularly the Oracle9i Servlet Engine (OSE). OSE is the Oracle9i servlet container.

For an overview of standard JavaServer Pages features, see Chapter 1, "General Overview".


■ Portability and Functionality Across Servlet Environments

■ Support for OracleJSP in Oracle Environments

■ Support for OracleJSP in Non-Oracle Environments

■ Overview of OracleJSP Programmatic Extensions

■ Overview of Oracle Caching Support for Web Applications

■ Summary of OracleJSP Releases and Feature Sets

■ OracleJSP Execution Models

■ Oracle JDeveloper Support for OracleJSP

tation 2-1

Portability and Functionality Across Servlet Environments

Portability and Functionality Across Servlet EnvironmentsOracle’s JavaServer Pages implementation is highly portable across server platforms and servlet environments. It also supplies a framework for Web applications in older servlet environments, where servlet context behavior was not yet sufficiently defined.

OracleJSP PortabilityOracleJSP can run on any servlet environment that complies with version 2.0 or higher of the Sun Microsystems Java Servlet Specification. This is in contrast to most JSP implementations, which require a servlet 2.1(b) or higher implementation. As the next section explains, OracleJSP provides functionality equivalent to what is lacking in older servlet environments.

Furthermore, the OracleJSP container is independent of the server environment and its servlet implementation. This is in contrast to vendors who deliver their JSP implementation as part of their servlet implementation instead of as a standalone product.

This portability makes it much easier to run OracleJSP in both your development environment and the target environment, as opposed to having to use a different JSP implementation on your development system because of any server or servlet platform limitations. There are usually benefits to developing on a system with the same JSP container as the target server; but realistically speaking, there is usually some variation between environments.

OracleJSP Extended Functionality for Servlet 2.0 EnvironmentsBecause of interdependence between servlet specifications and JSP functionality, Sun Microsystems has tied versions of the JavaServer Pages Specification to versions of the Java Servlet Specification. According to Sun, JSP 1.0 requires a servlet 2.1(b) implementation, and JSP 1.1 requires a servlet 2.2 implementation.

The servlet 2.0 specification was limited in that it provided only a single servlet context per Java virtual machine, instead of a servlet context for each application. The servlet 2.1 specification allowed, but did not mandate, a separate servlet context for each application. The servlet 2.1(b) and servlet 2.2 specifications mandated separate servlet contexts. (For background information about servlets and servlet contexts, see "Background on Servlets" on page B-2.)

The OracleJSP container, however, offers functionality that emulates the application support provided with the servlet 2.1(b) specification. This allows a full application


Portability and Functionality Across Servlet Environments

framework in a servlet 2.0 environment such as Apache/JServ. This includes providing applications with distinct ServletContext and HttpSession objects.

This extended support is provided through a file, globals.jsa, that acts as a JSP application marker, application and session event handler, and centralized location for application-global declarations and directives. (For information, see "Overview of globals.jsa Functionality" on page 5-38.)

Because of this extended functionality, OracleJSP is not limited by the underlying servlet environment.

Overview of Oracle’s JSP Implementation 2-3

Support for OracleJSP in Oracle Environments

Support for OracleJSP in Oracle EnvironmentsThis section provides brief overviews of Oracle environments that support and provide OracleJSP, covering the following topics:

■ Overview of the Oracle9i Servlet Engine (OSE)

■ Overview of the Oracle9i Application Server

■ Role of the Oracle HTTP Server, Powered by Apache

■ Oracle Web Application Data-Access Strategies

■ Overview of Other Oracle JSP Environments

The Oracle9i Servlet Engine, the servlet container in Oracle9i, supports a JSP pre-translation model. JSP pages are translated into servlets prior to or during deployment to Oracle9i.

For the other Oracle environments, the OracleJSP container supports the typical on-demand translation model, typically translating the pages at runtime. OracleJSP is designed to run effectively in either situation and provide consistent semantics regardless of your choice of server.

Overview of the Oracle9i Servlet Engine (OSE)If your JSP pages are intended to access an Oracle9i database, you have the option of executing them in the Oracle9i Servlet Engine (OSE), either inside the Oracle9i database or inside the Oracle9i Application Server middle-tier database cache. OSE, which is included with Oracle9i, incorporates the OracleJSP container. This reduces communication overhead compared to JSP execution in a middle tier. Access to the database is through the Oracle JDBC server-side internal driver.

The OSE execution model requires the developer to take some special steps to deploy the JSP pages to Oracle9i. This includes pre-translating the pages, loading them into Oracle9i, and "publishing" them to make them available for execution.

During installation of Oracle9i, the Oracle HTTP Server powered by Apache is set as the default Web server, acting as a front-end for JSP and servlet applications running in OSE. Refer to your installation instructions if you want to change this setting.

In Oracle9i database release 9.0.1, the Oracle9i Servlet Engine supports the servlet 2.2 and JSP 1.1 specifications, incorporating OracleJSP release 1.1.2.3.



Overview of the Oracle9i Application ServerThe Oracle9i Application Server is a scalable, secure, middle-tier application server. It can be used to deliver Web content, host Web applications, connect to back-office applications, and make these services accessible to any client browser. Users can access information, perform business analysis, and run business applications on the Internet or corporate intranets or extranets.

To deliver this range of content and services, Oracle9i Application Server release 1.0.x incorporates the Oracle HTTP Server (powered by Apache), a middle-tier database cache for read-only data, Oracle Forms Services and Oracle Reports Services to support Oracle Forms-based applications and reports generation, and various business logic runtime environments that support Enterprise JavaBeans, stored procedures, and Oracle Business Components for Java.

For database access, the Oracle HTTP Server can route HTTP requests to servlets or JSP pages running in either of the following scenarios:

■ in the Apache/JServ environment (routing is through the Apache mod_jserv module)

In this scenario, database access is through client-side/middle-tier JDBC drivers (using either JDBC or SQLJ code).

■ in the OSE environment in the database or middle-tier database cache (routing is through the Apache mod_ose module)

In this scenario, database access is through the JDBC server-side internal driver (using either JDBC or SQLJ code).

The Oracle9i Application Server 1.0.x releases include the Apache/JServ servlet environment, supporting the servlet 2.0 specification, and provide JSP environments as follows:

■ 1.0.2.x and 1.0.1.x releases include OracleJSP release 1.1.x, supporting the JSP 1.1 specification.

■ Release 1.0.0 includes OracleJSP release 1.0.0.6.1, supporting the JSP 1.0 specification.

See the Oracle9i Application Server Documentation Library for more information about the Oracle9i Application Server.



Role of the Oracle HTTP Server, Powered by ApacheOracle HTTP Server, powered by the Apache Web server, is included with the Oracle9i Application Server and Oracle9i database as the HTTP entry point for Web applications accessing the database. Database access is through Apache add-on modules.

The remainder of this section covers the following topics:

■ Use of Apache Mods

■ More About mod_ose

■ More About mod_jserv

Use of Apache ModsIn using the Oracle HTTP Server, powered by Apache, dynamic content is delivered through various Apache mod components provided either by Apache or by other vendors such as Oracle. (Static content is typically delivered from the file system.) An Apache mod is typically a module of C code, running in the Apache address space, that passes requests to a particular mod-specific processor. (The mod software will have been written specifically for use with the particular processor.)

The following Apache mods are of interest to OracleJSP developers:

■ mod_ose is provided by Oracle for JSP pages and servlets that have been deployed to Oracle9i and will be executed by the Oracle9i Servlet Engine inside the database or middle-tier database cache address space.

■ mod_jserv is provided by Apache and can be used in accessing Oracle9i data from JSP pages or servlets running in the Apache/JServ servlet environment in a middle-tier JVM.

Note: Future releases of Oracle9i Application Server may replace the Apache/JServ environment with an alternative servlet environment.

Note: When using OSE, it is advisable to use it as a servlet container in conjunction with the Oracle HTTP Server, particularly for applications with static HTML.



More About mod_oseThe mod_ose component, supplied by Oracle, delegates HTTP requests to JSP pages or servlets running in OSE inside the database or middle-tier database cache. It communicates with OSE using HTTP over the Oracle9i Net protocol and can handle either stateless or stateful requests. Each virtual domain configured in the Oracle HTTP Server is associated with a database connection string (an Oracle9i Net name-value list) that indicates where to make a connection to execute the request. The connection uses Oracle9i Net directly, providing the same load balancing and hot backup functionality as OCI.

If an application running in an Oracle9i Application Server framework uses mod_ose, then the application server’s Apache/JServ servlet 2.0 environment is not involved. The Oracle9i Servlet Engine’s own servlet 2.2 environment is used instead.

JSP applications and servlets running in OSE in the database or middle-tier database cache use the Oracle JDBC server-side internal driver for rapid database access. For an overview of OSE, see "Overview of the Oracle9i Servlet Engine (OSE)" on page 2-4.

You can use the Oracle9i session shell exportwebdomain command to configure mod_ose to find published servlets and JSP pages in the database.

See the Oracle9i Servlet Engine Developer’s Guide for more information about mod_ose and for information about the exportwebdomain command.

More About mod_jservThe mod_jserv component, supplied by Apache, delegates HTTP requests to JSP pages or servlets running in the Apache/JServ servlet container in a middle-tier JVM. Oracle9i Application Server release 1.0.x includes the Apache/JServ servlet

Notes:

■ For Oracle9i Application Server releases 1.0.0 and 1.0.1, you cannot use the mod_ose/OSE scenario because those releases of the database cache did not yet include the Oracle9i Servlet Engine. This was resolved as of release 1.0.2.

■ Many additional Apache "mod" components are available for use in an Apache environment, provided by Apache for general use or by Oracle for Oracle-specific use, but they are not relevant for JSP applications.



container, which supports the servlet 2.0 specification, and either JDK 1.1.8 or 1.2.2. The middle-tier environment may or may not be on the same physical host as the back-end Oracle9i database.

Communication between mod_jserv and middle-tier JVMs uses a proprietary Apache/JServ protocol over TCP/IP. The mod_jserv component can delegate requests to multiple JVMs in a pool for load balancing.

JSP applications running in middle-tier JVMs use the Oracle JDBC OCI driver or Thin driver to access the database.

Servlet 2.0 environments (as opposed to servlet 2.1 or 2.2 environments) have issues that require special consideration. See "Considerations for Apache/JServ Servlet Environments" on page 4-38.

Refer to Apache documentation for mod_jserv configuration information. (This documentation is provided with Oracle9i.)

Oracle Web Application Data-Access StrategiesDevelopers who are targeting the Oracle9i database or middle-tier database cache from JSP applications have the following options:

1. Run in the Apache/JServ servlet container through the Oracle HTTP Server, using mod_jserv.

2. Run in the Oracle9i Servlet Engine in the database or middle-tier database cache through the Oracle HTTP Server, using mod_ose.

Running in Apache/JServ, because it uses a standard JVM (currently JDK 1.2.2 or 1.1.8), is necessary if you want to use the JDBC OCI driver or if the application requires Java features not available in the Oracle JVM (JNI, for example).

However, running in Apache/JServ has the disadvantage of requiring a pool of multiple JVMs that must be configured manually. (For more information, refer to the Apache mod_jserv documentation provided with Oracle9i.)

Note: When you use the Oracle HTTP Server, be aware that the Apache/JServ servlet container has a different default doc root for static files than the Oracle9i Servlet Engine has. See "Doc Root for Oracle9i Application Server Versus Oracle9i Servlet Engine" on page 6-73.



In using the Oracle9i Servlet Engine, access through the Oracle HTTP Server and mod_ose is the typical scenario and is recommended, although employing OSE directly as the Web server (either in the database or database cache) is feasible.

In particular, Oracle HTTP Server and mod_ose can handle the following situations that OSE by itself cannot:

■ database access through a firewall certified with Oracle9i Net

■ implementation of a fault-tolerant system using multiple databases

■ database access through port 80

This is typically not possible when using OSE as a Web server directly. In a UNIX environment, for example, port 80 is accessible only from the root account, and end-users do not have root access.

■ connection pooling for stateless applications so that session startup overhead is mostly avoided

The default installation of Oracle9i uses the Oracle HTTP Server as the front-end Web server for JSP pages and servlets that run in OSE.

Overview of Other Oracle JSP EnvironmentsIn addition to the Oracle9i Servlet Engine and Oracle9i Application Server, the following Oracle environments support OracleJSP:

■ Oracle Application Server

■ Oracle Web-to-go

■ Oracle JDeveloper

Oracle Application ServerOracle Application Server (OAS) preceded the Oracle Internet Application Server, which is now known as the Oracle9i Application Server. OAS is a scalable, standards-based middle-tier environment for application logic, offering database integration in supporting business applications in both corporate and e-business environments.

New customers will presumably use the Oracle9i Application Server, discussed previously, instead of OAS. For existing OAS customers, however, Oracle Application Server release 4.0.8.2 includes a servlet 2.1 environment and OracleJSP release 1.0.0.6.0 (supporting the JSP 1.0 specification).



Refer to the Oracle Application Server Developer’s Guide: JServlet and JSP Applications for more information.

Oracle Web-to-goOracle Web-to-go, a component of Oracle9i Lite, consists of a collection of modules and services that facilitate development, deployment, and management of mobile Web applications.

Web-to-go lets developers extend Web-based applications to intermittently connected users without coding the infrastructure required for replication, synchronization, and other networking issues. Unlike traditional mobile computing technologies, which rely on custom or proprietary application-programming interfaces (APIs), Web-to-go uses industry-standard Internet technologies.

Web-to-go release 1.3 provides a servlet 2.1 environment and OracleJSP release 1.0.0.6.1 (supporting the JSP 1.0 specification). Future releases will offer a servlet 2.2 environment and OracleJSP 1.1.x.

Refer to the Oracle Web-to-go Implementation Guide for more information.

Oracle JDeveloperJDeveloper is a Java development tool, rather than a "platform" like the other Oracle products listed here. It incorporates a Web listener, servlet runner, and the OracleJSP container for execution and testing.

See "Oracle JDeveloper Support for OracleJSP" on page 2-28 for more information.

JDeveloper version 3.1 provides a servlet 2.1 environment and OracleJSP release 1.0.0.6.1 (supporting the JSP 1.0 specification). Future releases will offer a servlet 2.2 environment and OracleJSP 1.1.x.


Support for OracleJSP in Non-Oracle Environments

Support for OracleJSP in Non-Oracle EnvironmentsYou should be able to install and run the OracleJSP container on any server environment supporting servlet specification 2.0 or higher. In particular, OracleJSP has been tested in the following environments as of release 1.1.3.x:

■ Apache Software Foundation Apache/JServ 1.1

This is a Web server and servlet 2.0 environment without a JSP environment. To run JSP pages, you must install a JSP environment on top of it.

■ Sun Microsystems JSWDK 1.0 (JavaServer Web Developer’s Kit)

This is a Web server with the servlet 2.1 and JavaServer Pages 1.0 reference implementations. You can, however, install OracleJSP on top of the JSWDK servlet environment to replace the original JSP environment.

■ Apache Software Foundation Tomcat 3.1

This cooperative effort between Sun Microsystems and the Apache Software Foundation is a Web server with the servlet 2.2 and JavaServer Pages 1.1 reference implementations. You can, however, install OracleJSP on top of the Tomcat servlet environment to replace the original JSP environment. You can also run Tomcat in conjunction with the Apache Web server instead of using the Tomcat Web server.


Overview of OracleJSP Programmatic Extensions

Overview of OracleJSP Programmatic ExtensionsThis section is an overview of extended programming features supported by OracleJSP.

OracleJSP provides the following extended functionality through custom tag libraries and custom JavaBeans, all of which are portable to other JSP environments:

■ extended datatypes implemented as JavaBeans that can have a specified scope

■ integration with XML and XSL

■ data-access JavaBeans

■ the Oracle JSP Markup Language (JML) custom tag library, which reduces the level of Java proficiency required for JSP development

■ a custom tag library for SQL functionality

OracleJSP also provides the following Oracle-specific extensions:

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

■ extended globalization support

■ JspScopeListener for event handling

■ globals.jsa file for application support

Discussion of these topics is followed by a brief description of how OracleJSP pages can interact with Oracle PL/SQL Server Pages.

Overview of Portable OracleJSP ExtensionsThe Oracle extensions discussed in this section are implemented either through the OracleJSP JML sample tag library or through custom JavaBeans. They are portable to other JSP environments.

OracleJSP Extended DatatypesJSP pages generally rely on core Java datatypes in representing scalar values. However, neither of the type categories listed below is fully suitable for use in JSP pages.



■ primitive types such as int, float, and double

Values of these types cannot have a specified scope—they cannot be stored in a JSP scope object (for page, request, session, or application scope), because only objects can be stored in a scope object.

■ wrapper classes in the standard java.lang package, such as Integer, Float, and Double

Values of these types are objects, so they can theoretically be stored in a JSP scope object. However, they cannot be declared in a jsp:useBean action, because the wrapper classes do not follow the JavaBean model and do not provide a zero-argument constructor.

Additionally, instances of the wrapper classes are immutable. To change a value, you must create a new instance and assign it appropriately.

To work around these limitations, OracleJSP provides the JmlBoolean, JmlNumber, JmlFPNumber, and JmlString JavaBean classes in package oracle.jsp.jml to wrap the most common Java datatypes.

See "JML Extended Datatypes" on page 5-2 for more information.

Integration with XML and XSLYou can use JSP syntax to generate any text-based MIME type, not just HTML code. In particular, you can dynamically create XML output. When you use JSP pages to generate an XML document, however, you often want a stylesheet applied to the XML data before it is sent to the client. This is difficult in JavaServer Pages technology, because the standard output stream used for a JSP page is written directly back through the server.

OracleJSP provides special tags in its sample JML tag library to specify that all or part of a JSP page should be transformed through an XSL stylesheet before it is output. You can use this JML tag multiple times in a single JSP page if you want to specify different style sheets for different portions of the page. Note that the JML tag library is portable to other JSP environments.

In addition, the OracleJSP translator supports XML-alternative syntax as specified in the Sun Microsystems JavaServer Pages Specification, Version 1.1.

See "OracleJSP Support for XML and XSL" on page 5-9 for more information.



Custom Data-Access JavaBeansOracleJSP supplies a set of custom JavaBeans for use in accessing the Oracle9i database or middle-tier database cache. The following beans are provided in the oracle.jsp.dbutil package:

■ ConnBean opens a simple database connection.

■ ConnCacheBean uses Oracle’s connection caching implementation for database connections.

■ DBBean executes a database query.

■ CursorBean provides general DML support for UPDATE, INSERT, and DELETE statements, as well as queries.

See "Oracle Data-Access JavaBeans" on page 5-13 for more information.

OracleJSP SQL Custom Tag LibraryOracleJSP provides a custom tag library for SQL functionality. The following tags are provided:

■ dbOpen—Open a database connection.

■ dbClose—Close a database connection.

■ dbQuery—Execute a query.

■ dbCloseQuery—Close the cursor for a query.

■ dbNextRow—Move to the next row of the result set.

■ dbExecute—Execute any SQL DML or DDL statement.

See "OracleJSP Tag Library for SQL" on page 5-24 for more information.

Oracle JSP Markup Language (JML) Custom Tag LibraryAlthough the Sun Microsystems JavaServer Pages Specification, Version 1.1 supports scripting languages other than Java, Java is the primary language used. Even though JavaServer Pages technology is designed to separate the dynamic/Java development effort from the static/HTML development effort, it is no doubt still a hindrance if the Web developer does not know any Java, especially in small development groups where no Java experts are available.

OracleJSP provides custom tags as an alternative—the JSP Markup Language (JML). The Oracle JML sample tag library provides an additional set of JSP tags so that you can script your JSP pages without using Java statements. JML provides tags for



variable declarations, control flow, conditional branches, iterative loops, parameter settings, and calls to objects. The JML tag library also supports XML functionality, as noted previously.

The following example shows use of the jml:for tag, repeatedly printing "Hello World" in progressively smaller headings (H1, H2, H3, H4, H5):

<jml:for id="i" from="<%= 1 %>" to="<%= 5 %>" > <H<%=i%>> Hello World! </H<<%=i%>></jml:for>

For more information, see "Overview of the JSP Markup Language (JML) Sample Tag Library" on page 7-20.

Overview of Oracle-Specific ExtensionsThe OracleJSP extensions listed in this section are not portable to other JSP environments.

SQLJ Support in OracleJSPDynamic server pages commonly include data extracted from databases; however, JavaServer Pages technology does not offer built-in support to facilitate database access. JSP developers typically must rely on the standard Java Database Connectivity (JDBC) API or a custom set of database JavaBeans.

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 SQLJ programming in JSP scriptlets.

SQLJ statements are indicated by the #sql token. You can trigger the OracleJSP translator to invoke the Oracle SQLJ translator by using the file name extension .sqljsp for the JSP source code file.

For more information, see "OracleJSP Support for Oracle SQLJ" on page 5-34.

Note: OracleJSP versions preceding the JSP 1.1 specification used an Oracle-specific compile-time implementation of the JML tag library. This implementation is still supported as an alternative to the standard runtime implementation. For information, see Appendix C, "Compile-Time JML Tag Support".



Extended Globalization Support in OracleJSPOracleJSP provides extended globalization support for servlet environments that cannot encode multibyte request parameters and bean property settings.

For such environments, OracleJSP offers the translate_params configuration parameter, which can be enabled to direct OracleJSP to override the servlet container and do the encoding itself.

For more information, see "OracleJSP Extended Support for Multibyte Parameter Encoding" on page 10-5.

JspScopeListener for Event HandlingOracleJSP provides the JspScopeListener interface for lifecycle management of Java objects of various scopes within a JSP application.

Standard servlet and JSP event-handling is provided through the javax.servlet.http.HttpSessionBindingListener interface, but this handles session-based events only. The Oracle JspScopeListener can handle page-based, request-based, and application-based events as well.

For more information, see "OracleJSP Event Handling—JspScopeListener" on page 5-33.

globals.jsa File for Application Support (Servlet 2.0)For servlet 2.0 environments, where servlet contexts are not fully defined, OracleJSP defines a file, globals.jsa, to extend servlet application support.

Within any single Java virtual machine, there can be a globals.jsa file for each application (or, equivalently, for each servlet context). This file supports the concept of Web applications through use as an application location marker. Based on globals.jsa functionality, the OracleJSP container can also mimic servlet context and HTTP session behavior for servlet environments, where such behavior is not sufficiently defined.

The globals.jsa file also provides a vehicle for global Java declarations and JSP directives across all JSP pages of an application.

Use of OracleJSP with Oracle PL/SQL Server PagesOracle provides a product called PL/SQL Server Pages (PSP). PSP technology allows embedded PL/SQL scriptlets and stored procedure calls within an HTML page, offering development advantages similar to those offered by JSP technology; namely, that coding the dynamic portion of the page and the static portion of the



page can be largely separate development efforts. An HTML expert can code the static part of the page and a PL/SQL expert can code the dynamic part of the page. The syntax used to distinguish PL/SQL scriptlets in a PSP page is identical to that used to distinguish Java scriptlets in a JSP page.

The remainder of this section discusses support for JSP-PSP interaction, and includes some background on PSP URLs.

For general information about PL/SQL Server Pages, see the Oracle9i Application Developer’s Guide - Fundamentals.

Supported Interaction between JSP Pages and PSP PagesWhen an end-user runs a PSP application, PSP pages are translated into stored procedures for execution by the embedded PL/SQL gateway in producing output to the Web browser. The embedded PL/SQL gateway in Oracle9i executes in a servlet wrapper, and JSP pages running in the Oracle9i Servlet Engine can interact with PSP pages as follows (as of Oracle9i release 9.0.1):

■ You can dynamically forward to a PSP page from a JSP page (jsp:forward).

■ You cannot dynamically include a PSP page from a JSP page (jsp:include).

■ You cannot statically include a PSP page from a JSP page (the include directive to include a file during translation).

■ You cannot forward to or include a JSP page from a PSP page.

For information about the embedded PL/SQL gateway, refer to the Oracle9i Servlet Engine Developer’s Guide and to Using the PL/SQL Gateway in the Oracle Application Server 9i Documentation Library.

PSP Page URLsEach PSP page, when loaded and compiled in the database, becomes a PL/SQL stored procedure. The name of the stored procedure for a PSP page is either explicitly declared in the page, using <%@ plsql procedure="proc-name" %> syntax, or is derived from the name of the PSP file.

Note: The "dynamic include" restriction in the embedded PL/SQL gateway applies to servlets in general, not just JSP pages. Dynamically including a PSP page through the embedded PL/SQL gateway using the request dispatcher is not currently functional.



Given the name of the PL/SQL stored procedure, the URL is determined according to the following general syntax:

http://host[:port]/some-prefix/dad/[schema.]proc-name

In this syntax, <some-prefix> is plsql for the embedded PL/SQL module, and <dad> is the database access descriptor to run the stored procedure.

For more information, see the Oracle9i Application Developer’s Guide - Fundamentals.


Overview of Oracle Caching Support for Web Applications

Overview of Oracle Caching Support for Web ApplicationsFaced 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 the following:

■ performance

■ scalability

■ high availability

■ cost savings

■ network traffic reduction

This section provides the following information:

■ an introduction to caching features supported by the Oracle9i Application Server in general and OracleJSP in particular

■ a discussion of the role of the OracleJSP Web Object Cache in relation to other Oracle9iAS caching products

Oracle9i Application Server and OracleJSP Caching FeaturesThe Oracle9i Application Server and OracleJSP provide the following caching features:

■ Oracle Web Cache

This is an HTTP-level cache, maintained outside the application, providing very fast cache operations. It is a pure, content-based cache, capable of caching static data (such as HTML, GIF, or JPEG files) or dynamic data (such as servlet or JSP results). Given that it exists as a flat content-based cache outside the application, it cannot cache objects (such as Java objects or XML DOM objects) in a structured format. In addition, it has relatively limited post-processing abilities on cached data.

The Oracle Web Cache provides an ESI processor to support Edge Side Includes, an XML-style markup language that allows dynamic content assembly away from the Web server. This technology allows you to break cacheable pages into separate cached objects, as desired. OracleJSP supports this technology through its JESI tag library.



For an overview of Edge Side Includes and the Oracle Web Cache, as well as detailed documentation of the JESI tag library, see Chapter 8, "JESI Tags for Edge Side Includes".

For additional information about the Oracle Web Cache, see the Oracle Web Cache Administration and Deployment Guide.

■ OracleJSP Web Object Cache

This is an application-level cache, embedded and maintained within a Java Web application. It is a hybrid cache, both Web-based and object-based. A custom tag library or API allows you to define page fragment boundaries and to capture, store, reuse, process, and manage the intermediate and partial execution results of JSP pages and servlets as cached objects. Each block can produce its own resulting cache object. The produced objects can be HTML or XML text fragments, XML DOM objects, or Java serializable objects. These objects can be cached conveniently in association with HTTP semantics. Alternatively, they can be reused outside HTTP, such as in outputting cached XML objects through Simple Mail Transfer Protocol (SMTP), Java Messaging Service (JMS), Advanced Queueing (AQ), or Simple Object Access Protocol (SOAP).

For more information, see Chapter 9, "Web Object Cache Tags and API".

■ Oracle9iAS Object Caching Service for Java

The Oracle9iAS Object Caching Service for Java is a general-use Java object cache to manage Java objects within a process, across processes, and on local disk. By managing local copies of objects that are difficult or expensive to retrieve or create, the object caching service significantly improves server performance. (By default, the OracleJSP Web Object Cache uses the Oracle9iAS Object Caching Service for Java as its underlying cache repository.)

For details, see the Oracle9iAS Object Caching Service for Java Developer’s Guide.

■ Oracle9iAS Database Cache

This is a database-replicant cache that is directly associated with the back-end Oracle9i database, not with any particular application. A copy of the data is loaded from the back-end database into the database cache, which is on the middle tier and, therefore, closer to the application for faster access. Queries are made locally to the cache instead of across the network to the back-end database, saving costly round trips.

For information, refer to the Oracle9i Application Server documentation library.



Role of the OracleJSP Web Object CacheIt is important to understand the role of the OracleJSP Web Object Cache in the overall setup of a Web application. It works at the Java level and is closely integrated with the HTTP environment of servlet and JSP applications. By contrast, The Oracle9iAS Object Caching Service for Java works at the Java object level, but is not integrated with HTTP. As for the Oracle Web Cache, it is well integrated with HTTP and is an order of magnitude faster than the Web Object Cache, but it does not operate at the Java level. For example, it cannot apply a stylesheet to a cached DOM object or reuse the cached result in other protocols.

The Web Object Cache is not intended for use as the main Web cache for an application. It is an auxiliary cache embedded within the same Java VM that is running your servlets and JSP pages. Because the retrieval path for cached results in the Web Object Cache includes the Java VM and the JSP and servlet engines, it generally takes much longer to serve a page from the Web Object Cache compared to the Oracle Web Cache.

The Web Object Cache does not replace or eliminate the need for either the Oracle Web Cache or the Oracle9iAS Object Caching Service for Java—it is a complementary caching component in the overall framework of a Web application and should be used together with the other caching products, as appropriate. In fact, the Web Object Cache uses the Oracle9iAS Object Caching service for Java as its default repository. And through combined use of the OracleJSP JESI tags and Web Object Cache tags, you can use the Web Object Cache and Oracle Web Cache together in the same page.

Web Object Cache Versus Oracle Web CacheYou can think of the Oracle Web Cache as the primary caching component. It serves cached pages directly to HTTP clients and can handle large volumes of HTTP traffic quickly, fitting the requirements of most Web sites. You can use the Oracle Web Cache to store complete Web pages or partial pages (through use of the JESI tags). Cached pages can be customized, to a certain extent, before being sent to a client, including cookie-replacement and page fragment concatenation, for example.

It is advisable to use the Oracle Web Cache as much as possible to reduce the load on the Web application server and back-end database. The caching needs of a large percentage of Web pages can be addressed by the Oracle Web Cache alone.

As a complement to the Oracle Web Cache, you can use the Web Object Cache to capture intermediate results of JSP and servlet execution, and subsequently reuse these cached results in other parts of the Java application logic. It is not beneficial to use the Web Object Cache in your Web application unless you are doing a



significant amount of post-processing on cached objects between the time they are cached and the time they are served to a client.

Web Object Cache Versus Oracle9iAS Object Caching Service for JavaIn comparison to the Oracle9i Application Server Object Caching Service for Java, the Web Object Cache makes it much easier to store and maintain partial execution results in dynamic Web pages. The object caching service, being a pure object-based framework for any general Java application, is not aware of the HTTP environment in which it may be embedded. For example, it does not directly depend on HTTP cookies or sessions. When you directly use the object caching service within a Web application, you are responsible for creating any necessary interfacing. The object caching service does not provide a way to specify maintenance policies declaratively.


Summary of OracleJSP Releases and Feature Sets

Summary of OracleJSP Releases and Feature SetsOracleJSP release 1.1.2.3, a complete implementation the JSP 1.1 specification, is provided with Oracle9i database release 9.0.1.

Some other Oracle platforms supporting OracleJSP have not yet incorporated the latest OracleJSP release, however—they integrate OracleJSP release 1.1.0.0.0 (also a JSP 1.1 implementation) or 1.0.0.6.1 or 1.0.0.6.0 (JSP 1.0 implementations).

OracleJSP Releases Provided with Oracle PlatformsTable 2–1 summarizes which OracleJSP releases are provided with which Oracle platform releases as of this writing.

The "OracleJSP Feature Notes" column refers to OracleJSP release 1.1.3.x features documented in this manual that are limited in the OracleJSP release noted for the particular Oracle platform, or have special significance for the platform. For more information, see "OracleJSP Feature Notes for Previous Releases" on page 2-24.

Table 2–1 Oracle Platform Releases and OracleJSP Releases

Oracle Platform Servlet Environment OracleJSP ReleaseOracleJSP Feature Notes

Oracle9i Application Server, release 1.0.2.2

servlet 2.0

(Apache/JServ

OracleJSP 1.1.3.0(JSP 1.1)

globals.jsa

Oracle9i Servlet Engine, release 9.0.1

servlet 2.2 OracleJSP 1.1.2.3 (JSP 1.1)

n/a

Oracle9i Servlet Engine, release 9.0.0

servlet 2.2 OracleJSP 1.1.2.0 (JSP 1.1)

n/a

Oracle Servlet Engine (Oracle8i), release 8.1.7

servlet 2.2 OracleJSP 1.1.0.0.0 (JSP 1.1)

config params

Oracle9i Application Server, release 1.0.2.0

servlet 2.0 (Apache/JServ)

OracleJSP 1.1.0.0.0 (JSP 1.1)

globals.jsaconfig params

Oracle Internet Application Server, release 1.0.1



globals.jsaconfig params

Oracle Internet Application Server, release 1.0.0



globals.jsaconfig paramsJML restrictions



It is possible to download, incorporate, and use more recent OracleJSP versions with the above Oracle platforms; the OracleJSP versions documented are the versions that are supplied as part of the product.

To verify the OracleJSP release being used in a particular environment, retrieve the release number from the implicit application object in a JSP page, as follows:

<%= application.getAttribute("oracle.jsp.versionNumber") %>

OracleJSP Feature Notes for Previous ReleasesThe following points describe the significance of the "OracleJSP Feature Notes" column in Table 2–1 above, regarding previous OracleJSP releases.

■ The servlet 2.0 specification did not provide a complete framework for Web applications. For servlet 2.0 environments such as Apache/JServ and Oracle9i Application Server (which uses Apache/JServ), all releases of OracleJSP offer extensions through the globals.jsa mechanism to support a more complete application framework. See "OracleJSP Application and Session Support for Servlet 2.0" on page 5-38 for more information.

■ Some OracleJSP configuration parameters that are supported in release 1.1.3.x were not yet supported in previous releases. See "Configuration Parameters Summary Table" on page A-15.

■ Release 1.0.0.6.x of OracleJSP complied with the JSP 1.0 specification, not the JSP 1.1 specification, so could not support the JSP 1.1 custom tag library mechanism. As a result, these OracleJSP releases supported JML tags through

Oracle Application Server, release 4.0.8.2


config paramsJML restrictions

Oracle Web-to-go, release 1.3



Oracle JDeveloper, release 3.2


config params

Oracle JDeveloper, release 3.1



Table 2–1 Oracle Platform Releases and OracleJSP Releases (Cont.)

Oracle Platform Servlet Environment OracleJSP ReleaseOracleJSP Feature Notes



an Oracle-specific compile-time implementation, using extensions to the OracleJSP translator.

Use of JML in OracleJSP release 1.0.0.6.x requires a taglib directive (as specified for JSP 1.1 and supported by OracleJSP 1.1.x.x), but the directive must specify the class that contains the library, as follows:

<%@ taglib uri="oracle.jsp.parse.OpenJspRegisterLib" prefix="jml" %>

By contrast, when using a JSP implementation that complies with the JSP 1.1 specification, such as any OracleJSP 1.1.x release, the taglib directive specifies the tag library description file (in a .tld file or .jar file), as follows:

<%@ taglib uri="/WEB-INF/tlds/jmltags.tld" prefix="jml" %>

For information about the JML compile-time implementation, see Appendix C, "Compile-Time JML Tag Support".


OracleJSP Execution Models

OracleJSP Execution ModelsAs mentioned earlier, you can use the OracleJSP framework in a variety of server environments. OracleJSP offers two distinct execution models:

■ In environments other than the Oracle9i Servlet Engine, the OracleJSP container typically translates pages on demand before triggering their execution, as is also true with most other vendors’ JSP implementations.

■ In the Oracle9i Servlet Engine environment—for JSP pages running in the Oracle9i database or middle-tier database cache—the developer translates the pages in advance and loads them into Oracle9i as working servlets. (Command-line tools are available to translate the pages, load them, and "publish" them to make them available for execution. You can have the translation occur either on the client or in the server.) When the end-user requests the JSP page, it is executed directly, with no translation necessary.

On-Demand Translation ModelOracleJSP uses the typical on-demand translation model for all server environments that support OracleJSP, other than the Oracle9i Servlet Engine. This includes using OracleJSP with the Apache Web server with JServ, for example, as well as various Oracle environments.

When a JSP page is requested from a Web server that incorporates the OracleJSP container, the servlet oracle.jsp.JspServlet is instantiated and invoked (assuming proper Web server configuration). This servlet can be thought of as the front-end of the OracleJSP container.

JspServlet locates the JSP page, translates and compiles it if necessary (if the page implementation class does not exist or has an earlier timestamp than the JSP page source), and triggers its execution.

Note that the Web server must be properly configured to map the *.jsp file name extension (in a URL) to JspServlet. The steps to accomplish this for Apache/JServ, the Sun Microsystems JWSDK, and Tomcat are discussed in detail in "Configuration of Web Server and Servlet Environment to Run OracleJSP" on page A-7.

Oracle9i Servlet Engine Pre-Translation ModelJSP pages intended to run in the Oracle9i Servlet Engine (OSE) are pre-translated and deployed to Oracle9i as working servlets. OSE incorporates the OracleJSP runtime.


OracleJSP Execution Models

Deployment Steps to Run JSP Pages in the Oracle9i Servlet EnginePerform the following steps to deploy JSP pages into Oracle9i:

1. Pre-translate the JSP pages (typically including compilation). The page implementation classes produced by the JSP translator are essentially working servlets.

2. Load the translated JSP pages into Oracle9i.

3. Optionally "hotload" the generated page implementation classes.

4. "Publish" the JSP pages to make them accessible for execution.

Command-line tools are available to translate, load, and publish the pages. The translator creates the page implementation class in a .java file and compiles it into a .class file.

Hotloading can be enabled and accomplished through additional steps. This is a feature that allows more efficient use of literal strings such as the generated HTML tags in a page implementation class. See "Overview of Hotloaded Classes in Oracle9i" on page 6-24.

Deployment to Oracle9i can be performed with the translation being done either beforehand on the client or as part of the deployment. For more information about these scenarios and the steps involved, see "Deployment to Oracle9i with Server-Side Translation" on page 6-45 and "Deployment to Oracle9i with Client-Side Translation" on page 6-59.

Oracle9i Servlet Engine JSP ContainerThe Oracle9i Servlet Engine incorporates its own OracleJSP container, which consists of most of the overall OracleJSP container without the OracleJSP translator (because any JSP page that runs in the OSE environment is pre-translated).

The OSE includes front-end JSP processing, with functionality similar to JspServlet in the on-demand translation model.

The front-end component finds and executes JSP pages according to a servlet path (often referred to as a "virtual path") that was entered in the Oracle9i JNDI name space during publishing. You specify a servlet path name when you publish the JSP page.


Oracle JDeveloper Support for OracleJSP

Oracle JDeveloper Support for OracleJSPVisual Java programming tools are beginning to support JSP coding. In particular, Oracle JDeveloper supports OracleJSP and includes the following features:

■ integration of the OracleJSP 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

■ a deployment option for JSP applications that rely on the JDeveloper Business Components for Java (BC4J)

See "Deployment of JSP Pages with JDeveloper" on page 6-79 for more information about JSP deployment support.

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 their online help.


B

3
Basics
This chapter discusses basic issues such as applications and sessions, JSP-servlet interaction, resource management, and application roots and doc roots. This is followed by a JSP "starter sample" for data access.

The following topics are included:

■ Preliminary Considerations

■ Application Root and Doc Root Functionality

■ Overview of JSP Applications and Sessions

■ JSP-Servlet Interaction

■ JSP Resource Management

■ JSP Runtime Error Processing

■ JSP Starter Sample for Data Access

asics 3-1

Preliminary Considerations

Preliminary ConsiderationsThis section discusses a few issues to be aware of before you start developing. The following topics are covered:

■ Installation and Configuration Overview

■ Development Environments Versus Deployment Environments

■ Client-Side Considerations

Installation and Configuration OverviewInstallation and configuration, primarily for key non-Oracle environments, is covered in Appendix A, "General Installation and Configuration".

For installation and configuration of Oracle environments that support OracleJSP, consult the documentation for the particular Oracle product.

Within Oracle9i, the Oracle9i Servlet Engine (OSE) incorporates OracleJSP.

Development Environments Versus Deployment EnvironmentsJSP developers targeting a non-Oracle environment, such as Apache/JServ, typically develop in the same environment as the target environment. In this case, the installation and configuration instructions in Appendix A apply to both the development environment and the deployment environment, although some of the configuration parameters are of interest only during development.

JSP developers targeting the Oracle9i Servlet Engine or some other Oracle environment have at least two development options:

■ Use Oracle JDeveloper for development and deployment.

JDeveloper incorporates OracleJSP and a servlet container for use in testing during development. It also incorporates features to help you deploy the finished product to the target location.

See "Oracle JDeveloper Support for OracleJSP" on page 2-28 for an introduction to OracleJSP support in JDeveloper. Refer to JDeveloper documentation for installation and configuration instructions.

■ Develop and test in a non-Oracle environment such as Apache/JServ before deploying to the target Oracle environment for final testing and end use.

In this case, the information in Appendix A is presumably of interest to you for your development environment.


Preliminary Considerations

After testing in the development environment, you can pre-translate the JSP pages and deploy them to Oracle9i using command-line tools available with the OracleJSP installation. The OracleJSP command-line translator has options that are equivalent to relevant translation-time configuration parameters. For information, see "The ojspc Pre-Translation Tool" on page 6-26 and "Deployment to Oracle9i with Client-Side Translation" on page 6-59.

For information about installing and configuring any of the Oracle environments that support OracleJSP, refer to the documentation for the particular product.

Client-Side ConsiderationsJSP pages will run with any standard browser supporting HTTP 1.0 or higher.

The JDK or other Java environment in the end-user’s Web browser is irrelevant, because all the Java code in a JSP page is executed in the Web server or data server.

Basics 3-3

Application Root and Doc Root Functionality

Application Root and Doc Root FunctionalityThis section provides an overview of application roots and doc roots, distinguishing between servlet 2.2 functionality and servlet 2.0 functionality.

Application Roots in Servlet 2.2 EnvironmentsAs mentioned earlier, the servlet 2.2 specification provides for each application to have its own servlet context. Each servlet context is associated with a directory path in the server file system, which is the base path for modules of the application. This is the application root. Each application has its own application root.

This is similar to how a Web server uses a doc root as the root location for HTML pages and other files belonging to a Web application.

For an application in a servlet 2.2 environment, there is a one-to-one mapping between the application root (for servlets and JSP pages) and the doc root (for static files, such as HTML files)—they are essentially the same thing.

Note that a servlet URL has the following general form:

http://host[:port]/contextpath/servletpath

When a servlet context is created, a mapping is specified between the application root and the context path portion of a URL.

For example, consider an application with the application root /home/dir/mybankappdir, which is mapped to the context path mybank. Further assume the application includes a servlet whose servlet path is loginservlet. This servlet can be invoked as follows:

http://host[:port]/mybank/loginservlet

(The application root directory name itself is not visible to the end-user.)

To continue this example for an HTML page in this application, the following URL points to the file /home/dir/mybankappdir/dir1/abc.html:

http://host[:port]/mybank/dir1/abc.html

For each servlet environment there is also a default servlet context. For this context, the context path is simply "/", which is mapped to the default servlet context application root.

For example, assume the application root for the default context is /home/mydefaultdir, and a servlet with the servlet path myservlet uses the


Application Root and Doc Root Functionality

default context. Its URL would be as follows (again, the application root directory name itself is not visible to the user):

http://host[:port]/myservlet

(The default context is also used if there is no match for the context path specified in a URL.)

Continuing this example for an HTML file, the following URL points to the file /home/mydefaultdir/dir2/def.html:

http://host[:port]/dir2/def.html

OracleJSP Application Root Functionality in Servlet 2.0 EnvironmentsApache/JServ and other servlet 2.0 environments have no concept of application roots, because there is only a single application environment. The Web server doc root is effectively the application root.

For Apache, the doc root is typically some .../htdocs directory. In addition, it is possible to specify "virtual" doc roots through alias settings in the httpd.conf configuration file.

In a servlet 2.0 environment, OracleJSP offers the following functionality regarding doc roots and application roots:

■ By default, OracleJSP uses the doc root as an application root.

■ Through the OracleJSP globals.jsa mechanism, you can designate a directory under the doc root to serve as an application root for any given application. This is accomplished by placing a globals.jsa file as a marker in the desired directory. (See "Overview of globals.jsa Functionality" on page 5-38.)

Basics 3-5

Overview of JSP Applications and Sessions

Overview of JSP Applications and SessionsThis section provides a brief overview of how JSP applications and sessions are supported by OracleJSP.

General OracleJSP Application and Session SupportOracleJSP uses underlying servlet mechanisms for managing applications and sessions. For information about these mechanisms, see "Servlet Sessions" on page B-4 and "Servlet Contexts" on page B-6. For servlet 2.1 and servlet 2.2 environments, these underlying mechanisms are sufficient, providing a distinct servlet context and session object for each JSP application.

Using the servlet mechanisms becomes problematic, however, in a servlet 2.0 environment such as Apache/JServ. The concept of a Web application was not well defined in the servlet 2.0 specification, so in a servlet 2.0 environment there is only one servlet context per servlet container. Additionally, there is one session object only per servlet container. However, for Apache/JServ and other servlet 2.0 environments, OracleJSP provides extensions to optionally allow distinct servlet contexts and session objects for each application. (This is unnecessary for Web servers hosting just a single application.)

JSP Default Session RequestsGenerally speaking, servlets do not request an HTTP session by default. However, JSP page implementation classes do request an HTTP session by default. You can override this by setting the session parameter to false in a JSP page directive, as follows:

<%@ page ... session="false" %>

Note: For additional information relevant to Apache/JServ and other servlet 2.0 environments, see "Considerations for Apache/JServ Servlet Environments" on page 4-38 and "Overview of globals.jsa Functionality" on page 5-38.


JSP-Servlet Interaction

JSP-Servlet InteractionAlthough coding JSP pages is convenient in many ways, some situations call for servlets. One example is when you are outputting binary data, as discussed in "Reasons to Avoid Binary Data in JSP Pages" on page 4-22.

Therefore, it is sometimes necessary to go back and forth between servlets and JSP pages in an application. This section discusses how to accomplish this, covering the following topics:

■ Invoking a Servlet from a JSP Page

■ Passing Data to a Servlet Invoked from a JSP Page

■ Invoking a JSP Page from a Servlet

■ Passing Data Between a JSP Page and a Servlet

■ JSP-Servlet Interaction Samples

Invoking a Servlet from a JSP PageAs when invoking one JSP page from another, you can invoke a servlet from a JSP page through the jsp:include and jsp:forward action tags. (See "JSP Actions and the <jsp: > Tag Set" on page 1-18.) Following is an example:

<jsp:include page="/servlet/MyServlet" flush="true" />

When this statement is encountered during page execution, the page buffer is output to the browser and the servlet is executed. When the servlet has finished executing, control is transferred back to the JSP page and the page continues executing. This is the same functionality as for jsp:include actions from one JSP page to another.

And as with jsp:forward actions from one JSP page to another, the following statement would clear the page buffer, terminate the execution of the JSP page, and execute the servlet:

<jsp:forward page="/servlet/MyServlet" />

Important: This discussion assumes a servlet 2.2 environment. Appropriate reference is made to other sections of this document for related considerations for Apache/JServ and other servlet 2.0 environments.

Basics 3-7


Passing Data to a Servlet Invoked from a JSP PageWhen dynamically including or forwarding to a servlet from a JSP page, you can use a jsp:param tag to pass data to the servlet (the same as when including or forwarding to another JSP page).

A jsp:param tag is used within a jsp:include or jsp:forward tag. Consider the following example:

<jsp:include page="/servlet/MyServlet" flush="true" > <jsp:param name="username" value="Smith" /> <jsp:param name="userempno" value="9876" /></jsp:include>

For more information about the jsp:param tag, see "JSP Actions and the <jsp: > Tag Set" on page 1-18.

Alternatively, you can pass data between a JSP page and a servlet through an appropriately scoped JavaBean or through attributes of the HTTP request object. Using attributes of the request object is discussed later, in "Passing Data Between a JSP Page and a Servlet" on page 3-9.

Invoking a JSP Page from a ServletYou can invoke a JSP page from a servlet through functionality of the standard javax.servlet.RequestDispatcher interface. Complete the following steps in your code to use this mechanism:

1. Get a servlet context instance from the servlet instance:

ServletContext sc = this.getServletContext();

Important: You cannot include or forward to a servlet in Apache/JServ or other servlet 2.0 environments; you would have to write a JSP wrapper page instead. For information, see "Dynamic Includes and Forwards in Apache/JServ" on page 4-39.

Note: The jsp:param tag was introduced in the JSP 1.1 specification.



2. Get a request dispatcher from the servlet context instance, specifying the page-relative or application-relative path of the target JSP page as input to the getRequestDispatcher() method:

RequestDispatcher rd = sc.getRequestDispatcher("/jsp/mypage.jsp");

Prior to or during this step, you can optionally make data available to the JSP page through attributes of the HTTP request object. See "Passing Data Between a JSP Page and a Servlet" below for information.

3. Invoke the include() or forward() method of the request dispatcher, specifying the HTTP request and response objects as arguments. For example:

rd.include(request, response);

or:

rd.forward(request, response);

The functionality of these methods is similar to that of jsp:include and jsp:forward actions. The include() method only temporarily transfers control; execution returns to the invoking servlet afterward.

Note that the forward() method clears the output buffer.

Passing Data Between a JSP Page and a ServletThe preceding section, "Invoking a JSP Page from a Servlet", notes that when you invoke a JSP page from a servlet through the request dispatcher, you can optionally pass data through the HTTP request object.

Notes:

■ The request and response objects would have been obtained earlier using standard servlet functionality, such as the doGet() method specified in the javax.servlet.http.HttpServlet class.

■ This functionality was introduced in the servlet 2.1 specification.

Basics 3-9

You can accomplish this using either of the following approaches:

■ You can append a query string to the URL when you obtain the request dispatcher, using "?" syntax with name=value pairs. For example:

RequestDispatcher rd = sc.getRequestDispatcher("/jsp/mypage.jsp?username=Smith");

In the target JSP page (or servlet), you can use the getParameter() method of the implicit request object to obtain the value of a parameter set in this way.

■ You can use the setAttribute() method of the HTTP request object. For example:

request.setAttribute("username", "Smith");RequestDispatcher rd = sc.getRequestDispatcher("/jsp/mypage.jsp");

In the target JSP page (or servlet), you can use the getAttribute() method of the implicit request object to obtain the value of a parameter set in this way.

JSP-Servlet Interaction SamplesThis section provides a JSP page and a servlet that use functionality described in the preceding sections. The JSP page Jsp2Servlet.jsp includes the servlet MyServlet, which includes another JSP page, welcome.jsp.

Code for Jsp2Servlet.jsp

<HTML><HEAD> <TITLE> JSP Calling Servlet Demo </TITLE> </HEAD><BODY>

<% request.setAttribute("empid", "1234"); %>

Notes:

■ This functionality was introduced in the servlet 2.1 specification. Be aware that the semantics are different between the servlet 2.1 specification and the servlet 2.2 specification—in a servlet 2.1 environment a given attribute can be set only once.

■ Mechanisms discussed in this section can be used instead of the jsp:param tag to pass data from a JSP page to a servlet.


<jsp:include page="/servlet/MyServlet?user=Smith" flush="true"/>

</BODY></HTML>

Code for MyServlet.java

import javax.servlet.*;import javax.servlet.http.*;import java.io.PrintWriter;import java.io.IOException;

public class MyServlet extends HttpServlet {

public void doGet (HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { PrintWriter out= response.getWriter(); out.println("<B><BR>User:" + request.getParameter("user")); out.println (", Employee number:" + request.getAttribute("empid") + "</B>"); this.getServletContext().getRequestDispatcher("/jsp/welcome.jsp"). include(request, response); }}

Code for welcome.jsp

<%----------------------------------------------------------- Copyright © 1999, Oracle Corporation. All rights reserved.------------------------------------------------------------%>

<HTML><HEAD> <TITLE> The Welcome JSP </TITLE> </HEAD><BODY>

<H3> Welcome! </H3><P><B> Today is <%= new java.util.Date() %>. Have a nice day! </B></P></BODY></HTML>

Basics 3-11

JSP Resource Management

JSP Resource ManagementThe javax.servlet.http package offers a standard mechanism for managing session resources. Additionally, Oracle provides extensions for managing application, session, page, and request resources.

Standard Session Resource Management—HttpSessionBindingListenerA 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-scoped resources. Through this mechanism, a session-scoped query bean could, for example, acquire a database cursor when the bean is instantiated and close it when the HTTP session is terminated. (The example in "JSP Starter Sample for Data Access" on page 3-21 opens and closes the connection for each query, which adds overhead.)

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

The valueBound() and valueUnbound() MethodsAn 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; the valueUnbound() method when the object is removed from the session or when the session times-out 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).

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.



"JDBCQueryBean JavaBean Code" below provides a sample JavaBean that implements HttpSessionBindingListener and a sample JSP page that calls the bean.

JDBCQueryBean JavaBean CodeFollowing 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 "The UseJDBCQueryBean JSP Page" on page 3-15), 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(); }

Note: OracleJSP provides extensions for additional resource management, allowing you to program JavaBeans to manage page-scoped, request-scoped, or application-scoped resources as well as session-scoped resources. See "OracleJSP Event Handling—JspScopeListener" on page 5-33.

Basics 3-13


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(1) + " 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-scoped bean is already bound } public synchronized void valueUnbound(HttpSessionBindingEvent event) { try { if (conn != null) conn.close(); } catch (SQLException ignored) {} }}

The UseJDBCQueryBean JSP PageThe following JSP page uses the JDBCQueryBean JavaBean defined in "JDBCQueryBean JavaBean Code" 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 command 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 is what 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");

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.

Basics 3-15


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:

Advantages of HttpSessionBindingListenerIn 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.

Overview of Oracle Extensions for Resource ManagementOracle provides the following extensions for managing application and session resources as well as page and request resources:

■ JspScopeListener—for managing application, session, page, or request resources

For information, see "OracleJSP Event Handling—JspScopeListener" on page 5-33.

■ globals.jsa application and session events—for start and end events for applications and sessions, typically in a servlet 2.0 environment such as Apache/JServ

See "The globals.jsa Event Handlers" on page 5-43 for information.

Basics 3-17

JSP Runtime Error Processing

JSP Runtime Error ProcessingWhile a JSP page is executing and processing client requests, runtime errors can occur either inside the page or outside the page (such as in a called JavaBean). This section describes the JSP error processing mechanism and provides a simple example.

Using JSP Error PagesAny runtime error encountered during execution of a JSP page is handled using the standard Java exception mechanism in one of two ways:

■ You can catch and handle exceptions in a Java scriptlet within the JSP page itself, using standard Java exception-handling code.

■ Exceptions you do not catch in the JSP page will result in forwarding of the request and uncaught exception to an error page. This is the preferred way to handle JSP errors.

You can specify the URL of an error page by setting the errorPage parameter in a page directive in the originating JSP page. (For an overview of JSP directives, including the page directive, see "Directives" on page 1-10. )

In a servlet 2.2 environment, you can also specify a default error page in the web.xml deployment descriptor with instructions such as the following:

<error-page> <error-code>404</error-code> <location>/error404.html</location></error-page>

(See the Sun Microsystems Java Servlet Specification, Version 2.2 for more information about default error pages.)

An error page must have a page directive setting the isErrorPage parameter to true.

The exception object describing the error is a java.lang.Exception instance that is accessible in the error page through the implicit exception object.

Only an error page can access the implicit exception object. (For information about JSP implicit objects, including the exception object, see "Implicit Objects" on page 1-15.)

See "JSP Error Page Example" below for an example of error page usage.



JSP Error Page ExampleThe following example, nullpointer.jsp, generates an error and uses an error page, myerror.jsp, to output contents of the implicit exception object.

Code for nullpointer.jsp

<HTML><BODY><%@ page errorPage="myerror.jsp" %>Null pointer is generated below:<% String s=null; s.length();%></BODY></HTML>

Code for myerror.jsp

<HTML><BODY><%@ page isErrorPage="true" %>Here is your error:<%= exception %></BODY></HTML>

Note: There is ambiguity in the JSP 1.1 specification regarding exception types that can be handled through the JSP mechanism.

In OracleJSP, a page implementation class generated by the translator can handle an instance of the java.lang.Exception class or a subclass, but cannot handle an instance of the java.lang.Throwable class or any subclass other than Exception. A Throwable instance will be thrown by the OracleJSP container to the servlet container.

The ambiguity is expected to be addressed in the JSP 1.2 specification. OracleJSP behavior will be modified appropriately in a future release.

Basics 3-19


This example results in the following output:

Note: The line "Null pointer is generated below:" in nullpointer.jsp is not output when processing is forwarded to the error page. This shows the difference between JSP "include" and "forward" functionality—with a "forward", the output from the "forward-to" page replaces the output from the "forward-from" page.


JSP Starter Sample for Data Access

JSP Starter Sample for Data AccessChapter 1, "General Overview", provides a couple of simple JSP examples; however, if you are using OracleJSP, you presumably want to access an Oracle database or middle-tier database cache. This section offers a more interesting sample that uses standard JDBC code in a JSP page to perform a query.

Because the JDBC API is simply a set of Java interfaces, JavaServer Pages technology directly supports its use within JSP scriptlets.

The following example creates a query dynamically from search conditions the user enters through an HTML form (typed into a box and entered with an Ask Oracle button). To perform the specified query, it uses JDBC code in a method called runQuery() that is defined in a JSP declaration. It also defines a method formatResult() within the JSP declaration to produce the output. The runQuery() method uses the scott schema with password tiger. (JDBC is used because SQLJ is primarily for static SQL, although Oracle SQLJ adds extensions for dynamic SQL.)

The HTML INPUT tag specifies that the string entered in the form be named cond. Therefore, cond is also the input parameter to the getParameter() method of the implicit request object for this HTTP request, and the input parameter to the runQuery() method (which puts the cond string into the query WHERE clause).

Notes:

■ Oracle JDBC provides several driver alternatives: 1) the JDBC OCI driver for use with an Oracle client installation; 2) a 100%-Java JDBC Thin driver that can be used in essentially any client situation (including applets); 3) a JDBC server-side Thin driver to access one Oracle database or database cache from within another Oracle database or database cache; and 4) a JDBC server-side internal driver to access the database or database cache within which the Java code is running (such as from a Java stored procedure or Enterprise JavaBean). For more information about Oracle JDBC, see the Oracle9i JDBC Developer’s Guide and Reference.

■ OracleJSP also supports SQLJ (embedded SQL in Java) for static SQL operations and provides custom JavaBeans and custom SQL tags for data access. These features are discussed in Chapter 5, "OracleJSP Extensions".

Basics 3-21


<%@ page language="java" import="java.sql.*" %><HTML><HEAD> <TITLE> The JDBCQuery JSP </TITLE> </HEAD><BODY BGCOLOR="white"><% String searchCondition = request.getParameter("cond"); if (searchCondition != null) { %> <H3> Search results for <I> <%= searchCondition %> </I> </H3> <B> <%= runQuery(searchCondition) %> </B> <HR><BR><% } %><B>Enter a search condition:</B><FORM METHOD="get"> <INPUT TYPE="text" NAME="cond" SIZE=30><INPUT TYPE="submit" VALUE="Ask Oracle");</FORM></BODY></HTML><%-- Declare and define the runQuery() method. --%><%! private String runQuery(String cond) throws SQLException { Connection conn = null; Statement stmt = null; ResultSet rset = null; try { DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver()); conn = DriverManager.getConnection("jdbc:oracle:oci8:@", "scott", "tiger"); stmt = conn.createStatement(); // dynamic query rset = stmt.executeQuery ("SELECT ename, sal FROM scott.emp "+ (cond.equals("") ? "" : "WHERE " + cond )); return (formatResult(rset)); } catch (SQLException e) { return ("<P> SQL error: <PRE> " + e + " </PRE> </P>\n"); } finally {

Notes:

■ Another approach to this example would be to define the runQuery() method in <%...%> scriptlet syntax instead of <%!...%> declaration syntax.

■ This example uses the JDBC OCI driver, which requires an Oracle client installation. If you want to run this sample, use an appropriate JDBC driver and connection string.



if (rset!= null) rset.close(); if (stmt!= null) stmt.close(); if (conn!= null) conn.close(); } } 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>"); do { sb.append("<LI>" + rset.getString(1) + " earns $ " + rset.getInt(2) + ".</LI>\n"); } while (rset.next()); sb.append("</UL>"); } return sb.toString(); }%>

The graphic below illustrates sample output for the following input:

sal >= 2500 AND sal < 5000

Basics 3-23

Key Considera

4
Key Considerations
This chapter discusses important programming, configurational, and runtime considerations, as well as special considerations for particular execution environments. The following topics are covered:

■ General JSP Programming Strategies, Tips, and Traps

■ Key OracleJSP Configuration Issues

■ OracleJSP Runtime Page and Class Reloading (Non-OSE Only)

■ Considerations for the Oracle9i Servlet Engine

■ Considerations for Apache/JServ Servlet Environments

tions 4-1

General JSP Programming Strategies, Tips, and Traps

General JSP Programming Strategies, Tips, and TrapsThis section discusses issues you should consider when programming JSP pages that will run in the OracleJSP container, regardless of the particular target environment. The following assortment of topics are covered:

■ JavaBeans Versus Scriptlets

■ Use of Enterprise JavaBeans in JSP Pages

■ Use of JDBC Performance Enhancement Features

■ Static Includes Versus Dynamic Includes

■ When to Consider Creating and Using JSP Tag Libraries

■ Use of a Central Checker Page

■ Workarounds for Large Static Content in JSP Pages

■ Method Variable Declarations Versus Member Variable Declarations

■ Page Directive Characteristics

■ JSP Preservation of White Space and Use with Binary Data

JavaBeans Versus ScriptletsThe section "Separation of Business Logic from Page Presentation—Calling JavaBeans" on page 1-5 describes a key advantage of JavaServer Pages technology: Java code containing the business logic and determining the dynamic content can be separated from the HTML code containing the request processing, presentation logic, and static content. This separation allows HTML experts to focus on presentation logic in the JSP page itself, while Java experts focus on business logic in JavaBeans that are called from the JSP page.

A typical JSP page will have only brief snippets of Java code, usually for Java functionality for request processing or presentation. The sample page in "JSP Starter Sample for Data Access" on page 3-21, although illustrative, is probably not an ideal design. Data access, such as in the runQuery() method in the sample, is usually

Note: In addition to being aware of what is discussed in this section, you should be aware of OracleJSP translation and deployment issues and behavior. See Chapter 6, "JSP Translation and Deployment".



more appropriate in a JavaBean. However, the formatResult() method in the sample, which formats the output, is more appropriate for the JSP page itself.

Use of Enterprise JavaBeans in JSP PagesTo use an Enterprise JavaBean (EJB) in a JSP page, choose either of the following approaches:

■ Call the EJB directly from the JSP page.

■ Use a JavaBean wrapper for the EJB and call the JavaBean from the JSP page as you would any other JavaBean (preferred).

For general information, this section provides two examples of calling an EJB from a JSP page—one where the JSP page runs in a middle-tier environment and one where it runs in the Oracle9i Servlet Engine. These two examples point out some significant advantages in using OSE.

These are followed by an example using the more modular approach of calling an EJB from a JavaBean wrapper.

For general information about the Oracle EJB implementation, see the Oracle9i Enterprise JavaBeans Developer’s Guide and Reference.

Calling an EJB from a JSP Page in the Middle TierThe following JSP page calls an EJB from a middle-tier environment such as the Oracle9i Application Server. In this case, the service URL is specified as sess_iiop://localhost:2481:ORCL ( you may need to modify it to use your own hostname, IIOP port number and Oracle instance name). The JNDI naming context is set up through the new InitialContext(env) construction, where env is a hashtable defining the parameters for the context. Once the initial context (ic) is created, the code looks up the EJB home object using the service URL and the JNDI name for the EJB:

EmployeeHome home = (EmployeeHome) ic.lookup (surl + "/test/employeeBean");

Then the home.create() method is called to create an instance of the bean, and the bean’s query() method is called to get the name and salary for the employee whose number was entered through the HTML form in the JSP page.

Key Considerations 4-3


Following is the sample code:

<HTML><%@ page import="employee.Employee, employee.EmployeeHome,employee.EmpRecord, oracle.aurora.jndi.sess_iiop.ServiceCtx,javax.naming.Context, javax.naming.InitialContext, java.util.Hashtable"%>

<HEAD> <TITLE> The CallEJB JSP </TITLE> </HEAD><BODY BGCOLOR="white"><BR><% String empNum = request.getParameter("empNum"); String surl = request.getParameter("surl"); if (empNum != null) { try { Hashtable env = new Hashtable(); env.put(Context.URL_PKG_PREFIXES, "oracle.aurora.jndi"); env.put(Context.SECURITY_PRINCIPAL, "scott"); env.put(Context.SECURITY_CREDENTIALS, "tiger"); env.put(Context.SECURITY_AUTHENTICATION, ServiceCtx.NON_SSL_LOGIN); Context ic = new InitialContext (env); EmployeeHome home = (EmployeeHome)ic.lookup (surl + "/test/employeeBean"); Employee testBean = home.create(); EmpRecord empRec = testBean.query (Integer.parseInt(empNum));%><h2><BLOCKQUOTE><BIG><PRE> Hello, I’m an EJB in Oracle9i. Employee <%= empRec.ename %> earns $ <%= empRec.sal %><% } catch (Exception e) { %> Error occurred: <%= e %><% } } %></PRE></BIG></BLOCKQUOTE></h2> <HR><P><B>Enter an employee number and EJB service URL:</B></P><FORM METHOD=get><INPUT TYPE=text NAME="empNum" SIZE=10 value="7654"><INPUT TYPE=text NAME="surl" SIZE=40 value="sess_iiop://localhost:2481:ORCL"><INPUT TYPE=submit VALUE="Ask Oracle"></FORM></BODY></HTML>



Calling an EJB from a JSP Page in the Oracle9i Servlet EngineIf you are deploying the JSP page to Oracle9i to execute in the OSE environment, the EJB lookup and invocation is much simpler and highly optimized. In this case, the bean lookup is done locally within the Oracle9i JNDI namespace. An explicit service URL specification is not required. The naming context is initialized for the current session with the simple call:

Context ic = new InitialContext();

Note that the constructor in this case does not require any arguments, unlike the middle-tier example. The bean is looked up using just its JNDI name (without the service URL):

EmployeeHome home = (EmployeeHome)ic.lookup ("/test/employeeBean");

Following is the sample code:

<HTML><%@ page import="employee.Employee, employee.EmployeeHome,employee.EmpRecord, oracle.aurora.jndi.sess_iiop.ServiceCtx,javax.naming.Context, javax.naming.InitialContext,java.util.Hashtable" %>

<HEAD> <TITLE> The CallEJB JSP </TITLE> </HEAD><BODY BGCOLOR="white"><BR><% String empNum = request.getParameter("empNum"); if (empNum != null) { try { Context ic = new InitialContext(); EmployeeHome home = (EmployeeHome)ic.lookup("/test/employeeBean"); Employee testBean = home.create(); EmpRecord empRec = testBean.query (Integer.parseInt(empNum));%><h2><BLOCKQUOTE><BIG><PRE> Hello, I’m an EJB in Oracle9i. Employee <%= empRec.ename %> earns $ <%= empRec.sal %><% } catch (Exception e) { %> Error occurred: <%= e %><% } } %></PRE></BIG></BLOCKQUOTE></h2> <HR>

<P><B>Enter an employee number URL:</B></P>



<FORM METHOD=get><INPUT TYPE=text NAME="empNum" SIZE=10 value="7654"><INPUT TYPE=submit VALUE="Ask Oracle"></FORM></BODY></HTML>

Calling an EJB from a JavaBean Wrapper Called from a JSP PageThe following example provides a JSP page that calls a JavaBean wrapper, which in turn calls an EJB.

The JSP page uses an instance, employeeBean, of the EmployeeEJBWrapper JavaBean class. It calls the setServiceURL() method on the bean to set the database URL, according to the URL entered through the HTTP request object. It calls the doCallEJB() method on the bean to call the EJB.

The JavaBean implements the HttpSessionBindingListener interface. (See "Standard Session Resource Management—HttpSessionBindingListener" on page 3-12 for information about this interface.) When the session expires, the valueUnbound() method is called to destroy the EJB instance.

JNDI setup, in the bean, is accomplished as in the preceding examples.

Following is the JSP page:

<HTML><%@ page import="beans.EmployeeEJBWrapper" %>

<jsp:useBean id="employeeBean" class="beans.EmployeeEJBWrapper" scope="session" />

<HEAD> <TITLE> The CallEJB JSP </TITLE> </HEAD><BODY BGCOLOR="white"><BR><% String empNum = request.getParameter("empNum"); String surl = request.getParameter("surl"); String inJServer = System.getProperty("oracle.jserver.version"); // save the parameters in the bean instance if (surl != null) { employeeBean.setServiceURL(surl); } if (empNum != null) { employeeBean.setEmpNumber(empNum);



%>

<h2><BLOCKQUOTE><BIG><PRE> Employee Salary <%= employeeBean.doCallEJB(Integer.parseInt(empNum), inJServer) %> </PRE></BIG></BLOCKQUOTE></h2> <HR><% } // show the defaults or the values last entered String val1 = ((empNum == null) ? "7654" : employeeBean.getEmpNumber()); String val2 = ((surl == null) ? "sess_iiop://localhost:2481:ORCL" : employeeBean.getServiceURL());%>

<P><B>Enter the following data: <FORM METHOD=get> Employee Number: <INPUT TYPE=text NAME="empNum" SIZE=10 VALUE= <%= val1 %>><% if (inJServer == null) { // not running in JServer, need a service URL %> <P> EJB Service URL: <INPUT TYPE=text NAME="surl" SIZE=40 VALUE= <%= val2 %>><% } %><INPUT TYPE=submit VALUE="Ask Oracle"></FORM></BODY></HTML>

And here is the JavaBean code:

package beans;

import employee.Employee;import employee.EmployeeHome;import employee.EmpRecord;import oracle.aurora.jndi.sess_iiop.ServiceCtx;import javax.naming.Context;import javax.naming.InitialContext;import javax.servlet.http.HttpSessionBindingListener;import javax.servlet.http.HttpSessionBindingEvent;import java.util.Hashtable;



public class EmployeeEJBWrapper implements HttpSessionBindingListener{ public EmployeeEJBWrapper() {} // no arg bean constructor private Employee employeeEJB = null; private String empNumber = null; private String serviceURL = null;

public String doCallEJB(int empno, String inJServer) { try { if (employeeEJB == null) { Context ic = null; EmployeeHome home = null; if (inJServer == null) { // not running in JServer, usual client setup Hashtable env = new Hashtable(); env.put(Context.URL_PKG_PREFIXES, "oracle.aurora.jndi"); env.put(Context.SECURITY_PRINCIPAL, "scott"); env.put(Context.SECURITY_CREDENTIALS, "tiger"); env.put(Context.SECURITY_AUTHENTICATION, ServiceCtx.NON_SSL_LOGIN); ic = new InitialContext (env); home = (EmployeeHome)ic.lookup (serviceURL + "/test/employeeBean"); } else { // in JServer, use simplified and optimized lookup ic = new InitialContext(); home = (EmployeeHome)ic.lookup ("/test/employeeBean"); } employeeEJB = home.create(); } EmpRecord empRec = empRec = employeeEJB.query (empno); return empRec.ename + " $" + empRec.sal; } catch (Exception e) { return "Error occurred: " + e;} }

public void setServiceURL (String serviceURL) { this.serviceURL = serviceURL; }

public String getServiceURL () { return serviceURL; }

public void setEmpNumber(String empNo) { empNumber = empNo;



}

public String getEmpNumber() { return empNumber; }

public void valueBound(HttpSessionBindingEvent event) { // nothing to do here, EJB will be created when query is submitted } public synchronized void valueUnbound(HttpSessionBindingEvent event) { if (employeeEJB != null) { try { employeeEJB.remove(); // destroy the bean instance } catch (Exception ignore) {} employeeEJB = null; } }}

Use of JDBC Performance Enhancement FeaturesYou can use the following performance enhancement features, supported through Oracle JDBC extensions, in JSP applications executed by OracleJSP:

■ caching database connections

■ caching JDBC statements

■ batching update statements

■ prefetching rows during a query

■ caching rowsets

Most of these performance features are supported by the ConnBean and ConnCacheBean data-access JavaBeans (but not by DBBean). "Oracle Data-Access JavaBeans" on page 5-13 describes these beans.

Database Connection CachingCreating a new database connection is an expensive operation that you should avoid whenever possible. Instead, use a cache of database connections. A JSP application can get a logical connection from a pre-existing pool of physical connections, and return the connection to the pool when done.



You can create a connection pool at any one of the four JSP scopes—application, session, page, or request. It is most efficient to use the maximum possible scope—application scope if that is permitted by the Web server, or session scope if not.

The Oracle JDBC connection caching scheme, built upon standard connection pooling as specified in the JDBC 2.0 standard extensions, is implemented in the ConnCacheBean data-access JavaBean provided with OracleJSP. This is probably how most OracleJSP developers will use connection caching. For information, see "ConnCacheBean for Connection Caching" on page 5-16.

It is also possible to use the Oracle JDBC OracleConnectionCacheImpl class directly, as though it were a JavaBean, as in the following example (although all OracleConnectionCacheImpl functionality is available through ConnCacheBean):

<jsp:useBean id="occi" class="oracle.jdbc.pool.OracleConnectionCacheImpl" scope="session" />

The same properties are available in OracleConnectionCacheImpl as in ConnCacheBean. They can be set either through jsp:setProperty statements or directly through the class setter methods.

For examples of using OracleConnectionCacheImpl directly, see "Connection Caching—ConnCache3.jsp and ConnCache1.jsp" on page 11-18.

For information about the Oracle JDBC connection caching scheme and the OracleConnectionCacheImpl class, see the Oracle9i JDBC Developer’s Guide and Reference.

JDBC Statement CachingStatement caching, an Oracle JDBC extension, improves performance by caching executable statements that are used repeatedly within a single physical connection, such as in a loop or in a method that is called repeatedly. When a statement is cached, the statement does not have to be re-parsed, the statement object does not have to be recreated, and parameter size definitions do not have to be recalculated each time the statement is executed.

The Oracle JDBC statement caching scheme is implemented in the ConnBean and ConnCacheBean data-access JavaBeans that are provided with OracleJSP. Each of these beans has a stmtCacheSize property that can be set through a jsp:setProperty statement or the bean’s setStmtCacheSize() method. For information, see "ConnBean for a Database Connection" on page 5-14 and "ConnCacheBean for Connection Caching" on page 5-16.



Statement caching is also available directly through the Oracle JDBC OracleConnection and OracleConnectionCacheImpl classes. For information about the Oracle JDBC statement caching scheme and the OracleConnection and OracleConnectionCacheImpl classes, see the Oracle9i JDBC Developer’s Guide and Reference.

Update BatchingThe Oracle JDBC update batching feature associates a batch value (limit) with each prepared statement object. With update batching, instead of the JDBC driver executing a prepared statement each time its "execute" method is called, the driver adds the statement to a batch of accumulated execution requests. The driver will pass all the operations to the database for execution once the batch value is reached. For example, if the batch value is 10, then each batch of ten operations will be sent to the database and processed in one trip.

OracleJSP supports Oracle JDBC update batching directly, through the executeBatch property of the ConnBean data-access JavaBean. You can set this property through a jsp:setProperty statement or through the setter method of the bean. If you use ConnCacheBean instead, you can enable update batching through Oracle JDBC functionality in the connection and statement objects you create. See "ConnBean for a Database Connection" on page 5-14 and "ConnCacheBean for Connection Caching" on page 5-16 for information about these JavaBeans.

For more information about Oracle JDBC update batching, see the Oracle9i JDBC Developer’s Guide and Reference.

Row PrefetchingThe Oracle JDBC row prefetching feature allows you to set the number of rows to prefetch into the client during each trip to the database or middle-tier database cache while a result set is being populated during a query, reducing the number of round trips to the server.

OracleJSP supports Oracle JDBC row prefetching directly, through the preFetch property of the ConnBean data-access JavaBean. You can set this property through

Important: Statements can be cached only within a single physical connection. When you enable statement caching for a connection cache, statements can be cached across multiple logical connection objects from a single pooled connection object, but not across multiple pooled connection objects.



a jsp:setProperty statement or through the setter method of the bean. If you use ConnCacheBean instead, you can enable row prefetching through Oracle JDBC functionality in the connection and statement objects you create. See "ConnBean for a Database Connection" on page 5-14 and "ConnCacheBean for Connection Caching" on page 5-16 for information about these JavaBeans.

For more information about Oracle JDBC row prefetching, see the Oracle9i JDBC Developer’s Guide and Reference.

Rowset CachingA cached rowset provides a disconnected, serializable, and scrollable container for retrieved data. This feature is useful for small sets of data that do not change often, particularly when the client requires frequent or continued access to the information. By contrast, using a normal result set requires the underlying connection and other resources to be held. Be aware, however, that large cached rowsets consume a lot of memory on the client.

In Oracle9i, Oracle JDBC provides a cached rowset implementation. If you are using an Oracle JDBC driver, use code inside a JSP page to create and populate a cached rowset as follows:

CachedRowSet crs = new CachedRowSet();crs.populate(rset); // rset is a previously created JDBC ResultSet object.

Once the rowset is populated, the connection and statement objects used in obtaining the original result set can be closed.

For more information about Oracle JDBC cached rowsets, see the Oracle9i JDBC Developer’s Guide and Reference.

Static Includes Versus Dynamic IncludesThe include directive, described in "Directives" on page 1-10, makes a copy of the included page and copies it into a JSP page (the "including page") during translation. This is known as a static include (or translate-time include) and uses the following syntax:

<%@ include file="/jsp/userinfopage.jsp" %>

The jsp:include action, described in "JSP Actions and the <jsp: > Tag Set" on page 1-18, dynamically includes output from the included page within the output of the including page, during runtime. This is known as a dynamic include (or runtime include).



Here is an example of jsp:include syntax:

<jsp:include page="/jsp/userinfopage.jsp" flush="true" />

For those of you who are familiar with C syntax, a static include is comparable to a #include statement. A dynamic include is similar to a function call. They are both useful, but serve different purposes.

Logistics of Static IncludesA static include increases the size of the generated code for the including JSP page, as though the text of the included page is physically copied into the including page during translation (at the point of the include directive). If a page is included multiple times within an including page, multiple copies are made.

A JSP page that is statically included does not need to stand as an independent, translatable entity. It simply consists of text that will be copied into the including page. The including page, with the included text copied in, must then be translatable. And, in fact, the including page does not have to be translatable prior to having the included page copied into it. A sequence of statically included pages can each be fragments unable to stand on their own.

Logistics of Dynamic IncludesA dynamic include does not significantly increase the size of the generated code for the including page, although method calls, such as to the request dispatcher, will be added. The dynamic include results in runtime processing being switched from the including page to the included page, as opposed to the text of the included page being physically copied into the including page.

A dynamic include does increase processing overhead, with the necessity of the additional call to the request dispatcher.

A page that is dynamically included must be an independent entity, able to be translated and executed on its own. Likewise, the including page must be independent as well, able to be translated and executed without the dynamic include.

Note: Both static includes and dynamic includes can be used only between pages in the same servlet context.



Advantages, Disadvantages, and Typical UsesStatic includes affect page size; dynamic includes affect processing overhead. Static includes avoid the overhead of the request dispatcher that a dynamic include necessitates, but may be problematic where large files are involved. (There is a 64K size limit on the service method of the generated page implementation class—see "Workarounds for Large Static Content in JSP Pages" on page 4-16.)

Overuse of static includes can also make debugging your JSP pages difficult, making it harder to trace program execution. Avoid subtle interdependencies between your statically included pages.

Static includes are typically used to include small files whose content is used repeatedly in multiple JSP pages. For example:

■ Statically include a logo or copyright message at the top or bottom of each page in your application.

■ Statically include a page with declarations or directives (such as imports of Java classes) that are required in multiple pages.

■ Statically include a central "status checker" page from each page of your application. (See "Use of a Central Checker Page" on page 4-15.)

Dynamic includes are useful for modular programming. You may have a page that sometimes executes on its own but sometimes is used to generate some of the output of other pages. Dynamically included pages can be reused in multiple including pages without increasing the size of the including pages.

When to Consider Creating and Using JSP Tag LibrariesSome situations dictate that the development team consider creating and using custom tags. In particular, consider the following situations:

■ JSP pages would otherwise have to include a significant amount of Java logic regarding presentation and format of output.

■ Special manipulation or redirection of JSP output is required.

Replacing Java SyntaxBecause one cannot count on JSP developers being experienced in Java programming, they may not be ideal candidates for coding Java logic in the page—logic that dictates presentation and format of the JSP output, for example.



This is a situation where JSP tag libraries might be helpful. If many of your JSP pages will require such logic in generating their output, a tag library to replace Java logic would be a great convenience for JSP developers.

An example of this is the JML sample tag library provided with OracleJSP. This library includes tags that support logic equivalent to Java loops and conditionals. See "Overview of the JSP Markup Language (JML) Sample Tag Library" on page 7-20 for information.

Manipulating or Redirecting JSP OutputAnother common situation for custom tags is if special runtime processing of the response output is required. Perhaps the desired functionality requires an extra processing step or redirection of the output to somewhere other than the browser.

An example is to create a custom tag that you can place around a body of text whose output will be redirected into a log file instead of to a browser, such as in the following example (where cust is the prefix for the tag library and log is one of the library’s tags):

<cust:log> Today is <%= new java.util.Date() %> Text to log. More text to log. Still more text to log.</cust:log>

See "Tag Handlers" on page 7-4 for information about processing of tag bodies.

Use of a Central Checker PageFor general management or monitoring of your JSP application, it may be useful to use a central "checker" page that you include from each page in your application. A central checker page could accomplish tasks such as the following during execution of each page:

■ Check session status.

■ Check login status (such as checking the cookie to see if a valid login has been accomplished).

■ Check usage profile (if a logging mechanism has been implemented to tally events of interest, such as mouse clicks or page visits).

There could be many more uses as well.



As an example, consider a session checker class, MySessionChecker, that implements the HttpSessionBindingListener interface. (See "Standard Session Resource Management—HttpSessionBindingListener" on page 3-12.)

public class MySessionChecker implements HttpSessionBindingListener{ ... valueBound(HttpSessionBindingEvent event) {...} valueUnbound(HttpSessionBindingEvent event) {...} ...}

You can create a checker JSP page, suppose centralcheck.jsp, that includes something like the following:

<jsp:useBean id="sessioncheck" class="MySessionChecker" scope="session" />

In any page that includes centralcheck.jsp, the servlet container will call the valueUnbound() method implemented in the MySessionChecker class as soon as sessioncheck goes out of scope (at the end of the session). Presumably this is to manage session resources. You could include centralcheck.jsp at the end of each JSP page in your application.

Workarounds for Large Static Content in JSP PagesJSP pages with large amounts of static content (essentially, large amounts of HTML code without content that changes at runtime) may result in slow translation and execution.

There are two primary workarounds for this (either workaround will speed translation):

■ Put the static HTML into a separate file and use a dynamic include command (jsp:include) to include its output in the JSP page output at runtime. See "JSP Actions and the <jsp: > Tag Set" on page 1-18 for information about the jsp:include command.



■ Put the static HTML into a Java resource file.

OracleJSP will do this for you if you enable the external_resource configuration parameter. This parameter is documented in "OracleJSP Configuration Parameters (Non-OSE)" on page A-15.

For deployment to Oracle9i, the -extres and -hotload options of the ojspc pre-translation tool, and the -hotload option of the publishjsp session shell command, also offer this functionality.

Another possible, though unlikely, problem with JSP pages that have large static content is that most (if not all) JVMs impose a 64K byte size limit on the code within any single method. Although javac would be able to compile it, the JVM would be unable to execute it. Depending on the implementation of the JSP translator, this may become an issue for a JSP page, because generated Java code from essentially the entire JSP page source file goes into the service method of the page implementation class. (Java code is generated to output the static HTML to the browser, and Java code from any scriptlets is copied directly.)

Another possible, though rare, scenario is for the Java scriptlets in a JSP page to be large enough to create a size limit problem in the service method. If there is enough Java code in a page to create a problem, however, then the code should be moved into JavaBeans.

Important: A static <%@ include... %> command would not work. It would result in the included file being included at translation time, with its code being effectively copied back into the including page. This would not solve the problem.

Note: Putting static HTML into a resource file may result in a larger memory footprint than the jsp:include workaround mentioned above, because the page implementation class must load the resource file whenever the class is loaded.



Method Variable Declarations Versus Member Variable DeclarationsIn "Scripting Elements" on page 1-12, it is noted that JSP <%! ... %> declarations are used to declare member variables, while method variables must be declared in <% ... %> scriptlets.

Be careful to use the appropriate mechanism for each of your declarations, depending on how you want to use the variables:

■ A variable that is declared in <%! ... %> JSP declaration syntax is declared at the class level in the page implementation class that is generated by the JSP translator.

■ A variable that is declared in <% ... %> JSP scriptlet syntax is local to the service method of the page implementation class.

Consider the following example, decltest.jsp:

<HTML><BODY><% double f2=0.0; %><%! double f1=0.0; %>Variable declaration test.</BODY></HTML>

This results in something like the following code in the page implementation class:

package ...;import ...;

public class decltest extends oracle.jsp.runtime.HttpJsp { ...

// ** Begin Declarations double f1=0.0; // *** f1 declaration is generated here *** // ** End Declarations

public void _jspService (HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { ...

try { out.println( "<HTML>"); out.println( "<BODY>"); double f2=0.0; // *** f2 declaration is generated here ***



out.println( ""); out.println( ""); out.println( "Variable declaration test."); out.println( "</BODY>"); out.println( "</HTML>"); out.flush(); } catch( Exception e) { try { if (out != null) out.clear(); } catch( Exception clearException) { } finally { if (out != null) out.close(); } }}

Page Directive CharacteristicsThis section discusses the following page directive characteristics:

■ A page directive is static and takes effect during translation; you cannot specify parameter settings to be evaluated at runtime.

■ Java import settings in page directives are cumulative within a JSP page.

Page Directives Are StaticA page directive is static; it is interpreted during translation. You cannot specify dynamic settings to be interpreted at runtime. Consider the following examples:

Example 1 The following page directive is valid.

<%@ page contentType="text/html; charset=EUCJIS" %>

Note: This code is provided for conceptual purposes only. Most of the class is deleted for simplicity, and the actual code of a page implementation class generated by OracleJSP would differ somewhat.



Example 2 The following page directive is not valid and will result in an error. (EUCJIS is hard-coded here, but the example also holds true for any character set determined dynamically at runtime.)

<% String s="EUCJIS"; %><%@ page contentType="text/html; charset=<%=s%>" %>

For some page directive settings there are workarounds. Reconsidering Example 2, there is a setContentType() method that allows dynamic setting of the content type, as described in "Dynamic Content Type Settings" on page 10-4.

Page Directive Import Settings Are CumulativeJava import settings in page directives within a JSP page are cumulative.

Within any single JSP page, the following two examples are equivalent:

<%@ page language="java" %><%@ page import="sqlj.runtime.ref.DefaultContext, java.sql.*" %>

or:

<%@ page language="java" %><%@ page import="sqlj.runtime.ref.DefaultContext" %><%@ page import="java.sql.*" %>

After the first page directive import setting, the import setting in the second page directive adds to the set of classes or packages to be imported, as opposed to replacing the classes or packages to be imported.

JSP Preservation of White Space and Use with Binary DataOracleJSP (and JavaServer Pages implementations in general) preserves source code white space, including carriage returns and linefeeds, in what is output to the browser. Insertion of such white space may not be what the developer intended, and typically makes JSP technology a poor choice for generating binary data.

White Space ExamplesThe following two JSP pages produce different HTML output, due to the use of carriage returns in the source code.



Example 1—No Carriage Returns

The following JSP page does not have carriage returns after the Date() and getParameter() calls. (The third and fourth lines, starting with the Date() call, actually comprise a single wrap-around line of code.)

nowhitsp.jsp:

<HTML><BODY><%= new java.util.Date() %> <% String user=request.getParameter("user"); %> <%= (user==null) ? "" : user %><B>Enter name:</B><FORM METHOD=get><INPUT TYPE="text" NAME="user" SIZE=15><INPUT TYPE="submit" VALUE="Submit name"></FORM></BODY></HTML>

This results in the following HTML output to the browser. (Note that there are no blank lines after the date.)

<HTML><BODY>Tue May 30 20:07:04 PDT 2000 <B>Enter name:</B><FORM METHOD=get><INPUT TYPE="text" NAME="user" SIZE=15><INPUT TYPE="submit" VALUE="Submit name"></FORM></BODY></HTML>

Example 2—Carriage Returns

The following JSP page does include carriage returns after the Date() and getParameter() calls.

whitesp.jsp:

<HTML><BODY><%= new java.util.Date() %><% String user=request.getParameter("user"); %><%= (user==null) ? "" : user %>



<B>Enter name:</B><FORM METHOD=get><INPUT TYPE="text" NAME="user" SIZE=15><INPUT TYPE="submit" VALUE="Submit name"></FORM></BODY></HTML>

This results in the following HTML output to the browser.

<HTML><BODY>Tue May 30 20:19:20 PDT 2000

<B>Enter name:</B><FORM METHOD=get><INPUT TYPE="text" NAME="user" SIZE=15><INPUT TYPE="submit" VALUE="Submit name"></FORM></BODY></HTML>

Note the two blank lines between the date and the "Enter name:" line. In this particular case the difference is not significant, because both examples produce the same appearance in the browser, as shown below. However, this discussion nevertheless demonstrates the general point about preservation of white space.

Reasons to Avoid Binary Data in JSP PagesFor the following reasons, JSP pages are a poor choice for generating binary data. Generally you should use servlets instead.



■ JSP implementations are not designed to handle binary data—there are no methods for writing raw bytes in the JspWriter object.

■ During execution, the JSP container preserves whitespace. Whitespace is sometimes unwanted, making JSP pages a poor choice for generating binary output to the browser (a .gif file, for example) or other uses where whitespace is significant.

Consider the following example:

...<% out.getOutputStream().write(...binary data...) %><% out.getOutputStream().write(...more binary data...) %>

In this case, the browser will receive an unwanted newline characters in the middle of the binary data or at the end, depending on the buffering of your output buffer. You can avoid this problem by not using a carriage return between the lines of code, but of course this is an undesirable programming style.

Trying to generate binary data in JSP pages largely misses the point of JSP technology anyway, which is intended to simplify the programming of dynamic textual content.


Key OracleJSP Configuration Issues

Key OracleJSP Configuration IssuesThis section covers important effects of how you set key page directive parameters and OracleJSP configuration parameters. The discussion focuses on JSP page optimization, classpath issues, and class loader issues. The following topics are covered:

■ Optimization of JSP Execution

■ Classpath and Class Loader Issues (Non-OSE Only)

Optimization of JSP ExecutionThere are settings you can consider to optimize JSP performance, including the following:

■ Unbuffering a JSP Page

■ Not Checking for Retranslation (Non-OSE Only)

■ Not Using an HTTP Session

Unbuffering a JSP PageBy default, a JSP page uses an area of memory known as a page buffer. This buffer (8KB by default) is required if the page uses dynamic globalization support content type settings, forwards, or error pages. If it does not use any of these features, you can disable the buffer in a page directive:

<%@ page buffer="none" %>

This will improve the performance of the page by reducing memory usage and saving an output step. Output goes straight to the browser instead of going through the buffer first.

Not Checking for Retranslation (Non-OSE Only)When OracleJSP executes a JSP page, by default it will check whether a page implementation class already exists, compare the .class file timestamp against the .jsp source file timestamp, and retranslate the page if the .class file is older.

If comparing timestamps is unnecessary (as is the case in a typical deployment environment, where source code will not change), you can avoid the timestamp comparison by disabling the OracleJSP developer_mode flag (developer_mode=false).



The default setting is true. For information about how to set this flag in the Apache/JServ, JSWDK, and Tomcat environments, see "OracleJSP Configuration Parameter Settings" on page A-26.

Not Using an HTTP SessionIf a JSP page does not need an HTTP session (essentially, does not need to store or retrieve session attributes), then you can avoid using a session through the following page directive:

<%@ page session="false" %>

This will improve the performance of the page by eliminating the overhead of session creation or retrieval.

Note that although servlets by default do not use a session, JSP pages by default do use a session. For background information, see "Servlet Sessions" on page B-4.)

Classpath and Class Loader Issues (Non-OSE Only)OracleJSP uses its own classpath, distinct from the Web server classpath, and by default uses its own class loader to load classes from this classpath. This has significant advantages and disadvantages.

The OracleJSP classpath combines the following elements:

■ the OracleJSP default classpath

■ additional classpaths you specify in the OracleJSP classpath parameter

If there are classes you want loaded by the OracleJSP class loader instead of the system class loader, use the OracleJSP classpath configuration parameter, or place the classes in the OracleJSP default classpath. See "Advantages and Disadvantages of the OracleJSP Class Loader" on page 4-27 for related discussion.

OracleJSP Default ClasspathOracle JSP defines standard locations on the Web server for locating .class files and .jar files for classes (such as JavaBeans) that it requires. OracleJSP will find files in these locations without any Web server classpath configuration.

These locations are as follows and are relative to the application root:

/WEB-INF/classes /WEB-INF/lib /_pages



The _pages directory is the default location for translated and compiled JSP pages (as output by the JSP translator).

The classes directory is for individual Java .class files. These classes should be stored in subdirectories under the classes directory, according to Java package naming conventions.

For example, consider a JavaBean called LottoBean whose code defines it to be in the oracle.jsp.sample.lottery package. OracleJSP will look for LottoBean.class in the following location relative to the application root:

/WEB-INF/classes/oracle/jsp/sample/lottery/LottoBean.class

The lib directory is for .jar files. Because Java package structure is specified in the .jar file structure, the .jar files are all directly in the lib directory (not in subdirectories).

As an example, LottoBean.class might be stored in lottery.jar, located as follows relative to the application root:

/WEB-INF/lib/lottery.jar

The application root directory can be located in any of the following locations (as applicable, depending on your Web server and servlet environment), listed in the order they are searched:

■ the Web server directory the application is mapped to

■ the Web server document root directory

■ the directory containing the globals.jsa file (where applicable, typically in a servlet 2.0 environment)

Important: If you want classes in the WEB-INF directories to be loaded by the system class loader instead of the OracleJSP class loader, place the classes somewhere in the Web server classpath as well. The system class loader takes priority—any class that is placed in both classpaths will always be loaded by the system class loader.



OracleJSP classpath Configuration ParameterUse the OracleJSP classpath configuration parameter to add to the OracleJSP classpath.

For more information about this parameter, see "OracleJSP Configuration Parameters (Non-OSE)" on page A-15.

For information about how to set this parameter in the Apache/JServ, JSWDK, and Tomcat environments, see "OracleJSP Configuration Parameter Settings" on page A-26.

Advantages and Disadvantages of the OracleJSP Class LoaderUsing the OracleJSP class loader results in the following advantages and disadvantages:

■ limited access to OracleJSP-loaded classes from classes loaded by any other class loader

When a class is loaded by the OracleJSP class loader , its definition exists in the OracleJSP class loader only. Classes loaded by the system class loader or any other class loader, including any servlets, would have only limited access. The classes loaded by another class loader could not cast the OracleJSP-loaded class or call methods on it. This may be desirable or undesirable, depending on your situation.

■ automatic class reloading

By default, the OracleJSP class loader will automatically reload a class in the OracleJSP classpath whenever the class file or JAR file has been modified since

Notes:

■ Some Web servers, particularly those supporting the servlet 2.0 specification, do not offer full application support such as complete servlet context functionality. In this case, or when application mapping is not used, the default application is the server itself, and the application root is the Web server document root.

■ For older servlet environments, the globals.jsa file is an Oracle extension that can be used as an application marker to establish an application root. See "OracleJSP Application and Session Support for Servlet 2.0" on page 5-38.



it was last loaded. For a JSP page, for example, this can happen as a result of dynamic retranslation, which occurs by default if the .jsp source file for a page has a more recent timestamp than its corresponding page implementation .class file.

This is usually only advantageous in a development environment. In a typical deployment environment, the source, class, and JAR files will not change, and it is inefficient to check them for changes.

See "Dynamic Class Reloading" on page 4-30 for more information.

It follows that in a deployment environment, you will typically not want to use the OracleJSP classpath. By default, the classpath parameter is empty.


OracleJSP Runtime Page and Class Reloading (Non-OSE Only)

OracleJSP Runtime Page and Class Reloading (Non-OSE Only)This section describes conditions under which OracleJSP retranslates pages, reloads pages, and reloads classes during runtime. This discussion does not apply to JSP pages running in the Oracle9i Servlet Engine.

Dynamic Page RetranslationAs a Web application is running, the OracleJSP container by default will automatically retranslate and reload a JSP page whenever the page source is modified.

OracleJSP checks whether the last-modified time of the page implementation class file, as indicated in the OracleJSP in-memory cache, is older than the last-modified time of the JSP page source file.

You can avoid the overhead of OracleJSP checking timestamps for retranslation by setting the OracleJSP developer_mode flag to false. This is advantageous in a deployment environment, where source and class files will typically not change. For more information about this flag, see "OracleJSP Configuration Parameters (Non-OSE)" on page A-15. For how to set it, see "OracleJSP Configuration Parameter Settings" on page A-26.

Dynamic Page ReloadingThe OracleJSP container will automatically reload a JSP page (in other words, reload the generated page implementation class) in the following circumstances:

■ the page is retranslated

(See "Dynamic Page Retranslation" above.)

Notes:

■ Because of the usage of in-memory values for the class file last-modified time, note that removing a page implementation class file from the file system will not cause OracleJSP to retranslate the associated JSP page source. OracleJSP will only retranslate when the JSP page source file timestamp changes.

■ The class file will be regenerated when the cache is lost. This happens whenever a request is directed to this page after the server is restarted or after another page in this application has been retranslated.



■ a Java class that is called by the page and was loaded by the OracleJSP class loader (and not the system class loader) is modified

(See "Dynamic Class Reloading" below.)

■ any page in the same application is reloaded

A JSP pages is associated with the overall Web application within which it runs. (Even JSP pages not associated with a particular application are considered to be part of a "default application".)

Whenever a JSP page is reloaded, all JSP pages in the application are reloaded.

Dynamic Class ReloadingBy default, before OracleJSP dispatches a request that will execute a Java class that was loaded by the OracleJSP class loader, it checks to see if the class file has been modified since it was first loaded. If the class has been modified, then the OracleJSP class loader reloads it.

This applies only to classes in the OracleJSP classpath, which includes the following:

■ JAR files in the /WEB-INF/lib directory

■ .class files in the /WEB-INF/classes directory

■ classes in paths specified through the OracleJSP classpath configuration parameter

■ generated .class files in the _pages output directory

As mentioned in the preceding section, "Dynamic Page Reloading", reloading a class results in the dynamic reloading of JSP pages that reference that class.

Notes:

■ OracleJSP does not reload a page just because a statically included file has changed. (Statically included files, included through <%@ include %> syntax, are included during translation-time.)

■ Page reloading and page retranslation are not the same thing. Reloading does not imply retranslation.



For information about the classpath and developer_mode configuration parameters and how to set them, see "OracleJSP Configuration Parameters (Non-OSE)" on page A-15 and "OracleJSP Configuration Parameter Settings" on page A-26.

Important:

■ Remember that classes must be in the JSP classpath, not the system classpath, to be dynamically reloaded. If they are in the system classpath as well, the system class loader may take precedence in some circumstances, possibly interfering with JSP automatic-reloading functionality.

■ Dynamic class reloading can be expensive in terms of CPU usage. You can disable this feature by setting the OracleJSP developer_mode parameter to false. This is appropriate in deployment environments where classes are not expected to change.


Considerations for the Oracle9i Servlet Engine

Considerations for the Oracle9i Servlet EngineThe Oracle9i Servlet Engine (OSE) is integrated with the Oracle9i database and middle-tier database cache. To run in OSE, a JSP page must be deployed (loaded and published) into Oracle9i. The details of deploying JSP pages into Oracle9i 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 Data-Access Strategies" on page 2-8. When installing Oracle9i, 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 Oracle9i Servlet Engine are intended for data access, so some background is provided on database connections through Java.

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

Aside from connecting through the server-side internal driver or using any other features specific to the Oracle JVM, JSP pages written for OSE are portable to other environments running OracleJSP. The original code has to be modified and re-translated only if Oracle9i-specific features were used.


■ Introduction to the Oracle JVM and JDBC Server-Side Internal Driver

■ Database Connections Through Java

■ Use of JNDI by the Oracle9i Servlet Engine

■ 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 Oracle9i" on page 6-14.



Introduction to the Oracle JVM and JDBC Server-Side Internal DriverEach Oracle session through Java 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 a JVM in the target Oracle9i database or middle-tier database cache typically uses the JDBC server-side internal driver to access the local SQL engine. This driver is intrinsically tied to Oracle9i and the Oracle JVM. The driver runs as part of the same process as the database. It also runs within a default Oracle session—the same session in which the JVM was invoked.

The server-side internal driver is optimized to run within the database or database cache and provide direct access to SQL data and PL/SQL subprograms. The entire JVM operates in the same address space as the database or database cache 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 Oracle Net call to access the SQL engine.

Database Connections Through JavaThe information here is applicable for connections to either the middle-tier database cache or the back-end database. (Both are referred to as simply "the database" for this discussion.)

Because the JDBC server-side internal driver runs within a default Oracle 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.



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

Connecting with the OracleDriver Class defaultConnection() MethodThe 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; } }

Notes:

■ Alternatively, you can connect using custom JavaBeans provided with OracleJSP. See "Oracle Data-Access JavaBeans" on page 5-13.

■ 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.



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() MethodInstead 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 Oracle9i JDBC Developer’s Guide and Reference.



Connecting with the Server-Side Thin DriverThe 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 Oracle9i Servlet Engine and other servlet environments; however, the server-side internal driver offers more efficient performance.

No Auto-Commit in Server-Side Internal DriverThe 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 DriverConnection 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 Oracle9i Servlet EngineThe Oracle9i 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 Oracle9i 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 Oracle9i (Session Shell publishjsp)" on page 6-46, for deployment with server-side translation, or "Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)" on page 6-69, for deployment with client-side translation.

For general information about how the Oracle9i Servlet Engine uses JNDI, see the Oracle9i Servlet Engine Developer’s Guide.

Equivalent Code for OracleJSP Runtime Configuration ParametersSome OracleJSP configuration parameters take effect during translation; others take effect during runtime. When you deploy JSP pages to Oracle9i to run in the Oracle9i Servlet Engine, you can make appropriate translation-time settings through command-line options of the OracleJSP pre-translation tool.

At runtime, however, OSE does not support execution-time configuration parameters. The most significant runtime parameter is translate_params, which relates to globalization support. For a discussion of equivalent code, see "Code Equivalent to the translate_params Configuration Parameter" on page 10-7.


Considerations for Apache/JServ Servlet Environments

Considerations for Apache/JServ Servlet Environments There are special considerations in running OracleJSP in Apache/JServ-based platforms, including Oracle9i Application Server release 1.0.x, because this is a servlet 2.0 environment. The servlet 2.0 specification lacked support for some significant features that are available in servlet 2.1 and 2.2 environments.

For information about how to configure an Apache/JServ environment for OracleJSP, see the following sections:

■ "Add OracleJSP-Related JAR and ZIP Files to Web Server Classpath" on page A-8

■ "Map JSP File Name Extensions to Oracle JspServlet" on page A-11

■ "Setting OracleJSP Parameters in Apache/JServ" on page A-27

(If you use Apache/JServ through an Oracle platform, see the installation and configuration documentation for that platform instead.)

The rest of this section, after summarizing the use of Apache/JServ by the Oracle9i Application Server, discusses the following Apache-specific considerations:

■ Dynamic Includes and Forwards in Apache/JServ

■ Application Framework for Apache/JServ

■ JSP and Servlet Session Sharing

■ Directory Alias Translation

Use of Apache/JServ in the Oracle9i Application ServerAs of Oracle9i Application Server release 1.0.x, this product uses Apache/JServ as its servlet environment. As in any Apache/JServ or other servlet 2.0 environment, there are special considerations relating to servlet and JSP usage. These are detailed in the sections that follow.



For a brief overview of the Oracle9i Application Server and its use of the Oracle HTTP Server, see "Support for OracleJSP in Oracle Environments" on page 2-4.

Dynamic Includes and Forwards in Apache/JServJSP dynamic includes (the jsp:include action) and forwards (the jsp:forward action) rely on request dispatcher functionality that is present in servlet 2.1 and 2.2 environments but not in servlet 2.0 environments.

OracleJSP, however, provides extended functionality to allow dynamic includes and forwards from one JSP page to another JSP page or to a static HTML file in Apache/JServ and other servlet 2.0 environments.

This OracleJSP functionality for servlet 2.0 environments does not, however, allow dynamic forwards or includes to servlets. (Servlet execution is controlled by the JServ or other servlet container, not the OracleJSP container.)

If you want to include or forward to a servlet in Apache/JServ, however, you can create a JSP page that acts as a wrapper for the servlet.

The following example shows a servlet, and a JSP page that acts as a wrapper for that servlet. In an Apache/JServ environment, you can effectively include or forward to the servlet by including or forwarding to the JSP wrapper page.

Servlet Code Presume that you want to include or forward to the following servlet:

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

Notes:

■ The Oracle9i Application Server includes the Oracle HTTP Server, powered by Apache, as its Web server. Be aware that if you use the Oracle HTTP Server mod_ose Apache mod to run your JSP application in the Oracle9i Servlet Engine, you are using the OSE servlet 2.2 environment, not the Oracle9i Application Server Apache/JServ servlet 2.0 environment.

■ Future releases of the Oracle HTTP Server and Oracle9i Application Server may use a servlet environment other than Apache/JServ.



public class TestServlet extends HttpServlet {

public void init(ServletConfig config) throws ServletException { super.init(config); System.out.println("initialized"); }

public void destroy() { System.out.println("destroyed"); }

public void service (HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType("text/html"); PrintWriter out = response.getWriter(); out.println("<HTML><BODY>"); out.println("TestServlet Testing"); out.println("<H3>The local time is: "+ new java.util.Date()); out.println("</BODY></HTML>"); }}

JSP Wrapper Page Code You can create the following JSP wrapper (wrapper.jsp) for the preceding servlet.

<%-- wrapper.jsp--wraps TestServlet for JSP include/forward --%><%@ page isThreadSafe="true" import="TestServlet" %><%! TestServlet s=null; public void jspInit() { s=new TestServlet(); try { s.init(this.getServletConfig()); } catch (ServletException se) { s=null; } } public void jspDestroy() { s.destroy();



}%><% s.service(request,response); %>

Including or forwarding to wrapper.jsp in a servlet 2.0 environment has the same effect as directly including or forwarding to TestServlet in a servlet 2.1 or 2.2 environment.

Application Framework for Apache/JServThe servlet 2.0 specification does not provide the full servlet context framework for application support that is provided in later specifications.

For servlet 2.0 environments, including Apache/JServ, OracleJSP supplies its own application framework using a file, globals.jsa, that you can use as an application marker.

For more information, see "Distinct Applications and Sessions Through globals.jsa" on page 5-39.

Notes:

■ Whether to set isThreadSafe to true or false in the wrapper JSP page depends on whether the original servlet is thread-safe.

■ As an alternative to using a wrapper JSP page for this situation, you can add HTTP client code to the original JSP page (the one from which the include or forward is to occur). You can use an instance of the standard java.net.URL class to create an HTTP request from the original JSP page to the servlet. (Note that you cannot share session data or security credentials in this scenario.) Alternatively, you can use the HTTPClient class from Innovation GmbH. The Oracle JVM provides a modified version of this class that supports SSL, directly or through a proxy, when you use https:// for the URL. (See http://www.innovation.ch/java/HTTPClient for general information about this class. Click "Getting Started" for information that includes how to replace the JDK HTTP client with the HTTPClient class.) Details of these alternatives are outside the scope of this document, however, and this approach is generally not recommended.



JSP and Servlet Session SharingTo share HTTP session information between JSP pages and servlets in an Apache/JServ environment, you must configure your environment so that oracle.jsp.JspServlet (the servlet that acts as the front-end of the OracleJSP container) is in the same zone as the servlet or servlets with which you want your JSP pages to share a session. Consult your Apache documentation for more information.

To verify proper zone setup, some browsers allow you to enable a warning for cookies. In an Apache environment, the cookie name includes the zone name.

Additionally, for applications that use a globals.jsa file, the OracleJSP configuration parameter session_sharing should be set to true (the default) for JSP session data to be accessible to servlets. See these sections for related information:

■ "OracleJSP Application and Session Support for Servlet 2.0" on page 5-38

■ "OracleJSP Configuration Parameters (Non-OSE)" on page A-15

■ "OracleJSP Configuration Parameter Settings" on page A-26

Directory Alias TranslationApache supports directory aliasing by allowing you to create a "virtual directory" through an Alias command in the httpd.conf configuration file. This allows Web documents to be placed outside the default doc root directory.

Consider the following sample httpd.conf entry:

Alias /icons/ "/apache/apache139/icons/"

This command should result in icons being usable as an alias for the /apache/apache139/icons/ path. In this way, for example, the file /apache/apache139/icons/art.gif, could be accessed by the following URL:

http://host[:port]/icons/art.gif

Currently, however, this functionality does not work properly for servlets and JSP pages, because the Apache/JServ getRealPath() method returns an incorrect value when processing a file under an alias directory.

OracleJSP provides an Apache-specific configuration parameter, alias_translation, that works around this limitation when you set alias_translation=true (the default setting is false).



Be aware that setting alias_translation=true also results in the alias directory becoming the application root. Therefore, in a dynamic include or forward command where the target file name starts with "/", the expected target file location will be relative to the alias directory.

Consider the following example, which results in all JSP and HTML files under /private/foo being effectively under the application /mytest:

Alias /mytest/ "/private/foo/"

And assume there is a JSP page located as follows:

/private/foo/xxx.jsp

The following dynamic include command will work, because xxx.jsp is directly below the aliased directory, /private/foo, which is effectively the application root:

<jsp:include page="/xxx.jsp" flush="true" />

JSP pages in other applications or in the general doc root cannot forward to or include JSP pages or HTML files under the /mytest application. It is only possible to forward to or include pages or HTML files within the same application (per the servlet 2.2 specification).

Notes:

■ An implicit application is created for the Web server document root and each aliasing root.

■ For information about how to set OracleJSP configuration parameters in an Apache/JServ environment, see "Setting OracleJSP Parameters in Apache/JServ" on page A-27.


OracleJSP Exten

5
OracleJSP Extensions
This chapter discusses extended functionality offered by OracleJSP, covering the following topics:

■ Portable OracleJSP Programming Extensions

■ Oracle-Specific Programming Extensions

■ OracleJSP Application and Session Support for Servlet 2.0

Portable extensions are provided through Oracle’s JSP Markup Language (JML) custom tags, JML extended datatypes, SQL custom tags, and data-access JavaBeans. You can use these features in other JSP environments.

Non-portable extensions are those that require OracleJSP for translation and execution.

Extended application and session support for servlet 2.0 environments is supplied through Oracle globals.jsa functionality and also requires OracleJSP.

sions 5-1

Portable OracleJSP Programming Extensions

Portable OracleJSP Programming ExtensionsThe Oracle extensions documented in this section are implemented either through the Oracle JSP Markup Language (JML) sample tag library, custom JavaBeans, or the custom SQL tag library. These extensions are portable to any standard JSP environment. This includes the following:

■ JML extended datatypes

■ XML and XSL support (including JML tags)

■ data-access JavaBeans

■ SQL tags

JML Extended DatatypesTo work around shortcomings for JSP usage in the Java primitive datatypes and java.lang wrapper types (as discussed in "OracleJSP Extended Datatypes" on page 2-12), OracleJSP provides the following JavaBean classes in the oracle.jsp.jml package to act as wrappers for the most common Java datatypes:

■ JmlBoolean to represent a boolean value

■ JmlNumber to represent an int value

■ JmlFPNumber to represent a double value

■ JmlString to represent a String value

Each of these classes has a single attribute, value, and includes methods to get the value, set the value from input in various formats, test whether the value is equal to a value specified in any of several formats, and convert the value to a string.

Alternatively, instead of using the getValue() and setValue() methods, you can use the jsp:getProperty and jsp:setProperty tags, as with any other bean.

The following example creates a JmlNumber instance called count that has application scope:

<jsp:useBean id="count" class="oracle.jsp.jml.JmlNumber" scope="application" />

Important: To use any of the JML functionality, see "Overview of the JSP Markup Language (JML) Sample Tag Library" on page 7-20.



Later, assuming that the value has been set elsewhere, you can access it as follows:

<h3> The current count is <%=count.getValue() %> </h3>

The following example creates a JmlNumber instance called maxSize that has request scope, and sets it using setProperty:

<jsp:useBean id="maxSize" class="oracle.jsp.jml.Number" scope="request" > <jsp:setProperty name="maxSize" property="value" value="<%= 25 %>" /></jsp:useBean>

The remainder of this section documents the public methods of the four extended datatype classes, followed by an example.

Type JmlBooleanA JmlBoolean object represents a Java boolean value.

The getValue() and setValue() methods get or set the value property of the bean as a Java boolean value.

■ boolean getValue()

■ void setValue(boolean)

The setTypedValue() method has several signatures and can set the value property from a string (such as "true" or "false"), a java.lang.Boolean value, a Java boolean value, or a JmlBoolean value. For the string input, conversion of the string is performed according to the same rules as for the standard java.lang.Boolean.valueOf() method.

■ void setTypedValue(String)

■ void setTypedValue(Boolean)

■ void setTypedValue(boolean)

■ void setTypedValue(JmlBoolean)

The equals() method tests whether the value property is equal to the specified Java boolean value.

■ boolean equals(boolean)

The typedEquals() method has several signatures and tests whether the value property has a value equivalent to a specified string (such as "true" or "false"), java.lang.Boolean value, or JmlBoolean value.

■ boolean typedEquals(String)

OracleJSP Extensions 5-3


■ boolean typedEquals(Boolean)

■ boolean typedEquals(JmlBoolean)

The toString() method returns the value property as a java.lang.String value, either "true" or "false".

■ String toString()

Type JmlNumberA JmlNumber object represents a 32-bit number equivalent to a Java int value.

The getValue() and setValue() methods get or set the value property of the bean as a Java int value.

■ int getValue()

■ void setValue(int)

The setTypedValue() method has several signatures and can set the value property from a string, a java.lang.Integer value, a Java int value, or a JmlNumber value. For the string input, conversion of the string is performed according to the same rules as for the standard java.lang.Integer.decode() method.


■ void setTypedValue(Integer)

■ void setTypedValue(int)

■ void setTypedValue(JmlNumber)

The equals() method tests whether the value property is equal to the specified Java int value.

■ boolean equals(int)

The typedEquals() method has several signatures and tests whether the value property has a value equivalent to a specified string (such as "1234"), java.lang.Number value, or JmlNumber value.


■ boolean typedEquals(Integer)

■ boolean typedEquals(JmlNumber)



The toString() method returns the value property as an equivalent java.lang.String value (such as "1234"). This method has the same functionality as the standard java.lang.Integer.toString() method.


Type JmlFPNumberA JmlFPNumber object represents a 64-bit floating point number equivalent to a Java double value.

The getValue() and setValue() methods get or set the value property of the bean as a Java double value.

■ double getValue()

■ void setValue(double)

The setTypedValue() method has several signatures and can set the value property from a string (such as "3.57"), a java.lang.Integer value, a Java int value, a java.lang.Float value, a Java float value, a java.lang.Double value, a Java double value, or a JmlFPNumber value. For the string input, conversion of the string is according to the same rules as for the standard java.lang.Double.valueOf() method.


■ void setTypedValue(Integer)

■ void setTypedValue(int)

■ void setTypedValue(Float)

■ void setTypedValue(float)

■ void setTypedValue(Double)

■ void setTypedValue(double)

■ void setTypedValue(JmlFPNumber)

The equals() method tests whether the value property is equal to the specified Java double value.

■ boolean equals(double)

The typedEquals() method has several signatures and tests whether the value property has a value equivalent to a specified string (such as "3.57"), java.lang.Integer value, Java int value, java.lang.Float value, Java



float value, java.lang.Double value, Java double value, or JmlFPNumber value.


■ boolean typedEquals(Integer)

■ boolean typedEquals(int)

■ boolean typedEquals(Float)

■ boolean typedEquals(float)

■ boolean typedEquals(Double)

■ boolean typedEquals(JmlFPNumber)

The toString() method returns the value property as a java.lang.String value (such as "3.57"). This method has the same functionality as the standard java.lang.Double.toString() method.


Type JmlStringA JmlString object represents a java.lang.String value.

The getValue() and setValue() methods get or set the value property of the bean as a java.lang.String value. If the input in a setValue() call is null, then the value property is set to an empty (zero-length) string.

■ String getValue()

■ void setValue(String)

The toString() method is functionally equivalent to the getValue() method.


The setTypedValue() method sets the value property according to the specified JmlString value. If the JmlString value is null, then the value property is set to an empty (zero-length) string.

■ void setTypedValue(JmlString)

The isEmpty() method tests whether the value property is an empty (zero-length) string: ""

■ boolean isEmpty()



The equals() method has two signatures and tests whether the value property is equal to a specified java.lang.String value or JmlString value.

■ boolean equals(String)

■ boolean equals(JmlString)

JML Datatypes ExampleThis example illustrates use of JML datatype JavaBeans for management of simple datatypes at scope. The page declares four session objects—one for each JML type. The page presents a form that allows you to enter values for each of these types. Once new values are submitted, the form displays both the new values and the previously set values. In the process of generating this output, the page updates the session objects with the new form values.

<jsp:useBean id = "submitCount" class = "oracle.jsp.jml.JmlNumber" scope = "session" />

<jsp:useBean id = "bool" class = "oracle.jsp.jml.JmlBoolean" scope = "session" > <jsp:setProperty name = "bool" property = "value" param = "fBoolean" /></jsp:useBean>

<jsp:useBean id = "num" class = "oracle.jsp.jml.JmlNumber" scope = "session" > <jsp:setProperty name = "num" property = "value" param = "fNumber" /></jsp:useBean>

<jsp:useBean id = "fpnum" class = "oracle.jsp.jml.JmlFPNumber" scope = "session" > <jsp:setProperty name = "fpnum" property = "value" param = "fFPNumber" /></jsp:useBean>

<jsp:useBean id = "str" class = "oracle.jsp.jml.JmlString" scope = "session" > <jsp:setProperty name = "str" property = "value" param = "fString" /></jsp:useBean>

<HTML>

<HEAD> <META HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=iso-8859-1"> <META NAME="GENERATOR" Content="Visual Page 1.1 for Windows"> <TITLE>OracleJSP Extended Datatypes Sample</TITLE></HEAD>

<BODY BACKGROUND="images/bg.gif" BGCOLOR="#FFFFFF">



<% if (submitCount.getValue() > 1) { %> <h3> Last submitted values </h3> <ul> <li> bool: <%= bool.getValue() %> <li> num: <%= num.getValue() %> <li> fpnum: <%= fpnum.getValue() %> <li> string: <%= str.getValue() %> </ul><% }

if (submitCount.getValue() > 0) { %>

<jsp:setProperty name = "bool" property = "value" param = "fBoolean" /> <jsp:setProperty name = "num" property = "value" param = "fNumber" /> <jsp:setProperty name = "fpnum" property = "value" param = "fFPNumber" /> <jsp:setProperty name = "str" property = "value" param = "fString" />

<h3> New submitted values </h3> <ul> <li> bool: <jsp:getProperty name="bool" property="value" /> <li> num: <jsp:getProperty name="num" property="value" /> <li> fpnum: <jsp:getProperty name="fpnum" property="value" /> <li> string: <jsp:getProperty name="str" property="value" /> </ul><% } %>

<jsp:setProperty name = "submitCount" property = "value" value = "<%= submitCount.getValue() + 1 %>" />

<FORM ACTION="index.jsp" METHOD="POST" ENCTYPE="application/x-www-form-urlencoded"><P> <pre> boolean test: <INPUT TYPE="text" NAME="fBoolean" VALUE="<%= bool.getValue() %>" > number test: <INPUT TYPE="text" NAME="fNumber" VALUE="<%= num.getValue() %>" >fpnumber test: <INPUT TYPE="text" NAME="fFPNumber" VALUE="<%= fpnum.getValue() %>" > string test: <INPUT TYPE="text" NAME="fString" VALUE= "<%= str.getValue() %>" ></pre>

<P> <INPUT TYPE="submit">

</FORM>

</BODY>

</HTML>



OracleJSP Support for XML and XSLJSP technology can be used to produce dynamic XML pages as well as dynamic HTML pages. OracleJSP supports the use of XML and XSL technology with JSP pages in two ways:

■ The OracleJSP translator includes logic to recognize standard XML-alternative JSP syntax.

■ OracleJSP provides JML tags to apply an XSL stylesheet to the JSP output stream.

Additionally, the oracle.xml.sql.query.OracleXMLQuery class is provided with Oracle9i as part of the XML-SQL utility for XML functionality in database queries. This class requires file xsu12.jar (for JDK 1.2.x) or xsu111.jar (for JDK 1.1.x), which is also required for XML functionality in the OracleJSP data-access JavaBeans, and which is provided with Oracle9i.

For a JSP sample using OracleXMLQuery, see "XML Query—XMLQuery.jsp" on page 11-38.

For information about the OracleXMLQuery class and other XML-SQL utility features, refer to the Oracle9i Application Developer’s Guide - XML and the Oracle9i XML Reference.

XML-Alternative SyntaxJSP tags, such as <%...%> for scriptlets, <%!...%> for declarations, and <%=...%> for expressions, are not syntactically valid within an XML document. Sun Microsystems addressed this in the JavaServer Pages Specification, Version 1.1 by defining equivalent JSP tags using syntax that is XML-compatible. This is implemented through a standard DTD that you can specify within a jsp:root start tag at the beginning of an XML document.

This functionality allows you, for example, to write XML-based JSP pages in an XML authoring tool.

OracleJSP does not use this DTD directly or require you to use a jsp:root tag, but the OracleJSP translator includes logic to recognize the alternative syntax specified in the standard DTD. Table 5–1 documents this syntax.



JSP action tags, such as jsp:useBean, for the most part already use syntax that complies with XML. Changes due to quoting conventions or for request-time attribute expressions may be necessary, however.

JML Tags for XSL StylesheetsMany uses of XML and XSL for dynamic pages require an XSL transformation to occur in the server before results are returned to the client.

OracleJSP provides two synonymous JML tags to simplify this process. Use either the JML transform tag or the JML styleSheet tag (their effects are identical), as in the following example:

<jml:transform href="xslRef" >

...Tag body contains regular JSP commands and static text that produce the XML code that the stylesheet is to be applies to...

</jml:transform >

(The jml: prefix is used by convention, but you can specify any prefix in your taglib directive.)

Table 5–1 XML-Alternative Syntax

Standard JSP Syntax XML-Alternative JSP Syntax

<%@ directive ...%>

Such as:<%@ page ... %><%@ include ... %>

<jsp:directive.directive ... />

Such as:<jsp:directive.page ... /><jsp:directive.include ... />

<%! ... %> (declaration) <jsp:declaration>...declarations go here...</jsp:declaration>

<%= ... %> (expression) <jsp:expression>...expression goes here...</jsp:expression>

<% ... %> (scriptlet) <jsp:scriptlet>...code fragment goes here...</jsp:scriptlet>



Note the following regarding the href parameter:

■ It can refer to either a static XSL stylesheet or a dynamically generated one. For example, it can refer to a JSP page or servlet that generates the stylesheet.

■ It can be a fully qualified URL (http://host[:port]/path), an application-relative JSP reference (starting with "/"), or a page-relative JSP reference (not starting with "/"). See "Indirectly Requesting a JSP Page" on page 1-9 for information about application-relative and page-relative paths.

■ It can be dynamically specified. By default, the value of href is a static Java string. However, you can use standard JSP expression syntax to provide a dynamically computed value.

Typically, you would use the transform or styleSheet tag to transform an entire page. However, the tag applies only to what is in its body, between its start and end tags. Therefore, you can have distinct XSL blocks within a page, each block bounded by its own transform or styleSheet tag set, specifying its own href pointer to the appropriate stylesheet.

XSL Example using jml:transformThis section provides a sample XSL stylesheet and a sample JSP page that uses the jml:transform tag to filter its output through the stylesheet. (This is a simplistic example—the XML in the page is static. A more realistic example might use the JSP page to dynamically generate all or part of the XML before performing the transformation.)

Sample Stylesheet: hello.xsl

<?xml version="1.0"?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="page"> <html> <head> <title> <xsl:value-of select="title"/> </title>

Important: If you will use any JML tags, refer to "Overview of the JSP Markup Language (JML) Sample Tag Library" on page 7-20.



</head> <body bgcolor="#ffffff"> <xsl:apply-templates/> </body> </html> </xsl:template>

<xsl:template match="title"> <h1 align="center"> <xsl:apply-templates/> </h1> </xsl:template>

<xsl:template match="paragraph"> <p align="center"> <i> <xsl:apply-templates/> </i> </p> </xsl:template>

</xsl:stylesheet>

Sample JSP Page: hello.jsp

<%@ page session = "false" %><%@ taglib uri="/WEB-INF/jmltaglib.tld" prefix="jml" %>

<jml:transform href="style/hello.xsl" >

<page> <title>Hello</title> <content> <paragraph>This is my first XML/XSL file!</paragraph> </content></page>

</jml:transform>



This example results in the following output:

Oracle Data-Access JavaBeansOracleJSP supplies a set of custom JavaBeans for accessing an Oracle database or middle-tier database cache (either is referred to simply as "the database" in the discussion below). The following beans are included in the oracle.jsp.dbutil package:

■ ConnBean opens a simple database connection.

■ ConnCacheBean uses Oracle’s connection caching implementation for database connections. (This requires JDBC 2.0.)

■ DBBean executes a database query.

■ CursorBean provides general DML support for queries; UPDATE, INSERT, and DELETE statements; and stored procedure calls.

For examples using these beans, see "Data-Access JavaBean Samples" on page 11-23.

All four beans implement the OracleJSP JspScopeListener interface for event notification. See "OracleJSP Event Handling—JspScopeListener" on page 5-33.

This section presumes a working knowledge of Oracle JDBC. Consult the Oracle9i JDBC Developer’s Guide and Reference as necessary.



ConnBean for a Database ConnectionUse oracle.jsp.dbutil.ConnBean to establish a simple database connection (one that uses no connection pooling or caching).

ConnBean has the following properties:

■ user (user ID for database schema)

■ password (user password)

■ URL (database connection string)

■ stmtCacheSize (cache size for Oracle JDBC statement caching)

Setting stmtCacheSize enables the Oracle JDBC statement caching feature. See "JDBC Statement Caching" on page 4-10 for a brief overview of statement caching features and limitations.

■ executeBatch (batch size for Oracle JDBC update batching)

Setting executeBatch enables Oracle JDBC update batching. See "Update Batching" on page 4-11 for a brief overview of this feature.

■ preFetch (number of statements to prefetch in Oracle JDBC row prefetching)

Setting preFetch enables Oracle JDBC row prefetching. Refer to "Row Prefetching" on page 4-11 for a brief overview of this feature.

ConnBean provides the following setter and getter methods for these properties:

■ void setUser(String)

Important: To use the Oracle data-access JavaBeans, install the file ojsputil.jar and include it in your classpath. This file is provided with the OracleJSP installation. For XML-related methods and functionality, you will also need file xsu12.jar (for JDK 1.2.x) or xsu111.jar (for JDK 1.1.x), which is provided with Oracle9i.

Notes:

■ For queries only, it is simpler to use DBBean, which has its own connection mechanism.

■ To use connection caching, use ConnCacheBean instead.



■ String getUser()

■ void setPassword(String)

■ String getPassword()

■ void setURL(String)

■ String getURL()

■ void setStmtCacheSize(int)

■ int getStmtCacheSize()

■ void setExecuteBatch(int)

■ int getExecuteBatch()

■ void setPreFetch(int)

■ int getPreFetch()

Use the following methods to open and close a connection:

■ void connect()—Establish a database connection using ConnBean property settings.

■ void close()—Close the connection and any open cursors.

Use the following method to open a cursor and return a CursorBean object:

■ CursorBean getCursorBean(int, String)

or:

■ CursorBean getCursorBean(int)

Input the following:

– one of the following int constants to specify the type of JDBC statement you want: CursorBean.PLAIN_STMT (for a Statement object), CursorBean.PREP_STMT (for a PreparedStatement object), or CursorBean.CALL_STMT (for a CallableStatement object)

Note: As with any JavaBean you use in a JSP page, you can set any of the ConnBean properties with a jsp:setProperty action instead of using the setter method directly.



– a string specifying the SQL operation to execute (optional; alternatively, the SQL operation can be specified in the CursorBean method call that executes the statement)

See "CursorBean for DML and Stored Procedures" on page 5-20 for information about CursorBean functionality.

ConnCacheBean for Connection CachingUse oracle.jsp.dbutil.ConnCacheBean to use the Oracle JDBC connection caching mechanism (using JDBC 2.0 connection pooling) for your database connections. For a brief overview of connection caching, see "Database Connection Caching" on page 4-9.

ConnCacheBean has the following properties:




■ maxLimit (maximum number of connections allowed by this cache)

■ minLimit (minimum number of connections existing for this cache)

If you are using fewer than this number, then there will also be connections in the "idle pool" of the cache.

■ stmtCacheSize (cache size for Oracle JDBC statement caching)

Setting stmtCacheSize enables the Oracle JDBC statement caching feature. See "JDBC Statement Caching" on page 4-10 for a brief overview of Oracle JDBC statement caching features and limitations.

Notes:

■ To use simple connection objects (no pooling or caching), use ConnBean instead.

■ ConnCacheBean extends OracleConnectionCacheImpl, which extends OracleDataSource (both in Oracle JDBC package oracle.jdbc.pool).



■ cacheScheme (type of cache, indicated by one of the following int constants):

– DYNAMIC_SCHEME—New pooled connections can be created above and beyond the maximum limit, but each one is automatically closed and freed as soon as the logical connection instance that it provided is no longer in use.

– FIXED_WAIT_SCHEME—When the maximum limit is reached, any new connection waits for an existing connection object to be released.

– FIXED_RETURN_NULL_SCHEME—When the maximum limit is reached, any new connection fails (null is returned) until connection objects have been released.

The ConnCacheBean class supports methods defined in the Oracle JDBC OracleConnectionCacheImpl class, including the following getter and setter methods for its properties:






■ String getURL()

■ void setMaxLimit(int)

■ int getMaxLimit()

■ void setMinLimit(int)

■ int getMinLimit()

■ void setStmtCacheSize(int)

■ int getStmtCacheSize()

■ void setCacheScheme(int)

Specify ConnCacheBean.DYNAMIC_SCHEME, ConnCacheBean.FIXED_WAIT_SCHEME, or ConnCacheBean.FIXED_RETURN_NULL_SCHEME.



■ int getCacheScheme()

Returns ConnCacheBean.DYNAMIC_SCHEME, ConnCacheBean.FIXED_WAIT_SCHEME, or ConnCacheBean.FIXED_RETURN_NULL_SCHEME.

The ConnCacheBean class also inherits properties and related getter and setter methods from the oracle.jdbc.pool.OracleDataSource class. This provides getter and setter methods for the following properties: databaseName, dataSourceName, description, networkProtocol, portNumber, serverName, and driverType. For information about these properties and their getter and setter methods, see the Oracle9i JDBC Developer’s Guide and Reference.


■ Connection getConnection()—Get a connection from the connection cache using ConnCacheBean property settings.

■ void close()—Close all connections and any open cursors.

Although the ConnCacheBean class does not support Oracle JDBC update batching and row prefetching directly, you can enable these features by calling the setDefaultExecuteBatch(int) and setDefaultRowPrefetch(int) methods of the Connection object that you retrieve from the getConnection() method. Alternatively, you can use the setExecuteBatch(int) and setRowPrefetch(int) methods of JDBC statement objects that you create from the Connection object (update batching is supported only in prepared statements). See "Update Batching" on page 4-11 and "Row Prefetching" on page 4-11 for brief overviews of these features.

Note: As with any JavaBean you use in a JSP page, you can set any of the ConnCacheBean properties with a jsp:setProperty action instead of using the setter method directly.



DBBean for Queries OnlyUse oracle.jsp.dbutil.DBBean to execute queries only.

DBBean has the following properties:




DBBean provides the following setter and getter methods for these properties:






■ String getURL()

Notes:

■ ConnCacheBean has the same functionality as OracleConnectionCacheImpl. See the Oracle9i JDBC Developer’s Guide and Reference for more information.

■ Unlike ConnBean, when you use ConnCacheBean, you use normal Connection object functionality to create and execute statement objects.

Notes:

■ DBBean has its own connection mechanism; do not use ConnBean.

■ Use CursorBean for any other DML operations (UPDATE, INSERT, DELETE, or stored procedure calls).




■ void connect()—Establish a database connection using DBBean property settings.

■ void close()—Close the connection and any open cursors.

Use either of the following methods to execute a query:

■ String getResultAsHTMLTable(String)—Input a string that contains the SELECT statement.

This method returns a string with the HTML commands necessary to output the result set as an HTML table. SQL column names (or aliases) are used for the table column headers.

■ String getResultAsXMLString(String)—Input a string with the SELECT statement.

This method returns the result set as an XML string, using SQL names (or aliases) for the XML tags.

CursorBean for DML and Stored ProceduresUse oracle.jsp.dbutil.CursorBean for SELECT, UPDATE, INSERT, or DELETE operations or stored procedure calls on a simple connection. It uses a previously defined ConnBean object for the connection.

You can specify a SQL operation in a ConnBean object getCursorBean() call, or through a call to one of the create(), execute(), or executeQuery() methods of a CursorBean object as described below.

CursorBean supports scrollable and updatable cursors, update batching, row prefetching, and query timeout limits. For information about these Oracle JDBC features, see the Oracle9i JDBC Developer’s Guide and Reference.

Note: As with any JavaBean you use in a JSP page, you can set any of the DBBean properties with a jsp:setProperty statement instead of using the setter method directly.



CursorBean has the following properties:

■ executeBatch (batch size for Oracle JDBC update batching)

Setting this property enables Oracle JDBC update batching.

■ preFetch (number of statements to prefetch in Oracle JDBC row prefetching)

Setting this property enables Oracle JDBC row prefetching.

■ queryTimeout (number of seconds for the driver to wait for a statement to execute before issuing a timeout)

■ resultSetType (scrollability of the result set, as indicated by one of the following int constants):

– TYPE_FORWARD_ONLY (default)—A result set that can scroll only forward (using the next() method) and is not positionable.

– TYPE_SCROLL_INSENSITIVE—A result set that can scroll forward or backward and is positionable, but is not sensitive to underlying data changes.

– TYPE_SCROLL_SENSITIVE—A result set that can scroll forward or backward, is positionable, and is sensitive to underlying data changes.

See the Oracle9i JDBC Developer’s Guide and Reference for information about result set scrollability types.

■ resultSetConcurrency (updatability of the result set, as indicated by one of the following int constants):

– CONCUR_READ_ONLY (default)—A result set that is read-only (cannot be updated).

– CONCUR_UPDATABLE—A result set that is updatable.

See the Oracle9i JDBC Developer’s Guide and Reference for information about updatable result sets.

You can set these properties with the following methods to enable Oracle JDBC features, as desired:

■ void setExecuteBatch(int)

Note: To use connection caching, use ConnCacheBean and normal Connection object functionality. Do not use CursorBean.



■ int getExecuteBatch()

■ void setPreFetch(int)

■ int getPreFetch()

■ void setQueryTimeout(int)

■ int getQueryTimeout()

■ void setResultSetConcurrency(int)

Specify CursorBean.CONCUR_READ_ONLY or CursorBean.CONCUR_UPDATABLE.

■ int getResultSetConcurrency()

Returns CursorBean.CONCUR_READ_ONLY or CursorBean.CONCUR_UPDATABLE.

■ void setResultSetType(int)

Specify CursorBean.TYPE_FORWARD_ONLY, CursorBean.TYPE_SCROLL_INSENSITIVE, or CursorBean.TYPE_SCROLL_SENSITIVE.

■ int getResultSetType()

Returns CursorBean.TYPE_FORWARD_ONLY, CursorBean.TYPE_SCROLL_INSENSITIVE, or CursorBean.TYPE_SCROLL_SENSITIVE.

To execute a query once a CursorBean instance has been defined in a jsp:useBean statement, you can use CursorBean methods to create a cursor in one of two ways. You can use the following methods to create the cursor and supply a connection in separate steps:

■ void create()

■ void setConnBean(ConnBean)

Or you can combine the process into a single step:

■ void create(ConnBean)

Note: As with any JavaBean you use in a JSP page, you can set any of the CursorBean properties with a jsp:setProperty action instead of using the setter method directly.



(Set up the ConnBean object as described in "ConnBean for a Database Connection" on page 5-14.)

Then use the following method to specify and execute a query. (This uses a JDBC plain Statement object behind the scenes.)

■ ResultSet executeQuery(String)

Input a string that contains the SELECT statement.

Alternatively, if you want to format the result set as an HTML table or XML string, use either of the following methods instead of executeQuery():

■ String getResultAsHTMLTable(String)

Returns a string with HTML statements to create an HTML table for the result set. Specify a string with the SELECT statement.

■ String getResultAsXMLString(String)

Returns the result set data in an XML string. Specify a string with the SELECT statement.

To execute an UPDATE, INSERT, or DELETE statement once a CursorBean instance has been defined in a jsp:useBean action, you can use CursorBean methods to create a cursor in one of two ways. You can use the following methods to create the cursor (specifying a statement type as an integer and SQL statement as a string) and supply a connection:

■ void create(int, String)

■ void setConnBean(ConnBean)

Or you can combine the process into a single step:

■ void create(ConnBean, int, String)

(Set up the ConnBean object as described in "ConnBean for a Database Connection" on page 5-14.)

The int input takes one of the following constants to specify the type of JDBC statement you want: CursorBean.PLAIN_STMT (for a Statement object), CursorBean.PREP_STMT (for a PreparedStatement object), or CursorBean.CALL_STMT (for a CallableStatement object).

The String input is to specify the SQL statement.



Then use the following method to execute the INSERT, UPDATE, or DELETE statement. (You can ignore the boolean return value.)

■ boolean execute()

Or for update batching, use the following method, which returns the number of rows affected. (See below for how to enable update batching.)

■ int executeUpdate()

Additionally, CursorBean supports Oracle JDBC functionality such as registerOutParameter() for callable statements, setXXX() methods for prepared statements and callable statements, and getXXX() methods for result sets and callable statements.

Use the following method to close the database cursor:

■ void close()

OracleJSP Tag Library for SQLOracleJSP supplies a custom tag library for SQL functionality (separate from the JML custom tag library).

The following tags are provided:

■ dbOpen—Open a database connection.

■ dbClose—Close a database connection.

■ dbQuery—Execute a query.

■ dbCloseQuery—Close the cursor for a query.

■ dbNextRow—Process the rows of a result set.

■ dbExecute—Execute any SQL statement (DML or DDL).

These tags are described in the following subsections. For examples, see "SQL Tag Examples" on page 5-29.

Note: The execute() and executeUpdate() methods can optionally take a String to specify a SQL operation. The corresponding create() call, as well as the getCursorBean() call in ConnBean, optionally does not take a String to specify the SQL operation. Specify an operation either on statement creation or execution, but not both.



Note the following requirements for using SQL tags:

■ Install the file ojsputil.jar and include it in your classpath. This file is provided with the OracleJSP installation.

■ Make sure the tag library description file, sqltaglib.tld, is deployed with the application and is in the location specified in the taglib directives of your JSP pages, such as in the following example:

<%@ taglib uri="/WEB-INF/sqltaglib.tld" prefix="sql" %>

For general information about JSP 1.1 tag library usage, including tag library description files and taglib directives, see "Standard Tag Library Framework" on page 7-2.

SQL dbOpen TagUse the dbOpen tag to open a database connection.

<sql:dbOpen [ connId="connection-id" ] user="username" password="password" URL="databaseURL" >

...

</sql:dbOpen>

Nested code that you want to execute through this connection can go into the tag body, between the dbOpen start and end tags. (See "SQL Tag Examples" on page 5-29.) If you use the optional connId parameter to set a connection identifier, then code to execute through this connection can reference the connection identifier and does not have to be between the dbOpen start and end tags. (The connection identifier can be any arbitrary string.)

Note that you do not have to hardcode a password into the JSP page (which would be a security concern). Instead, you can get it and other parameters from the request object, as follows:

<sql:dbOpen connId="conn1" user=<%=request.getParameter("user")%> password=<%=request.getParameter("password")%> URL="url" />



(In this example you do not need a tag body for code that will use this connection; statements using the connection can reference it through the conn1 value of connId.)

If you set a connection identifier, then the connection is not closed until you close it explicitly with a dbClose tag. Without a connection identifier, the connection is closed automatically when the </sql:dbOpen> end tag is encountered.

This tag uses a ConnBean object for the connection. You can optionally set the additional ConnBean properties stmtCacheSize, preFetch, and batchSize to enable those Oracle JDBC features. See "ConnBean for a Database Connection" on page 5-14 for more information.

SQL dbClose TagUse the dbClose tag to close a connection associated with the optional connId parameter specified in a dbOpen tag. If connId is not used in the dbOpen tag, then the connection is closed automatically when the dbOpen end tag is reached; no dbClose tag is required.

<sql:dbClose connId="connection-id" />

SQL dbQuery TagUse the dbQuery tag to execute a query, outputting the result either as a JDBC result set, HTML table, or XML string. Place the SELECT statement (one only) in the tag body, between the dbQuery start and end tags.

<sql:dbQuery [ queryId="query-id" ] [ connId="connection-id" ] [ output="HTML|XML|JDBC"] > ...SELECT statement (one only)... </sql:dbQuery>

Note: In an OracleJSP environment, you can have the connection closed automatically with session-based event handling through the Oracle JspScopeListener mechanism. See "OracleJSP Event Handling—JspScopeListener" on page 5-33.



All parameters of this tag are optional, depending on your intended uses as described below.

You must use the queryId parameter to set a query identifier if you want to process the result set using a dbNextRow tag. The queryId can be any arbitrary string.

Additionally, if the queryId parameter is present, then the cursor is not closed until you close it explicitly with a dbCloseQuery tag. Without a query identifier, the cursor is closed automatically when the </sql:dbQuery> end tag is encountered.

If connId is not specified, then dbQuery must be nested within the body of a dbOpen tag and will use the connection opened in the dbOpen tag.

For the output type:

■ HTML puts the result set into an HTML table (default).

■ XML puts the result set into an XML string.

■ JDBC puts the result set into a JDBC ResultSet object that can be processed using the dbNextRow tag to iterate through the rows.

This tag uses a CursorBean object for the cursor. See "CursorBean for DML and Stored Procedures" on page 5-20 for information about CursorBean functionality.

SQL dbCloseQuery TagUse the dbCloseQuery tag to close a cursor associated with the optional queryId parameter specified in a dbQuery tag. If queryId is not used in the dbQuery tag, then the cursor is closed automatically when the dbQuery end tag is reached; no dbCloseQuery tag is required.

<sql:dbCloseQuery queryId="query-id" />

Important: In OracleJSP release 1.1.3.x, do not terminate the SELECT statement with a semi-colon. This would result in a syntax error.



SQL dbNextRow TagUse the dbNextRow tag to process each row of a result set obtained in a dbQuery tag and associated with the specified queryId. Place the processing code in the tag body, between the dbNextRow start and end tags. The body is executed for each row of the result set.

For you to use the dbNextRow tag, the dbQuery tag must specify output=JDBC, and specify a queryId for the dbNextRow tag to reference.

<sql:dbNextRow queryId="query-id" >

...Row processing...

</sql:dbNextRow >

The result set object is created in an instance of the tag-extra-info class of the dbQuery tag (see "Tag Library Description Files" on page 7-11 for information about tag-extra-info classes).

SQL dbExecute TagUse the dbExecute tag to execute any DML or DDL statement (one only). Place the statement in the tag body, between the dbExecute start and end tags.

<sql:dbExecute [connId="connection-id"] [output="yes|no"] > ...DML or DDL statement (one only)...</sql:dbExecute >

If you do not specify connId, then you must nest dbExecute within the body of a dbOpen tag and use the connection opened in the dbOpen tag.

Note: In an OracleJSP environment, you can have the cursor closed automatically with session-based event handling through the Oracle JspScopeListener mechanism. See "OracleJSP Event Handling—JspScopeListener" on page 5-33.

Important: In OracleJSP release 1.1.3.x, do not terminate the DML or DDL statement with a semi-colon. This would result in a syntax error.



If output=yes, then for DML statements the HTML string "number row[s] affected" will be output to the browser to notify the user how many database rows were affected by the operation; for DDL statements, the statement execution status will be printed. The default setting is no.

This tag uses a CursorBean object for the cursor. See "CursorBean for DML and Stored Procedures" on page 5-20 for information about CursorBean functionality.

SQL Tag ExamplesThe following examples show how to use the OracleJSP SQL tags. (To run them yourself, you will need to set the URL, user name, and password appropriately.)

Example 1: Query with Connection ID

<%@ taglib uri="/WEB-INF/sqltaglib.tld" prefix="sql" %> <HTML> <HEAD> <TITLE>A simple example with open, query, and close tags</TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> <HR> <sql:dbOpen URL="jdbc:oracle:thin:@dlsun991:1521:816" user="scott" password="tiger" connId="con1"> </sql:dbOpen> <sql:dbQuery connId="con1"> select * from EMP </sql:dbQuery> <sql:dbClose connId="con1" /> <HR> </BODY> </HTML>

Example 2: Query Nested in dbOpen Tag

<%@ taglib uri="/WEB-INF/sqltaglib.tld" prefix="sql" %> <HTML> <HEAD> <TITLE>Nested Tag with Query inside Open </TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> <HR> <sql:dbOpen URL="jdbc:oracle:thin:@dlsun991:1521:816" user="scott" password="tiger">



<sql:dbQuery> select * from EMP </sql:dbQuery> </sql:dbOpen> <HR> </BODY> </HTML>

Example 3: Query with XML Output

<%@ page import="oracle.sql.*, oracle.jdbc.driver.*, oracle.jdbc.*, java.sql.*" %><%@ taglib uri="/WEB-INF/jml.tld" prefix="jml" %><%@ taglib uri="/WEB-INF/sqltaglib.tld" prefix="sql" %>

<% String connStr=request.getParameter("connStr"); if (connStr==null) { connStr=(String)session.getValue("connStr"); } else { session.putValue("connStr",connStr); } if (connStr==null) { %><jsp:forward page="../setconn.jsp" /><% }

%><jml:transform href="style/rowset.xsl" > <sql:dbOpen connId="conn1" URL="<%= connStr %>" user="scott" password="tiger"> </sql:dbOpen> <sql:dbQuery connId="conn1" output="xml" queryId="myquery"> select ENAME, EMPNO from EMP </sql:dbQuery> <sql:dbCloseQuery queryId="myquery" /> <sql:dbClose connId="con1" /></jml:transform>



Example 4: Result Set Iteration

<%@ taglib uri="/WEB-INF/sqltaglib.tld" prefix="sql" %> <HTML> <HEAD> <TITLE>Result Set Iteration Sample </TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> <HR> <sql:dbOpen connId="con1" URL="jdbc:oracle:thin:@dlsun991:1521:816" user="scott" password="tiger"> </sql:dbOpen> <sql:dbQuery connId="con1" output="jdbc" queryId="myquery"> select * from EMP </sql:dbQuery> <sql:dbNextRow queryId="myquery"> <%= myquery.getString(1) %> </sql:dbNextRow> <sql:dbCloseQuery queryId="myquery" /> <sql:dbClose connId="con1" /> <HR> </BODY> </HTML>

Example 5: DDL and DML Statements This example uses an HTML form to let the user specify what kind of DML or DDL statement to execute.

<%@ taglib uri="/WEB-INF/sqltaglib.tld" prefix="sql" %><HTML> <HEAD><TITLE>DML Sample</TITLE></HEAD><FORM METHOD=get><INPUT TYPE="submit" name="drop" VALUE="drop table test_table"><br><INPUT TYPE="submit" name="create" VALUE="create table test_table (col1 NUMBER)"><br><INPUT TYPE="submit" name="insert" VALUE="insert into test_table values (1234)"><br><INPUT TYPE="submit" name="select" VALUE="select * from test_table"><br></FORM><BODY BGCOLOR="#FFFFFF"> Result: <HR> <sql:dbOpen URL="jdbc:oracle:thin:@dlsun991:1521:816" user="scott" password="tiger"> <% if (request.getParameter("drop")!=null) { %>



<sql:dbExecute output="yes"> drop table test_table </sql:dbExecute> <% } %> <% if (request.getParameter("create")!=null) { %> <sql:dbExecute output="yes"> create table test_table (col1 NUMBER) </sql:dbExecute> <% } %> <% if (request.getParameter("insert")!=null) { %> <sql:dbExecute output="yes"> insert into test_table values (1234) </sql:dbExecute> <% } %> <% if (request.getParameter("select")!=null) { %> <sql:dbQuery> select * from test_table </sql:dbQuery> <% } %> </sql:dbOpen> <HR> </BODY> </HTML>


Oracle-Specific Programming Extensions

Oracle-Specific Programming ExtensionsThe 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

OracleJSP Event Handling—JspScopeListenerIn 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.

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" on page 5-38 describes this mechanism.

■ OracleJSP also provides extended (and non-portable) globalization support, which is described in "OracleJSP Extended Support for Multibyte Parameter Encoding" on page 10-5.



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" on page 11-34.

OracleJSP Support for Oracle SQLJSQLJ 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 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 ExampleFollowing 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 for the schema used in the example results in the following output:

For further examples of using SQLJ in JSP pages, see "SQLJ Queries—SQLJSelectInto.sqljsp and SQLJIterator.sqljsp" on page 11-39.

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.



Triggering the SQLJ TranslatorYou 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)" on page 6-7.

Setting Oracle SQLJ OptionsWhen 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 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 was not available prior to OracleJSP release 1.1.0.0.0.)

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

■ 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" on page 6-30 and "Option Descriptions for ojspc" on page 6-30.

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" on page A-3.

■ 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.


OracleJSP Application and Session Support for Servlet 2.0

OracleJSP Application and Session Support for Servlet 2.0OracleJSP defines a file, globals.jsa, as a mechanism for implementing the JSP specification in a servlet 2.0 environment. Web applications and servlet contexts were not fully defined in the servlet 2.0 specification.

This section discusses the globals.jsa mechanism and covers the following topics:

■ Overview of globals.jsa Functionality

■ Overview of globals.jsa Syntax and Semantics

■ The globals.jsa Event Handlers

■ Global Declarations and Directives

For sample applications, see "Samples Using globals.jsa for Servlet 2.0 Environments" on page 11-81.

Overview of globals.jsa FunctionalityWithin any single Java virtual machine, you can use a globals.jsa file for each application (or, equivalently, for each servlet context). This file supports the concept of Web applications in the following areas:

■ application deployment—through its role as an application location marker to define an application root

■ distinct applications and sessions—through its use by OracleJSP in providing distinct servlet context and session objects for each application

■ application lifecycle management—through start and end events for sessions and applications

The globals.jsa file also provides a vehicle for global Java declarations and JSP directives across all JSP pages of an application.

Important: Use all lowercase for the globals.jsa file name. Mixed case works in a non-case-sensitive environment, but makes it difficult to diagnose resulting problems if you port the pages to a case-sensitive environment.



Application Deployment through globals.jsaTo deploy an OracleJSP application that does not incorporate servlets, copy the directory structure into the Web server and create a file called globals.jsa to place at the application root directory.

The globals.jsa file can be of zero size. The OracleJSP container will locate it, and its presence in a directory defines that directory (as mapped from the URL virtual path) as the root directory of the application.

OracleJSP also defines default locations for JSP application resources. For example, application beans and classes in the application-relative /WEB-INF/classes and /WEB-INF/lib directories will automatically be loaded by the OracleJSP classloader without the need for specific configuration.

Distinct Applications and Sessions Through globals.jsaThe servlet 2.0 specification does not have a clearly defined concept of a Web application and there is no defined relationship between servlet contexts and applications, as there is in later servlet specifications. In a servlet 2.0 environment such as Apache/JServ, there is only one servlet context object per JVM. A servlet 2.0 environment also has only one session object.

The globals.jsa file, however, provides support for multiple applications and multiple sessions in a Web server, particularly for use in a servlet 2.0 environment.

Where a distinct servlet context object would not otherwise be available for each application, the presence of a globals.jsa file for an application allows the OracleJSP container to provide the application with a distinct ServletContext object.

Additionally, where there would otherwise be only one session object (with either one servlet context or across multiple servlet contexts), the presence of a globals.jsa file allows the OracleJSP container to provide a proxy HttpSession object to the application. This prevents the possibility of session variable-name collisions with other applications, although unfortunately it cannot protect application data from being inspected or modified by other applications.

Notes: For an application that does incorporate servlets, especially in a servlet environment preceding the servlet 2.2 specification, manual configuration is required as with any servlet deployment. For servlets in a servlet 2.2 environment, you can include the necessary configuration in the standard web.xml deployment descriptor.



This is because HttpSession objects must rely on the underlying servlet session environment for some of their functionality.

Application and Session Lifecycle Management Through globals.jsaAn application must be notified when a significant state transition occurs. For example, applications often want to acquire resources when an HTTP session begins and release resources when the session ends, or restore or save persistent data when the application itself is started or terminated.

In standard servlet and JSP technology, however, only session-based events are supported.

For applications that use a globals.jsa file, OracleJSP extends this functionality with the following four events:

■ session_OnStart

■ session_OnEnd

■ application_OnStart

■ application_OnEnd

You can write event handlers in the globals.jsa file for any of these events that the server should respond to.

The session_OnStart event and session_OnEnd event are triggered at the beginning and end of an HTTP session, respectively.

The application_OnStart event is triggered for any application by the first request for that application within any single JVM. The application_OnEnd event is triggered when the OracleJSP container unloads an application.

For more information, see "The globals.jsa Event Handlers" on page 5-43.

Overview of globals.jsa Syntax and SemanticsThis section is an overview of general syntax and semantics for a globals.jsa file.

Each event block in a globals.jsa file—a session_OnStart block, a session_OnEnd block, an application_OnStart block, or an application_OnEnd block—has an event start tag, an event end tag, and a body (everything between the start and end tags) that includes the event-handler code.



The following example shows this pattern:

<event:session_OnStart> <% This scriptlet contains the implementation of the event handler %></event:session_OnStart>

The body of an event block can contain any valid JSP tags—standard tags as well as tags defined in a custom tag library.

The scope of any JSP tag in an event block, however, is limited to only that block. For example, a bean that is declared in a jsp:useBean tag within one event block must be redeclared in any other event block that uses it. You can avoid this restriction, however, through the globals.jsa global declaration mechanism—see "Global Declarations and Directives" on page 5-47.

For details about each of the four event handlers, see "The globals.jsa Event Handlers" on page 5-43.

JSP implicit objects are available in globals.jsa event blocks as follows:

■ The application_OnStart block has access to the application object.

■ The application_OnEnd block has access to the application object.

■ The session_OnStart block has access to the application, session, request, response, page, and out objects.

■ The session_OnEnd block has access to the application and session objects.

Example of a Complete globals.jsa File This example shows you a complete globals.jsa file, using all four event handlers.

<event:application_OnStart>

<%-- Initializes counts to zero --%> <jsp:useBean id="pageCount" class="oracle.jsp.jml.JmlNumber" scope = "application" /> <jsp:useBean id="sessionCount" class="oracle.jsp.jml.JmlNumber" scope = "application" /> <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" />

Important: Static text as used in a regular JSP page can reside in a session_OnStart block only. Event blocks for session_OnEnd, application_OnStart, and application_OnEnd can contain only Java scriptlets.



</event:application_OnStart>

<event:application_OnEnd>

<%-- Acquire beans --%> <jsp:useBean id="pageCount" class="oracle.jsp.jml.JmlNumber" scope = "application" /> <jsp:useBean id="sessionCount" class="oracle.jsp.jml.JmlNumber" scope = "application" /> <% application.log("The number of page hits were: " + pageCount.getValue() ); %> <% application.log("The number of client sessions were: " + sessionCount.getValue() ); %>

</event:application_OnEnd>

<event:session_OnStart>

<%-- Acquire beans --%> <jsp:useBean id="sessionCount" class="oracle.jsp.jml.JmlNumber" scope = "application" /> <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" /> <% sessionCount.setValue(sessionCount.getValue() + 1); activeSessions.setValue(activeSessions.getValue() + 1); %> <br> Starting session #: <%=sessionCount.getValue() %> <br> There are currently <b> <%= activeSessions.getValue() %> </b> active sessions <p>

</event:session_OnStart>

<event:session_OnEnd>

<%-- Acquire beans --%> <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" /> <% activeSessions.setValue(activeSessions.getValue() - 1); %>

</event:session_OnEnd>



The globals.jsa Event HandlersThis section provides details about each of the four globals.jsa event handlers.

application_OnStartThe application_OnStart block has the following general syntax:

<event:application_OnStart> <% This scriptlet contains the implementation of the event handler %></event:application_OnStart>

The body of the application_OnStart event handler is executed when OracleJSP loads the first JSP page in the application. This usually occurs when the first HTTP request is made to any page in the application, from any client. Applications use this event to initialize application-wide resources, such as a database connection pool or data read from a persistent repository into application objects.

The event handler must contain only JSP tags (including custom tags) and white space—it cannot contain static text.

Errors that occur in this event handler but are not processed in the event-handler code are automatically trapped by the OracleJSP container and logged using the servlet context of the application. Event handling then proceeds as if no error had occurred.

Example: application_OnStart The following application_OnStart example is from the "globals.jsa Example for Application Events—lotto.jsp" on page 11-81. In this example, the generated lottery numbers for a particular user are cached for an entire day. If the user re-requests the picks, he or she gets the same set of numbers. The cache is recycled once a day, giving each user a new set of picks. To function as intended, the lotto application must make the cache persistent when the application is being shut down, and must refresh the cache when the application is reactivated.

The application_OnStart event handler reads the cache from the lotto.che file.


<% Calendar today = Calendar.getInstance(); application.setAttribute("today", today); try {



FileInputStream fis = new FileInputStream (application.getRealPath("/")+File.separator+"lotto.che"); ObjectInputStream ois = new ObjectInputStream(fis); Calendar cacheDay = (Calendar) ois.readObject(); if (cacheDay.get(Calendar.DAY_OF_YEAR) == today.get(Calendar.DAY_OF_YEAR)) { cachedNumbers = (Hashtable) ois.readObject(); application.setAttribute("cachedNumbers", cachedNumbers); } ois.close(); } catch (Exception theE) { // catch all -- can’t use persistent data }%>


application_OnEndThe application_OnEnd block has the following general syntax:

<event:application_OnEnd> <% This scriptlet contains the implementation of the event handler %></event:application_OnEnd>

The body of the application_OnEnd event handler is executed when OracleJSP unloads the JSP application. Unloading occurs whenever a previously loaded page is reloaded after on-demand dynamic re-translation (unless the OracleJSP unsafe_reload configuration parameter is enabled), or when the OracleJSP container, which itself is a servlet, is terminated by having its destroy() method called by the underlying servlet container. Applications use the application_OnEnd event to clean up application level resources or to write application state to a persistent store.

The event handler must contain only JSP tags (including custom tags) and white space—it cannot contain static text.




Example: application_OnEnd The following application_OnEnd example is from the "globals.jsa Example for Application Events—lotto.jsp" on page 11-81. In this event handler, the cache is written to file lotto.che before the application is terminated.


<% Calendar now = Calendar.getInstance(); Calendar today = (Calendar) application.getAttribute("today"); if (cachedNumbers.isEmpty() || now.get(Calendar.DAY_OF_YEAR) > today.get(Calendar.DAY_OF_YEAR)) { File f = new File(application.getRealPath("/")+File.separator+"lotto.che"); if (f.exists()) f.delete(); return; }

try { FileOutputStream fos = new FileOutputStream (application.getRealPath("/")+File.separator+"lotto.che"); ObjectOutputStream oos = new ObjectOutputStream(fos); oos.writeObject(today); oos.writeObject(cachedNumbers); oos.close(); } catch (Exception theE) { // catch all -- can’t use persistent data }%>


session_OnStartThe session_OnStart block has the following general syntax:

<event:session_OnStart> <% This scriptlet contains the implementation of the event handler %> Optional static text...</event:session_OnStart>

The body of the session_OnStart event handler is executed when OracleJSP creates a new session in response to a JSP page request. This occurs on a per client basis, whenever the first request is received for a session-enabled JSP page in an application.



Applications might use this event for the following purposes:

■ to initialize resources tied to a particular client

■ to control where a client starts in an application

Because the implicit out object is available to session_OnStart, this is the only globals.jsa event handler that can contain static text in addition to JSP tags.

The session_OnStart event handler is called before the code of the JSP page is executed. As a result, output from session_OnStart precedes any output from the page.

The session_OnStart event handler and the JSP page that triggered the event share the same out stream. The buffer size of this stream is controlled by the buffer size of the JSP page. The session_OnStart event handler does not automatically flush the stream to the browser—the stream is flushed according to general JSP rules. Headers can still be written in JSP pages that trigger the session_OnStart event.


Example: session_OnStart The following example makes sure that each new session starts on the initial page (index.jsp) of the application.


<% if (!page.equals("index.jsp")) { %> <jsp:forward page="index.jsp" /> <% } %>


session_OnEndThe session_OnEnd block has the following general syntax:

<event:session_OnEnd> <% This scriptlet contains the implementation of the event handler %></event:session_OnEnd>



The body of the session_OnEnd event handler is executed when OracleJSP invalidates an existing session. This occurs in either of the following circumstances:

■ The application invalidates the session by calling the session.invalidate() method.

■ The session expires ("times out") on the server.

Applications use this event to release client resources.

The event handler must contain only JSP tags (including tag library tags) and white space—it cannot contain static text.


Example: session_OnEnd The following example decrements the "active session" count when a session is terminated.


<%-- Acquire beans --%> <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" /> <% activeSessions.setValue(activeSessions.getValue() - 1); %>


Global Declarations and DirectivesIn addition to holding event handlers, a globals.jsa file can be used to globally declare directives and objects for the JSP application. You can include JSP directives, JSP declarations, JSP comments, and JSP tags that have a scope parameter (such as jsp:useBean).

This section covers the following topics:

■ Global JSP Directives

■ globals.jsa Declarations



■ Global JavaBeans

■ globals.jsa Structure

■ Global Declarations and Directives Example

Global JSP DirectivesDirectives used within a globals.jsa file serve a dual purpose:

■ They declare the information that is required to process the globals.jsa file itself.

■ They establish default values for succeeding pages.

A directive in a globals.jsa file becomes an implicit directive for all JSP pages in the application, although a globals.jsa directive can be overwritten for any particular page.

A globals.jsa directive is overwritten in a JSP page on an attribute-by-attribute basis. If a globals.jsa file has the following directive:

<%@ page import="java.util.*" bufferSize="10kb" %>

and a JSP page has the following directive:

<%@page bufferSize="20kb" %>

then this would be equivalent to the page having the following directive:

<%@ page import="java.util.*" bufferSize="20kb" %>

globals.jsa DeclarationsIf you want to declare a method or data member to be shared across any of the event handlers in a globals.jsa file, use a JSP <%!... %> declaration within the globals.jsa file.

Note that JSP pages in the application do not have access to these declarations, so you cannot use this mechanism to implement an application library. Declaration support is provided in the globals.jsa file for common functions to be shared across event handlers.

Global JavaBeansProbably the most common elements declared in globals.jsa files are global objects. Objects declared in a globals.jsa file become part of the implicit object



environment of the globals.jsa event handlers and all the JSP pages in the application.

An object declared in a globals.jsa file (such as by a jsp:useBean statement) does not need to be redeclared in any of the individual JSP pages of the application.

You can declare a global object using any JSP tag or extension that has a scope parameter, such as jsp:useBean or jml:useVariable. Globally declared objects must be of either session or application scope (not page or request scope).

Nested tags are supported. Thus, a jsp:setProperty command can be nested in a jsp:useBean declaration. (A translation error occurs if jsp:setProperty is used outside a jsp:useBean declaration.)

globals.jsa StructureWhen a global object is used in a globals.jsa event handler, the position of its declaration is important. Only those objects that are declared before a particular event handler are added as implicit objects to that event handler. For this reason, developers are advised to structure their globals.jsa file in the following sequence:

1. global directives

2. global objects

3. event handlers

4. globals.jsa declarations

Global Declarations and Directives ExampleThe sample globals.jsa file below accomplishes the following:

■ It defines the JML tag library (in this case, the compile-time implementation) for the globals.jsa file, as well as for all subsequent pages.

By including the taglib directive in the globals.jsa file, the directive does not have to be included in any of the individual JSP pages of the application.

■ It declares three application variables for use by all pages (in the jsp:useBean statements).

For an additional example of using globals.jsa for global declarations, see "globals.jsa Example for Global Declarations—index2.jsp" on page 11-87.



<%-- Directives at the top --%>


<%-- Declare global objects here --%>


<%-- Application lifecycle event handlers go here --%>

<event:application_OnStart> <% This scriptlet contains the implementation of the event handler %> </event:application_OnStart>

<event:application_OnEnd> <% This scriptlet contains the implementation of the event handler %> </event:application_OnEnd>

<event:session_OnStart> <% This scriptlet contains the implementation of the event handler %> </event:session_OnStart>

<event:session_OnEnd> <% This scriptlet contains the implementation of the event handler %> </event:session_OnEnd>

<%-- Declarations used by the event handlers go here --%>


JSP Translation and Deploy

6
JSP Translation and Deployment
This chapter primarily discusses considerations and procedures for deploying JSP applications to the Oracle9i database or middle-tier database cache to run in the Oracle9i Servlet Engine. It also describes general OracleJSP translation features and briefly discusses deployment in other environments, particularly the Apache/JServ environment used by the Oracle9i Application Server.

The following topics are covered:

■ Functionality of the OracleJSP Translator

■ Overview of Features and Logistics in Deployment to Oracle9i

■ Tools and Commands for Translation and Deployment to Oracle9i

■ Deployment to Oracle9i with Server-Side Translation

■ Deployment to Oracle9i with Client-Side Translation

■ Additional JSP Deployment Considerations

ment 6-1

Functionality of the OracleJSP Translator

Functionality of the OracleJSP TranslatorJSP translators generate standard Java code for a JSP page implementation class. This class is essentially a servlet class wrapped with features for JSP functionality.

This section discusses general functionality of the OracleJSP translator, focusing on its behavior in on-demand translation environments such as Apache/JServ, which is included with the Oracle9i Application Server. The following topics are covered:

■ Generated Code Features

■ Generated Package and Class Names (On-Demand Translation)

■ Generated Files and Locations (On-Demand Translation)

■ Sample Page Implementation Class Source

You must pre-translate JSP pages targeted for the Oracle9i Servlet Engine, either as a result of running the session shell publishjsp command (for deployment with server-side translation), by running the ojspc pre-translation tool directly (for deployment with client-side translation), or by using Oracle WAR deployment. In any case, there are some differences in functionality compared with the discussion in this section, such as in placement of output files. See "Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)" on page 6-46 and "The ojspc Pre-Translation Tool" on page 6-26 for information about the first two scenarios. For information about Oracle WAR deployment, see the Oracle9i Servlet Engine Developer’s Guide.

Important: Implementation details in this section regarding package and class naming, file and directory naming, output file locations, and generated code are for illustrative purposes. The precise details apply to OracleJSP 1.1.x releases only and are subject to change from release to release.



Generated Code FeaturesThis section discusses general features of the page implementation class code that is produced by the OracleJSP translator in translating JSP source (.jsp and .sqljsp files).

Features of Page Implementation Class CodeWhen the OracleJSP translator generates servlet code in the page implementation class, it automatically handles some of the standard programming overhead. For both the on-demand translation model and the pre-translation model, generated code automatically includes the following features:

■ It extends a wrapper class (oracle.jsp.runtime.HttpJsp) provided by the OracleJSP container that implements the standard javax.servlet.jsp.HttpJspPage interface (which extends the more generic javax.servlet.jsp.JspPage interface, which in turn extends the standard javax.servlet.Servlet interface).

■ It implements the _jspService() method specified by the HttpJspPage interface. This method, often referred to generically as the "service" method, is the central method of the page implementation class. Code from any Java scriptlets and expressions in the JSP page is incorporated into this method implementation.

■ It includes code to request an HTTP session, unless your JSP source code specifically sets session=false (which can be done in a page directive).

For introductory information about key JSP and servlet classes and interfaces, see Appendix B, "Servlet and JSP Technical Background".

Inner Class for Static TextThe service method, _jspService(), of the page implementation class includes print commands—out.print() calls on the implicit out object—to print any static text in the JSP page. The OracleJSP translator, however, places the static text itself in an inner class within the page implementation class. The service method out.print() statements reference attributes of the inner class to print the text.

This inner class implementation results in an additional .class file when the page is translated and compiled. In a client-side pre-translation scenario (usually for deployment to Oracle9i), be aware this means there is an extra .class file to deploy.

JSP Translation and Deployment 6-3


The name of the inner class will always be based on the base name of the .jsp file or .sqljsp file. For mypage.jsp, for example, the inner class (and its .class file) will always include "mypage" in its name.

General Conventions for Output NamesThe OracleJSP translator follows a consistent set of conventions in naming output classes, packages, files and directories (and, in the case of deployment to the Oracle9i database or database cache, in naming schema paths). However, this set of conventions and other implementation details may change from release to release.

One fact that is not subject to change is that the base name of a JSP page will be included intact in output class and file names as long as it does not include special characters. For example, translating MyPage123.jsp will always result in the string "MyPage123" being part of the page implementation class name, Java source file name, and class file name.

In OracleJSP release 1.1.3.x (as well as some previous releases), the base name is preceded by an underscore ("_"). Translating MyPage123.jsp results in page implementation class _MyPage123 in source file _MyPage123.java, which is compiled into _MyPage123.class.

Similarly, where path names are used in creating Java package names (and schema path names for Oracle9i), each component of the path is preceded by an underscore. Translating /jspdir/myapp/MyPage123.jsp, for example, results in class _MyPage123 being in the following package:

_jspdir._myapp

Note: The OracleJSP translator can optionally place the static text in a Java resource file, which is advantageous for pages with large amounts of static text. (See "Workarounds for Large Static Content in JSP Pages" on page 4-16.) You can request this feature through the OracleJSP external_resource configuration parameter for on-demand translation, or the ojspc -extres option for pre-translation. Enabling hotloading, in deployment to Oracle9i, also results in the static text going into a resource file.

Even when static text is placed in a resource file, the inner class is still produced, and its .class file must be deployed. (This is only noteworthy if you are in a client-side pre-translation scenario.)



The package name is used in creating directories for output .java and .class files, so the underscores are also evident in output directory names. For example, in translating a JSP page in the directory htdocs/test, the OracleJSP translator by default will create directory htdocs/_pages/_test for the page implementation class source.

If special characters are included in a JSP page name or path name, the OracleJSP translator takes steps to ensure that no characters that would be illegal in Java appear in the output class, package, and file names. For example, translating My-name_foo12.jsp results in _My_2d_name__foo12 being the class name, in source file _My_2d_name__foo12.java. The hyphen is converted to a string of alpha-numeric characters. (An extra underscore is also inserted before "foo12".) In this case, you can only be assured that alphanumeric components of the JSP page name will be included intact in the output class and file names. For example, you could search for "My", "name", or "foo12".

These conventions are demonstrated in examples provided later in this section and later in this chapter.

Generated Package and Class Names (On-Demand Translation)Although the Sun Microsystems JavaServer Pages Specification, Version 1.1 defines a uniform process for parsing and translating JSP text, it does not describe how the generated classes should be named—that is up to each JSP implementation.

This section describes how OracleJSP creates package and class names when it generates code during translation.

Note: All output directories are created under the standard _pages directory by default, as described in"Generated Files and Locations (On-Demand Translation)" on page 6-7. You can change this behavior, however, through the page_repository_root configuration parameter, described in "OracleJSP Configuration Parameters (Non-OSE)" on page A-15, or the ojspc -d and -srcdir options, described in "Option Descriptions for ojspc" on page 6-30.



Package NamingIn an on-demand translation scenario, the URL path that is specified when the user requests a JSP page—specifically, the path relative to the doc root or application root—determines the package name for the generated page implementation class. Each directory in the URL path represents a level of the package hierarchy.

It is important to note, however, that generated package names are always lowercase, regardless of the case in the URL.

Consider the following URL as an example:

http://host[:port]/HR/expenses/login.jsp

In OracleJSP release 1.1.3.x, this results in the following package specification in the generated code (implementation details are subject to change in future releases):

package _hr._expenses;

No package name is generated if the JSP page is at the doc root or application root directory, where the URL is as follows:

http://host[:port]/login.jsp

Class NamingThe base name of the .jsp file (or .sqljsp file) determines the class name in the generated code.

Consider the following URL example:

http://host[:port]/HR/expenses/UserLogin.jsp

In OracleJSP 1.1.3.x, this yields the following class name in the generated code (implementation details are subject to change in future releases):

public class _UserLogin extends ...

Be aware that the case (lowercase/uppercase) that end users type in the URL must match the case of the actual .jsp or .sqljsp file name. For example, they can specify UserLogin.jsp if that is the actual file name, or userlogin.jsp if that is

Note: For information about general conventions used by OracleJSP in naming output classes, packages, files, and schema paths, see "General Conventions for Output Names" on page 6-4



the actual file name, but not userlogin.jsp if UserLogin.jsp is the actual file name.

In OracleJSP release 1.1.3.x, the translator determines the case of the class name according to the case of the file name. For example:

■ UserLogin.jsp results in class _UserLogin.

■ Userlogin.jsp results in class _Userlogin.

■ userlogin.jsp results in class _userlogin.

If you care about the case of the class name, then you must name the .jsp file or .sqljsp file accordingly. However, because the page implementation class is invisible to the end user, this is usually not a concern.

Generated Files and Locations (On-Demand Translation)This section describes files that are generated by the OracleJSP translator and where they are placed. For pre-translation scenarios, ojspc places files differently and has its own set of relevant options—see "Summary of ojspc Output Files, Locations, and Related Options" on page 6-38.

The following subsections mention several OracleJSP configuration parameters. For more information about them, see "OracleJSP Configuration Parameters (Non-OSE)" on page A-15 and "OracleJSP Configuration Parameter Settings" on page A-26.

Files Generated by OracleJSPThis section considers both regular JSP pages (.jsp files) and SQLJ JSP pages (.sqljsp files) in listing files that are generated by the OracleJSP translator. For the file name examples, presume a file Foo.jsp or Foo.sqljsp is being translated.

Source files:

■ A.sqlj file is produced by the OracleJSP translator if the page is a SQLJ JSP page (for example, _Foo.sqlj).

■ A .java file is produced for the page implementation class and inner class (for example, _Foo.java). It is produced either directly by the OracleJSP translator from the.jsp file, or by the SQLJ translator from the.sqlj file if the page is a

Note: For information about general conventions used by OracleJSP in naming output classes, packages, files, and schema paths, see "General Conventions for Output Names" on page 6-4



SQLJ JSP page. (The currently installed Oracle SQLJ translator is used by default, but you can specify an alternative translator or an alternative release of the Oracle SQLJ translator by using the OracleJSP sqljcmd configuration parameter.)

Binary files:

■ In the case of a SQLJ JSP page, one or more binary files are produced during SQLJ translation for SQLJ profiles. By default these are .ser Java resource files, but they will be .class files if you enable the SQLJ -ser2class option (through the OracleJSP sqljcmd configuration parameter). The resource file or .class file has "Foo" as part of its name.

■ A .class file is produced by the Java compiler for the page implementation class. (The Java compiler is javac by default, but you can specify an alternative compiler using the OracleJSP javaccmd configuration parameter.)

■ An additional .class file is produced for the inner class of the page implementation class. This file will have "Foo" as part of its name.

■ A .res Java resource file is optionally produced for the static page content (for example, _Foo.res) if the OracleJSP external_resource configuration parameter is enabled.

Note: Discussion of SQLJ profiles assumes standard SQLJ code generation. Oracle9i SQLJ provides an option, -codegen=oracle, for Oracle-specific code generation, in which case no profiles are produced.

Note: The exact names of generated files for the page implementation class may change in future releases, but will still have the same general form. The names would always include the base name (such as "Foo" in these examples), but may include slight variations.



OracleJSP Translator Output File LocationsOracleJSP uses the Web server document repository to generate or load translated JSP pages.

By default, the root directory is the Web server doc root directory (for Apache/JServ) or the servlet context root directory of the application the page belongs to.

You can specify an alternative root directory through the OracleJSP page_repository_root configuration parameter.

In OracleJSP release 1.1.3.x, generated files are placed as follows (implementation details may change in future releases):

■ If the .jsp (or .sqljsp) file is directly in the root directory, then OracleJSP will place generated files into a default _pages subdirectory directly under the root directory.

■ If the .jsp (or .sqljsp) file is in a subdirectory under the root directory, then a parallel directory structure is created under the _pages subdirectory for the generated files. Subdirectory names under the _pages directory are based on subdirectory names under the root directory.

As an example, consider an Apache/JServ environment with an htdocs doc root directory. If a .jsp file is in the following directory:

htdocs/subdir/test

then generated files will be placed in the following directory:

htdocs/_pages/_subdir/_test

Sample Page Implementation Class SourceThis section uses an example to illustrate the information in the preceding sections.

Consider the following scenario:

■ JSP page code is in the file hello.jsp.

■ The page is executed in an Apache/JServ environment.

■ The hello.jsp file is located in the following directory:

htdocs/test



Sample Page Source: hello.jspFollowing is the JSP code in hello.jsp:

<HTML><HEAD><TITLE>The Hello User JSP</TITLE></HEAD><BODY><% String user=request.getParameter("user"); %><H3>Welcome <%= (user==null) ? "" : user %>!</H3><P><B> Today is <%= new java.util.Date() %>. Have a nice day! :-)</B></P><B>Enter name:</B><FORM METHOD=get><INPUT TYPE="text" NAME="user" SIZE=15><INPUT TYPE="submit" VALUE="Submit name"></FORM></BODY></HTML>

Sample: Generated Package and ClassBecause hello.jsp is in the test subdirectory of the root directory (htdocs), OracleJSP release 1.1.3.x generates the following package name in the page implementation code:

package _test;

The Java class name is determined by the base name of the .jsp file (including case), so the following class definition is generated in the page implementation code:

public class _hello extends oracle.jsp.runtime.HttpJsp{ ...}

(Because the page implementation class is invisible to the end user, the fact that its name does not adhere to Java capitalization conventions is generally not a concern.)

Important: Code generation details discussed here are according to Oracle’s implementation of the JSP 1.1 specification. Details may change in the future, as the result of either changes in the specification or changes in how Oracle implements aspects that are not specified.



Sample: Generated FilesBecause hello.jsp is located as follows:

htdocs/test/hello.jsp

OracleJSP release 1.1.3.x generates output files as follows (the page implementation class .java file and .class file, and the inner class .class file, respectively):

htdocs/_pages/_test/_hello.javahtdocs/_pages/_test/_hello.classhtdocs/_pages/_test/_hello$__jsp_StaticText.class

Sample Page Implementation Code: _hello.javaFollowing is the generated page implementation class Java code (_hello.java), as generated by OracleJSP release 1.1.3.x:

package _test;

import oracle.jsp.runtime.*;import javax.servlet.*;import javax.servlet.http.*;import javax.servlet.jsp.*;import java.io.*;import java.util.*;import java.lang.reflect.*;import java.beans.*;

public class _hello extends oracle.jsp.runtime.HttpJsp {

public final String _globalsClassName = null;

// ** Begin Declarations

// ** End Declarations

Note: These file names are based specifically on the OracleJSP 1.1.3.x implementation; the exact details may change in future releases. All file names will always include the base "hello", however.



public void _jspService(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {

/* set up the intrinsic variables using the pageContext goober: ** session = HttpSession ** application = ServletContext ** out = JspWriter ** page = this ** config = ServletConfig ** all session/app beans declared in globals.jsa */ JspFactory factory = JspFactory.getDefaultFactory(); PageContext pageContext = factory.getPageContext( this, request, response, null, true, JspWriter.DEFAULT_BUFFER, true); // Note: this is not emitted if the session directive == false HttpSession session = pageContext.getSession(); if (pageContext.getAttribute(OracleJspRuntime.JSP_REQUEST_REDIRECTED, PageContext.REQUEST_SCOPE) != null) { pageContext.setAttribute(OracleJspRuntime.JSP_PAGE_DONTNOTIFY, "true", PageContext.PAGE_SCOPE); factory.releasePageContext(pageContext); return;} ServletContext application = pageContext.getServletContext(); JspWriter out = pageContext.getOut(); hello page = this; ServletConfig config = pageContext.getServletConfig();

try { // global beans // end global beans

out.print(__jsp_StaticText.text[0]); String user=request.getParameter("user"); out.print(__jsp_StaticText.text[1]); out.print( (user==null) ? "" : user ); out.print(__jsp_StaticText.text[2]); out.print( new java.util.Date() ); out.print(__jsp_StaticText.text[3]);

out.flush();

} catch( Exception e) {



try { if (out != null) out.clear(); } catch( Exception clearException) { } pageContext.handlePageException( e); } finally { if (out != null) out.close(); factory.releasePageContext(pageContext); }

} private static class __jsp_StaticText { private static final char text[][]=new char[4][]; static { text[0] = "<HTML>\r\n<HEAD><TITLE>The Welcome User JSP</TITLE></HEAD>\r\n<BODY>\r\n".toCharArray(); text[1] = "\r\n<H3>Welcome ".toCharArray(); text[2] = "!</H3>\r\n<P><B> Today is ".toCharArray(); text[3] = ". Have a nice day! :-)</B></P>\r\n<B>Enter name:</B>\r\n<FORM METHOD=get>\r\n<INPUT TYPE=\"text\" NAME=\"user\" SIZE=15>\r\n<INPUT TYPE=\"submit\" VALUE=\"Submit name\">\r\n</FORM>\r\n</BODY>\r\n</HTML>".toCharArray(); } }}


Overview of Features and Logistics in Deployment to Oracle9i

Overview of Features and Logistics in Deployment to Oracle9iThis section is an overview of considerations and logistics in deploying a JSP application into Oracle9i to run in the Oracle9i Servlet Engine. The following topics are covered:

■ Database Schema Objects for Java

■ Oracle HTTP Server as a Front-End Web Server

■ URLs for the Oracle9i Servlet Engine

■ Static Files for JSP Applications in the Oracle9i Servlet Engine

■ Server-Side Versus Client-Side Translation

■ Overview of Hotloaded Classes in Oracle9i

Database Schema Objects for JavaJava code that executes in the Oracle9i Servlet Engine in the Oracle9i database or database cache uses the Oracle JVM. The code must be loaded into a particular Oracle9i schema as one or more schema objects.

The three kinds of schema objects for Java are:

■ source schema objects (corresponding to Java source files)

■ class schema objects (corresponding to Java class files)

■ resource schema objects (corresponding to Java resource files)

Each schema object is an individual library unit. When you query the ALL_OBJECTS table of the schema, Java schema objects are seen as type JAVA SOURCE, JAVA CLASS, or JAVA RESOURCE, respectively.

See the Oracle9i Java Developer’s Guide for more information.

Loading Java Files to Create Schema ObjectsThe Oracle9i loadjava tool is used to load Java files into Oracle9i as schema objects. (See "Overview of the loadjava Tool" on page 6-40.)

When you compile on the client and load the .class file directly, loadjava stores the .class file as a class schema object in Oracle9i.

When you load a resource file (such as a .res file for static JSP content or .ser profile file for SQLJ), loadjava stores the resource file as a resource schema object in Oracle9i.



When you load a .java (or .sqlj) source file, loadjava stores the source file as a source schema object in Oracle9i and compiles it inside the database (or database cache) to create one or more class schema objects.

When you load a .jsp or .sqljsp page source file (for server-side translation), loadjava stores the page source as a resource schema object. During server-side translation (through the Oracle9i session shell publishjsp command), server-side loadjava is invoked automatically to create source schema objects, class schema objects, and resource schema objects during translation and compilation.

(See "Tools and Commands for Translation and Deployment to Oracle9i" on page 6-26 for an overview of the loadjava and session shell tools.)

Schema Object Full Names and Short NamesThe two forms of schema object names in Oracle9i are full names and short names.

Full names are fully qualified and are used as the schema object names wherever possible. If any full name contains more than 31 characters, however, or contains characters that are illegal or cannot be converted to characters in the database character set, then Oracle9i converts the full name to a short name to employ as the name of the schema object, keeping track of both names and how to convert between them. If the full name contains 31 characters or less and has no illegal or inconvertible characters, then the full name is used as the schema object name.

For more information about these and about other file naming considerations, including DBMS_JAVA procedures to retrieve a full name from a short name and a short name from a full name, see the Oracle9i Java Developer’s Guide.

Java Schema Object Package Determination During LoadingDuring loading of Java files into Oracle9i, the loadjava tool uses the following logic to determine the package for Java schema objects it creates:

■ For source schema objects (created from.java and .sqlj files) and class schema objects (created from .class files or by compiling .java files), the schema package is determined by any package information in the Java code.

For example, a class Foo that specifies the package pkg1.pkg2 and is being loaded into the SCOTT schema will be stored in the schema as follows:

SCOTT:pkg1/pkg2/Foo



■ For resource schema objects (created from .res and .ser Java resource files, for example), the schema package is determined by any path information in the loadjava command line (if the Java resource file is being loaded directly) or the JAR file (if the Java resource file is being loaded as part of a JAR file).

For example, a .res file being loaded into the SCOTT schema as pkg3/pkg4/abcd.res will be stored in a schema object as follows:

SCOTT:pkg3/pkg4/abcd.res

Publishing Schema ObjectsAny JSP page (or servlet) that will run in the Oracle9i Servlet Engine must be "published", a process that makes its executable Java code (the class schema objects) accessible through entries in the Oracle9i JNDI namespace.

Publishing the JSP page links its page implementation class schema object to a servlet path (and optionally to a non-default servlet context path). The servlet path (and context path, if applicable) becomes part of the URL that an end user would specify to access and execute the page. See "URLs for the Oracle9i Servlet Engine" on page 6-17 for more information.

To publish a JSP page, use the Oracle9i session shell publishjsp command for the "deployment with server-side translation" scenario, or the session shell publishservlet command for the "deployment with client-side translation" scenario. See "Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)" on page 6-46 or "Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)" on page 6-69.

Oracle HTTP Server as a Front-End Web ServerJSP pages and servlets running in the Oracle9i Servlet Engine are typically accessed through the Oracle HTTP Server, powered by Apache, and its mod_ose module. It is possible, however, to use OSE itself as the Web server.

For more information about the role of the Oracle HTTP Server and mod_ose, see "Role of the Oracle HTTP Server, Powered by Apache" on page 2-6.

Note: When pre-translating a JSP page with the ojspc tool (for deployment to Oracle9i with client-side translation), you can specify the package of the generated .java file through the ojspc -packageName option.



URLs for the Oracle9i Servlet EngineThis section describes how URLs are formed for servlets and JSP pages that will run in the Oracle9i Servlet Engine.

Context Path and Servlet PathAs with servlet URLs in general, URLs to invoke JSP pages running in the Oracle9i Servlet Engine are formed by a combination of two components in addition to the hostname and port:

■ the context path of the servlet context in OSE, as determined when the servlet context was created

■ the servlet path of the JSP page in OSE, as determined when the JSP page was published

The servlet path is often referred to as the "virtual path" and is determined by the -virtualpath option when you publish a servlet or JSP page. Be aware, however, that it is the context path that is determined through the -virtualpath option when a servlet context is created. Do not confuse the servlet path "virtual path" and the context path "virtual path".

For every OSE Web domain there is a default context, /domain_name/contexts/default (where domain_name represents the name of the particular domain). The context path for any OSE default context is simply:

/

The context path for any other OSE servlet context you create, which you accomplish using the Oracle9i session shell createcontext command, is whatever you specify in the createcontext -virtualpath option. It is conventional, but not required, to specify that the context path be the same as the context name. (The -virtualpath option is required whenever you execute the createcontext command.)



For general information about the session shell createcontext command, see the Oracle9i Java Tools Reference. For an overview of the Oracle9i session shell, see "Overview of the sess_sh Session Shell Tool" on page 6-42.

The servlet path (JSP page "virtual path") is determined by how you publish the JSP page, as follows:

■ If you use the session shell publishjsp command (for server-side translation), then it is determined by the publishjsp -virtualpath option, or is the same as the specified schema path by default.

■ If you use the session shell publishservlet command (after client-side translation), then it is determined by the publishservlet -virtualpath option (which you must specify when you use publishservlet for a JSP page).

See "Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)" on page 6-46 or "Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)" on page 6-69.

OSE PortsEach OSE Web service has a port associated with it, which an end user must specify as part of the URL if the OSE default Web service (admin) is not being used:

http://host[:port]/path

In this syntax, path is the combination of the context path and servlet path.

The port for the default admin Web service is 8080. The port for any other Web service is determined using the session shell tool addendpoint command. (See "Overview of the sess_sh Session Shell Tool" on page 6-42 for general information about the tool. See the Oracle9i Java Tools Reference for information about the addendpoint command.)

Notes: For purposes of the discussion here and elsewhere in this chapter, assume OSE single-domain mode. In this case, there is just one domain per Web service. For information about single-domain mode versus multi-domain mode and how this would affect the URL, see the Oracle9i Servlet Engine Developer’s Guide.



OSE scottServiceA Makefile is provided with Oracle9i to create an OSE Web service called scottService. The domain is /scottRoot, the default context is /scottRoot/contexts/default, and an additional context, /scottRoot/contexts/scottContext, is also created automatically. (Note that these are JNDI names only and are not directly related to URLs.)

The context path for the default context is:

/

The context path for scottContext is:

/ose

The scottService port number is 8088.

The scottRoot servlet contexts will be used in the examples in the next section and elsewhere in this chapter.

URL ExamplesThis section provides examples of OSE URLs, using servlet contexts of scottService as described immediately above.

Example 1 As an example, consider a JSP page that is published to the scottService default context with a servlet path (virtual path), as follows:

mydir/mypage.jsp

This page is accessed as follows:

http://host:8088/mydir/mypage.jsp

You can access it from another page in the application, say mydir/mypage2.jsp, in either of the following ways (the first is a page-relative path; the second is an application-relative path):

<jsp:include page="mypage.jsp" flush="true" />

<jsp:include page="/mydir/mypage.jsp" flush="true" />



Example 2 Now consider the scottContext servlet context, created as follows ($ is the session shell prompt):

$ createcontext -virtualpath /ose /scottRoot scottContext

This does the following:

■ It specifies the domain /scottRoot.

■ It creates the servlet context /scottRoot/contexts/scottContext (all servlet contexts in OSE go under /domain_name/contexts).

■ It specifies /ose as the context path.

If mydir/mypage.jsp is published to the scottContext servlet context, it is accessed as follows:

http://host:8088/ose/mydir/mypage.jsp

(Note that /scottRoot and /scottRoot/contexts/scottContext are JNDI names only and are not related to the URL. It is the context path that is relevant to the URL.)

You can access the page from another page in the application, say mydir/mypage2.jsp, in either of the following ways (the first is a page-relative path; the second is an application-relative path):

<jsp:include page="mypage.jsp" flush="true" />

<jsp:include page="/mydir/mypage.jsp" flush="true" />

The syntax for the dynamic jsp:include statements is the same as in Example 1. Even though a different servlet context is used, the path of the pages relative to the context is unchanged.

Static Files for JSP Applications in the Oracle9i Servlet EngineThis section describes the required placement of static files, such as HTML files, that are used in a JSP application that runs in the Oracle9i Servlet Engine (with OSE being used as its own Web server).

Files for Dynamic Includes and ForwardsStatic files that are dynamic include or forward targets (jsp:include or jsp:forward) in a JSP application running in the Oracle9i Servlet Engine must be manually moved or copied to the OSE doc root directory corresponding to the



servlet context of the application. When you create an OSE servlet context, using the session shell createcontext command, you specify a doc root directory through the createcontext -docroot option. Each OSE doc root directory is linked to the Oracle9i JNDI namespace. (For more information about the session shell createcontext command, see the Oracle9i Java Tools Reference.)

OSE doc root directories are outside the database (or database cache). The JNDI lookup mechanism for static files is a front-end for the file system of the server on which the database resides.

Files for Static IncludesAny file that is statically included (through an include directive) by a JSP page, whether it is another JSP page or a static file such as an HTML file, must be accessible by the OracleJSP translator during translation.

In the case of a JSP application targeted for OSE, there are three translation scenarios:

■ server-side translation

This is where you load a .jsp file into Oracle9i as a Java resource, then use publishjsp to invoke the OracleJSP translator in the server. (See "Deployment to Oracle9i with Server-Side Translation" on page 6-45.)

In this case, static files must be loaded beforehand, using loadjava, as resource schema objects.

Notes:

■ If you are migrating your JSP application from Apache to OSE, any static files that will be dynamic include or forward targets should be copied from the Apache doc root to the OSE servlet context doc root, as opposed to mapping the OSE servlet context doc root to the Apache doc root. Mapping the doc roots may ultimately cause confusion.

■ The OSE default service, admin, has the following default servlet context:

/system/admin/contexts/default

■ The default servlet context has the following doc root:

$ORACLE_HOME/jis/public_html



■ client-side translation

This is where you translate a .jsp file on the client using ojspc and load the generated components into Oracle9i.

In this case, static files do not have to be in the server at all. They only have to be accessible by ojspc on the client during translation. (For application-relative static include directives, see the discussion of the ojspc -appRoot option under "Option Descriptions for ojspc" on page 6-30.)

■ Oracle WAR deployment

See the Oracle9i Servlet Engine Developer’s Guide for information, or "WAR Deployment" on page 6-77 for an overview.

Server-Side Versus Client-Side TranslationDevelopers who are deploying their JSP pages to Oracle9i to run in the Oracle9i Servlet Engine can translate either in the server or on the client.

Deployment with server-side translation requires two steps:

1. Run loadjava to load the JSP page source (.jsp or .sqljsp file) into Oracle9i as a resource schema object. (You must also load any required Java classes or other required JSP pages.)

2. Run the session shell publishjsp command. This will automatically accomplish the following:

■ The JSP page source is translated into Java code for the page implementation class (first producing a SQLJ source file and invoking the SQLJ translator in the case of a SQLJ JSP page).

■ The Java code is compiled into one or more class files.

■ The page implementation class is optionally hotloaded (if you specified the publishjsp -hotload option).

■ The page implementation class is published as a servlet for execution in Oracle9i.

This step also produces source schema objects, class schema objects, and resource schema objects for all generated .java files (and .sqlj files for .sqljsp pages), .class files, and resource files, respectively.

See "Deployment to Oracle9i with Server-Side Translation" on page 6-45 for more information.



Deployment with client-side translation requires three, or optionally four, steps:

1. Run the OracleJSP pre-translation tool, ojspc. This accomplishes the following:

■ The JSP page source is translated into Java code for the page implementation class. (In the case of a SQLJ JSP page, ojspc first produces a SQLJ source file then invokes the SQLJ translator to produce Java code.)

■ A Java resource file is optionally produced for static text, depending on the ojspc -extres and -hotload options.

■ The Java code is compiled into its class files.

2. Run the Oracle9i loadjava utility to load the class files and any resource files into Oracle9i as class schema objects and resource schema objects.

3. Optionally hotload the classes (if you enabled the ojspc -hotload option during translation) by using the Oracle9i session shell java command to execute the main() method of the page implementation class.

4. Run the session shell publishservlet command to publish the page implementation classes for execution in Oracle9i.

See "Deployment to Oracle9i with Client-Side Translation" on page 6-59 for more information.

If you are using Oracle JDeveloper, you may find it more convenient to translate on the client using the OracleJSP translator provided with JDeveloper and then deploy the resulting classes and resources, as in steps 2, 3, and 4.

If you are not using JDeveloper, however, translating in the server is likely to be more convenient, because the session shell publishjsp command combines translation, optional hotloading, and publishing into a single step.

In addition, either of the following situations may dictate the need to translate in the server:

■ if required libraries are not available on the client

■ if you want to compile against the exact set of classes that will be used at runtime

Note: Another possible scenario is to use Oracle WAR deployment. See the Oracle9i Servlet Engine Developer’s Guide for information, or "WAR Deployment" on page 6-77 for an overview.



Overview of Hotloaded Classes in Oracle9iOracle9i offers a feature known as hotloading classes for more efficient use of static final variables (constants). This becomes relevant whenever the hotloaded classes might be used by multiple concurrent users.

A separate JVM is invoked for each Oracle9i session created in Java. Normally each session gets its own copy of all static final variables in its session space or, in the case of literal strings, in a hashtable known as the intern table in shared memory. Use of literal strings in the intern table is synchronized across sessions.

The processing of literal strings is especially relevant to JSP pages. By default (without hotloading), the static text in a JSP page is ultimately represented as literal strings.

Enabling and Accomplishing HotloadingThe ability to hotload a JSP page is enabled during translation, through the ojspc -hotload option (for client-side translation) or the publishjsp -hotload option (for server-side translation).

Enabling the -hotload option directs the OracleJSP translator to do the following:

■ It generates code in the page implementation class to allow hotloading, by creating a hotloading method and a main() method that invokes the hotloading method.

■ It writes static text to a Java resource file. (Otherwise, static text is written to an inner class of the page implementation class.)

The hotloading itself is accomplished as follows:

■ For deployment with client-side translation, you must hotload as an extra deployment step. After translating with the ojspc -hotload option enabled and loading the page class and static resources into Oracle9i, and before invoking publishservlet to publish the page, you must use the session shell java command to invoke the main() method of the page implementation class. Details of the process are discussed in "Deployment to Oracle9i with Client-Side Translation" on page 6-59.

Note: This section refers to the OracleJSP pre-translation tool (ojspc), the Oracle session shell tool (sess_sh), and the session shell publishjsp command. For an overview of these tools, see "Tools and Commands for Translation and Deployment to Oracle9i" on page 6-26.



■ For deployment with server-side translation, hotloading is accomplished automatically as part of publishjsp functionality when you enable the publishjsp -hotload option.

The act of hotloading a page implementation class, either directly through the session shell java command or indirectly through the publishjsp command, actually just makes the inner class static text shareable among multiple JVMs in Oracle9i.

Features and Advantages of HotloadingHotloading classes results in the following logistical features and advantages:

■ The translator generates code to read the Java resource containing the static text in static initializers, to initialize the char arrays representing static text.

■ During hotloading, each hotloaded inner class is initialized only once, and static JSP text is converted into static Java char arrays only once.

These char arrays, instead of being stored in the synchronized intern table, are stored elsewhere in a global area that is shared across all sessions without synchronization (which is feasible because of the knowledge that none of the variables will change).

Hotloading, by avoiding synchronization and other costly overhead, can significantly improve the runtime performance and scalability of JSP pages executed in the Oracle9i Servlet Engine. Furthermore, when a hotloaded class is referenced, the class initializer is not rerun. The session has instant access to the literal strings and other static final variables.

In addition to allowing better performance of individual JSP pages, hotloading reduces overall CPU usage of the server.

Note: JSP pages that will not be used by multiple users concurrently, or small JSP pages with few literal strings, may have little or no performance improvement from hotloading.


Tools and Commands for Translation and Deployment to Oracle9i

Tools and Commands for Translation and Deployment to Oracle9iOracle provides the following tools to use, as applicable, in translating JSP pages and deploying them to Oracle9i. How they are implemented depends on your operating system (such as shell scripts for Solaris or .bat files for Windows NT):

■ ojspc (OracleJSP pre-translation tool)

■ loadjava (tool for loading JSP pages or Java files into the Oracle9i database or database cache)

■ sess_sh (Oracle9i session shell tool)

Deployment with client-side translation requires all three tools. Pre-translate JSP pages on the client using ojspc, load the translated pages into Oracle9i using loadjava, and publish them using the session shell publishservlet command.

Deployment with server-side translation does not require ojspc. Load the untranslated JSP pages into Oracle9i using loadjava, then translate and publish them using the session shell publishjsp command.

The loadjava and sess_sh tools are general-purpose tools for the Oracle9i Java environment; ojspc is for JSP pages only.

The ojspc Pre-Translation ToolThe first step in deploying a JSP application to Oracle9i with client-side translation is to run the OracleJSP pre-translation tool, ojspc.

You will then use loadjava, introduced in the next section, to load the resulting .class files and resource files (if any) into Oracle9i as class schema objects and resource schema objects, respectively.


■ Overview of ojspc Functionality

Notes:

■ Another tool, the Oracle9i Accelerator, is relevant if you want to natively compile your application to run in Oracle9i. This tool, invoked as ncomp, is documented in the Oracle9i Java Tools Reference.

■ The tools discussed in this section are located in the [ORACLE_HOME]/bin directory.



■ Option Summary Table for ojspc

■ Command-Line Syntax for ojspc

■ Option Descriptions for ojspc

■ Summary of ojspc Output Files, Locations, and Related Options

Overview of ojspc FunctionalityFor a simple JSP (not SQLJ JSP) page, default functionality for ojspc is as follows:

■ It takes a .jsp file as an argument.

■ It invokes the OracleJSP translator to translate the .jsp file into Java page implementation class code, producing a .java file. The page implementation class includes an inner class for static page content.

■ It invokes the Java compiler to compile the .java file, producing two .class files (one for the page implementation class itself and one for the inner class).

And following is the default ojspc functionality for a SQLJ JSP page:

■ It takes a .sqljsp file as an argument instead of a .jsp file.

■ It invokes the OracleJSP translator to translate the .sqljsp file into a .sqlj file for the page implementation class (and inner class).

■ It invokes the Oracle SQLJ translator to translate the .sqlj file. This produces a .java file for the page implementation class (and inner class) and a SQLJ "profile" file that is, by default, a .ser Java resource file.

For information about SQLJ profiles and Oracle-specific code generation, see the Oracle9i SQLJ Developer’s Guide and Reference.

Notes: There are other possible scenarios, such as in a middle-tier environment, for using ojspc to pre-translate JSP pages. See "Use of ojspc for Pre-Translation for Non-OSE Environments" on page 6-74.




■ It invokes the Java compiler to compile the .java file, producing two .class files (one for the page implementation class itself and one for the inner class).

Under some circumstances (see the -hotload and -extres option descriptions below), ojspc options direct the OracleJSP translator to produce a .res Java resource file for static page content instead of putting this content into the inner class of the page implementation class. However, the inner class is still created and must still be deployed with the page implementation class.

Because ojspc invokes the OracleJSP translator, ojspc output conventions are the same as for OracleJSP in general, as applicable. For general information about OracleJSP translator output, including generated code features, general conventions for output names, generated package and class names, and generated files and locations, see "Functionality of the OracleJSP Translator" on page 6-2.

Option Summary Table for ojspcTable 6–1 describes the options supported by the ojspc pre-translation utility. These options are further discussed in "Option Descriptions for ojspc" on page 6-30.

The second column notes comparable or related OracleJSP configuration parameters for on-demand translation environments (such as Apache/JServ).

Note: The ojspc command-line tool is a front-end utility that invokes the oracle.jsp.tool.Jspc class.

Note: A boolean ojspc option is enabled by typing only the option name, not by setting it to true. Setting it to true will cause an error.

Table 6–1 Options for ojspc Pre-Translation Utility

Option

Related OracleJSP Configuration Parameters Description Default

-addclasspath classpath (related, but with different functionality)

additional classpath entries for javac

empty (no additional path entries)

-appRoot n/a application root directory for application-relative static include directives from the page

current directory



-debug emit_debuginfo boolean to direct ojspc to generate a line map to the original .jsp file for debugging

false

-d page_repository_root location where ojspc should place generated binary files (.class and resource)

current directory

-extend n/a class for the generated page implementation class to extend

empty

-extres external_resource boolean to direct ojspc to generate an external resource file for static text from the .jsp file

false

-hotload(for OSE only)

n/a boolean to direct ojspc to implement code in the page implementation class to allow hotloading

false

-implement n/a interface for the generated page implementation class to implement

empty

-noCompile javaccmd boolean to direct ojspc not to compile the generated page implementation class

false

-packageName n/a package name for the generated page implementation class

empty (generate package names per .jsp file location)

-S-<sqlj option> sqljcmd -S prefix followed by an Oracle SQLJ option (for .sqljsp files)

empty

-srcdir page_repository_root location where ojspc should place generated source files (.java and .sqlj)

current directory

-verbose n/a boolean to direct ojspc to print status information as it executes

false

Table 6–1 Options for ojspc Pre-Translation Utility (Cont.)

Option




Command-Line Syntax for ojspcFollowing is the general ojspc command-line syntax (assume % is a UNIX prompt):

% ojspc [option_settings] file_list

The file list can include .jsp files or .sqljsp files.

Be aware of the following syntax notes:

■ If multiple .jsp files are translated, they all must use the same character set (either by default or through page directive contentType settings).

■ Use spaces between file names in the file list.

■ Use spaces as separators between option names and option values in the option list.

■ Option names are not case sensitive, but option values usually are (such as package names, directory paths, class names, and interface names).

■ Enable boolean options, which are disabled by default, by typing only the option name. For example, type -hotload, not -hotload true.)

Following is an example:

% ojspc -d /myapp/mybindir -srcdir /myapp/mysrcdir -hotload MyPage.sqljsp MyPage2.jsp

Option Descriptions for ojspcThis section describes the ojspc options in more detail.

-addclasspath (fully qualified path; ojspc default: empty)

Use this option to specify additional classpath entries for javac to use when compiling generated page implementation class source. Otherwise, javac uses only the system classpath.

-version n/a boolean to direct ojspc to display the OracleJSP version number

false

Table 6–1 Options for ojspc Pre-Translation Utility (Cont.)

Option




-appRoot (fully qualified path; ojspc default: current directory)

Use this option to specify an application root directory. The default is the current directory, from which ojspc was run.

The specified application root directory path is used as follows:

■ It is used for static include directives in the page being translated. The specified directory path is prepended to any application-relative (context-relative) paths in the include directives of the translated page.

■ It is used in determining the package of the page implementation class. The package will be based on the location of the file being translated relative to the application root directory. The package, in turn, determines the placement of output files. (See "Summary of ojspc Output Files, Locations, and Related Options" on page 6-38.)

This option is necessary, for example, so included files can still be found if you run ojspc from some other directory.


■ You want to translate the following file:

/abc/def/ghi/test.jsp

■ You run ojspc from the current directory, /abc, as follows (assume % is a UNIX prompt):

% cd /abc% ojspc def/ghi/test.jsp

■ The test.jsp page has the following include directive:

<%@ include file="/test2.jsp" %>

Notes:

■ In an on-demand translation scenario, the OracleJSP classpath configuration parameter provides related, although different, functionality. See "OracleJSP Configuration Parameters (Non-OSE)" on page A-15.

■ The -addclasspath setting is also used by the SQLJ translator for SQLJ JSP pages.



■ The test2.jsp page is in the /abc directory, as follows:

/abc/test2.jsp

This requires no -appRoot setting, because the default application root setting is the current directory, which is the /abc directory. The include directive uses the application-relative /test2.jsp syntax (note the beginning "/"), so the included page will be found as /abc/test2.jsp.

The package in this case is _def._ghi, based simply on the location of test.jsp relative to the current directory, from which ojspc was run (the current directory is the default application root). Output files are placed accordingly.

If, however, you run ojspc from some other directory, suppose /home/mydir, then you would need an -appRoot setting as in the following example:

% cd /home/mydir% ojspc -appRoot /abc /abc/def/ghi/test.jsp

The package is still _def._ghi, based on the location of test.jsp relative to the specified application root directory.

-d (fully qualified path; ojspc default: current directory)

Use this option to specify a base directory for ojspc placement of generated binary files—.class files and Java resource files. (The .res files produced for static content by the -extres and -hotload options are Java resource files, as are .ser profile files produced by the SQLJ translator for SQLJ JSP pages.)

The specified path is taken simply as a file system path (not an application-relative or page-relative path).

Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. See "Summary of ojspc Output Files, Locations, and Related Options" on page 6-38 for more information.

The default is to use the current directory (your current directory when you executed ojspc).

Note: It is typical for the specified application root directory to be some level of parent directory of the directory where the translated JSP page is located.



It is recommended that you use this option to place generated binary files into a clean directory so that you easily know what files have been produced.

-debug (boolean; ojspc default: false)

Enable this flag to instruct ojspc to generate a line map to the original .jsp file for debugging. Otherwise, line-mapping will be to the generated page implementation class.

This is useful for source-level JSP debugging, such as when using Oracle JDeveloper.

-extend (fully qualified Java class name; ojspc default: empty)

Use this option to specify a Java class that the generated page implementation class will extend.

-extres (boolean; ojspc default: false)

Enable this flag to instruct ojspc to place generated static content (the Java print commands that output static HTML code) into a Java resource file instead of into an inner class of the generated page implementation class.

The resource file name is based on the JSP page name. For release 1.1.3.x it will be the same core name as the JSP name (unless special characters are included in the JSP name), but with an underscore ("_") prefix and .res suffix. Translation of MyPage.jsp, for example, would create _MyPage.res in addition to normal

Notes:

■ In environments such as Windows NT that allow spaces in directory names, enclose the directory name in quotes.

■ In an on-demand translation scenario, the OracleJSP page_repository_root configuration parameter provides related functionality. See "OracleJSP Configuration Parameters (Non-OSE)" on page A-15.

Note: In an on-demand translation scenario, the OracleJSP emit_debuginfo configuration parameter provides the same functionality. See "OracleJSP Configuration Parameters (Non-OSE)" on page A-15.



output. The exact implementation for name generation may change in future releases, however.

The resource file is placed in the same directory as .class files.

If there is a lot of static content in a page, this technique will speed translation and may speed execution of the page. For more information, see "Workarounds for Large Static Content in JSP Pages" on page 4-16.

-hotload (boolean; ojspc default: false) (for OSE only)

Enable this flag to allow hotloading. This is relevant only if you will be loading the translated pages into Oracle9i to run in the Oracle9i Servlet Engine.

The -hotload flag directs ojspc to do the following:

1. Perform -extres functionality, writing static output to a Java resource file (see the -extres description above).

2. Create a main() method and a hotloading method in the generated page implementation class to allow hotloading.

For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle9i" on page 6-24. For how to accomplish the hotloading step (once hotloading has been enabled), see "Hotloading Page Implementation Classes in Oracle9i" on page 6-68.

-implement (fully qualified Java interface name; ojspc default: empty)

Use this option to specify a Java interface that the generated page implementation class will implement.

Notes:

■ The inner class is still created and must still be deployed.

■ In an on-demand translation scenario, the OracleJSP external_resource configuration parameter provides the same functionality. See "OracleJSP Configuration Parameters (Non-OSE)" on page A-15.

Note: To write static content to a resource file without enabling hotloading (if the page will not be running in OSE, for example), use the -extres option.



-noCompile (boolean; ojspc default: false)

Enable this flag to direct ojspc not to compile the generated page implementation class Java source. This allows you to compile it later with an alternative Java compiler.

-packageName (fully qualified package name; ojspc default: per .jsp file location)

Use this option to specify a package name for the generated page implementation class, using Java "dot" syntax.

Without setting this option, the package name is determined according to the location of the .jsp file relative to the current directory (from which you ran ojspc).

Consider an example where you run ojspc from the /myapproot directory, while the .jsp file is in the /myapproot/src/jspsrc directory (assume % is a UNIX prompt):

% cd /myapproot% ojspc -packageName myroot.mypackage src/jspsrc/Foo.jsp

This results in myroot.mypackage being used as the package name.

If this example did not use the -packageName option, OracleJSP release 1.1.3.x would use _src._jspsrc as the package name, by default. (Be aware that such implementation details are subject to change in future releases.)

-S-<sqlj option> <value> (-S followed by SQLJ option setting; ojspc default: empty)

For SQLJ JSP pages, use the ojspc -S option to pass an Oracle SQLJ option to the SQLJ translator. You can use multiple occurrences of -S, with one SQLJ option per occurrence.

Notes:

■ In an on-demand translation scenario, the OracleJSP javaccmd configuration parameter provides related functionality, allowing you to specify an alternative Java compiler directly. See "OracleJSP Configuration Parameters (Non-OSE)" on page A-15.

■ For a SQLJ JSP page, enabling -noCompile does not prevent SQLJ translation, just Java compilation.



Unlike when you run the SQLJ translator directly, use a space between a SQLJ option and its value (this is for consistency with other ojspc options).

For example (from a UNIX prompt):

% ojspc -S-default-customizer mypkg.MyCust -d /myapproot/mybindir MyPage.jsp

This invokes the Oracle SQLJ -default-customizer option to choose an alternative profile customizer, as well as setting the ojspc -d option.

Here is another example:

% ojspc -S-ser2class true -S-status true -d /myapproot/mybindir MyPage.jsp

This enables the SQLJ -ser2class option (to convert the profile to a .class file) and the SQLJ -status option (to display status information as the .sqlj file is translated).

Note the following for particular Oracle SQLJ options:

■ Do not use the SQLJ -encoding option; instead, use the contentType parameter in a page directive in the JSP page.

■ Do not use the SQLJ -classpath option if you use the ojspc -addclasspath option.

■ Do not use the SQLJ -compile option if you use the ojspc -noCompile option.

■ Do not use the SQLJ -d option if you use the ojspc -d option.

■ Do not use the SQLJ -dir option if you use the ojspc -srcdir option.

For information about Oracle SQLJ translator options, see the Oracle9i SQLJ Developer’s Guide and Reference.

Note: As the preceding example shows, you can use an explicit true setting in enabling a SQLJ boolean option through the -S option setting. This is in contrast to ojspc boolean options, which do not take an explicit true setting.



-srcdir (fully qualified path; ojspc default: current directory)

Use this option to specify a base directory location for ojspc placement of generated source files—.sqlj files (for SQLJ JSP pages) and .java files.

The specified path is taken simply as a file system path (not an application-relative or page-relative path).

Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. See "Summary of ojspc Output Files, Locations, and Related Options" on page 6-38 for more information.

The default is to use the current directory (your current directory when you executed ojspc).

It is recommended that you use this option to place generated source files into a clean directory so that you conveniently know what files have been produced.

-verbose (boolean; ojspc default: false)

Enable this option to direct ojspc to report its translation steps as it executes.

The following example shows -verbose output for the translation of myerror.jsp (in this example, ojspc is run from the directory where myerror.jsp is located; assume % is a UNIX prompt):

% ojspc -verbose myerror.jspTranslating file: myerror.jsp

Note: In an on-demand translation scenario, the OracleJSP sqljcmd configuration parameter provides related functionality, allowing you to specify an alternative SQLJ translator or specify SQLJ option settings. See "OracleJSP Configuration Parameters (Non-OSE)" on page A-15.

Notes:

■ In environments such as Windows NT that allow spaces in directory names, enclose the directory name in quotes.

■ In an on-demand translation scenario, the OracleJSP page_repository_root configuration parameter provides related functionality. See "OracleJSP Configuration Parameters (Non-OSE)" on page A-15.



1 JSP files translated successfully.Compiling Java file: ./_myerror.java

-version (boolean; ojspc default: false)

Enable this option for ojspc to display the OracleJSP version number and then exit.

Summary of ojspc Output Files, Locations, and Related OptionsBy default, ojspc generates the same set of files that are generated by the OracleJSP translator in an on-demand translation scenario and places them in or under the current directory (from which ojspc was executed).

Here are the files:

■ a .sqlj source file (SQLJ JSP pages only)

■ a .java source file

■ a .class file for the page implementation class

■ a .class file for the inner class for static text

■ a Java resource file (.ser) or, optionally, a .class file for the SQLJ profile (SQLJ JSP pages only)

This assumes standard SQLJ code generation. Oracle-specific SQLJ code generation produces no profiles.

■ optionally, a Java resource file (.res) for the static text of the page

For more information about files that are generated by the OracleJSP translator, see "Generated Files and Locations (On-Demand Translation)" on page 6-7.

To summarize some of the commonly used options described under "Option Descriptions for ojspc" on page 6-30, you can use the following ojspc options to affect file generation and placement:

■ -appRoot to specify an application root directory

■ -srcdir to place source files in a specified alternative location

■ -d to place binary files (.class files and Java resource files) in a specified alternative location

■ -noCompile to not compile the generated page implementation class source (as a result of this, no .class files are produced)



In the case of SQLJ JSP pages, translated .java files are still produced, but not compiled.

■ -extres to put static text into a Java resource file

■ -hotload to put static text into a Java resource file and to enable hotloading (relevant only for pages targeting the Oracle9i Servlet Engine)

■ -S-ser2class (SQLJ -ser2class option, for SQLJ JSP pages only) to generate the SQLJ profile in a .class file instead of a .ser Java resource file

For output file placement, the directory structure underneath the current directory (or directories specified by the -d and -srcdir options, as applicable) is based on the package. The package is based on the location of the file being translated relative to the application root, which is either the current directory or the directory specified in the -appRoot option.

For example, presume you run ojspc as follows (presume % is a UNIX prompt):

% cd /abc% ojspc def/ghi/test.jsp

Then the package is _def._ghi and output files will be placed in the directory /abc/_def/_ghi, where the _def/_ghi subdirectory structure is created as part of the process.

If you specify alternate output locations through the -d and -srcdir options, a _def/_ghi subdirectory structure is created under the specified directories.

Now presume ojspc is run from some other directory, as follows:

% cd /home/mydir% ojspc -appRoot /abc /abc/def/ghi/test.jsp

The package is still _def._ghi, according to the location of test.jsp relative to the specified application root. Output files will be placed in the directory /home/mydir/_def/_ghi or in a _def/_ghi subdirectory under locations specified through the -d and -srcdir options. In either case, the _def/_ghi subdirectory structure is created as part of the process.

Notes: It is advisable that you run ojspc once for each directory of your JSP application, so files in different directories can be given different package names, as appropriate.



Overview of the loadjava ToolThe loadjava command-line tool is supplied with Oracle9i to create schema objects from Java files and load them into a specified Oracle9i schema.

For information beyond what is provided here, and for information about the associated dropjava tool (for removing Java source, class, and resource schema objects from Oracle9i), see the Oracle9i Java Tools Reference.

Generally speaking (not for JSP applications in particular), a Java developer can compile Java source on the client and then load the resulting class files, or can load Java source and have it compiled in Oracle9i automatically by the server-side compiler. In the first case, only class schema objects are created. In the second case, both source schema objects and class schema objects are created. In either case, the developer can also load Java resource files, creating resource schema objects.

The loadjava tool accepts source files, class files, resource files, JAR files, and ZIP files on the command line. Source files and class files cannot be loaded simultaneously, however. A JAR file, ZIP file, or loadjava command line can contain source files or class files, but not both. (In either case, resource files can be included.)

A JAR or ZIP file is opened and processed, with each file within the JAR or ZIP file resulting in one or more schema objects.

For OracleJSP, use loadjava as follows:

■ For client-side translation, you will have already translated your JSP pages using ojspc, which, by default, also compiles the translated Java source. Then use loadjava to load the resulting .class files and any resource files (the ojspc -hotload option, for example, produces a resource file), typically all bundled into a JAR file.

Alternatively, you can load the translated .java file instead of the compiled .class files. You can have the server-side compiler compile the .java file as it is being loaded.

■ For server-side translation, use loadjava to load untranslated .jsp files, typically bundled into a JAR file, as resource schema objects. (They will be translated and published later, in the server, as a result of the session shell publishjsp command.)

Following is the complete loadjava option syntax. Brackets, {...}, are not part of the syntax. They are used to surround two possible option formats that are followed by option input.



loadjava {-user | -u} user/password[@database] [options] file.java | file.class | file.jar | file.zip | file.sqlj | resourcefile [-debug] [-d | -definer] [{-e | -encoding} encoding_scheme] [-f | -force] [{-g | -grant} user [, user]...] [-o | -oci8] [ -order ] [-noverify] [-r | -resolve] [{-R | -resolver} "resolver_spec"] [{-S | -schema} schema] [ -stdout ] [-s | -synonym] [-t | -thin] [-v | -verbose]

Of particular significance are the -user and -resolve options (which can be abbreviated to -u and -r, respectively). Use the -user option to specify the schema name and password. Use the -resolve option to specify whether loadjava is to compile (if applicable) and resolve external references in the classes you are loading, after all classes on the command line have been loaded.

If you are loading a .java source file that you want compiled by the server-side compiler during loading, you must enable the -resolve option.

Following is an example for a client-side translation scenario where the JSP page has already been translated and compiled using the ojspc utility, producing file _HelloWorld.class and another .class file for the page implementation inner class (with a name that starts with "_HelloWorld"). Assume % is a UNIX prompt:

% loadjava -u scott/tiger -r _HelloWorld*.class

Or you can bundle the files into a JAR file:

% loadjava -v -u scott/tiger -r HelloWorld.jar

The loadjava -v (-verbose) option, which provides detailed status reporting as loading progresses, is especially useful when you are loading a number of files or compiling in the server.

The following example is also for a client-side translation scenario (_HelloWorld.java is the JSP translator output), but where you have elected to



skip the compilation step on the client (using the ojspc -noCompile option) and instead have the server-side compiler handle the compilation:

% loadjava -v -u scott/tiger -r _HelloWorld.java

The following example is for a server-side translation scenario:

% loadjava -u scott/tiger -r HelloWorld.jsp

Overview of the sess_sh Session Shell ToolThe sess_sh (session shell) tool is provided with Oracle9i as an interactive interface to the session namespace of an Oracle9i instance. You specify connection arguments when you start sess_sh. It then presents you with its $ prompt to indicate that it is ready for commands.

The session shell tool has many commands you can run from the $ prompt, each of which may have its own set of options. For OracleJSP developers, the publishservlet and unpublishservlet commands (for deployment with client-side translation), publishjsp and unpublishjsp commands (for deployment with server-side translation), and createcontext command (for creating OSE servlet contexts) are of primary interest.

Following are the key sess_sh syntax elements for starting the tool:

sess_sh -user user -password password -service serviceURL

■ The -user parameter specifies the user name of the schema.

■ The -password parameter specifies the password for the specified user name.

■ The -service parameter specifies the URL of the database or database cache whose session namespace is to be "opened" by sess_sh. The serviceURL parameter should have one of the three following forms:

sess_iiop://host:port:sidjdbc:oracle:type:spechttp://host[:port]

Following are some general examples:

sess_iiop://localhost:2481:orcljdbc:oracle:thin:@myhost:1521:orclhttp://localhost:8000



Here is an example of a sess_sh command line:

% sess_sh -user SCOTT -password TIGER -service jdbc:oracle:thin:@myhost:5521:orcl

After starting sess_sh, you will see its command prompt:

$

In addition to publish object commands, such as publishservlet and publishjsp, the session shell tool offers shell commands that give the session namespace much of the "look and feel" of a UNIX file system as seen from one of the UNIX shells (such as the C shell). For example, the following sess_sh command displays the published objects and publishing contexts in the /alpha/beta/gamma publishing context (publishing contexts are nodes in the session namespace, analogous to directories in a file system):

$ ls /alpha/beta/gamma

As mentioned previously, key sess_sh commands for OracleJSP developers include the following:

$ publishjsp ...$ unpublishjsp ...$ publishservlet ...$ unpublishservlet ...$ createcontext ...

For information about the publishservlet and unpublishservlet commands, see "Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)" on page 6-69. For information about the publishjsp and unpublishjsp commands, see "Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)" on page 6-46.

Each session shell command has a -describe option to describe its operation, a -help option to summarize its syntax, and a -version option to show its version number.



Note: This document provides only abbreviated discussion of sess_sh syntax and options. It presents only the simplest invocation and usage of the tool.

Beyond what is presented here, for example, commands can be specified within quotes on the sess_sh command line instead of at the $ prompt.

There are also top-level options to connect with plain IIOP instead of the default session IIOP, to specify a role, to connect to the database or database cache with SSL server authentication, and to use a service name instead of an SID in the URL.

For complete information about the sess_sh tool, see the Oracle9i Java Tools Reference.


Deployment to Oracle9i with Server-Side Translation

Deployment to Oracle9i with Server-Side TranslationThis section describes the steps for deployment to Oracle9i with server-side translation.

The steps are as follows:

1. Use loadjava to load untranslated JSP page or SQLJ JSP page source files into Oracle9i.

2. Use the session shell publishjsp command to translate and publish the pages.

The publishjsp step automatically handles translation, compilation, hotloading (if applicable), and publishing.

Loading Untranslated JSP Pages into Oracle9i (loadjava)As the first step for deployment with server-side translation, use the Oracle loadjava tool to load untranslated .jsp or .sqljsp files into Oracle9i as Java resource files.

If you are loading multiple files, it is recommended that you put the files into a JAR file for loading.

The loadjava tool is provided with Oracle9i as a general-purpose tool for loading Java files into the server. For an overview, see "Overview of the loadjava Tool" on page 6-40. For further information, see the Oracle9i Java Tools Reference.

Following is an example of loading an untranslated page:

% loadjava -u scott/tiger Foo.jsp

This loads Foo.jsp into the SCOTT schema (password TIGER) as a Java resource object. There is no need to specify the loadjava -resolve (-r) option.

This will result in the following resource schema object being created in Oracle9i:

■ SCOTT:Foo.jsp

Note that any path information you specify for the .jsp file, either in a JAR file or on the loadjava command line, determines placement of the resource schema object. Consider the following modification of the previous example:

% loadjava -u scott/tiger xxx/yyy/Foo.jsp



This will result in the following resource schema object being created in Oracle9i:

■ SCOTT:xxx/yyy/Foo.jsp

For an overview of how loadjava names the schema objects it produces, see "Database Schema Objects for Java" on page 6-14.

You can also load a .sqljsp file:

% loadjava -u scott/tiger Foo.sqljsp

This loads Foo.sqljsp into the SCOTT schema and will result in the following resource schema object being created in Oracle9i:

■ SCOTT:Foo.sqljsp

If you want to load multiple .jsp (or .sqljsp) files, you can use a wildcard character (depending on your operating environment; assume % is a UNIX prompt):

% loadjava -u scott/tiger *.jsp

Or presume you had put the .jsp files into a JAR file:

% loadjava -u scott/tiger myjspapp.jar

Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)In the scenario of deployment with server-side translation, the translation (.jsp or .sqljsp to .java), compilation (.java to .class), hotloading (if enabled), and publishing all occur as the result of executing the Oracle9i session shell publishjsp command. See "Overview of the sess_sh Session Shell Tool" on page 6-42 for how to start the session shell and connect to Oracle9i.

Run publishjsp after you have loaded a .jsp (or .sqljsp) file into Oracle9i as a resource schema object. (This section includes separate discussion for running publishjsp on a .sqljsp file because there are some logistical differences in the results.)

Note: JSP pages that are published with publishjsp can be "unpublished" (removed from the Oracle9i JNDI namespace) with the session shell unpublishjsp command. See "Unpublishing JSP Pages with unpublishjsp" on page 6-58.



Overview of publishjsp Syntax and OptionsStarting sess_sh establishes a connection to Oracle9i. Once you start sess_sh, you can run the publishjsp command from the session shell $ prompt.

The publishjsp command uses the following general syntax:

$ publishjsp [options] path/name.jsp

The options can be any of the following:

-context context [-schema schemaname] [-virtualpath path] [-servletName name] [-packageName name] [-hotload] [-stateless] [-verbose] [-extend class] [-implement interface] [-resolver resolver]

The file name.jsp (or name.sqljsp for a SQLJ JSP page) is the JSP page resource schema object that you loaded with loadjava and is a required parameter, along with any relevant schema path information.

In addition, you should always specify a -context setting.

By default, if no -virtualpath option is specified, path/name.jsp becomes the servlet path. For example, running publishjsp on dir1/foo.jsp (the path within the current schema or specified schema) results in dir1/foo.jsp as the servlet path.

Together, the context path and servlet path (along with the host name and port) determine the URL to invoke the page, as described in "URLs for the Oracle9i Servlet Engine" on page 6-17.

The following informative options are also available:

■ Use -showVersion by itself to display the OracleJSP version number and exit.

■ Use -usage by itself to display a publishjsp option list and exit.

Important:

■ Enable boolean options, such as -hotload, by typing only the option name in the command line (as opposed to setting it to true).

■ For options where you specify a value, the value does not have to be in quotes.



Following are the option descriptions:

■ -context context

Use this option to specify a servlet context in the Oracle9i Servlet Engine. The context path of this servlet context becomes part of the URL used to invoke the page.

Any specified context should be under the appropriate Web domain, as follows:

/domain_name/contexts/context_name

(Where domain_name represents the name of the particular domain.)

■ -schema schemaname

Use this option to specify the schema where the JSP page resource schema object is located, if it is not in the same schema you logged in to through sess_sh.

This schema must be accessible from your sess_sh login schema. The publishjsp command does not offer a way to specify passwords.

■ -virtualpath path

You can use this option to specify an alternative servlet path for the JSP page; otherwise, the servlet path is simply the specified .jsp file name itself along with any specified schema path.

For example:

-virtualpath altpath/Foo.jsp

Important:

■ Always specify a -context setting.

■ Remember it is the context path of the servlet context, not the context name itself, that is used in URLs to access the page.

When a servlet context is created in OSE with the session shell createcontext command, both the context path (through the createcontext -virtualpath option) and the context name must be specified. It is convenient, and probably typical, to specify the context name and context path to be the same, but it is not required.



Or perhaps simply:

-virtualpath mypath.jsp

■ -servletName name

You can use this option to specify an alternative servlet name (in OSE named_servlets) for the JSP page; however, the servlet name has no bearing on how the page is invoked, so is rarely needed.

By default, the servlet name is based on the base name of the .jsp file along with any path you specified. For example, running publishjsp on SCOTT:dir1/Foo.jsp results in _dir1._Foo as the servlet name in OracleJSP release 1.1.3.x (Be aware that implementation details are subject to change in future releases.)

■ -packageName name

You can use this option to specify a package name for the generated page implementation class; otherwise, it is based on any path specification for the .jsp file when you run publishjsp. For example, running publishjsp on SCOTT:dir1/Foo.jsp results in package _dir1 for the page implementation class.

The -packageName option affects where schema objects are placed in the schema, but does not affect the servlet path of the JSP page.

Also be aware that if no -servletName setting is specified, the -packageName setting is also reflected in the servlet name. Consider the following example:

$ publishjsp -packageName mytestpkg -verbose simple1_a.jsp

This results in the following servlet name:

mytestpkg._simple1__a.jsp

Important: If you use the publishjsp -servletName option, you must also use the unpublishjsp -servletName option if you unpublish the page. Therefore, when you publish the page, it is advisable to use the publishjsp -verbose option to verify the resulting servlet name.



However, if a -servletName setting is specified, its effect on the servlet name overrides the effect of the -packageName setting.

■ -hotload

Enable this flag to enable and perform hotloading. This results in the following steps being performed automatically by the publishjsp command:

1. Static output is written to a resource schema object instead of to the page implementation class schema object.

2. A main() method and a hotloading method are implemented in the generated page implementation class to allow hotloading.

3. The main() method is executed to perform hotloading.

To use -hotload, you must have permission for the Oracle9i hotloader. This can be granted as follows (from SQL*Plus, for the SCOTT schema, for example):

dbms_java.grant_permission(’SCOTT’, ’SYS:oracle.aurora.security.JServerPermission’, ’HotLoader’, null);

For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle9i" on page 6-24.

■ -stateless

This is a boolean option that tells the Oracle9i Servlet Engine that the JSP page is to be stateless—the JSP page should not have access to the HttpSession object during execution.

This flag is used for mod_ose optimization. For information about the Apache mod_ose module, see the Oracle9i Servlet Engine Developer’s Guide.

■ -verbose

Set this option to true to direct publishjsp to report the translation steps as it executes.

Important: If you use the publishjsp -packageName option, you must use the unpublishjsp -servletName option if you unpublish the page. Therefore, when you publish the page, it is advisable to use the publishjsp -verbose option to verify the resulting servlet name.



■ -extend

Use this option to specify a Java class that the generated page implementation class will extend.

■ -implement

Use this option to specify a Java interface that the generated page implementation class will implement.

■ -resolver

Use this option to specify an alternative Java class resolver. The resolver is used in compiling and resolving Java source through loadjava, including locating classes used in JSP pages.

The default resolver is ((* user) (* PUBLIC)). For the SCOTT schema, for example, this is the following:

((* SCOTT) (* PUBLIC))

For the -resolver option, you must specify the value in quotes as in the following example:

$ publishjsp ... -resolver "((* BILL) (* SCOTT) (* PUBLIC))" ...

Examples: Publishing JSP Pages with publishjspThis section provides examples of using publishjsp to translate and publish .jsp pages in Oracle9i. The pages will have already been loaded as resource schema objects in a particular schema, such as SCOTT:Foo.jsp.

(For information about running publishjsp on .sqljsp pages, see "Publishing SQLJ JSP Pages with publishjsp" on page 6-55.)

To review how the servlet path and context path combine in forming the URL to invoke the page, see "URLs for the Oracle9i Servlet Engine" on page 6-17.

Example Notes These notes apply to the examples that follow:

■ The examples use the SCOTT schema. SCOTT must either be the schema specified when starting sess_sh, or accessible from the schema specified.

■ Each example lists the schema objects that are created, although this is secondary. All that matters in invoking the JSP page is the servlet path and context path. The page implementation class schema object is automatically mapped during the publishjsp publishing step. Note that default package



names and output schema object names have underscores in them, even though the original JSP resource schema object name and resulting servlet path do not have underscores. Again, this is secondary and does not impact the user.

■ Application-relative and page-relative syntax for dynamic jsp:include and jsp:forward statements inside Oracle9i is the same as for any JSP environment. The relative paths are according to how the JSP pages were published (as shown in the examples below).

■ The exact names of generated schema objects may change in future releases, but will still have the same general form. The names would always include the base name (such as "Foo" in these examples), but may include slight variations.

■ $ is the sess_sh prompt.

Example 1

$ publishjsp -schema SCOTT dir1/Foo.jsp

This uses the default servlet context of the relevant OSE Web domain, so the context path is "/".

The default servlet path is dir1/Foo.jsp.

After this command, Foo.jsp can be invoked as follows:

http://host[:port]/dir1/Foo.jsp

Access it dynamically from another JSP page in the application, suppose a page published as dir1/Bar.jsp, as follows (using page-relative syntax and then application-relative syntax):

<jsp:include page="Foo.jsp" flush="true" />

or:

<jsp:include page="/dir1/Foo.jsp" flush="true" />

By default, _dir1 is the Java package for the page implementation class and inner class. The following schema objects are created:

■ SCOTT:_dir1/_Foo source schema object

■ SCOTT:_dir1/_Foo class schema object

■ a class schema object for the inner class for static text (with "Foo" in the name, such as SCOTT:_dir1/_Foo$__jsp_StaticText)



Example 2

$ publishjsp -schema SCOTT -context /scottRoot/contexts/scottContext Foo.jsp

Presume scottContext had been created as follows:


The publishjsp command publishes the page to the scottContext servlet context, which was created with /ose specified as the context path.

The default servlet path is simply Foo.jsp.

After this command, Foo.jsp can be invoked as follows (assume port 8088 for the Web service):

http://host:8088/ose/Foo.jsp

Access it dynamically from another JSP page in the application, suppose a page published as Bar.jsp, as follows (using page-relative syntax and then application-relative syntax):


or:

<jsp:include page="/Foo.jsp" flush="true" />

Even though this example specifies a non-default servlet context, that is not relevant for dynamic jsp:include or jsp:forward commands. What is relevant is that the published path of the page relative to that context is simply /Foo.jsp.

By default, there is no Java package for the page implementation class and inner class (because no path is specified in the SCOTT schema). The following schema objects are created:

■ SCOTT:_Foo source schema object

■ SCOTT:_Foo class schema object

■ a class schema object for the inner class for static text (with "Foo" in the name, such as SCOTT:_Foo$__jsp_StaticText)



Example 3

$ publishjsp -schema SCOTT -context /scottRoot/contexts/scottContext dir1/Foo.jsp

Presume scottContext had been created as follows:


The publishjsp command publishes the page to the scottContext servlet context, which was created with /ose specified as the context path.

The default servlet path is dir1/Foo.jsp.

After this command, Foo.jsp can be invoked as follows (assume port 8088 for the Web service):

http://host:8088/ose/dir1/Foo.jsp



or:


Example 1 and Example 3 use different servlet contexts, but in either case what is relevant for the application-relative include command is that the published path of the page relative to that context is /dir1/Foo.jsp.

By default, _dir1 is the Java package for the page implementation class and inner class. The following schema objects are created:



■ a class schema object under _dir1 for the inner class for static text (with "Foo" in the name, such as SCOTT:_dir1/_Foo$__jsp_StaticText)



Example 4

$ publishjsp -schema SCOTT -hotload -packageName mypkg dir1/Foo.jsp

This performs hotloading, uses the default servlet context of the relevant OSE Web domain, and overrides the default _dir1 package.

The context path is "/".

The -packageName option does not affect the servlet path, which, by default, remains dir1/Foo.jsp.

After this command, Foo.jsp can be invoked as follows:

http://host[:port]/dir1/Foo.jsp



or:


The following schema objects are created:

■ SCOTT:mypkg/_Foo source schema object

■ SCOTT:mypkg/_Foo class schema object

■ a class schema object under mypkg for the inner class (with "Foo" in the name, such as SCOTT:mypkg/_Foo$__jsp_StaticText)

■ SCOTT:mypkg/_Foo.res resource schema object for the static text that is normally in the inner class (the resource is hotloaded as part of publishjsp functionality)

Publishing SQLJ JSP Pages with publishjspThis section provides an example of using publishjsp to translate and publish a .sqljsp page in Oracle9i. The page will have already been loaded as a resource schema object in a particular schema, such as SCOTT:Foo.sqljsp.

In addition, see "Examples: Publishing JSP Pages with publishjsp" on page 6-51.

To review how the servlet path and context path combine in forming the URL to invoke the page, see "URLs for the Oracle9i Servlet Engine" on page 6-17.



Be aware of the following for .sqljsp pages:

■ Beyond what is created for a .jsp page, an additional schema object is created—a resource schema object for the SQLJ profile. This is always a .ser resource schema object, as opposed to a class schema object, because there is no SQLJ -ser2class option when translating in the server.


■ The generated source schema object is SQLJ source instead of Java source.

■ SQLJ has very limited option support in the server.

Server-Side SQLJ Options Client-side SQLJ options are not available for translation in the server (this is true in general, not just for JSP pages). Instead, there is a small set of options available through the standard Oracle9i JAVA$OPTIONS table. These options can be set through the dbms_java.set_compiler_option() stored procedure (using SQL*Plus, for example). Of these options, only the following is supported for JSP pages:

■ online

This is a boolean option that enables online semantics-checking through the default oracle.sqlj.checker.OracleChecker front-end.

For more information about server-side SQLJ and semantics-checking, see the Oracle9i SQLJ Developer’s Guide and Reference.

Example of publishjsp for SQLJ JSP Page This section presents an example of publishjsp usage for a .sqljsp page ($ is the sess_sh prompt). Be aware of the following:

■ This example uses the SCOTT schema. SCOTT must either be the schema specified when starting sess_sh, or accessible from the schema specified.

■ This example documents the schema objects that are created, although this is secondary. All that matters in invoking the JSP page is the servlet path and context path. The page implementation class schema object is automatically




mapped during the publishjsp publishing step. Note that default package names and output schema object names have underscores in them, even though the original SQLJSP resource schema object name and resulting servlet path do not have underscores. Again, this is secondary and does not impact the user.

■ The exact names of generated schema objects may change in future releases, but will still have the same general form. The names would always include the base name (such as "Foo" in these examples), but may include slight variations, such as _Foo instead of Foo.

Here is the example:

$ publishjsp -schema SCOTT dir1/Foo.sqljsp

This uses the default OSE servlet context, the context path of which is "/".

The servlet path, by default, is dir1/Foo.sqljsp.

After this command, Foo.sqljsp can be invoked as follows:

http://host[:port]/dir1/Foo.sqljsp


<jsp:include page="Foo.sqljsp" flush="true" />

or:

<jsp:include page="/dir1/Foo.sqljsp" flush="true" />

By default, _dir1 is the Java package for the page implementation class and inner class, based on the specified path in the SCOTT schema. The following schema objects are created:



■ a class schema object under _dir1 for the inner class for static text (with "Foo" in the name, such as SCOTT:_dir1/_Foo$__jsp_StaticText)

■ a resource schema object under _dir1 for the SQLJ profile, if applicable (with "Foo" in the name, such as SCOTT:_dir1/_Foo_SJProfile0.ser)



Unpublishing JSP Pages with unpublishjspThe sess_sh tool also has an unpublishjsp command that removes a JSP page from the Oracle9i JNDI namespace. This does not, however, remove the page implementation class schema object from Oracle9i.

Unlike the unpublishservlet command, you do not need to specify a servlet name (unless you specified one when you ran publishjsp). Generally, the only required input is the servlet path (sometimes referred to as the "virtual path").

Following is the general syntax:

$ unpublishjsp [-servletName name] [-context context] [-showVersion] [-usage] [-verbose] servletpath

As an example, here is the command to unpublish the page that was published in Example 1 on page 6-52:

$ unpublishjsp dir1/Foo.jsp

The -servletName, -context, -showVersion, -usage, and -verbose options are the same as for publishjsp, as described in "Overview of publishjsp Syntax and Options" on page 6-47.

In using unpublishjsp, remember the following:

■ If you used the publishjsp -context option in publishing the page, use the unpublishjsp -context option with the same setting when you unpublish the page.

■ If you used the publishjsp -servletName or -packageName option in publishing a page, you must use the unpublishjsp -servletName option to specify the resulting servlet name when you unpublish the page. For information about how these publishjsp options affect the servlet name, see the option descriptions in "Overview of publishjsp Syntax and Options" on page 6-47.

Note: If you use the publishjsp -schemaName or -packageName option in publishing a JSP page, it is advisable to also use the -verbose option to verify the servlet name for later use in unpublishjsp.


Deployment to Oracle9i with Client-Side Translation

Deployment to Oracle9i with Client-Side TranslationThis section describes the steps for deployment to Oracle9i with client-side translation.

The steps are as follows:

1. Use ojspc to pre-translate JSP pages or SQLJ JSP pages on the client.

2. Use loadjava to load files into Oracle9i—.class files (or, optionally, .java or .sqlj files instead) and any Java resource files resulting from the page translation.

3. Optionally "hotload" the pages in Oracle9i (if hotloading was enabled during translation). See "Overview of Hotloaded Classes in Oracle9i" on page 6-24 for background information about hotloading.

4. Use the session shell publishservlet command to publish the pages.

Pre-Translating JSP Pages (ojspc)To pre-translate JSP pages on a client (typically for pages that will run in the Oracle9i Servlet Engine), use the ojspc command-line tool to invoke the OracleJSP translator.

For general information about ojspc and description of its options, see "The ojspc Pre-Translation Tool" on page 6-26.

The rest of this section covers the following topics:

■ Simplest ojspc Usage

■ ojspc for SQLJ JSP Pages

■ Enabling Hotloading with ojspc

■ Other Key ojspc Features and Options for Deployment to Oracle9i

■ ojspc Examples

Note: For simplicity and convenience, deployment with server-side translation is generally recommended. See "Deployment to Oracle9i with Server-Side Translation" on page 6-45.



Simplest ojspc UsageThe following example shows the simplest usage of ojspc:

% ojspc Foo.jsp

With this invocation, the following files are produced:

■ _Foo.java

■ _Foo.class

■ _Foo$__jsp_StaticText.class for the inner class for static content

By default, all output goes to the current directory, from which ojspc was run.

ojspc for SQLJ JSP PagesThe ojspc tool also accepts .sqljsp files for JSP pages that use SQLJ code, as follows:

% ojspc Foo.sqljsp

For .sqljsp files, ojspc automatically invokes the SQLJ translator as well as the JSP translator.

With this invocation, the following files are produced:

■ _Foo.sqlj (produced from Foo.sqljsp by the JSP translator)

■ _Foo.java (produced from _Foo.sqlj by the SQLJ translator)

■ _Foo.class

■ _Foo$__jsp_StaticText.class for the inner class for static content

■ a Java resource file (.ser) or class file (.class), depending on the setting of the SQLJ -ser2class option, for the SQLJ "profile" (with "Foo" in the name)

Note: The exact names of generated files may change in future releases, but will still have the same general form. The names would always include the base name (such as "Foo" in these examples), but may include slight variations.




By default, all output goes to the current directory, from which ojspc was run.

Enabling Hotloading with ojspcUse the ojspc -hotload option to enable hotloading, which (among other things) results in static page content going into a Java resource file instead of into the inner class of the page implementation class.

The following example translates the page and directs the OracleJSP translator to enable hotloading:

% ojspc -hotload Foo.jsp

With this command, the translator will generate the following output:

■ _Foo.java (as usual)

■ _Foo.class (as usual)

■ _Foo.res, a Java resource file to contain the static page content

■ _Foo$__jsp_StaticText.class for the inner class, as usual, although the static content goes into Foo.res instead of going into the inner class

Be aware that the ojspc -hotload option merely enables hotloading; it does not actually hotload the page. Hotloading requires an additional deployment step, as described in "Hotloading Page Implementation Classes in Oracle9i" on page 6-68.

For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle9i" on page 6-24.

Other Key ojspc Features and Options for Deployment to Oracle9i The following ojspc options, fully described in "Option Descriptions for ojspc" on page 6-30, are especially useful:

■ -appRoot—Set an application root directory if you do not want the default (the current directory, from which ojspc was run).




■ -noCompile—Enable this flag if you do not want to compile .java or .sqlj files during translation. You would do this, for example, if you want to load the translated page into Oracle9i as a .java file and have compilation performed by the server-side compiler.

In the case of SQLJ JSP pages, translated .java files are still produced, but not compiled.

■ -d—Specify the directory where ojspc will place the generated binary files (.class files and Java resource files). This makes it easier to know what was generated, and therefore what needs to be loaded into Oracle9i.

■ -srcdir—Specify the directory where ojspc will place the generated .java or .sqlj source files. For example, this would be useful instead of -d if you are enabling -noCompile and will load your translated page into Oracle9i as .java source.

■ -extres—Direct the OracleJSP translator to put static content into a Java resource file instead of into the inner class of the page implementation class.

■ -hotload—Direct the OracleJSP translator to put static content into a Java resource file instead of into the inner class of the page implementation class, and generate code in the page implementation class to enable hotloading.

■ -S—For SQLJ JSP pages, use the -S prefix to set an Oracle SQLJ option; ojspc will pass the option setting to the Oracle SQLJ translator. (You can have multiple -S settings in the ojspc command line.)

ojspc ExamplesThe following examples show the use of key ojspc options.

Example 1

% ojspc -appRoot /myroot/pagesrc -d /myroot/bin -hotload /myroot/pagesrc/Foo.jsp

This example accomplishes the following:

■ Specifies an application root for application-relative static include directives in the translated page.

■ Enables hotloading and produces the Java resource file _Foo.res for static content.

■ Places _Foo.java into the current directory, by default. There is no package, because Foo.jsp is directly under the specified application root directory.



■ Places _Foo.class, _Foo.res, and the .class file for the inner class into the /myroot/bin directory.

Example 2

% ojspc -appRoot /myroot/pagesrc -srcdir /myroot/gensrc -noCompile -extres /myroot/pagesrc/Foo.jsp



■ Produces the Java resource file _Foo.res for static content (without enabling hotloading).

■ Places _Foo.java into the /myroot/gensrc directory. There is no package, because Foo.jsp is directly under the specified application root directory.

■ Does not compile _Foo.java (no .class files are produced).

■ Places _Foo.res into the current directory, by default.

Example 3

% ojspc -appRoot /myroot/pagesrc -d /myroot/bin -extres -S-ser2class true /myroot/pagesrc/Foo.sqljsp



■ Produces the Java resource file _Foo.res for static content (without enabling hotloading).

■ Places _Foo.sqlj and _Foo.java into the current directory, by default. There is no package, because Foo.jsp is directly under the specified application root directory.

■ Places _Foo.class, _Foo.res, a .class file for the inner class, and a .class file for the SQLJ profile into the /myroot/bin directory. (Without the SQLJ -ser2class option setting, the profile would be generated in a .ser Java resource file instead of a .class file.)



Loading Translated JSP Pages into Oracle9i (loadjava)After client-side pre-translation, use the Oracle loadjava tool to load generated files into Oracle9i. You can use either of the following scenarios:

■ Load .class files and Java resource files (if any).

■ Use the ojspc -noCompile option during translation, then load the translated .java file and resource files (if any). The .java file can be compiled by the Oracle9i server-side compiler during loading.

In either case, whenever you have multiple files it is recommended that you put the files into a JAR file for loading.

The loadjava tool is provided with Oracle9i as a general-purpose tool for loading Java files into the database or database cache. For an overview, see "Overview of the loadjava Tool" on page 6-40. For further information, see the Oracle9i Java Tools Reference.

Loading Class Files with loadjavaAssume you translated a JSP page Foo.jsp with the ojspc -extres or -hotload option enabled, producing the following files:

■ _Foo.java

Note: As Example 3 shows, you can use an explicit true setting in enabling a SQLJ boolean option through the -S option setting. This is in contrast to ojspc boolean options, such as -extres, which do not take an explicit true setting.

Important: In the next two subsections, "Loading Class Files with loadjava" and "Loading Java or SQLJ Source Files with loadjava", be aware of the following important considerations.

■ Even when you enable the -extres or -hotload option to place static text into a resource file, the page implementation inner class is still produced and must still be loaded.

■ Like a Java compiler, loadjava resolves references to classes, but not to resources; be sure to correctly load the resource files your classes need—they must be in the same package as the .java file.



■ _Foo.class

■ _Foo$__jsp_StaticText.class

■ _Foo.res

You can ignore _Foo.java, but the binary files (.class and .res) must all be loaded into Oracle9i. Typically, you would put _Foo.class, _Foo$__jsp_StaticText.class, and _Foo.res into a JAR file, suppose Foo.jar, and load it as follows (assume % is a UNIX prompt):

% loadjava -v -u scott/tiger -r Foo.jar

The -u (-user) option specifies the user name and password for the Oracle9i schema; the -r (-resolve) option resolves the classes as they are loaded. Optionally use the -v (-verbose) option for detailed status output.

Alternatively, you can load the files individually, as follows. (The syntax depends on your operating environment. In these examples, assume % is a UNIX prompt.)

% loadjava -v -u scott/tiger -r _Foo*.class _Foo.res

or:

% loadjava -v -u scott/tiger -r _Foo*.*

All these examples result in the following schema objects being created in Oracle9i (you typically need to know only the name of the page implementation class schema object):

■ SCOTT:_Foo page implementation class schema object

Or there may be an additional package designation, according to either the ojspc -packageName option or the relative location of the .jsp file to the current directory when you ran ojspc. For example, a -packageName setting of abc.def results in that being the package of the _Foo class, so there would be a SCOTT:abc/def/_Foo class schema object.

Note: Generated names used here are provided as examples only. Such implementation details are subject to change in future releases, although the base name (such as "Foo" here) will always be part of the generated names.



■ SCOTT:abc/def/_Foo$__jsp_StaticText class schema object

With the same package designation as the page implementation class.

■ SCOTT:abc/def/_Foo.res resource schema object

With a package designation according to any path specification, either in a JAR file or on the loadjava command line, when it was loaded.


Loading Java or SQLJ Source Files with loadjavaAssume that you translated a JSP page, Foo.jsp, with the ojspc -noCompile and -extres options enabled, producing the following files:

■ _Foo.java (which you want to load into Oracle9i as source to be compiled by the server-side compiler)

■ _Foo.res

Typically, you would put _Foo.java and _Foo.res into a JAR file, suppose Foo.jar, and load it as follows:

% loadjava -v -u scott/tiger -r Foo.jar

When you enable the loadjava -r (-resolve) option, this results in the source file being compiled automatically by the server-side compiler, producing class schema objects. The -u (-user) option specifies the user name and password for the Oracle9i schema. Optionally use the -v (-verbose) option for detailed status reporting.

Alternatively, you can load the files individually:

% loadjava -v -u scott/tiger -r _Foo.java _Foo.res

Note: If you are loading a pre-translated SQLJ JSP page, you must also load the generated profile file, if applicable—either a .ser Java resource file or a .class file, depending on the SQLJ -ser2class option. If it is a .ser file, schema object naming is comparable to that of a .res Java resource file; if it is a .class file, schema object naming is comparable to that of the other .class files.



Or load them using a wildcard character:

% loadjava -v -u scott/tiger -r _Foo.*

All these examples result in the following schema objects being created in Oracle9i (you typically need to know only the name of the page implementation class schema object):

■ SCOTT:_Foo source schema object

When you load a source file into Oracle9i with loadjava, the source is stored separately as a source schema object, in addition to the class schema objects produced by the server-side compiler.

■ SCOTT:_Foo page implementation class schema object

Or there may be an additional package designation for the _Foo class and source schema objects, according either to the ojspc -packageName option or the relative location of the .jsp file to the current directory when you ran ojspc. For example, a -packageName setting of abc.def results in that being the package of the _Foo class, so you would have a SCOTT:abc/def/_Foo class schema object.

■ SCOTT:_Foo$__jsp_StaticText class schema object


■ SCOTT:_Foo.res resource schema object





Hotloading Page Implementation Classes in Oracle9iTo optionally "hotload" translated JSP pages in Oracle9i, use the session shell java command to invoke the main() method of the page implementation class schema object. See "Overview of the sess_sh Session Shell Tool" on page 6-42 for how to start the tool and connect to the database or database cache.

You are required to have previously enabled hotloading through the ojspc -hotload option during translation. The -hotload option results in a main() method and hotloading method being implemented in the page implementation class. Invoking the main() method calls the hotloading method and hotloads the page implementation class.

Here is an example ($ is the sess_sh prompt):

$ java SCOTT:_Foo

Assuming _Foo is a class that was translated with the -hotload option enabled and was then loaded with loadjava into the SCOTT schema as in earlier examples, this session shell java command will hotload the static text portion of the _Foo page implementation class.

For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle9i" on page 6-24. For more information about the session shell java command, see the Oracle9i Java Tools Reference.

Notes:

■ Generated names used here are provided as examples only. Such implementation details are subject to change in future releases, although the base name (such as "Foo" here) will always be part of generated names.

■ If you are loading translated source (.java) for a SQLJ JSP page, you must also load the generated profile file, if applicable—either a .ser Java resource file or a .class file, depending on the SQLJ -ser2class option. If it is a .ser file, schema object naming is comparable to that of a .res Java resource file; if it is a .class file, schema object naming is comparable to that of other .class files. (Remember that the ojspc -noCompile option prevents Java compilation, but not SQLJ translation.)



Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)To publish translated pages as part of the "deployment with client-side translation" scenario, use the session shell publishservlet command. See "Overview of the sess_sh Session Shell Tool" on page 6-42 for how to start the tool and connect to Oracle9i.

The publishservlet command is for general use in publishing any servlet to run in OSE, but also applies to JSP page implementation classes (which are essentially servlets).

Overview of publishservlet Syntax and OptionsStarting sess_sh establishes a connection to Oracle9i. Once you start sess_sh, you can run the publishservlet command from the session shell $ prompt.

The publishservlet command uses the following general syntax:

$ publishservlet context servletName className -virtualpath path [-stateless] [-reuse] [-properties props]

When using publishservlet, you must specify the following:

■ a servlet context (context in the command line above)

This is required by publishservlet. You can use the default servlet context of the relevant Web domain:

/domain_name/contexts/default

This results in a context path of "/".

If you specify some other servlet context, then the context path of that servlet context will be used.

For example, if you specify a servlet context, mycontext, created as follows:


Then /ose will be the context path for the published JSP page.

Note: Servlets and JSP pages that are published with publishservlet can be "unpublished" (removed from the Oracle9i JNDI namespace) with the session shell unpublishservlet command. See "Unpublishing JSP Pages with unpublishservlet" on page 6-72.



■ a servlet name (servletName in the command line above)

This is required by publishservlet to specify the name for the JSP page in the named_servlets directory, but has no practical use for the JSP developer or user other than for unpublishing. It can be an arbitrary name.

■ a class name (className in the command line above)

This is the name of the page implementation class schema object being published.

■ a servlet path (referred to on the command line as the "virtual path")

Use the -virtualpath option. This is required for a JSP page, although it is optional for publishing servlets in general.

Together, the context path and servlet path (along with the host name and port) determine the URL to invoke the page, as described in "URLs for the Oracle9i Servlet Engine" on page 6-17.

In addition to the required parameters, you can specify any of the following options:

■ -stateless

This is a boolean option that tells the Oracle9i Servlet Engine that the JSP page is to be stateless—it should not have access to the HttpSession object during execution.

■ -reuse

This is a boolean option to specify a new servlet path (referred to as the "virtual path") for a JSP page. If you enable it, then the specified servlet path will be

Important:

■ The servlet context, servlet name, and class name are not preceded by any designating syntax, so must appear on the command line in the above order relative to each other. (Any publishservlet options can be intermixed with these parameters, however.)

■ Enable boolean options, such as -stateless, by typing only the option name in the command line (as opposed to setting it to true).



linked to the specified servlet name in the JNDI namespace without publishservlet going through the complete publishing process.

When you enable the -reuse option, specify a new servlet path, the servlet context, and a previously published servlet name.

■ -properties props

Use this option to specify properties to be passed to the JSP page as initialization parameters upon execution.

For more information about the publishservlet command, see the Oracle9i Java Tools Reference.

Example: Publishing JSP Pages with publishservletThe following example publishes a JSP page that has been loaded into Oracle9i ($ is the sess_sh prompt):

$ publishservlet /scottRoot/contexts/default -virtualpath Foo.jsp FooServlet SCOTT:_Foo

For simplicity, the default servlet context (of the /scottRoot domain) is specified, resulting in "/" as the context path.

Foo.jsp will be the servlet path. (You can specify any name you want for the servlet path, but naming it according to the original source file name is a good convention.)

FooServlet will be the servlet name in the OSE named_servlets directory, but this name generally will not be used, except for unpublishing.

SCOTT:_Foo is the page implementation class schema object being published.

After the above publishservlet command, the end user would invoke the JSP page with a URL as follows:

http://host[:port]/Foo.jsp

Access it dynamically from another JSP page in the application, suppose a page published as Bar.jsp, as follows (using page-relative syntax and then application-relative syntax):


or:

<jsp:include page="/Foo.jsp" flush="true" />



Unpublishing JSP Pages with unpublishservletThe sess_sh tool also has an unpublishservlet command that removes a servlet or JSP page from the Oracle9i JNDI namespace. This does not, however, remove the servlet class schema object or page implementation class schema object from Oracle9i.

Specify the context, servlet path (referred to on the command line as the "virtual path"), and servlet name. Following is the general syntax to unpublish a JSP page:

$ unpublishservlet -virtualpath path context servletName

For example, to unpublish the page that was published in the previous section:

$ unpublishservlet -virtualpath Foo.jsp /scottRoot/contexts/default FooServlet

Note: Both the servlet path and the servlet name specified in the publishservlet command are entered into the Oracle9i JNDI namespace, although only the servlet path is generally of interest to JSP users. OSE uses JNDI to look up any published JSP page or servlet.


Additional JSP Deployment Considerations

Additional JSP Deployment ConsiderationsMost of this chapter focuses on translation and deployment when targeting the Oracle9i Servlet Engine, because running in Oracle9i is a special situation requiring special considerations and logistics.

This section covers a variety of additional deployment considerations and scenarios, mostly for situations where you are not targeting OSE.


■ Doc Root for Oracle9i Application Server Versus Oracle9i Servlet Engine

■ Use of ojspc for Pre-Translation for Non-OSE Environments

■ General JSP Pre-Translation Without Execution

■ Deployment of Binary Files Only

■ WAR Deployment

■ Deployment of JSP Pages with JDeveloper

Doc Root for Oracle9i Application Server Versus Oracle9i Servlet EngineBoth the Oracle9i Servlet Engine and the Oracle9i Application Server use the Oracle HTTP Server, essentially an Apache environment, as a Web server for HTTP requests. However, each environment uses its own doc root.

JSP pages and servlets running in the Oracle9i Servlet Engine, which are routed through the Apache mod_ose module provided by Oracle, use the OSE doc root of the relevant servlet context. OSE doc root directories are in the file system, but are linked to the Oracle9i JNDI mechanism.

Remember that for JSP pages running in OSE, only static files are located in or under the doc root. JSP pages are in the database or database cache.

The doc root directory for an OSE servlet context is specified using the session shell createcontext command -docroot option when the servlet context is created. For the default servlet context of the OSE default Web service, admin, the doc root is the [ORACLE_HOME]/jis/public_html directory. (It is possible to have a null doc root, although this may lead to undesirable behavior because the default OSE installation uses the doc root for error mapping.)

JSP pages and servlets running in the Apache/JServ environment of the Oracle9i Application Server (release 1.0.x), which are routed through the Apache mod_jserv module provided with JServ, use the Apache doc root. This doc root



(typically htdocs) is set in the DocumentRoot command of the Apache httpd.conf configuration file.

For JSP pages running in JServ, JSP pages as well as static files are located in or under the doc root.

If you are migrating between the Apache/JServ environment and the OSE environment, move or copy static files to the appropriate doc root.

Use of ojspc for Pre-Translation for Non-OSE EnvironmentsThe Oracle ojspc tool, described in detail in "The ojspc Pre-Translation Tool" on page 6-26, is typically used for client-side JSP translation for deployment to Oracle9i. However, you can use ojspc to pre-translate JSP pages in any environment, which may be useful in saving end users the translation overhead the first time a page is executed.

If you are pre-translating in some environment other than the target environment, specify the ojspc -d option to set an appropriate base directory for placement of generated binary files.

As an example, consider an Apache/JServ environment with the following JSP source file:

htdocs/test/foo.jsp

A user would invoke this with the following URL:

http://host[:port]/test/foo.jsp

During on-demand translation at execution time, the OracleJSP translator would use a default base directory of htdocs/_pages for placement of generated binary files. Therefore, if you pre-translate, you should set htdocs/_pages as the base directory for binary output, such as in the following example (assume % is a UNIX prompt):

% cd htdocs% ojspc -d _pages test/foo.jsp

The URL noted above specifies an application-relative path of test/foo.jsp, so at execution time the OracleJSP container looks for the binary files in a _test

Note: For an overview of the role of the Oracle HTTP Server and its mod_ose and mod_jserv modules, see "Role of the Oracle HTTP Server, Powered by Apache" on page 2-6.



subdirectory under the default htdocs/_pages directory. This subdirectory would be created automatically by ojspc if it is run as in the above example. At execution time, the OracleJSP container would find the pre-translated binaries and would not have to perform translation, assuming that the source file was not altered after pre-translation. (By default, the page would be re-translated if the source file timestamp is later than the binary timestamp, assuming the source file is available and the bypass_source configuration parameter is not enabled.)

General JSP Pre-Translation Without ExecutionIn an on-demand translation environment, it is possible to specify JSP pre-translation only, without execution, by enabling the standard jsp_precompile request parameter when invoking the JSP page from the end user’s browser.


http://host[:port]/foo.jsp?jsp_precompile

Refer to the Sun Microsystems JavaServer Pages Specification, Version 1.1, for more information.

Deployment of Binary Files OnlyIf your JSP source is proprietary, you can avoid exposing the source by pre-translating JSP pages and deploying only the translated and compiled binary files. Pages that are pre-translated, either from previous execution in an on-demand translation scenario or by using ojspc, can be deployed to any environment that supports the OracleJSP container. There are two aspects to this scenario:

■ You must deploy the binary files appropriately.

■ In the target environment, OracleJSP must be configured properly to run pages when the .jsp (or .sqljsp) source is not available.

Note: OracleJSP implementation details, such as use of an underscore ("_") in output directory names (as for _test above), are subject to change from release to release. This documentation applies specifically to OracleJSP release 1.1.3.x.



Deploying the Binary FilesAfter JSP pages have been translated, archive the directory structure and contents that are under the binary output directory, then copy the directory structure and contents to the target environment, as appropriate. For example:

■ If you pre-translate with ojspc, you should specify a binary output directory with the ojspc -d option, then archive the directory structure under that specified directory.

■ If you are archiving binary files produced during previous execution in an Apache/JServ (on-demand translation) environment, archive the output directory structure, typically under the default htdocs/_pages directory.

In the target environment, restore the archived directory structure under the appropriate directory, such as under the htdocs/_pages directory in an Apache/JServ environment.

Configuring OracleJSP for Execution with Binary Files OnlySet OracleJSP configuration parameters as follows to execute JSP pages when the .jsp or .sqljsp source is unavailable:

■ bypass_source=true

■ developer_mode=false

Without these settings, OracleJSP will always look for the .jsp or .sqljsp file to see if it has been modified more recently than the page implementation .class file, and abort with a "file not found" error if it cannot find the .jsp or .sqljsp file.

With these parameters set appropriately, the end user can invoke a page with the same URL that would be used if the source file were in place. For an example, consider an Apache/JServ environment—if the binary files for foo.jsp are in the htdocs/_pages/_test directory, then the page can be invoked with the following URL without foo.jsp being present:

http://host:[port]/test/foo.jsp

For how to set configuration parameters, see "OracleJSP Configuration Parameter Settings" on page A-26.



WAR DeploymentThe Sun Microsystems JavaServer Pages Specification, Version 1.1 supports the packaging and deployment of Web applications, including JavaServer Pages, according to the Sun Microsystems Java Servlet Specification, Version 2.2.

In typical JSP 1.1 implementations, JSP pages can be deployed through the WAR (Web archive) mechanism. WAR files are created using the JAR utility. The JSP pages can be delivered in source form and are deployed along with any required support classes and static HTML files.

Oracle9i provides a WAR deployment implementation that adheres to the Sun Microsystems standard.

Standard WAR FeaturesAccording to the servlet 2.2 specification, a Web application includes a deployment descriptor file—web.xml—that contains information about the JSP pages and other components of the application. The web.xml file must be included in the WAR file.

The servlet 2.2 specification also defines an XML DTD for web.xml deployment descriptors and specifies exactly how a servlet container must deploy a Web application to conform to the deployment descriptor.

Through these logistics, a WAR file is the best way to ensure that a Web application is deployed into any standard servlet environment exactly as the developer intended.

Deployment configurations in the web.xml deployment descriptor include mappings between servlet paths and the JSP pages and servlets that will be invoked. Many additional features can be specified in web.xml as well, such as timeout values for sessions, mappings of file name extensions to MIME types, and mappings of error codes to JSP error pages.

To summarize, the WAR file includes the following:

■ web.xml deployment descriptor

■ JSP pages

■ required JavaBeans and other support classes

■ required static HTML files

■ hierarchical organization (as with any JAR file)

For more information about standard WAR deployment, see the Sun Microsystems Java Servlet Specification, Version 2.2.



Oracle WAR ImplementationEach vendor providing a WAR implementation typically includes the following:

■ a DTD for an auxiliary descriptor, which is used for vendor-specific features in conjunction with the use of web.xml for standard features

■ a tool that performs the application deployment in the server

This section provides an overview of the Oracle implementation of these features. For more information about Oracle WAR deployment, see the Oracle9i Servlet Engine Developer’s Guide.

Oracle Auxiliary Descriptor The web.xml file is a vehicle for standard configuration instructions for a Web application and is portable to any standard runtime environment. However, web.xml cannot provide all the information necessary to deploy an application to a particular servlet container, because each vendor extends standard functionality with their own set of features. The servlet 2.2 specification suggests that each vendor provide an additional descriptor file for configuration of features unique to that vendor’s runtime environment.

Oracle specifies and supports such an additional descriptor, known as the Oracle auxiliary descriptor. Like the web.xml deployment descriptor, the auxiliary descriptor is in XML format. Oracle provides a DTD to specify supported elements and attributes.

Oracle Deployment Tool Oracle provides a tool that deploys a Web application to Oracle9i for execution in the Oracle9i Servlet Engine. The deployment tool requires that the application be packaged in a WAR file, and can be invoked in any of the following ways:

■ from the server, by using an Oracle session shell command (requires you to first manually upload the WAR file and auxiliary descriptor)

■ from the server, from Java code or a PL/SQL "call spec" (this also requires you to first manually upload the WAR file and auxiliary descriptor)

■ from any client, by invoking the Oracle deployment servlet (by default, the servlet class is automatically published to the Oracle9i Servlet Engine in advance)

■ from an Oracle client, through a client-side deployment script

■ from a non-Oracle client, by executing the deployment tool wrapper directly from Java



Deployment of JSP Pages with JDeveloperOracle JDeveloper release 3.1 and higher includes a deployment option, "Web Application to Web Server", that was added specifically for JSP applications.

This option generates a deployment profile that specifies the following:

■ a JAR file containing Business Components for Java (BC4J) classes required by the JSP application

■ static HTML files required by the JSP application

■ the path to the Web server

The developer can either deploy the application immediately upon creating the profile, or save the profile for later use.

Note: The client-side scripts and client-side wrapper are just convenient front ends that invoke the deployment servlet.


JSP Tag Libraries and the Oracle JML

7
JSP Tag Libraries and the Oracle JML Tags
This chapter discusses custom tag libraries, covering the basic framework that vendors can use to provide their own libraries and documenting the JML tag library that OracleJSP provides as a sample. This discussion includes the following topics:

■ Standard Tag Library Framework

■ Overview of the JSP Markup Language (JML) Sample Tag Library

■ JSP Markup Language (JML) Tag Descriptions

Tags 7-1

Standard Tag Library Framework

Standard Tag Library FrameworkStandard JavaServer Pages technology allows vendors to create custom JSP tag libraries.

A tag library defines a collection of custom actions. The tags can be used directly by developers in manually coding a JSP page, or automatically by Java development tools. A tag library must be portable between different JSP container implementations.

For information beyond what is provided here regarding tag libraries and the standard JavaServer Pages tag library framework, refer to the following resources:

■ Sun Microsystems JavaServer Pages Specification, Version 1.1

■ Sun Microsystems Javadoc for the javax.servlet.jsp.tagext package, at the following Web site:

http://java.sun.com/j2ee/j2sdkee/techdocs/api/javax/servlet/jsp/tagext/package-summary.html

Overview of a Custom Tag Library ImplementationA custom tag library is imported into a JSP page using a taglib directive of the following general form:

<%@ taglib uri="URI" prefix="prefix" %>

Note the following:

■ The tags of a library are defined in a tag library description file, as described in "Tag Library Description Files" on page 7-11.

■ The URI in the taglib directive specifies where to find the tag library description file, as described in "The taglib Directive" on page 7-14. It is possible to use URI shortcuts, as described in "Use of web.xml for Tag Libraries" on page 7-12.

Note: Do not use the servlet.jar file of the Tomcat 3.1 beta servlet/JSP implementation if you are using custom tags. The constructor signature was changed for the class javax.servlet.jsp.tagext.TagAttributeInfo, which will result in compilation errors. Instead, use the servlet.jar file that is provided with OracleJSP or the production version of Tomcat 3.1.



■ The prefix in the taglib directive is a string of your choosing that you use in your JSP page with any tag from the library.

Assume the taglib directive specifies a prefix oracust:

<%@ taglib uri="URI" prefix="oracust" %>

Further assume that there is a tag mytag in the library. You might use mytag as follows:

<oracust:mytag attr1="...", attr2="..." />

Using the oracust prefix informs the JSP translator that mytag is defined in the tag library description file that can be found at the URI specified in the above taglib directive.

■ The entry for a tag in the tag library description file provides specifications about usage of the tag, including whether the tag uses attributes (as mytag does), and the names of those attributes.

■ The semantics of a tag—the actions that occur as the result of using the tag—are defined in a tag handler class, as described in "Tag Handlers" on page 7-4. Each tag has its own tag handler class, and the class name is specified in the tag library description file.

■ The tag library description file indicates whether a tag uses a body.

As seen above, a tag without a body is used as in the following example:

<oracust:mytag attr1="...", attr2="..." />

By contrast, a tag with a body is used as in the following example:

<oracust:mytag attr1="...", attr2="..." > ...body...</oracust:mytag>

■ A custom tag action can create one or more server-side objects that are available for use by the tag itself or by other JSP scripting elements, such as scriptlets. These objects are referred to as scripting variables.

Details regarding the scripting variables that a custom tag uses are defined in a tag-extra-info class. This is described in "Scripting Variables and Tag-Extra-Info Classes" on page 7-8.

JSP Tag Libraries and the Oracle JML Tags 7-3


A tag can create scripting variables with syntax such as in the following example, which creates the object myobj:

<oracust:mytag id="myobj" attr1="...", attr2="..." />

■ The tag handler of a nested tag can access the tag handler of an outer tag, in case this is required for any of the processing or state management of the nested tag. See "Access to Outer Tag Handler Instances" on page 7-10.

The sections that follow provide more information about these topics.

Tag HandlersA tag handler describes the semantics of the action that results from use of a custom tag. A tag handler is an instance of a Java class that implements one of two standard Java interfaces, depending on whether the tag processes a body of statements (between a start tag and an end tag).

Each tag has its own handler class. By convention, the name of the tag handler class for a tag abc, for example, is AbcTag.

The tag library description (TLD) file of a tag library specifies the name of the tag handler class for each tag in the library. (See "Tag Library Description Files" on page 7-11.)

A tag handler instance is a server-side object used at request time. It has properties that are set by the JSP container, including the page context object for the JSP page that uses the custom tag, and a parent tag handler object if the use of this custom tag is nested within an outer custom tag.

See "Sample Tag Handler Class: ExampleLoopTag.java" on page 7-16 for sample code of a tag handler class.

Note: The Sun Microsystems JavaServer Pages Specification, Version 1.1 does not mandate whether multiple uses of the same custom tag within a JSP page should use the same tag handler instance or different tag handler instances—this implementation detail is left to the discretion of JSP vendors. OracleJSP uses a separate tag handler instance for each use of a tag.



Custom Tag Body ProcessingCustom tags, like standard JSP tags, may or may not have a body. And in the case of a custom tag, even when there is a body, it may not need special handling by the tag handler.

There are three possible situations:

■ There is no body.

In this case, there is just a single tag, as opposed to a start tag and end tag. Following is a general example:

<oracust:abcdef attr1="...", attr2="..." />

■ There is a body that does not need special handling by the tag handler.

In this case, there is a start tag and end tag with a body of statements in between, but the tag handler does not have to process the body—body statements are passed through for normal JSP processing only. Following is a general example:

<foo:if cond="<%= ... %>" >...body executed if cond is true, but not processed by tag handler...</foo:if>

■ There is a body that needs special handling by the tag handler.

In this case also, there is a start tag and end tag with a body of statements in between; however, the tag handler must process the body.

<oracust:ghijkl attr1="...", attr2="..." >...body processed by tag handler...</oracust:ghijkl>

Integer Constants for Body ProcessingThe tag handling interfaces that are described in the following sections specify a doStartTag() method (further described below) that you must implement to return an appropriate int constant, depending on the situation. The possible return values are as follows:

■ SKIP_BODY if there is no body or if evaluation and execution of the body should be skipped

■ EVAL_BODY_INCLUDE if there is a body that does not require special handling by the tag handler



■ EVAL_BODY_TAG if there is a body that requires special handling by the tag handler

Handlers for Tags That Do Not Process a BodyFor a custom tag that does not have a body, or has a body that does not need special handling by the tag handler, the tag handler class implements the following standard interface:

■ javax.servlet.jsp.tagext.Tag

The following standard support class implements the Tag interface and can be used as a base class:

■ javax.servlet.jsp.tagext.TagSupport

The Tag interface specifies a doStartTag() method and a doEndTag() method. The tag developer provides code for these methods in the tag handler class, as appropriate, to be executed as the start tag and end tag, respectively, are encountered. The JSP page implementation class generated by the OracleJSP translator includes appropriate calls to these methods.

Action processing—whatever you want the action tag to accomplish—is implemented in the doStartTag() method. The doEndTag() method would implement any appropriate post-processing. In the case of a tag without a body, essentially nothing happens between the execution of these two methods.

The doStartTag() method returns an integer value. For a tag handler class implementing the Tag interface (either directly or indirectly), this value must be either SKIP_BODY or EVAL_BODY_INCLUDE (described in "Integer Constants for Body Processing" above). EVAL_BODY_TAG is illegal for a tag handler class implementing the Tag interface.

Handlers for Tags That Process a BodyFor a custom tag with a body that requires special handling by the tag handler, the tag handler class implements the following standard interface:

■ javax.servlet.jsp.tagext.BodyTag

The following standard support class implements the BodyTag interface and can be used as a base class:

■ javax.servlet.jsp.tagext.BodyTagSupport



The BodyTag interface specifies a doInitBody() method and a doAfterBody() method in addition to the doStartTag() and doEndTag() methods specified in the Tag interface.

Just as with tag handlers implementing the Tag interface (described in the preceding section, "Handlers for Tags That Do Not Process a Body"), the tag developer implements the doStartTag() method for action processing by the tag, and the doEndTag() method for any post-processing.

The doStartTag() method returns an integer value. For a tag handler class implementing the BodyTag interface (directly or indirectly), this value must be either SKIP_BODY or EVAL_BODY_TAG (described in "Integer Constants for Body Processing" on page 7-5). EVAL_BODY_INCLUDE is illegal for a tag handler class implementing the BodyTag interface.

In addition to implementing the doStartTag() and doEndTag() methods, the tag developer, as appropriate, provides code for the doInitBody() method, to be invoked before the body is evaluated, and the doAfterBody() method, to be invoked after each evaluation of the body. (The body could be evaluated multiple times, such as at the end of each iteration of a loop.) The JSP page implementation class generated by the OracleJSP translator includes appropriate calls to all of these methods.

After the doStartTag() method is executed, the doInitBody() and doAfterBody() methods are executed if the doStartTag() method returned EVAL_BODY_TAG.

The doEndTag() method is executed after any body processing, when the end tag is encountered.

For custom tags that must process a body, the javax.servlet.jsp.tagext.BodyContent class is available for use. This is a subclass of javax.servlet.jsp.JspWriter that can be used to process body evaluations so that they can re-extracted later. The BodyTag interface includes a setBodyContent() method that can be used by the JSP container to give a BodyContent handle to a tag handler instance.



Scripting Variables and Tag-Extra-Info ClassesA custom tag action can create one or more server-side objects, known as scripting variables, that are available for use by the tag itself or by other scripting elements, such as scriptlets and other tags.

Details regarding scripting variables that a custom tag defines must be specified in a subclass of the standard javax.servlet.jsp.tagext.TagExtraInfo abstract class. This document refers to such a subclass as a tag-extra-info class.

The JSP container uses tag-extra-info instances during translation. (The tag library description file, specified in the taglib directive that imports the library into a JSP page, specifies the tag-extra-info class to use, if applicable, for any given tag.)

A tag-extra-info class has a getVariableInfo() method to retrieve names and types of the scripting variables that will be assigned during HTTP requests. The JSP translator calls this method during translation, passing it an instance of the standard javax.servlet.jsp.tagext.TagData class. The TagData instance specifies attribute values set in the JSP statement that uses the custom tag.


■ Defining Scripting Variables

■ Scripting Variable Scopes

■ Tag-Extra-Info Classes and the getVariableInfo() Method

Defining Scripting VariablesObjects that are defined explicitly in a custom tag can be referenced in other actions through the page context object, using the object ID as a handle. Consider the following example:

<oracust:foo id="myobj" attr1="..." attr2="..." />

This statement results in the object myobj being available to any scripting elements between the tag and the end of the page. The id attribute is a translation-time attribute. The tag developer provides a tag-extra-info class that will be used by the JSP container. Among other things, the tag-extra-info class specifies what class to instantiate for the myobj object.

The JSP container enters myobj into the page context object, where it can later be obtained by other tags or scripting elements using syntax such as the following:

<oracust:bar ref="myobj" />



The myobj object is passed through the tag handler instances for foo and bar. All that is required is knowledge of the name of the object (myobj).

Scripting Variable ScopesSpecify the scope of a scripting variable in the tag-extra-info class of the tag that creates the variable. It can be one of the following int constants:

■ NESTED—if the scripting variable is available between the start tag and end tag of the action that defines it

■ AT_BEGIN—if the scripting variable is available from the start tag until the end of the page

■ AT_END—if the scripting variable is available from the end tag until the end of the page

Tag-Extra-Info Classes and the getVariableInfo() MethodYou must create a tag-extra-info class for any custom tag that creates scripting variables. The class describes the scripting variables and must be a subclass of the standard javax.servlet.jsp.tagext.TagExtraInfo abstract class.

The key method of the TagExtraInfo class is getVariableInfo(), which is called by the JSP translator and returns an array of instances of the standard javax.servlet.jsp.tagext.VariableInfo class (one array instance for each scripting variable the tag creates).

The tag-extra-info class constructs each VariableInfo instance with the following information regarding the scripting variable:

■ its name

■ its Java type (cannot be a primitive type)

■ a boolean indicating whether it is a newly declared variable

■ its scope

Important: Note that id and ref are merely sample attribute names; there are no special predefined semantics for these attributes. It is up to the tag handler to define attribute names and create and retrieve objects in the page context.



See "Sample Tag-Extra-Info Class: ExampleLoopTagTEI.java" on page 7-17 for sample code of a tag-extra-info class.

Access to Outer Tag Handler InstancesWhere nested custom tags are used, the tag handler instance of the nested tag has access to the tag handler instance of the outer tag, which may be useful in any processing and state management performed by the nested tag.

This functionality is supported through the static findAncestorWithClass() method of the javax.servlet.jsp.tagext.TagSupport class. Even though the outer tag handler instance is not named in the page context object, it is accessible because it is the closest enclosing instance of a given tag handler class.

Consider the following JSP code example:

<foo:bar1 attr="abc" > <foo:bar2 /></foo:bar1>

Within the code of the bar2 tag handler class (class Bar2Tag, by convention), you can have a statement such as the following:

Tag bar1tag = TagSupport.findAncestorWithClass(this, Bar1Tag.class);

The findAncestorWithClass() method takes the following as input:

■ the this object that is the class handler instance from which findAncestorWithClass() was called (a Bar2Tag instance in the example)

■ the name of the bar1 tag handler class (presumed to be Bar1Tag in the example), as a java.lang.Class instance

Important: As of OracleJSP release 1.1.3.x, the getVariableInfo() method can return either a fully qualified class name (FQCN) or a partially qualified class name (PQCN) for the Java type of the scripting variable. FQCNs were required in previous releases, and are still preferred in order to avoid confusion in case there are duplicate class names between packages.

Note that primitive types are not supported.



The findAncestorWithClass() method returns an instance of the appropriate tag handler class, in this case Bar1Tag, as a javax.servlet.jsp.tagext.Tag instance.

It is useful for a Bar2Tag instance to have access to the outer Bar1Tag instance in case the Bar2Tag needs the value of a bar1 tag attribute or needs to call a method on the Bar1Tag instance.

Tag Library Description FilesA tag library description (TLD) file is an XML document that contains information about a tag library and about individual tags of the library. The name of a TLD file has the .tld extension.

A JSP container uses the TLD file in determining what action to take when it encounters a tag from the library.

A tag entry in the TLD file includes the following:

■ name of the custom tag

■ name of the corresponding tag handler class

■ name of the corresponding tag-extra-info class (if applicable)

■ information indicating how the tag body (if any) should be processed

■ information about the attributes of the tag (the attributes that you specify whenever you use the custom tag)

Here is a sample TLD file entry for the tag myaction:

<tag> <name>myaction</name> <tagclass>examples.MyactionTag</tagclass> <teiclass>examples.MyactionTagExtraInfo</teiclass> <bodycontent>JSP</bodycontent> <info> Perform a server-side action (one mandatory attr; one optional) </info> <attribute> <name>attr1</name> <required>true</required> </attribute> <attribute> <name>attr2</name> <required>false</required>



</attribute></tag>

According to this entry, the tag handler class is MyactionTag and the tag-extra-info class is MyactionTagExtraInfo. The attribute attr1 is required; the attribute attr2 is optional.

The bodycontent parameter indicates how the tag body (if any) should be processed. There are three valid values:

■ A value of empty indicates that the tag uses no body.

■ A value of JSP indicates that the tag body should be processed as JSP source and translated.

■ A value of tagdependent indicates that the tag body should not be translated. Any text in the body is treated as static text.

The taglib directive in a JSP page informs the JSP container where to find the TLD file. (See "The taglib Directive" on page 7-14.)

For more information about tag library description files, see the Sun Microsystems JavaServer Pages Specification, Version 1.1.

Use of web.xml for Tag LibrariesThe Sun Microsystems Java Servlet Specification, Version 2.2 describes a standard deployment descriptor for servlets—the web.xml file. JSP pages can use this file in specifying the location of a JSP tag library description file.

For JSP tag libraries, the web.xml file can include a taglib element and two subelements:

■ taglib-uri

■ taglib-location

The taglib-location subelement indicates the application-relative location (by starting with "/") of the tag library description file.

Note: In the Tomcat 3.1 servlet/JSP implementation, the TLD file bodycontent parameter for a given tag is not read if the tag itself (in the JSP page) has no body. It is possible, therefore, to have an invalid bodycontent value in your TLD file (such as none instead of empty) without realizing it. Using the file in another JSP environment, such as OracleJSP, would then result in errors.



The taglib-uri subelement indicates a "shortcut" URI to use in taglib directives in your JSP pages, with this URI being mapped to the TLD file location specified in the accompanying taglib-location subelement. (The term URI, universal resource indicator, is somewhat equivalent to the term URL, universal resource locator, but is more generic.)

Following is a sample web.xml entry for a tag library description file:

<taglib> <taglib-uri>/oracustomtags</taglib-uri> <taglib-location>/WEB-INF/oracustomtags/tlds/MyTLD.tld</taglib-location></taglib>

This makes /oracustomtags equivalent to /WEB-INF/oracustomtags/tlds/MyTLD.tld in taglib directives in your JSP pages. See "Using a Shortcut URI for the TLD File" below for an example.

See the Sun Microsystems Java Servlet Specification, Version 2.2 and the Sun Microsystems JavaServer Pages Specification, Version 1.1 for more information about the web.xml deployment descriptor and its use for tag library description files.

Important: When a JSP application uses a web.xml file, you must deploy web.xml with the application. Treat it as a Java resource file.

Notes:

■ Do not use the sample web.xml file from the Tomcat 3.1 servlet/JSP implementation. It introduces new elements that will not pass the standard DTD XML validation.

■ Do not use the term "urn" instead of "uri" in a web.xml file. Some JSP implementations allow this (such as Tomcat 3.1), but using "urn" will not pass the standard DTD XML validation.



The taglib DirectiveImport a custom library into a JSP page using a taglib directive, of the following form:

<%@ taglib uri="URI" prefix="prefix" %>

For the URI, you have the following options:

■ Specify a shortcut URI, as defined in a web.xml file (see "Use of web.xml for Tag Libraries" above).

■ Fully specify the tag library description (TLD) file name and location.

Using a Shortcut URI for the TLD FileAssume the following web.xml entry for a tag library defined in the tag library description file MyTLD.tld:

<taglib> <taglib-uri>/oracustomtags</taglib-uri> <taglib-location>/WEB-INF/oracustomtags/tlds/MyTLD.tld</taglib-location></taglib>

Given this example, the following directive in your JSP page results in the JSP container finding the /oracustomtags URI in web.xml and, therefore, finding the accompanying name and location of the tag library description file (MyTLD.tld):

<%@ taglib uri="/oracustomtags" prefix="oracust" %>

This statement allows you to use any of the tags of this custom tag library in a JSP page.

Fully Specifying the TLD File Name and LocationIf you do not want your JSP application to depend on a web.xml file for its use of a tag library, taglib directives can fully specify the name and location of the tag library description file, as follows:

<%@ taglib uri="/WEB-INF/oracustomtags/tlds/MyTLD.tld" prefix="oracust" %>

The location is specified as an application-relative location (by starting with "/", as in this example). See "Requesting a JSP Page" on page 1-8 for related discussion.



Alternatively, you can specify a .jar file instead of a .tld file in the taglib directive, where the .jar file contains a tag library description file. The tag library description file must be located and named as follows when you create the JAR file:

META-INF/taglib.tld

Then the taglib directive might be as follows, for example:

<%@ taglib uri="/WEB-INF/oracustomtags/tlds/MyTLD.jar" prefix="oracust" %>

End-to-End Example: Defining and Using a Custom TagThis section provides an end-to-end example of the definition and use of a custom tag, loop, that is used to iterate through the tag body a specified number of times.

Included in the example are the following:

■ JSP source for a page that uses the tag

■ source code for the tag handler class

■ source code for the tag-extra-info class

■ the tag library description file

Sample JSP Page: exampletag.jspFollowing is a sample JSP page that uses the loop tag, specifying that the outer loop be executed five times and the inner loop three times:

examplestag.jsp<%@ taglib prefix="foo" uri="/WEB-INF/exampletag.tld" %><% int num=5; %><br><pre><foo:loop index="i" count="<%=num%>">body1here: i expr: <%=i%> i property: <jsp:getProperty name="i" property="value" /> <foo:loop index="j" count="3"> body2here: j expr: <%=j%> i property: <jsp:getProperty name="i" property="value" /> j property: <jsp:getProperty name="j" property="value" /> </foo:loop></foo:loop></pre>



Sample Tag Handler Class: ExampleLoopTag.javaThis section provides source code for the tag handler class, ExampleLoopTag. Note the following:

■ The doStartTag() method returns the integer constant EVAL_BODY_TAG, so that the tag body (essentially, the loop) is processed.

■ After each pass through the loop, the doAfterBody() method increments the counter. It returns EVAL_BODY_TAG if there are more iterations left and SKIP_BODY after the last iteration.

Here is the code:

package examples;

import javax.servlet.jsp.*;import javax.servlet.jsp.tagext.*;import java.util.Hashtable;import java.io.Writer;import java.io.IOException;import oracle.jsp.jml.JmlNumber;

public class ExampleLoopTag extends BodyTagSupport{ String index; int count; int i=0; JmlNumber ib=new JmlNumber();

public void setIndex(String index) { this.index=index; } public void setCount(String count) { this.count=Integer.parseInt(count); }

public int doStartTag() throws JspException { return EVAL_BODY_TAG; }

public void doInitBody() throws JspException { pageContext.setAttribute(index, ib);



i++; ib.setValue(i); } public int doAfterBody() throws JspException { try { if (i >= count) { bodyContent.writeOut(bodyContent.getEnclosingWriter()); return SKIP_BODY; } else pageContext.setAttribute(index, ib); i++; ib.setValue(i); return EVAL_BODY_TAG; } catch (IOException ex) { throw new JspTagException(ex.toString()); } }}

Sample Tag-Extra-Info Class: ExampleLoopTagTEI.javaThis section provides the source code for the tag-extra-info class that describes the scripting variable used by the loop tag.

A VariableInfo instance is constructed that specifies the following for the variable:

■ The variable name is according to the index attribute.

■ The variable is of the type oracle.jsp.jml.JmlNumber (this must be specified as a fully qualified class name).

■ The variable is newly declared.

■ The variable scope is NESTED.

In addition, the tag-extra-info class has an isValid() method that determines whether the count attribute is valid—it must be an integer.

package examples;

import javax.servlet.jsp.tagext.*;

public class ExampleLoopTagTEI extends TagExtraInfo { public VariableInfo[] getVariableInfo(TagData data) {



return new VariableInfo[] { new VariableInfo(data.getAttributeString("index"), "oracle.jsp.jml.JmlNumber", true, VariableInfo.NESTED) }; }

public boolean isValid(TagData data) { String countStr=data.getAttributeString("count"); if (countStr!=null) // for request time case { try { int count=Integer.parseInt(countStr); } catch (NumberFormatException e) { return false; } } return true; }}

Sample Tag Library Description File: exampletag.tldThis section presents the tag library description (TLD) file for the tag library. In this example, the library consists of only the one tag, loop.

This TLD file specifies the following for the loop tag:

■ the tag handler class—examples.ExampleLoopTag

■ the tag-extra-info class—examples.ExampleLoopTagTEI

■ bodycontent specification of JSP

This means the JSP translator should process and translate the body code.

■ attributes index and count, both mandatory

The count attribute can be a request-time JSP expression.


Here is the TLD file:

<?xml version="1.0" encoding="ISO-8859-1" ?><!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN" "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd">



<taglib> 

<tlibversion>1.0</tlibversion> <jspversion>1.1</jspversion> <shortname>simple</shortname> <info> A simple tab library for the examples </info>

  <tag> <name>loop</name> <tagclass>examples.ExampleLoopTag</tagclass> <teiclass>examples.ExampleLoopTagTEI</teiclass> <bodycontent>JSP</bodycontent> <info>for loop</info> <attribute> <name>index</name> <required>true</required> </attribute> <attribute> <name>count</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

</taglib>

Overview of the JSP Markup Language (JML) Sample Tag Library

Overview of the JSP Markup Language (JML) Sample Tag LibraryOracleJSP supplies the JSP Markup Language (JML) sample tag library, which is portable to any standard JSP environment. JML tags, as with those of any standard tag library, are completely compatible with regular JSP script and can be used in any JSP page.

Many of the JML tags are intended to simplify coding syntax for JSP developers who are not proficient with Java. There are also tags for XML transformations (as described in "JML Tags for XSL Stylesheets" on page 5-10), bean binding, and general utility.


■ JML Tag Library Philosophy

■ JML Tag Categories

■ JML Tag Library Description File and taglib Directive

Note the following requirements for using JML tags:

■ Install the file ojsputil.jar and include it in your classpath. This file is provided with the OracleJSP installation.

■ Make sure that the tag library description file, jml.tld, is deployed with the application and is in the location specified in the taglib directives of your JSP pages. See "JML Tag Library Description File and taglib Directive" on page 7-22.

Notes:

■ OracleJSP also provides a tag library for SQL functionality. This is described in "OracleJSP Tag Library for SQL" on page 5-24.

■ Prior to OracleJSP release 1.1.0.0.0 and the release of the JSP 1.1 specification, OracleJSP supported JML tags only as Oracle extensions. (The tag library framework was not added to the JavaServer Pages specification until JSP 1.1.) For these releases, Oracle-specific JML tag processing was built into the OracleJSP translator. This is referred to as "compile-time JML support" and is described in Appendix C, "Compile-Time JML Tag Support".



JML Tag Library PhilosophyJavaServer Pages technology is intended for two separate developer communities:

■ those whose primary skill is Java programming

■ those whose primary skill is in designing static content, particularly in HTML, and who may have limited scripting experience

The JML tag library is designed to allow most Web developers, with little or no knowledge of Java, to assemble JSP applications with a full complement of program flow-control features.

This model presumes that the business logic is contained in JavaBeans that are developed separately by a Java developer.

JML Tag CategoriesThe JML tag library covers a wide feature set. The major functional categories are summarized in Table 7–1.

Table 7–1 JML Tag Functional Categories

Tag Categories Tags Functionality

bean binding tags useVariableuseFormuseCookieremove

These tags are to declare or undeclare a JavaBean at a specified JSP scope. See "Bean Binding Tag Descriptions" on page 7-30.

logic/flow control tags ifchoose..when..[otherwise]foreachreturnflush

These tags offer simplified syntax to define code flow, such as for iterative loops or conditional branches. See "Logic and Flow Control Tag Descriptions" on page 7-34.

XML transformation tags transformstyleSheet

These synonymous tags simplify the process of applying an XSL stylesheet to all or part of JSP page output. See "JML Tags for XSL Stylesheets" on page 5-10. (The tags are identical in effect. You need only one or the other.)


JML Tag Library Description File and taglib DirectiveAs with any tag library following the JSP 1.1 specification, the tags of the JML library are specified in an XML-style tag library description (TLD) file.

This TLD file is provided with the OracleJSP sample applications. It must be deployed with any JSP application that uses JML tags, and specified in a taglib directive for any page using JML tags.

JML taglib DirectiveA JSP page using JML tags must specify the TLD file in a taglib directive that supplies a standard universal resource indicator (URI) to locate the file. The URI syntax is typically application-relative, such as in the following example:

<%@ taglib uri="/WEB-INF/jml.tld" prefix="jml" %>

Alternatively, instead of using the full path to the TLD file, as in this example, you can specify a URI shortcut in the web.xml file then use the shortcut in your taglib directives. See "Use of web.xml for Tag Libraries" on page 7-12.

For general information about tag library description files, see "Tag Library Description Files" on page 7-11.

JML TLD File ListingThis section lists the entire TLD file for the JML tag library, as supported in OracleJSP release 1.1.3.x.



<taglib> 

<tlibversion>1.0</tlibversion> <jspversion>1.1</jspversion> <shortname>jml</shortname> <info> Oracle’s jml tag library. Not all of the jml

tag’s available in the Oracle JSP environment are provided in this library. No jsp: tags are duplicated, some tags are unavailable, and some tags have stricter syntax. No bean expressions are supported.

The differences are: *-jml:call - not available * jml:choose - works as documented * jml:flush - works as documented * jml:for - works as documented * jml:foreach - the type attribute is required, otherwise, as documented *!jml:forward - use jsp:forward *!jml:getProperty - use jsp:getProperty * jml:if - works as documented *!jml:include - use jsp:include *-jml:lock - not available *!jml:plugin - use jsp:plugin * jml:print - the expression to print must be supplied as an attribute. i.e. the tag cannot have a body * jml:remove - works as documented * jml:return - works as documented *-jml:set - not available *!jml:setProperty - use jsp:setProperty * jml:styleSheet - works as documented * jml:transform - works as documented *!jml:useBean - use jsp:useBean * jml:useCookie - works as documented * jml:useForm - works as documented * jml:useVariable - works as documented </info>

 <tag> <name>choose</name> <tagclass>oracle.jsp.jml.tagext.JmlChoose</tagclass> <bodycontent>JSP</bodycontent> <info> The outer tag of a multiple choice logic block, choose when condition1 when condition2 otherwise end choose </info>

</tag>

 <tag> <name>flush</name> <tagclass>oracle.jsp.jml.tagext.JmlFlush</tagclass> <bodycontent>empty</bodycontent> <info> Flush the current JspWriter </info> </tag>

 <tag> <name>for</name> <tagclass>oracle.jsp.jml.tagext.JmlFor</tagclass> <teiclass>oracle.jsp.jml.tagext.JmlForTEI</teiclass> <bodycontent>JSP</bodycontent> <info> A simple for loop </info>

<attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>from</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>to</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

 <tag> <name>foreach</name> <tagclass>oracle.jsp.jml.tagext.JmlForeach</tagclass> <teiclass>oracle.jsp.jml.tagext.JmlForeachTEI</teiclass> <bodycontent>JSP</bodycontent> <info>

A foreach loop for iterating arrays, enumerations, and vector’s. </info>

<attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>in</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>type</name> <required>true</required> </attribute> <attribute> <name>limit</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

 <tag> <name>if</name> <tagclass>oracle.jsp.jml.tagext.JmlIf</tagclass> <bodycontent>JSP</bodycontent> <info> A classic if </info>

<attribute> <name>condition</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

 <tag> <name>otherwise</name> <tagclass>oracle.jsp.jml.tagext.JmlOtherwise</tagclass>

<bodycontent>JSP</bodycontent> <info> (optional) final part of a choose block </info> </tag>

 <tag> <name>print</name> <tagclass>oracle.jsp.jml.tagext.JmlPrint</tagclass> <bodycontent>empty</bodycontent> <info> print the expression specified in the eval attribute </info> <attribute> <name>eval</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

 <tag> <name>remove</name> <tagclass>oracle.jsp.jml.tagext.JmlRemove</tagclass> <bodycontent>empty</bodycontent> <info> remove the specified object from the pageContext </info> <attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>scope</name> <required>false</required> </attribute> </tag>

 <tag> <name>return</name> <tagclass>oracle.jsp.jml.tagext.JmlReturn</tagclass> <bodycontent>empty</bodycontent> <info>

Skip the rest of the page </info> </tag>

 <tag> <name>styleSheet</name> <tagclass>oracle.jsp.jml.tagext.JmlStyleSheet</tagclass> <bodycontent>JSP</bodycontent> <info> Transform the body of the tag using a stylesheet </info> <attribute> <name>href</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

 <tag> <name>transform</name> <tagclass>oracle.jsp.jml.tagext.JmlStyleSheet</tagclass> <bodycontent>JSP</bodycontent> <info> Transform the body of the tag using a stylesheet </info> <attribute> <name>href</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

 <tag> <name>useCookie</name> <tagclass>oracle.jsp.jml.tagext.JmlUseCookie</tagclass> <teiclass>oracle.jsp.jml.tagext.JmlUseTEI</teiclass> <bodycontent>empty</bodycontent> <info> create a jml variable and initialize it to a cookie value </info> <attribute> <name>id</name>

<required>true</required> </attribute> <attribute> <name>scope</name> <required>false</required> </attribute> <attribute> <name>type</name> <required>true</required> </attribute> <attribute> <name>cookie</name> <required>true</required> </attribute> </tag>

 <tag> <name>useForm</name> <tagclass>oracle.jsp.jml.tagext.JmlUseForm</tagclass> <teiclass>oracle.jsp.jml.tagext.JmlUseTEI</teiclass> <bodycontent>empty</bodycontent> <info> create a jml variable and initialize it to a parameter value </info> <attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>scope</name> <required>false</required> </attribute> <attribute> <name>type</name> <required>true</required> </attribute> <attribute> <name>param</name> <required>true</required> </attribute> </tag>

 <tag>

<name>useVariable</name> <tagclass>oracle.jsp.jml.tagext.JmlUseVariable</tagclass> <teiclass>oracle.jsp.jml.tagext.JmlUseTEI</teiclass> <bodycontent>empty</bodycontent> <info> create a jml variable and initialize it to a parameter value </info> <attribute> <name>id</name> <required>true</required> </attribute> <attribute> <name>scope</name> <required>false</required> </attribute> <attribute> <name>type</name> <required>true</required> </attribute> <attribute> <name>value</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

 <tag> <name>when</name> <tagclass>oracle.jsp.jml.tagext.JmlWhen</tagclass> <bodycontent>JSP</bodycontent> <info> one part of a choose block, see choose </info> <attribute> <name>condition</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

</taglib>

JSP Markup Language (JML) Tag Descriptions

JSP Markup Language (JML) Tag DescriptionsThis section documents the JML tags that are supported in the OracleJSP 1.1.3.x runtime implementation, following the JSP 1.1 specification. They are categorized as follows:

■ Bean Binding Tag Descriptions

■ Logic and Flow Control Tag Descriptions

For an elementary sample using some of the tags described here, see "JML Tag Sample—hellouser_jml.jsp" on page 11-31.

Tags for XML transformations are documented separately, in "JML Tags for XSL Stylesheets" on page 5-10.

Syntax Symbology and NotesFor the syntax documentation in the tag descriptions, note the following:

■ Italics indicate that you must specify a value or string.

■ Optional attributes are enclosed in square brackets: [...]

■ Default values of optional attributes are indicated in bold.

■ Choices in how to specify an attribute are separated by vertical bars: |

■ The prefix "jml:" is used. This is by convention but is not required. You can specify any desired prefix in your taglib directive.

Bean Binding Tag DescriptionsThis section documents the following JML tags, which are used for bean-binding operations:

■ JML useVariable Tag

■ JML useForm Tag

■ JML useCookie Tag

■ JML remove Tag

JML useVariable TagThis tag offers a convenient alternative to the jsp:useBean tag for declaring simple variables.



Syntax

<jml:useVariable id = "beanInstanceName" [scope = "page | request | session | application"] type = "string | boolean | number | fpnumber" [value = "stringLiteral | <%= jspExpression %>"] />

Attributes

■ id—Names the variable being declared. This attribute is required.

■ scope—Defines the duration or scope of the variable (as with a jsp:useBean tag). This attribute is optional; the default scope is page.

■ type—Specifies the type of the variable. The type specifications refer to JmlString, JmlBoolean, JmlNumber, or JmlFPNumber. This attribute is required.

■ value—Allows the variable to be set directly in the declaration, as either a string literal or a JSP expression enclosed in <%=... %> syntax. This attribute is optional. If it is not specified, the value remains the same as when it was last set (if it already exists) or is initialized with a default value. If it is specified, then the value is always set, regardless of whether this declaration instantiates the object or merely acquires it from the named scope.

Example Consider the following example:

<jml:useVariable id = "isValidUser" type = "boolean" value = "<%= dbConn.isValid() %>" scope = "session" />

This is equivalent to the following:

<jsp:useBean id = "isValidUser" class = "oracle.jsp.jml.JmlBoolean" scope = "session" /><jsp:setProperty name="isValidUser" property="value" value = "<%= dbConn.isValid() %>" />

JML useForm TagThis tag provides a convenient syntax for declaring variables and setting them to values passed in from the request.

Syntax

<jml:useForm id = "beanInstanceName" [scope = "page | request | session | application"] [type = "string | boolean | number | fpnumber"] param = "requestParameterName" />



Attributes

■ id—Names the variable being declared or referenced. This attribute is required.

■ scope—Defines the duration or scope of the variable (as with a jsp:useBean tag). This attribute is optional; the default scope is page.

■ type—Specifies the type of the variable. The type specifications refer to JmlString, JmlBoolean, JmlNumber, or JmlFPNumber. This attribute is required.

■ param—Specifies the name of the request parameter whose value is used in setting the variable. This attribute is required. If the request parameter exists, then the variable value is always updated, regardless of whether this declaration brings the variable into existence. If the request parameter does not exist, then the variable value remains unchanged.

Example The following example sets a session variable named user of the type string to the value of the request parameter named user.

<jml:useForm id = "user" type = "string" param = "user" scope = "session" />


<jsp:useBean id = "user" class = "oracle.jsp.jml.JmlString" scope = "session" /><jsp:setProperty name="user" property="value" param = "user" />

JML useCookie TagThis tag offers a convenient syntax for declaring variables and setting them to values contained in cookies.

Syntax

<jml:useCookie id = "beanInstanceName" [scope = "page | request | session | application"] [type = "string | boolean | number | fpnumber"] cookie = "cookieName" />

Attributes

■ id—Names the variable being declared or referenced. This attribute is required.

■ scope—Defines the duration or scope of the variable. This attribute is optional; the default scope is page.



■ type—Identifies the type of the variable (the type specifications refer to JmlString, JmlBoolean, JmlNumber, or JmlFPNumber). This attribute is optional; the default setting is string.

■ cookie—Specifies the name of the cookie whose value is used in setting this variable. This attribute is required. If the cookie exists, then the variable value is always updated, regardless of whether this declaration brings the variable into existence. If the cookie does not exist, then the variable value remains unchanged.

Example The following example sets a request variable named user of the type string to the value of the cookie named user.

<jml:useCookie id = "user" type = "string" cookie = "user" scope = "request" />


<jsp:useBean id = "user" class = "oracle.jsp.jml.JmlString" scope = "request" /> <% Cookies [] cookies = request.getCookies(); for (int i = 0; i < cookies.length; i++) { if (cookies[i].getName().equals("user")) { user.setValue(cookies[i].getValue()); break; } }%>

JML remove TagThis tag removes an object from its scope.

Syntax

<jml:remove id = "beanInstanceName" [scope = "page | request | session | application" ] />

Attributes

■ id—Specifies the name of the bean being removed. This attribute is required.

■ scope—This attribute is optional. If not specified, then scopes are searched in the following order: 1) page, 2) request, 3) session, 4) application. The first object whose name matches id is removed.



Example The following example removes the session user object:

<jml:remove id = "user" scope = "session" />


<% session.removeValue("user"); %>

Logic and Flow Control Tag DescriptionsThis section documents the following JML tags, which are used for logic and flow control:

■ JML if Tag

■ JML choose...when...[otherwise] Tags

■ JML for Tag

■ JML foreach Tag

■ JML return Tag

■ JML flush Tag

These tags, which are intended for developers without extensive Java experience, can be used in place of Java logic and flow control syntax, such as iterative loops and conditional branches.

JML if TagThis tag evaluates a single conditional statement. If the condition is true, then the body of the if tag is executed.

Syntax

<jml:if condition = "<%= jspExpression %>" > ...body of if tag (executed if the condition is true)...</jml:if>

Attributes

■ condition—Specifies the conditional expression to be evaluated. This attribute is required.



Example The following e-commerce example displays information from a user’s shopping cart. The code checks to see if the variable holding the current T-shirt order is empty. If not, then the size that the user has ordered is displayed. Assume currTS is of type JmlString.

<jml:if condition = "<%= !currTS.isEmpty() %>" > <S>(size: <%= currTS.getValue().toUpperCase() %>)</S>&nbsp</jml:if>

JML choose...when...[otherwise] TagsThe choose tag, with associated when and otherwise tags, provides a multiple conditional statement.

The body of the choose tag contains one or more when tags, where each when tag represents a condition. For the first when condition that is true, the body of that when tag is executed. (A maximum of one when body is executed.)

If none of the when conditions are true, and if the optional otherwise tag is specified, then the body of the otherwise tag is executed.

Syntax

<jml:choose> <jml:when condition = "<%= jspExpression %>" > ...body of 1st when tag (executed if the condition is true)... </jml:when> ... [...optional additional when tags...] [ <jml:otherwise> ...body of otherwise tag (executed if all when conditions false)... </jml:otherwise> ]</jml:choose>

Attributes The when tag uses the following attribute (the choose and otherwise tags have no attributes):

■ condition—Specifies the conditional expression to be evaluated. This attribute is required.

Example The following e-commerce example displays information from a user's shopping cart. This code checks to see if anything has been ordered. If so, the current order is displayed; otherwise, the user is asked to shop again. (This example



omits the code to display the current order.) Presume orderedItem is of the type JmlBoolean.

<jml:choose> <jml:when condition = "<%= orderedItem.getValue() %>" > You have changed your order: -- output the current order -- </jml:when> <jml:otherwise> Are you sure we can’t interest you in something, cheapskate? </jml:otherwise></jml:choose>

JML for TagThis tag provides the ability to iterate through a loop, as with a Java for loop.

The id attribute is a local loop variable of the type java.lang.Integer that contains the value of the current range element. The range starts at the value expressed in the from attributed and is incremented by one after each execution of the body of the loop, until it exceeds the value expressed in the to attribute.

Once the range has been traversed, control goes to the first statement following the for end tag.

Syntax

<jml:for id = "loopVariable" from = "<%= jspExpression %>" to = "<%= jspExpression %>" > ...body of for tag (executed once at each value of range, inclusive)...</jml:for>

Attributes

■ id—Names the loop variable, which holds the current value in the range. This is a java.lang.Integer value and can be used only within the body of the tag. This attribute is required.

Note: Descending ranges are not supported—the from value must be less than or equal to the to value.



■ from—Specifies the start of the range. This is an expression that must evaluate to a Java int value. This is a required attribute.

■ to—Specifies the end of the range. This is an expression that must evaluate to a Java int value. This is a required attribute.

Example The following example repeatedly prints "Hello World" in progressively smaller headings (H1, H2, H3, H4, H5).

<jml:for id="i" from="<%= 1 %>" to="<%= 5 %>" > <H<%=i%>> Hello World! </H<<%=i%>></jml:for>

JML foreach TagThis tag provides the ability to iterate over a homogeneous set of values.

The body of the tag is executed once per element in the set. (If the set is empty, then the body is not executed.)

The id attribute is a local loop variable containing the value of the current set element. Its type is specified in the type attribute. (The specified type should match the type of the set elements, as applicable.)

This tag currently supports iterations over the following types of data structures:

■ Java array

■ java.util.Enumeration

■ java.util.Vector

Syntax

<jml:foreach id = "loopVariable" in = "<%= jspExpression %>" limit = "<%= jspExpression %>" type = "package.class" > ...body of foreach tag (executes once for each element in data structure)...</jml:foreach>



Attributes

■ id—Names the loop variable, which holds the value of the current element at each step of the iteration. It can be used only within the body of the tag. Its type is the same as specified in the type attribute. The id attribute is required.

■ in—Specifies a JSP expression that evaluates to a Java array, Enumeration object, or Vector object. This is a required attribute.

■ limit—Specifies a JSP expression that evaluates to a Java int value defining the maximum number of iterations, regardless of the number of elements in the set. This is a required attribute.

■ type—Specifies the type of the loop variable. This should match the type of the set elements, as applicable. This is a required attribute.

Example The following example iterates over the request parameters.

<jml:foreach id="name" in="<%= request.getParameterNames() %>" type="java.lang.String" > Parameter: <%= name %> Value: <%= request.getParameter(name) %> <br></jml:foreach>

Or, if you want to handle parameters with multiple values:

<jml:foreach id="name" in="<%= request.getParameterNames() %>" type="java.lang.String" > Parameter: <%= name %> Value: <jml:foreach id="val" in="<%=request.getParameterValues(name)%>" type="java.lang.String" > <%= val %> : </jml:foreach> <br></jml:foreach>

JML return TagWhen this tag is reached, execution returns from the page without further processing.

Syntax

<jml:return />

Attributes

None.



Example The following example returns without processing the page if the timer has expired.

<jml:if condition="<%= timer.isExpired() %>" > You did not complete in time! <jml:return /></jml:if>

JML flush TagThis tag writes the current contents of the page buffer back to the client. This applies only if the page is buffered; otherwise, there is no effect.

Syntax

<jml:flush />

Attributes

None.

Example The following example flushes the current page contents before performing an expensive operation.

<jml:flush /><% myBean.expensiveOperation(out); %>


JESI Tags for Edge Side Inc

8
JESI Tags for Edge Side Includes
This chapter describes the JESI (JSP to ESI) tag library that is supplied with OracleJSP. These tags are layered on top of an Edge Side Includes (ESI) framework to provide ESI caching functionality in a JSP application.

The chapter includes the following topics:

■ Overview of Edge Side Includes Technology and Processing

■ Overview of JESI Functionality

■ OracleJSP JESI Tag Descriptions

ludes 8-1

Overview of Edge Side Includes Technology and Processing

Overview of Edge Side Includes Technology and ProcessingThis section provides background information about some of the underlying technology upon which the OracleJSP JESI tags are based.

JESI tags, which are used to break down dynamic content of JSP pages into cacheable components, are based upon the Edge Side Includes architecture and ESI markup language.

Although the use of JESI tags is not dependent upon any particular ESI processor or caching system, it is reasonable to assume that most OracleJSP customers would use the Oracle Web Cache and its ESI processor.


■ Edge Side Includes Technology

■ Oracle Web Cache and ESI Processor

This discussion provides only a brief overview of the ESI architecture and language. For additional information about ESI technology, refer to the following Web site:

http://www.edge-delivery.org

Edge Side Includes TechnologyThis section introduces the features of ESI technology and the concept of ESI "surrogates".

Introduction to ESIEdge Side Includes is an XML-style markup language that allows dynamic content assembly away from the origin Web server—at the "edge" of the network—and is designed to take advantage of available tools such as Web caches and content delivery networks (CDNs) to improve performance for end users.

ESI provides a means of reducing the load on Web and application servers by promoting processing on intermediaries, known as surrogates or reverse proxies, that understand the ESI language and act on behalf of the Web server. ESI content is intended for processing somewhere between the time it leaves the originating Web server and the time it is displayed in the end user’s browser. A surrogate is commanded through HTTP headers. Such a surrogate can be referred to as an "ESI processor" and may be included as part of the functionality of a Web cache.



ESI lends itself to a partial-page caching methodology, where each dynamic portion of a Web page can be cached individually and retrieved separately and appropriately.

Using the ESI markup tags, a developer can define aggregate Web pages and the cacheable components that are to be retrieved and assembled, as appropriate, by the ESI processor for viewing in the HTTP client. You can think of an aggregate page, which is the resource associated with the URL that an end user specifies, as simply a container for assembly, including retrieval and assembly instructions that are specified through the ESI tags.

More About SurrogatesBecause surrogates act on behalf of Web servers, where page content is owned, they allow content owners to have sufficient control over their behavior. In this way, they offer greater potential for performance improvements than would otherwise be available.

The caching process in surrogates operates similarly to the caching process in HTTP in general, using similar freshness and validation mechanisms as the foundation. However, surrogates also possess additional control mechanisms.

Key ESI FeaturesVersion 1.0 of the ESI language includes the following key areas of functionality:

■ inclusion

An ESI processor assembles fragments of dynamic content, retrieved from the network, into aggregate pages to output to the user. Each fragment can have its own meta data to control its caching behavior.

■ support of variables

ESI supports the use of variables based on HTTP request attributes. ESI statements can use variables during processing or can output them directly into the processed markup.

Note: Bear in mind that a JESI user does not have to (and would typically not want to) use ESI tags directly. JESI tag handlers translate JESI tags to ESI tags behind the scenes.

JESI Tags for Edge Side Includes 8-3


■ conditional processing

ESI allows use of boolean comparisons for conditional logic in determining how pages are processed.

■ error handling and alternative processing

Some ESI tags support specification of a default resource and/or an alternative resource, such as an alternate Web page, if the primary resource cannot be found.

Oracle Web Cache and ESI ProcessorThis section introduces the Oracle Web Cache and its ESI processor. See the Oracle Web Cache Administration and Deployment Guide, in the Oracle 9i Application Server documentation library, for more information.

Introduction to Oracle Web CacheOracle offers Oracle Web Cache to help e-businesses manage Web site performance issues. Oracle Web Cache is a content-aware server accelerator, or reverse proxy server, that improves the performance, scalability, and availability of Web sites that run on the Oracle9i Application Server.

By storing pages from frequently accessed URLs in memory, Oracle Web Cache eliminates the need to repeatedly process requests for those URLs on the application Web server. Unlike legacy proxy servers that handle only static documents, Oracle Web Cache caches both static content and dynamically generated content from one or more application Web servers. As the result of more frequent cache hits, Oracle Web Cache offers greater performance enhancement than legacy proxies and greatly reduces the load on application servers.

Conceptually, the Oracle Web Cache is positioned in front of application Web servers, caching their content and providing that content to Web browsers that request it. When Web browsers access the Web site, they send HTTP protocol or HTTPS protocol requests to Oracle Web Cache, which, in turn, acts as a virtual server for the application Web servers. If the requested content has expired or been invalidated or is no longer accessible, Oracle Web Cache retrieves the new content from the application Web servers. The application Web servers may retrieve their content from an Oracle database.



Steps in Web Cache UsageHere are the steps for typical browser interaction with Oracle Web Cache:

1. A browser sends a request to a company’s Web site.

This request, in turn, generates a request to the Domain Name System (DNS) for the IP address of the Web site.

2. DNS returns the IP address of Oracle Web Cache.

3. The browser sends the request for the Web page to Oracle Web Cache.

4. If the requested content is in its cache, Oracle Web Cache sends the content directly to the browser. This is known as a cache hit.

5. If Oracle Web Cache does not have the requested content, or the content is stale or invalid, then the Web cache hands off the request to the application Web server. This is known as a cache miss.

6. The application Web server sends the content through Oracle Web Cache.

7. Oracle Web Cache sends the content to the client and makes a copy of the page in cache.

Oracle Web Cache ESI ProcessorOracle Web Cache release 2.0.0.0 includes an ESI processor to support the use of the Edge Side Includes markup language in caching. (See "Edge Side Includes Technology" on page 8-2.)

A Web developer in an Oracle Web Cache environment can use the ESI language directly in his application; however, for OracleJSP developers, there are a number of reasons to use the JESI tag library that is provided as a convenient JSP interface to the ESI language. (See "Motivation for JESI Tags" on page 8-6.)

Note: A page that is stored in the cache is removed when it becomes invalid or outdated.


Overview of JESI Functionality

Overview of JESI FunctionalityThis section introduces JESI functionality and the OracleJSP implementation, covering the following topics:

■ Motivation for JESI Tags

■ Overview of JESI Tags Implemented by OracleJSP

■ JESI Usage Models

■ Page Invalidation

■ Page Personalization

You can access the JESI specification at the following Web site:

http://www.edge-delivery.org

Motivation for JESI TagsOracleJSP provides the JESI tag library as a convenient interface to ESI tags and Edge Side Includes functionality for Web caching. Developers have the option of using ESI tags directly in any Web application, but JESI tags provide additional convenience in a JSP environment. Here are the main advantages in using JESI tags instead of using ESI tags directly:

■ standard JSP framework and convenient features

For developers accustomed to using JSP pages or working in a JSP IDE environment, JESI tags allow use of the familiar and convenient features of JSP programming. For example, you can reference included pages by page-relative or application-relative syntax instead of the complete URL or file path.

■ JESI shortcut syntax

JESI tags support convenient syntax and tag attributes for specifying meta data information (such as expiration for cached pages), explicitly invalidating pages as appropriate, and personalizing pages using cookie information.

■ application-level configuration files

The JESI tag library can use application-level configuration files for convenient specification of deployment-time parameters and application default settings that are appropriate to a particular environment. In this way, you can deploy to different environments that have diverse needs and set appropriate defaults without changing application code.



For example, you can use such a configuration file to preset the cache server URL, user name, and password for invalidation requests.

Overview of JESI Tags Implemented by OracleJSPThe OracleJSP JESI tag library, a standard JavaServer Pages tag library implementation, is included in the OracleJSP ojsputil.jar file. (See "Summary of Files" on page A-4 for information about OracleJSP files.)

The OracleJSP implementation of JESI is layered on top of the standard ESI framework.

Because the JESI tag library is a standard implementation, note the following:

■ You can use it in any standard JSP environment—it does not depend on the OracleJSP container.

■ Even though this document discusses the Oracle Web Cache and its ESI processor in particular, the JESI tag library does not depend on any particular caching environment or any particular ESI processor.

The OracleJSP JESI tag library supports the following tags:

■ jesi:control, jesi:include, jesi:template, and jesi:fragment for page setup and content

■ jesi:invalidate (and subtags) for explicit invalidation of cached objects when appropriate

■ jesi:personalize for page personalization

Included with the tag library are the following:

■ tag handler classes for these tags

■ a standard tag library description file (TLD) for these tags

JSP developers use these tags (such as jesi:include) instead of corresponding ESI tags (such as esi:include). The usefulness and convenience of this is discussed previously, in "Motivation for JESI Tags" on page 8-6.

The OracleJSP JESI tag library is a standard library. For general information about the standard JavaServer Pages tag library framework, see "Standard Tag Library Framework" on page 7-2.



JESI Usage ModelsThere are two models for how to use JESI tags to define aggregate pages and their cacheable components:

■ the control/include model

■ the template/fragment model

This section describes these models, and concludes with some special notes about the jesi:include tag.

Control/Include ModelOne JESI tag approach is a modular one, typically bringing most (or all) cacheable content into the aggregate page as included pages. Use the jesi:control tag to set caching parameters, and jesi:include tags to bring in dynamic content.

Both tags are optional, however, depending on the situation. If default cache settings are sufficient, you can omit the jesi:control tag. You can also have a jesi:control tag with no jesi:include tags. In fact, this is the simplest way to convert an existing page for JESI use.

Each included file is a distinct cacheable object (although caching may be disabled according to tag settings), and any additional content in the aggregate page is also a distinct object.

This document refers to this modular approach as the control/include model. It is particularly convenient in a situation where you are developing new pages.

See the following sections for tag syntax and examples:

■ "JESI control Tag" on page 8-12

■ "JESI include Tag" on page 8-14

■ "Examples—Control/Include Model" on page 8-15

Template/Fragment ModelThe other JESI tag approach is one where content is in the aggregate page itself, and you split the page into separately cacheable fragments as desired. Use the

Notes: The jesi:control tag in the aggregate page has no effect on included pages. An included page without its own jesi:control tag uses default cache settings.



jesi:template tag to enclose the aggregate of all cacheable content. This tag sets caching parameters for the aggregate page (anything outside the fragments); otherwise default settings are used. Use jesi:fragment tags as desired to define fragments within the aggregate, to be cached separately. As with the aggregate page, fragments can set caching parameters or use default settings.

There can optionally be jesi:include tags as well, either at the template level or the fragment level.

The jesi:template tag and jesi:fragment tag are always used together. If you do not need separate fragments in a page, use jesi:control instead of jesi:template.

Each fragment is a distinct cacheable object, and dynamic content at the template level, outside any fragments, is a distinct cacheable object.

This document refers to the preceding scenario as the template/fragment model. It is particularly convenient in a situation where you are converting existing pages for JESI use.

See the following sections for tag syntax and examples:

■ "JESI template Tag" on page 8-17

■ "JESI fragment Tag" on page 8-19

■ "JESI include Tag" on page 8-14

■ "Examples—Template/Fragment Model" on page 8-19

Notes About JESI IncludesIn using either model, be aware of the following notes regarding the jesi:include statement:

■ Nested "includes" are supported, either as a jesi:include statement that includes a page that in turn has its own jesi:include statement, or as a jesi:include statement inside a fragment defined with jesi:fragment.

In the latter case, for example, the ESI processor would first request content of the aggregate page, would next request content of the fragment, and finally would request content of the included page within the fragment.

■ Despite conceptual similarities between jesi:include and jsp:include, jesi:include is not a perfect substitute for jsp:include when you convert a JSP page for caching. Because the ESI processor uses separate HTTP requests, you are unable to pass an HTTP request or response object between an



aggregate page and a page it includes through a jesi:include tag. If the code in the included page needs access to the request or response object of the aggregate page, you can put the code in a jesi:fragment tag (within the jesi:template tag of the aggregate page) instead of in an included page.

Page InvalidationThere may be situations where cached objects must be explicitly invalidated due to external circumstances, such as changes to relevant data in a database. There may also be situations where execution of one page may invalidate the data of cached objects corresponding to another page.

For this reason, the JESI specification provides for the jesi:invalidate tag and several subtags. These tags allow you to invalidate pages based on appropriate combinations of the following:

■ a full URI or URI prefix

■ a cookie name-value pair (optional)

■ an HTTP/1.1 request header name-value pair (optional)

Invalidation messages are in an XML-based format, and specify the URLs to be invalidated. These messages are transmitted to the cache server over HTTP using a POST method. The cache server then replies with an invalidation response, sent back over HTTP.

See "Page Invalidation Tag and Subtag Descriptions" on page 8-21 for tag syntax and examples.

Page PersonalizationDynamic Web pages frequently display personalized information tailored to each individual user. For example, a welcome page may display the user’s name and a special greeting, or current quotes for stocks the user owns.

For this sort of tailored output, the Web page depends on cookie information. Without special tags to inform the ESI processor of this dependency, the Web page cannot be shared by multiple users at the ESI level.

See "Page Personalization Tag Description" on page 8-27 for tag syntax and examples.


OracleJSP JESI Tag Descriptions

OracleJSP JESI Tag DescriptionsThis section describes the syntax and attributes for the JESI tags provided with OracleJSP, followed by usage examples. Discussion is organized into the following categories:

■ Syntax Symbology and Notes

■ Page Setup and Content Tag Descriptions

■ Page Invalidation Tag and Subtag Descriptions

■ Page Personalization Tag Description

■ JESI Tag Handling and JESI-to-ESI Conversion

■ OracleJSP JESI Tag Library Description File


■ Italic indicates that you must specify a value or string.


■ Default values of some optional attributes are indicated in bold.


■ The prefix "jesi:" is used. This is by convention but is not required. You can specify any desired prefix in your taglib directive.

■ Wherever a value or string is to be specified for an attribute of any of the JESI tags, Oracle also supports a JSP expression that resolves to an appropriate value or string.

Note: Default settings (default expiration time, for example) are determined by the ESI processor. In the case of the Oracle Web Cache ESI processor, this is according to the Oracle Web Cache configuration file.



Page Setup and Content Tag DescriptionsThis section summarizes the use of the following tags and documents their syntax and attributes:

■ jesi:control

■ jesi:include

■ jesi:template

■ jesi:fragment

This section also provides examples of both the control/include model and the template/fragment model.

Summary of Page Setup and Usage ModelsAs "JESI Usage Models" on page 8-8 explains, there are two scenarios in using JESI tags in a JSP page:

■ control/include—Use a jesi:control tag to specify cache settings for a page, and use jesi:include tags to bring in dynamic pages that are separate cacheable objects (or non-cacheable, depending on tag settings).

■ template/fragment—Use a jesi:template tag to set up caching and specify cache settings in the aggregate page, and use nested jesi:fragment tags to specify individual cacheable (or non-cacheable) objects within the aggregate page (specifying alternative cache settings as desired). You can use jesi:include tags within fragments or within the overall template as well.

JESI control TagThe jesi:control tag controls caching characteristics for JSP pages in the control/include usage model. You can use a jesi:control tag in the aggregate page or any included page, but it is not mandatory. If default cache settings are sufficient, you can use jesi:include tags with no jesi:control tag. (See "JESI Usage Models" on page 8-8.) Corresponding HTTP headers will be set according to the edge architecture specification.

The jesi:control tag should appear as early as possible in the page, before any other JESI tags or any buffer flushes in the page.

Be aware of the following:

■ Do not use multiple jesi:control tags in a single JSP page. An exception would result.



■ Do not use a jesi:control tag and a jesi:template tag in the same page. An exception would result.

■ The jesi:control tag of the aggregate page has no effect on included pages. Use a jesi:control tag in each included page as well, as necessary (where default control settings are not sufficient).

Syntax

<jesi:control [expiration = "value"] [maxRemovalDelay = "value"] [cache = "yes | no | no-remote"] />

Attributes

■ expiration—Specifies the lifetime, in seconds, of the cached object. By default, the object never expires.

■ maxRemovalDelay—Specifies the maximum time, in seconds, that the ESI processor can store the cached object after it has expired. This is 0 by default, for immediate removal.

■ cache—Specifies whether the object corresponding to the page is cacheable. This is true by default, but you can also set cache to yes explicitly. Alternatively, you can set cache to no for a page to not be cacheable, or to no-remote for it to be cacheable only locally (as opposed to on a remote Web server or content delivery network).

One reason to make a page non-cacheable, for example, is if you are using a jesi:include tag with copyparam enabled. See "JESI include Tag" below.)

Note: The JESI specification includes a control attribute for the jesi:control tag. This attribute is for setting parameters of ESI control headers directly. The current Oracle implementation, however, supports setting only the control header max-age parameter. Setting this is unnecessary, though, because setting the expiration and maxRemovalDelay attributes of jesi:control serves the same purpose. Therefore, in this release, the control attribute is not documented. (Future releases will likely support setting additional ESI control header parameters, at which time the control attribute will be documented here.)



JESI include TagThe jesi:include tag, like a standard jsp:include tag, dynamically inserts output from the included page into output from the including page. Additionally, it is directing that the included page be processed and assembled by the ESI processor. Each included page is a separate cacheable object (or non-cacheable, depending on tag settings).

You can use this tag in both the control/include model and the template/fragment model, in any of the following scenarios:

■ by themselves, without a JESI control tag or JESI template/fragment tags

■ after a jesi:control tag

■ within a jesi:template tag, outside of any fragments

■ within a jesi:fragment tag

(See "JESI Usage Models" on page 8-8.)

Although the jesi:include tag has similarities in usage to jsp:include, its different semantics make it unsuitable for page inclusions where request or response objects must be passed between the originating page and the included page.

Syntax

<jesi:include page = "uri_string" [alt = "alt_uri_string"] [ignoreError = "true | false"] [copyparam = "true | false"] [flush = "true | false"] />

Attributes

■ page (required)—Specifies the URI of the JSP page to be included, using either page-relative or application-relative syntax. (See "Indirectly Requesting a JSP Page" on page 1-9 for information about page-relative versus application-relative syntax.) A full "http://..." or "https://..." URL is supported as well.

■ alt—Specifies a URI for an alternate page, to be included if the page that is specified in the page attribute cannot be accessed. Syntax is the same as for the page attribute.



■ ignoreError—Set this to true for processing of the including page to continue even if no included page (neither the page page nor alt page) can be accessed.

■ copyparam—Set this to true to copy parameters and their values from the HTTP request string of the including page to the included page.

■ flush—This attribute is ignored, but is supported to ease migration from jsp:include syntax.

Examples—Control/Include ModelThis section provides examples of JESI tag usage in the control/include model.

Example 1: Control/Include The following example employs default cache settings; no jesi:control tag is necessary. The jesi:include tags specify no alternate files, and a "file not found" error will halt processing. The flush attribute is permissible but ignored.

<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %><html><body><jesi:include page="stocks.jsp" flush="true" /><p><hr><jesi:include page="/weather.jsp" flush="true" /><p><hr><jesi:include page="../sales.jsp" flush="true" /></body></html>

Notes:

■ Use copyparam="true" in non-cacheable pages only (cache="no" in the jesi:control tag), because request parameters may change from request to request.

■ Future releases may support a jesi:param subtag, conceptually similar to the jsp:param subtag used with jsp:include.



Example 2: Control/Include This example uses the jesi:control tag to specify non-default cache settings for maxRemovalDelay and expiration. In addition, it explicitly enables caching of the page, though this is already enabled by default. The first jesi:include tag specifies an alternate page in case order.jsp cannot be retrieved by the ESI processor, and specifies that processing continue even if neither page can be retrieved. The second jesi:include tag specifies no alternate page, and processing will halt if the page cannot be retrieved.

As you can see, the HTML tags that "Example 1: Control/Include" uses are not actually required.

<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %>

<jesi:control maxRemovalDelay="1000" expiration="300" cache="yes"/><jesi:include page="order.jsp" alt="alt.jsp" ignoreError="true"/><jesi:include page="commit.jsp" />

Example 3: Control/Include This is an example of an aggregate page whose output is conditional. A cookie represents the identity of a customer. If no cookie is found, the user will see a generic welcome page with general product information. If a cookie is found, the user will see a list of products according to the user profile. This list is brought into the page through a jesi:include statement.

The jesi:control tag also sets non-default values for maxRemovalDelay and expiration, and explicitly enables caching for the page.


<jesi:control maxRemovalDelay="1000" expiration="300" cache="yes"/><% String customerId=CookieUtil.getCookieValue(request,"customerid");

if (customerId==null) {

// some unknown customer %> <jesi:include page="genericwelcome.jsp" /><% } else {

// a known customer; trying to retrieve recommended products from profiling String recommendedProductsDescPages[]= ProfileUtil.getRecommendedProductsDescURL(customerId);



for (int i=0; i < recommendedProductsDescPages.length; i++) {%> <jesi:include page="<%=recommendedProductsDescPages[i]%>" /><% } }%>

Example 4: Control/Include This example illustrates the use of jesi:include statements with request parameters. Assume the main page is accessed through the following URL:

http://host:port/application1/main.jsp?p2=abc

The main page takes the parameter setting p2=abc. Here is the page:

<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %><html> <jesi:control cache="no" /> <jesi:include page="a.jsp?p1=v1" /> <h3>hello ...</h3> <jesi:include page="b.jsp" /> <h3>world ...</h3> <jesi:include page="c.jsp?p1=v2" copyparam="true" /> </html>

The a.jsp page takes the parameter setting p1=v1. The c.jsp page takes the setting p1=v2 as well as the setting p2=abc (as a result of the copyparam setting and the p2 setting in the URL for the main page).

Additionally, this page is non-cacheable, according to the cache="no" setting. In fact, remember that you should use the copyparam setting only in non-cacheable pages, because the request attributes may change from one request to the next. Remember, too, that the cache="no" setting has no effect on the included pages—they are still cacheable by default. (In other words, they are cacheable unless any of them also have a jesi:control tag with cache="no" for some reason.)

JESI template TagUse the jesi:template tag to specify caching behavior for the aggregate page in the template/fragment usage model. (See "JESI Usage Models" on page 8-8.) The



corresponding HTTP header will be set according to the edge architecture specification.

Use one or more jesi:fragment tags within the jesi:template tag, between its start and end tags, to specify separate cacheable fragments within the template. Place the jesi:template start tag as early in the page as possible—it must appear before any other JESI tags or any buffer flushes in the page. Place the jesi:template end tag as late in the page as possible—it must appear after any other JESI tags in the page.

The aggregate content (outside the fragments) is a cacheable object, and each fragment set aside with a jesi:fragment tag is a separate cacheable object. For the aggregate content and for each fragment, you can set caching parameters as desired or use default settings. The jesi:template tag settings have no effect on the fragments.

The jesi:template tag is always used together with jesi:fragment tags. If you have no need for separate fragments, use a jesi:control tag instead of a jesi:template tag.


■ Do not use multiple jesi:template tags in a single JSP page. An exception would result.

■ Do not use a jesi:control tag and a jesi:template tag in the same page. An exception would result.

■ The jesi:template tag settings have no effect on the enclosed fragments; fragments must provide their own settings (or use defaults).

The jesi:template tag has the same attributes, with the same usage, as the jesi:control tag.

Syntax

<jesi:template [expiration = "value"] [maxRemovalDelay = "value"] [cache = "yes | no | no-remote"] >

...page content, jesi:fragment tags, jesi:include tags...

</jesi:template>



Attributes

For attribute descriptions, see "JESI control Tag" on page 8-12.

JESI fragment TagUse one or more jesi:fragment tags within a jesi:template tag, between the jesi:template start and end tags, in the template/fragment model. (See "JESI Usage Models" on page 8-8.) The jesi:fragment defines separate fragments of JSP code, as desired, for caching behavior. Each fragment is a separate cacheable object.

When a particular fragment is requested through the ESI mechanism, the ESI processor will retrieve only that fragment.

Each jesi:fragment tag specifies its own instructions to the ESI processor. Cache properties not specified in the jesi:fragment tag will be set according to default values. (The settings of the surrounding jesi:template tag have no effect on the fragments.) Corresponding HTTP headers will be set according to the edge architecture specification.

The jesi:fragment tag has the same attributes, with the same usage, as the jesi:control and jesi:template tags.

Syntax

<jesi:fragment [expiration = "value"] [maxRemovalDelay = "value"] [cache = "yes | no | no-remote"] >

...JSP code fragment...

</jesi:fragment>

Attributes

For attribute descriptions, see "JESI control Tag" on page 8-12.

Examples—Template/Fragment ModelThis section contains examples of JESI tag usage in the template/fragment model.

Example 1: Template/Fragment This is a general example showing use of the jesi:template and jesi:fragment tags. Because only the expiration attribute is set in any of the tags, all other settings are according to defaults.



The aggregate content (outside the fragments), according to the jesi:template tag, uses an expiration of 3600 seconds. This applies to all the HTML blocks because they are all outside the fragments. JSP code block #1 is cached with an expiration setting of 60; JSP code block #2 is cached with the default expiration setting; and JSP code block #3 is cached with an expiration setting of 600.

<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %><jesi:template expiration="3600"> ...HTML blcck #1... <jesi:fragment expiration="60"> ...JSP code block #1... </jesi:fragment> ...HTML block #2... <jesi:fragment> ...JSP code block #2... </jesi:fragment> ...HTML block #3... <jesi:fragment expiration="600"> ...JSP code block #3... </jesi:fragment> ...HTML block #4...</jesi:template>

Example 2: Template/Fragment This example employs jesi:include tags inside the fragments. The following are the cacheable objects for this page:

■ each included page

■ each fragment, outside of its included page

■ the aggregate of the HTML blocks, which are all at template level (outside the fragments)

<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %><jesi:template expiration="3600"> ...HTML blcck #1... <jesi:fragment expiration="60"> ...JSP code block #1... <jesi:include page="stocks.jsp" /> </jesi:fragment> ...HTML block #2... <jesi:fragment> ...JSP code block #2... <jesi:include page="/weather.jsp" /> </jesi:fragment>



...HTML block #3... <jesi:fragment expiration="600"> ...JSP code block #3... <jesi:include page="../sales.jsp" /> </jesi:fragment> ...HTML block #4...</jesi:template>

Page Invalidation Tag and Subtag DescriptionsUse the jesi:invalidate tag and the following subtags, as appropriate, to explicitly invalidate cached objects in the ESI processor:

■ jesi:object

■ jesi:cookie (subtag of jesi:object)

■ jesi:header (subtag of jesi:object)

See "Page Invalidation" on page 8-10 for an overview.

JESI invalidate TagYou can use the jesi:invalidate tag with its jesi:object subtag to explicitly invalidate one or more cached objects.

Use the subtags as follows:

■ Use the required jesi:object subtag to specify what to invalidate according to URI or URI prefix.

■ Optionally use the jesi:cookie subtag or jesi:header subtag of jesi:object to specify further criteria for what to invalidate, according to cookie or HTTP header information.

Syntax

<jesi:invalidate [url = "url_string" username = "username_string" password = "password_string"] [config = "configfilename_string"] [output = "browser"] >



Required subtag (described in "JESI object Subtag" on page 8-23):

<jesi:object ... >

Optional subtag of jesi:object (described in "JESI cookie Subtag" on page 8-24):

<jesi:cookie ... />

Optional subtag of jesi:object (described in "JESI header Subtag" on page 8-25):

<jesi:header ... />

</jesi:object>

</jesi:invalidate>

Either specify the user, password, and URL all through their individual tags, or all in the configuration file referred to in the config tag.

Attributes

■ url—Specifies the URL of the cache server. If this attribute is omitted, you must specify the URL in the JESI configuration file.

■ username—Specifies the user name for logging in to the cache server. If this attribute is omitted, you must specify the user name in the JESI configuration file.

■ password—Specifies the password for logging in to the cache server. If this attribute is omitted, you must specify the password in the JESI configuration file.

■ config—Specifies a JESI configuration file. You can use this file to provide the cache server URL, user name, and password information instead of using the corresponding tag attributes. Specify the location in application-relative syntax, starting with "/". (See "Indirectly Requesting a JSP Page" on page 1-9 for general information about application-relative syntax.)

■ output—Optionally sets an output device to receive the invalidation response from the cache server. Currently, the only supported setting is browser, to

Note: It is permissible to have multiple object tags within an invalidate tag.



show the message in the user’s Web browser. If you do not set this parameter, the confirmation message will not be displayed at all.

Example: Configuration File Following is an example of a configuration file that is used instead of the url, username, and password attributes to set the URL and login information:

<?xml version="1.0" ?><ojsp-config> <web-cache> <url>http://yourhost.yourcompany.com:4001</url> <username>invalidator</username> <password>invpwd</password> </web-cache></ojsp-config>

JESI object SubtagUse the required jesi:object subtag of the jesi:invalidate tag to specify cached objects to invalidate according to either the complete URI or a URI prefix. Optionally use its jesi:cookie subtag or jesi:header subtag to specify further criteria for invalidation, based on cookie or HTTP header information.

Specify either the complete URI or the URI prefix in the uri attribute setting. Whether this field is interpreted as a full URI or as a prefix depends on the setting of the prefix attribute.

Syntax

<jesi:object uri = "uri_or_uriprefix_string" maxRemovalDelay = "value" [prefix = "yes | no"] >

Optional subtag (described in "JESI cookie Subtag" on page 8-24):

<jesi:cookie ... />

Optional subtag (described in "JESI header Subtag" on page 8-25):

<jesi:header ... />

</jesi:object>



or (if not using either subtag):

<jesi:object [uri = "uri_or_uriprefix_string"] [prefix = "yes | no"] [maxRemovalDelay = "value"] />

Attributes

■ uri—Specifies either the complete URI of the page whose corresponding cached object is to be invalidated (if prefix="no"), or a URI prefix that specifies objects for multiple pages to be invalidated according to location (if prefix="yes").

If a prefix is specified, then cached objects for all pages under that location are invalidated. For example, for a prefix setting of /abc/def, cached objects for all pages in the corresponding directory and any subdirectories are invalidated.

■ prefix—Set this to yes if the uri attribute is to be interpreted as a URI prefix only, and to no if uri is to be interpreted as a complete URI.

■ maxRemovalDelay—Specifies the maximum time, in seconds, that the ESI processor can store the cached object after it has been invalidated. This is 0 by default, for immediate removal.

JESI cookie SubtagUse the jesi:cookie subtag of the jesi:object tag (which is a subtag of jesi:invalidate) to use cookie information as a further criterion for invalidation. This is used in addition to the URI or URI prefix setting in the jesi:object tag, and possibly in addition to a jesi:header tag as well.

Syntax

<jesi:cookie name = "name_string" value = "value_string" />

Note:

■ It is permissible to have multiple object tags within an invalidate tag.

■ It is permissible to have multiple cookie tags or header tags within an object tag.



Attributes

■ name (required)—The name of the cookie.

■ value (required)—The value of the cookie.

For a cached object to be invalidated, it would have to have a cookie that matches this name and value.

JESI header SubtagUse the jesi:header subtag of the jesi:object tag (which is a subtag of jesi:invalidate) to use HTTP/1.1 header information as a further criterion for invalidation. This is in addition to the URI or URI prefix setting in the jesi:object tag, and possibly in addition to a jesi:cookie tag as well.

Syntax

<jesi:header name = "name_string" value = "value_string" />

Attributes

■ name (required)—The name of the HTTP/1.1 header.

■ value (required)—The value of the HTTP/1.1 header.

For a cached object to be invalidated, it would have to have a header that matches this name and value.

Examples—Page InvalidationThis section provides examples of page invalidation using the jesi:invalidate tag, its jesi:object subtag, and the jesi:cookie subtag of the jesi:object tag.

Note: It is permissible to have multiple cookie tags within an object tag.

Note: It is permissible to have multiple header tags within an object tag.



Example 1: Page Invalidation This example invalidates a single object in the ESI processor, specified by its complete URI. (By default, uri specifies a full URI, not a URI prefix.) The jesi:invalidate tag also specifies the URL for the cache server and the user name and password for login, and it specifies that the invalidation response from the cache server should be displayed in the user’s browser.

...<jesi:invalidate url="http://yourhost.yourcompany.com:4001" username="invalidator" password="invpwd" output="browser"> <jesi:object uri="/images/logo.gif"/></jesi:invalidate>...

Example 2: Page Invalidation This is equivalent to Example 1: Page Invalidation, but uses a configuration file to specify the cache server URL and login information.

...<jesi:invalidate config="myconfig.xml" output="browser"> <jesi:object uri="/images/logo.gif"/></jesi:invalidate>...

The jesi:invalidate uses page-relative syntax for the configuration file, so myconfig.xml is presumably in the same directory as the JSP page. As an example, assume that it has the following content:

<?xml version="1.0" ?><ojsp-config> <web-cache> <url>http://yourhost.yourcompany.com:4001</url> <username>invalidator</username> <password>invpwd</password> </web-cache></ojsp-config>

Example 3: Page Invalidation This example invalidates all objects in the ESI processor, according to the URI prefix "/". It does not specify that the invalidation confirmation message be displayed in the browser, so it will not be displayed at all.

...<jesi:invalidate url="http://yourhost.yourcompany.com:4001" username="invalidator" password="invpwd">



<jesi:object uri="/" prefix="yes"/></jesi:invalidate>...

Example 4: Page Invalidation This example invalidates a single object but allows it to be served stale for up to 30 minutes (1800 seconds). Also, the invalidation message sent by OracleJSP to the cache server will include supplementary system information indicating that the operating system is UNIX.

...<jesi:invalidate url="http://yourhost.yourcompany.com:4001" username="invalidator" password="invpwd"> <jesi:object uri="/images/logo.gif" maxRemovalDelay="1800"/></jesi:invalidate>...

Example 5: Page Invalidation This example specifies the same object for invalidation as Example 1: Page Invalidation, but specifies that it should be invalidated only if it has a cookie named user_type with value customer.

...<jesi:invalidate url="http://yourhost.yourcompany.com:4001" username="invalidator" password="invpwd"> <jesi:object uri="/images/logo.gif"> <jesi:cookie name="user_type" value="customer"/> </jesi:object></jesi:invalidate>...

Page Personalization Tag DescriptionTo allow dynamic page personalization, the ESI processor must be informed of dependencies by the page on cookie and session information. Cookie value replacement, for example, occurs in the ESI processor instead of the Web server.

JESI personalize TagUse the jesi:personalize tag to allow page personalization, by informing the ESI processor of dependencies on cookie and session information.



Syntax

<jesi:personalize name = "name_string" [value = "default_value_string"] />

Attributes

■ name (required)—Specifies the name of the cookie whose value is used as the basis for personalizing the page.

■ value—An optional default value in case the cookie is not found. This allows the ESI processor to avoid having to go back to the Web server to look for the cookie.

Example—Page PersonalizationFollowing is an example showing use of the jesi:personalize tag:

<jesi:personalize name="user_id" value="guest" />

The corresponding ESI tag that is generated allows the ESI processor to find the necessary information. In this case, it looks for a cookie named user_id and retrieve its value. If it cannot find the cookie, it uses a default value of guest. Handling this cookie-value replacement in the ESI processor avoids having to send a request to the Web server.

JESI Tag Handling and JESI-to-ESI ConversionJESI tag handler classes, supplied as part of the OracleJSP JESI tag library, provide the bridge from JSP functionality to ESI functionality. Tag handlers translate JESI tags into ESI tags and, as appropriate, generate HTTP requests for invalidation, set HTTP response headers, and so on. (Be aware, however, that there is not always a simple one-to-one mapping between JESI tags and ESI tags, or between JESI tag attributes and ESI tag attributes.)

As an example, consider this JSP code from an example earlier in this chapter:

...<jesi:include page="stocks.jsp" flush="true" /><p><hr><jesi:include page="/weather.jsp" flush="true" /><p><hr><jesi:include page="../sales.jsp" flush="true" />...


The jesi:include tag handler generates ESI markup such as the following:

...<esi:include src="http://host:port/application1/dir2/dir3/stocks.jsp" /><p><hr><esi:include src="http://host:port/application1/weather.jsp" /><p><hr><esi:include src="http://host:port/application1/dir2/sales.jsp" />...

OracleJSP JESI Tag Library Description FileThis section presents a listing of jesitaglib.tld, the complete tag library description file (TLD) for the OracleJSP JESI tag library.

<?xml version="1.0" encoding="ISO-8859-1" ?><!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN" "web-jsptaglib_1_1.dtd">


<taglib> 

<tlibversion>1.0</tlibversion> <jspversion>1.1</jspversion> <shortname>simple</shortname> <info> A simple tab library for the jesi </info> 

 <tag> <name>invalidate</name> <tagclass>oracle.jsp.tags.jesi.InvalidationTag</tagclass> <bodycontent>JSP</bodycontent>


<attribute> <name>url</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>username</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>password</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>config</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>output</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

<tag> <name>object</name> <tagclass>oracle.jsp.tags.jesi.ObjectTag</tagclass> <bodycontent>JSP</bodycontent>

<attribute> <name>uri</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>maxRemovalDelay</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>prefix</name>


<required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <tag> <name>cookie</name> <tagclass>oracle.jsp.tags.jesi.CookieTag</tagclass> <bodycontent>JSP</bodycontent>

<attribute> <name>name</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>value</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <tag> <name>header</name> <tagclass>oracle.jsp.tags.jesi.HeaderTag</tagclass> <bodycontent>JSP</bodycontent>

<attribute> <name>name</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>value</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

 <tag> <name>fragment</name> <tagclass>oracle.jsp.tags.jesi.FragmentTag</tagclass> <bodycontent>JSP</bodycontent> <attribute> <name>control</name> <required>false</required>


<rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>cache</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>expiration</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>maxRemovalDelay</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

<tag> <name>include</name> <tagclass>oracle.jsp.tags.jesi.IncludeTag</tagclass> <bodycontent>JSP</bodycontent> <attribute> <name>page</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>ignoreError</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>alt</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>copyparam</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>flush</name>



<required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <tag> <name>control</name> <tagclass>oracle.jsp.tags.jesi.ControlTag</tagclass> <bodycontent>JSP</bodycontent> <attribute> <name>control</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>cache</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>expiration</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>maxRemovalDelay</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <tag> <name>template</name> <tagclass>oracle.jsp.tags.jesi.TemplateTag</tagclass> <bodycontent>JSP</bodycontent> <attribute> <name>control</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>cache</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>expiration</name>



<required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>maxRemovalDelay</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag> <tag> <name>personalize</name> <tagclass>oracle.jsp.tags.jesi.PersonalizeTag</tagclass> <bodycontent>JSP</bodycontent> <attribute> <name>name</name> <required>true</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>value</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag></taglib>


Web Object Cache Tags an

9
Web Object Cache Tags and API
This chapter describes the OracleJSP Web Object Cache, an application-level caching mechanism. For Web applications written in Java, you can use the Web Object Cache in conjunction with the Oracle Web Cache for increased speed and scalability.

This chapter includes the following topics:

■ Overview of the Web Object Cache

■ Key Functionality of the Web Object Cache

■ Attributes for Policy Specification and Use

■ Web Object Cache Tag Descriptions

■ Web Object Cache Servlet API Description

■ Cache Policy Descriptor

■ Cache Repository Descriptor

For an overview of Web caching, including a discussion of the Oracle Web Cache and Oracle9i Application Server Object Caching Service for Java, see "Overview of Oracle Caching Support for Web Applications" on page 2-19.

d API 9-1

Overview of the Web Object Cache

Overview of the Web Object CacheThe OracleJSP Web Object Cache is a mechanism that allows Web applications written in Java to capture, store, reuse, post-process, and maintain the partial and intermediate results generated by a dynamic Web page, such as a JSP or servlet. For programming interfaces, it provides a tag library (for use in JSP pages) and a Java API (for use in servlets).

The Web Object Cache works at the Java level and is closely integrated with the HTTP environment of JSP and servlet applications. Cached objects might consist of HTML or XML fragments, XML DOM objects, or Java serializable objects.

Through the Web Object Cache programming interfaces, you can decide how to split Web pages into page blocks that define separate cache objects for finer control of caching. (The terms block and object can be used somewhat interchangeably in this sense.) In this way, the application itself can control life span and other behavior of individual cache entities during runtime. Application developers have the best understanding of the life cycle patterns of their application Web pages, so are best suited to determine how to split pages into cache blocks. You can specify maintenance policies for partial results either declaratively in an external file (the cache policy descriptor), or programmatically within the application itself.


■ Benefits of the Web Object Cache

■ Web Object Cache Components

■ Cache Policy and Scope

Benefits of the Web Object Cache

Using the Web Object Cache can significantly reduce the amount of time spent in constructing page blocks or Java objects in dynamic applications, such as those with expensive intermediate operations like querying a database and formatting or

Note: The Web Object Cache is useful in particular scenarios and does not replace the need for other caching mechanisms, including the Oracle Web Cache. For an overview of the Web Object Cache, and how it relates to the Oracle Web Cache and the Oracle9iAS Object Caching Service for Java, including a discussion of when it is appropriate to use each one, see "Overview of Oracle Caching Support for Web Applications" on page 2-19.



transforming the results. Subsequent queries pull the information out of the cache, so the query and formatting do not have to be repeated.

Furthermore, developers can closely control the cache programmatically, through API calls or custom JSP tags. This can include controlling when cache entries are created, what they are named, when they expire, which users can see which cached data, and what operations can be applied to cached data before the results are served to the user.

Some kinds of Web applications benefit more than others by using the Web Object Cache, depending on the nature and use of their data. For example, applications such as catalog and directory browsing, delayed stock quotes, and personalized portals would particularly benefit. Applications such as real-time stock trading or real-time stock quotes, however, would not benefit, because the data has to be updated so frequently that the overhead of the caching operations would outweigh the benefits. (In these circumstances, however, the Oracle Web Cache might still be useful because of its lighter overhead.)

In general, the Web Object Cache is most useful in the following situations:

■ for special post-processing on cached data objects, such as XSLT or XML DOM operations

■ for sharing data in a non-HTTP situation, such as reusing cached XML data or Java objects and sending the data to others through SMTP, JMS, AQ, or SOAP.

■ for special storage needs, such as storing cached data in a file system or database for persistent storage of data with a long lifetime

■ for application-specific authorization, allowing different users to have different access rights to different data items, such as for a Web-based groupware application

The application can have its own authorization scheme. The Web Object Cache is embedded within Java authorization logic.

Using the Web Object Cache in JSP pages, as opposed to servlets, is particularly convenient. JSP code generation can save much of the development effort.

Web Object Cache Tags and API 9-3


Web Object Cache ComponentsThe Web Object Cache consists of two main components:

■ the cache repository

■ the cache programming interfaces

This section also provides a brief introduction to the Oracle9i Application Server Object Caching Service for Java, which the Web Object Cache uses as its default cache repository.

Cache RepositoryThe cache repository is the component that is responsible for data storage, data distribution, and cache expiration. Generally speaking, there can be multiple repository implementations for a programmable Web cache (such as the Web Object Cache), depending on the tier and platform. For example, the file system might be used for secondary storage in the middle tier, and database tables for primary storage in the database tier. ("Web Object Cache—Using a File System Cache" on page 11-65, for example, uses a simple file system cache.)

The Oracle Web Object Cache uses the Oracle9iAS Object Caching Service for Java as its default repository. This is a general-purpose caching service and API designed for Java application use, with objects being accessible by name.

The object caching service is a powerful and flexible programming facility. There are no restrictions on the types of objects that can be cached or the original source of the objects—the management of each object is easily customizable. Each object has a set of attributes such as the following:

■ how the object is loaded into the cache

■ where the object is stored (in memory, on disk, or both)

■ the lifetime, also known as the time-to-live, of the object

■ whom to notify when the object is invalidated

Objects can be invalidated as a group or individually.

For more information, see the Oracle9iAS Object Caching Service for Java Developer’s Guide.



Cache Programming InterfacesThe front-end caching interfaces are used through JSP pages and servlets to handle HTTP processing and to direct the semantics relating to the cache policy (rules and specifications determining how the cache works).

Generally speaking, the OracleJSP Web Object Cache programming interfaces can be further divided as follows:

■ Web Object Cache tag library

This is a convenient wrapper, using JSP custom tag functionality, for the Web Object Cache API. Use custom tags in a JSP page to control the caching, with the API being called through the underlying tag handler classes.

■ Web Object Cache servlet API

This is the common layer across servlets and JSP pages, dealing with the HTTP semantics and cache policy. This layer communicates with the cache repository.

This chapter describes these programming interfaces and their interaction with the cache repository. OracleJSP cache tags are described in "Web Object Cache Tag Descriptions" on page 9-21. The underlying cache policy API is described in "Web Object Cache Servlet API Description" on page 9-50. In servlets, you will use the underlying API; in JSP pages, you will typically use the more convenient tags.

Notes:

■ Web Object Cache sample applications include configuration notes for a file system cache repository or for the Oracle9iAS Object Caching Service for Java. See "Configuration Notes for File System Cache" on page 11-69 and "Configuration Notes for Oracle9iAS Object Caching Service for Java" on page 11-65.

■ In its current release, the Oracle9iAS Object Caching Service for Java is for use in the application server middle-tier JDK only.



Cache Policy and ScopeThe cache policy is a set of specifications determining details of the cache and how it will behave. This includes the following:

■ cache scope

■ cache block naming rules

■ data expiration rules

■ cache repository name

You can set cache policy specifications (per "Attributes for Policy Specification and Use" on page 9-12) through any of the following:

■ cache tag attributes (for JSP pages)

See "Web Object Cache Tag Descriptions" on page 9-21.

■ cache policy methods (for servlets)

See "Web Object Cache Servlet API Description" on page 9-50.

■ external cache policy descriptor files (for JSP pages or servlets)

See "Cache Policy Descriptor" on page 9-63.

A cache policy object—an instance of the oracle.jsp.jwcache.CachePolicy class—is created with policy settings based on these inputs. Because the expiration policy is part of the cache policy, each CachePolicy object includes an attribute that is an instance of the oracle.jsp.jwcache.ExpirationPolicy class.

Cache data can be of either session scope, where it is available to only the current HTTP session, or application scope, where it is available to all users of the application.

For example, consider an online banking application that caches the account balance. Only the current user is interested in this information, so session scope is appropriate.

By contrast, consider an online store with a welcome page that issues the same general product recommendations to all users. In this case, it is appropriate for the page to use a cache that has application scope.


Key Functionality of the Web Object Cache

Key Functionality of the Web Object CacheThis section discusses key areas of functionality of the Web Object Cache, covering the following:

■ Cache Block Naming—Implicit Versus Explicit

■ Cache Block Runtime Functionality

■ Data Invalidation and Expiration

Cache Block Naming—Implicit Versus ExplicitA cache block is associated with a cache block name, which can be determined either implicitly by the caching policy (generally advisable), or explicitly by your application code. For retrieval, to avoid regenerating the page fragment in question, there is a lookup of the cache block name.

For implicit naming, there are two inputs:

■ the cache policy

A cache policy API layer performs naming logic.

■ the HTTP request object

The caching logic borrows corresponding semantics from the standard Java servlet API.

For most situations, implicit naming will result in names that are sufficiently informative, because the HTTP request usually includes all the inputs to the Web application (inputs that determine what the application should generate).

Explicit naming might be desirable in some cases, however, such as when a group of users needs to share the same data. In this case, relevant identification information may not be available directly from the user’s HTTP request, so an implicit cache name would not be useful. Instead, you can write code to explicitly generate a cache name that identifies the group. (Preferably, the name-generation logic should still use only request parameters as input, not other states existing inside the application. This makes the semantics easier to follow and the code easier to debug.)

Following is an example of explicit naming. In the cache tag, note the name attribute with a JSP expression that calls someMethod() to set the cache block name:

<ojsp:cache policy="/WEB-INF/policy1.cpd"



name="<%= someObj.someMethod() %>" >...static text...<% // dynamic content ... %></ojsp:cache>

In the following example, because there is no name attribute in the cache tag, the cache block name will be determined implicitly according to the HTTP request and the cache policy:

<ojsp:cache policy="/WEB-INF/policy2.cpd" >...static text...<% // dynamic content ... %></ojsp:cache>

See "More About Cache Block Naming and the autoType Attribute" on page 9-16 for more information.

Cloneable Cache ObjectsThe OracleJSP Web Object Cache provides an interface, oracle.jsp.jwcache.CloneableCacheObj, that you can implement in serializable cache objects that you want to be cloneable. For mutable objects that are cached without being serialized, cloning is useful in providing a complete and hierarchical copy of the cache object. This section explains the usefulness of cloneability, first covering some necessary background information.

Memory-Oriented Repositories Versus Secondary Storage RepositoriesThere are two categories of repositories that can be used as the back end of the Web Object Cache:

■ secondary storage cache repository (such as a file system repository)

■ memory-oriented cache repository (such as the Oracle9iAS Object Caching Service for Java, the default repository of the Web Object Cache)

A secondary storage repository requires Java serialization during cache operations. During storage to the cache, objects are serialized into the repository; during retrieval from the cache, they are deserialized into memory. Therefore, as a result of

Note: Cache blocks can be nested. In this case, the logic of the inner cache block will be executed only when the content of the outer block must be regenerated.



the serialization/deserialization process, a complete and distinct copy of the cache object is automatically created during each cache operation.

This is not the case when you store or retrieve cache objects to or from a memory-oriented repository. With a memory-oriented repository, the identical object in the user application will be stored to the cache, or the identical object in the cache will be retrieved for the user. By default, no copy is made. If there are multiple retrievals, all retrievals share the same object.

Advantages in Cloning Copies of Cache ObjectsIn many cases in your applications, you will want to ensure that different retrievals use different copies of a cache object. There are two key reasons for this:

■ If the identical cache object is shared across multiple retrievals, changes made to the data in one place may unintentionally affect values retrieved and used elsewhere.

■ If the identical cache object is shared across multiple retrievals, then multiple Java threads may access the same object simultaneously. This would result in thread safety issues if the original object design was not thread-safe. (Perhaps, for example, the object was originally intended for page-scope or request-scope usage only, where there could be only one thread per object. This thread-behavior assumption would be violated.)

To avoid these possible problems, you should use complete and hierarchical copies when you store and retrieve generic Java serializable data to or from a memory-oriented repository. "Complete and hierarchical" means copying not just the direct members referenced by the object, but also any indirect variables that are referenced. For example, assume an object Y has a java.util.Vector instance as a member variable. Cloning a complete and hierarchical copy involves copying not just the Vector instance itself, but also all mutable objects or elements referenced by the Vector instance.

Use of the CloneableCacheObject InterfaceIf you implement the CloneableCacheObject interface and its cloneCacheObj() method in your cache objects, then the Web Object Cache will automatically call cloneCacheObj() to make a complete and hierarchical copy of each cache object whenever it is stored to or retrieved from a memory-oriented cache repository.

"Web Object Cache—Caching Generic Java Objects" on page 11-71 demonstrates the use of a cloneable cache object.



Cache Block Runtime FunctionalityDuring runtime, when a Web Object Cache cache tag is encountered, the tag handler checks whether a corresponding cache object exists and was created recently enough to reuse. If so, the code in the body of the tag is not executed; instead, the cache object is reused. But if the cache object does not exist or is too old, the tag body code will be executed to generate a new object (page fragment, XML DOM object, or Java serializable object). Then this freshly generated object will be captured (such as through special buffer writing or object passing) and stored into the cache.

If computations in content generation are costly (such as for a complicated database query) and the life span of the cache is appropriate (so that the cached data is reusable), the Web Object Cache can save significant amounts of time and system resources. Application speed and throughput will be greatly improved.

Data Invalidation and ExpirationCache blocks can be set up to expire after a specified duration or at a specified time, or can be invalidated explicitly by a method call or tag invocation.

Cache Block ExpirationBecause cache blocks mainly consist of semi-static fragments of information, OracleJSP does not require a tightly coherent expiration model. A looser model typically provides acceptable results and requires less synchronization overhead.

There are two categories of expiration for data in Web Object Cache blocks:

■ duration (time-to-live)—expiration occurs after data has been in the cache for a specified amount of time

■ fixed time/day—expiration occurs regularly at a set time, such as at a specified time each day or on a specified day each week

Expiration details are determined by the settings of attributes in an instance of the oracle.jsp.jwcache.ExpirationPolicy class. This ExpirationPolicy object is an attribute of the CachePolicy object associated with the cache block. See "Expiration Policy Attributes" on page 9-18.

In JSP pages, you can set ExpirationPolicy attributes through attributes of the Web Object Cache cache tags (such as cache, cacheXMLObj, or useCacheObj). See "Web Object Cache cache Tag" on page 9-22.

In servlets, you can use methods of the ExpirationPolicy object directly. See "ExpirationPolicy Methods" on page 9-57.



Alternatively, you can set ExpirationPolicy attributes through a cache policy descriptor. See "Cache Policy Descriptor" on page 9-63.

Cache Block InvalidationInstead of depending on expiration to invalidate a cache, you can invalidate it explicitly in one of the following ways:

■ Use the invalidateCache tag. See "Web Object Cache invalidateCache Tag" on page 9-34.

■ Use the overloaded invalidateCache(), invalidateCacheLike(), or invalidateCacheOtherPathLike() method of a CachePolicy instance to explicitly invalidate one or more cache blocks. See "CachePolicy Methods" on page 9-51.


Attributes for Policy Specification and Use

Attributes for Policy Specification and UseThis section describes cache policy attributes—specifically, attributes of the CachePolicy and ExpirationPolicy classes. You can set these attributes through OracleJSP custom tags in JSP pages, directly through the provided Java API in servlets, or through a cache policy descriptor file.

Cache Policy AttributesCache policies, introduced in "Cache Policy and Scope" on page 9-6, consist of the details that determine how cache blocks behave. You can set cache policy attributes in several ways, as described in subsequent sections:

■ in JSP pages through custom tags


■ in servlets through method calls

See "CachePolicy Methods" on page 9-51.

■ through a cache policy descriptor file


Specification of cache policy settings results in the creation of a cache policy object, which includes an expiration policy object as one of its attributes. Following is abbreviated code for the CachePolicy class (in package oracle.jsp.jwcache), for illustration purposes only, showing the names of the cache policy attributes:

class CachePolicy{ boolean ignoreCache; int scope; int autoType; String selectedParameters[]; String selectedCookies[]; Date reusableTimeStamp; long reusableDeltaTime; ExpirationPolicy expirationPolicy; String cacheRepositoryName; boolean reportException;}



Attribute DescriptionsTable 9–1 describes cache policy object attributes.

Note: The names documented below for integer constants are for servlet usage. Different names may be used for the Web Object Cache tags. See "Web Object Cache cache Tag" on page 9-22.

Table 9–1 Cache Policy Attribute Descriptions

Attribute Type Description

ignoreCache boolean This is intended for use during development only. When making frequent code changes, set this to true to disable the cache, typically so that results that were generated prior to your changes will not be returned.

default: false

scope int Specifies the scope of the cache. Use the integer constant SCOPE_SESSION (for the cache block to be accessible only to the current HTTP session) or SCOPE_APP (for the cache block to be accessible to all HTTP sessions of the application).

default: application

autoType int Specifies whether the cache block is named explicitly or implicitly, and how properties of the HTTP request are used in cache block naming (for implicit naming). The name is relevant in determining when the cache is reused for subsequent requests. See "More About Cache Block Naming and the autoType Attribute" on page 9-16.

selectedParameters[] String [] Selected request parameter names used in cache block naming; used in conjunction with autoType. See "More About Cache Block Naming and the autoType Attribute" on page 9-16.

default: null



selectedCookies[] String[] Selected cookie names used in cache block naming; used in conjunction with autoType. See "More About Cache Block Naming and the autoType Attribute" on page 9-16.

default: null

reusableTimeStamp java.util.Date An absolute time limit for cache usability, where any cache block created prior to that time will not be reused. Instead, data is regenerated, but the cache block is unaltered. See "More About reusableTimeStamp and reusableDeltaTime" on page 9-17.

Note the following regarding reusableTimeStamp:

■ It can be expressed as milliseconds between midnight, January 1, 1970 and the desired absolute time limit, or as a java.util.Date instance. Additional convenient formats are available through the cache tag—see "Web Object Cache Tag Descriptions" on page 9-21.

■ It takes precedence over reusableDeltaTime.

■ If its value is set as the integer constant REUSABLE_ALWAYS or the string constant REUSABLE_IGNORED, then cache entries are always reusable, for as long as they remain in the cache.

■ It is not available through the XML cache policy descriptor file.

default: always reusable

Table 9–1 Cache Policy Attribute Descriptions (Cont.)




reusableDeltaTime long A relative time limit for cache usability, where a cache block is not reused if the difference between cache block creation time and current time is greater than reusableDeltaTime. Instead, data is regenerated, but the cache block is unaltered. See "More About reusableTimeStamp and reusableDeltaTime" on page 9-17.

Note the following regarding reusableDeltaTime:

■ It is specified in seconds.

■ The reusableTimeStamp attribute overrides it.

■ If its value is set as the integer constant REUSABLE_ALWAYS or the string constant REUSABLE_IGNORED, then cache entries are always reusable, for as long as they remain in the cache.

default: always reusable

ExpirationPolicy ExpirationPolicy An expiration policy object (an instance of oracle.jsp.jwcache.ExpirationPolicy), which specifies circumstances under which the repository will remove cache blocks from storage.

default: the default expiration policy object

For information about expiration policy objects, parameters, and defaults, see "Expiration Policy Attributes" on page 9-18.

cacheRepositoryName String The name of the cache repository. Each cache policy can use its own repository.

The configurations of cache repositories are defined in the /WEB-INF/wcache.xml file.

default: "DefaultCacheRepository"

reportException boolean A false setting results in most cache operation failures being silent, without any exception being reported to the browser.

Default: true

Table 9–1 Cache Policy Attribute Descriptions (Cont.)




More About Cache Block Naming and the autoType AttributeAs discussed in "Cache Block Naming—Implicit Versus Explicit" on page 9-7, cache blocks can be named either implicitly, sometimes called auto-naming, or explicitly, sometimes called user-naming.

More specifically, there are six ways for cache blocks to be named. Explicit naming is the first way. Specify this with an autoType setting of TYPE_USERSPECIFIED (an integer constant).

The other five ways are variations of implicit naming:

■ implicit naming with only the request URI being used in the name

Specify this with an autoType setting of TYPE_URI_ONLY.

■ implicit naming according to the following:

request URI + query string + selected cookies

Specify this with an autoType setting of TYPE_URI_QUERYSTR. Specify the cookies in the selectedCookies[] attribute.


request URI + all parameters + selected cookies (default)

Specify this with an autoType setting of TYPE_URI_ALLPARAM. Specify the cookies in the selectedCookies[] attribute.


request URI + selected parameters + selected cookies

Specify this with an autoType setting of TYPE_URI_SELECTEDPARAM. Specify the parameters in the selectedParameters[] attribute and the cookies in the selectedCookies[] attribute.


request URI + all but excluded parameters + selected cookies

Specify this with an autoType setting of TYPE_URI_EXCLUDEDPARAM. Specify the cookies in the selectedCookies[] attribute, and specify the excluded parameters in the selectedParameters[] attribute.

As an example, assume that you have developed a JSP page, welcome.jsp, with a personalized greeting for each user who visits the site. The data with the personalized greeting is the only cache block in the page. Further assume that you have specified "request URI + selected parameters + selected cookies" naming, with



user as the only selected parameter for cache block naming and no selected cookies for naming.

Now assume the page is requested as follows:

http://host:port/a.jsp?user=Amy

In this case, a.jsp?user=Amy becomes the cache block name.

Now assume that the page is later requested by another user, as follows:

http://host:port/a.jsp?user=Brian

This will not reuse the "Amy" cache, because the value of user is different. Instead, a new cache block is created with a.jsp?user=Brian as the name.

Now assume a later request by the first user, as follows:

http://host:port/a.jsp?mypar=3&user=Amy

Because the user is again Amy, this request will reuse the first cache, displaying Amy’s personalized information without having to regenerate it. The mypar parameter is irrelevant to the caching mechanism because you did not include it in the selectedParameters[] list of the cache policy object (presumably because you determined that the value of mypar is not relevant in terms of cachable page output).

Now assume the following subsequent request:

http://host:port/a.jsp?yourpar=4&user=Brian&hello=true&foo=barfly

Because the user is again Brian, this request will reuse the second cache, displaying Brian’s personalized information without having to regenerate it. The yourpar, hello, and foo parameters are irrelevant to the caching mechanism because you did not include them in the selectedParameters[] list of the cache policy object.

More About reusableTimeStamp and reusableDeltaTimeBe aware that the concept of reusable is different than the concept of time-to-live (TTL), and is intended for more advanced use. Time-to-live, which controls the general lifetime of a cache, is described in "Expiration Policy Attributes" on page 9-18. Usually time-to-live is all that is required in terms of appropriately limiting the use of cached data.

The attributes for reusability—reusableTimeStamp and reusableDeltaTime—are intended for more specialized use and do not affect the



expiration or invalidation of cached data. As an example, consider a situation where different users have different requirements for how up-to-date a Web report is. Assume that most users can accept a report produced anytime within the past day, and that they all want to be looking at the same version so they can compare figures. An appropriate TTL value, then, would be one day.

Also presume, however, that there is a small group of privileged users for whom the data is much more time-sensitive. They want to have information that is no more than one hour old.

In this case, while TTL is set to one day for all users, there can be a reusableDeltaTime setting of one hour for the privileged users, which will result in the cache not being used for them if the data is more than one hour old. Remember, though, that reusableTimeStamp and reusableDeltaTime do not expire the cache or otherwise affect it—the cached data can still be used for non-privileged users, according to the time-to-live.

It is up to the application logic to set appropriate values of reusableTimeStamp and/or reusableDeltaTime for the privileged user group.

Expiration Policy AttributesExpiration policies are introduced in "Data Invalidation and Expiration" on page 9-10. Expiration policies contain the details that determine when cache blocks expire, at which point their data should no longer be used and the data should be regenerated instead. (Note that for most discussion, you can think of the expiration policies as being part of the cache policies.) ExpirationPolicy attributes, as with CachePolicy attributes, can be set in several ways:

■ in JSP pages through custom tags


■ in servlets through method calls

See "ExpirationPolicy Methods" on page 9-57.

■ through a cache policy descriptor file


The following abbreviated code for the ExpirationPolicy class (in package oracle.jsp.jwcache), provided for illustration purposes only, shows the names of the expiration policy attributes.



class ExpirationPolicy{ int expirationType; long TTL; long timeInaDay; int dayInaWeek; int dayInaMonth; boolean writeThrough;}

Table 9–2 describes the expiration policy object attributes.

Note: The names documented below for integer constants are for servlet usage. Different names may be used for the Web Object Cache tags. See "Web Object Cache cache Tag" on page 9-22.

Table 9–2 Expiration Policy Attribute Descriptions


expirationType int The type of expiration policy—one of the following (the TYPE_XXX values are integer constants):

■ time-to-live, specified with an expirationType setting of TYPE_TTL (also see the TTL attribute below)

■ daily (expire within a day, at a specified time), specified with an expirationType setting of TYPE_DAILY (also see the timeInaDay attribute below)

■ weekly (expire within a week, on a specified day at a specified time), specified with an expirationType setting of TYPE_WEEKLY (also see the timeInaDay and dayInaWeek attributes below)

■ monthly (expire within a month, on a specified date at a specified time), specified with an expirationType setting of TYPE_MONTHLY (also see the timeInaDay and dayInaMonth attributes below)

default: time-to-live



TTL long Time-to-live—the amount of time the cache block is good for, expressed in seconds.

default: 300 (5 minutes)

timeInaDay long The time of day used for daily, weekly, or monthly expiration, expressed in seconds from midnight—0 is 00:00:00 (midnight); 86399 is 23:59:59.

default: 300 (00:05:00); ignored if expirationType=TYPE_TTL

dayInaWeek int The day of the week for weekly expiration (at the specified timeInaDay)—WEEKLY_SUNDAY, WEEKLY_MONDAY, WEEKLY_TUESDAY, WEEKLY_WEDNESDAY, WEEKLY_THURSDAY, WEEKLY_FRIDAY, or WEEKLY_SATURDAY (integer constants).

default: Wednesday; ignored unless expirationType=TYPE_WEEKLY

dayInaMonth int The date of the month for monthly expiration (such as 10 for the 10th of each month, at the specified timeInaDay). The maximum setting is the number of days in the month when the cache block is created. For example, if a cache block is created in June and dayInaMonth has a setting of 31, then its effective value will be 30.

default: 10; ignored unless expirationType=TYPE_MONTHLY

writeThrough boolean A flag specifying whether the cache repository should treat the cache entry as a write-through cache, writing it immediately into secondary storage (such as a file system or database). Set this to true for write-through mode. A write-through cache will survive a server restart or power failure.

With a false setting, the cache entry is treated as a delayed-write cache, which is appropriate for caches that have a short life span (such as 5 or 10 minutes) and are not overly expensive to recompute.

default: true

Note: some cache repositories may not support write-through mode; others may always use write-through mode.

Table 9–2 Expiration Policy Attribute Descriptions (Cont.)



Web Object Cache Tag Descriptions

Web Object Cache Tag DescriptionsFrom JSP pages, you can specify cache policy settings, expiration policy settings, and explicit invalidation through custom tags provided with OracleJSP. Discussion is organized into the following categories:

■ Syntax Symbology and Notes

■ Cache Tag Descriptions

■ Cache Invalidation Tag Description

■ Web Object Cache Tag Library Description File


■ Italic indicates that you must specify a value or string.


■ Default values of some optional attributes are indicated in bold.


■ The prefix "ojsp:" is used. This is by convention, but is not required. You can specify any desired prefix in your taglib directive.

■ Except where otherwise noted, wherever a value or string is to be specified for an attribute of any of the Web Object Cache tags, Oracle also supports a JSP expression that resolves to an appropriate value or string.

Cache Tag DescriptionsThis section describes the following tags:

■ ojsp:cache

This is for general character-based caching (HTML or XML fragments).

Note: The Web Object Cache tag library is a standard library. For general information about the standard JavaServer Pages tag library framework, see "Standard Tag Library Framework" on page 7-2.



■ ojsp:cacheXMLObj

This is for caching XML objects; its parameters comprise a superset of the cache tag parameters. Because the Web Object Cache is particularly useful when post-processing XML documents, you will likely use the cacheXMLObj tag more often than the cache tag.

■ ojsp:useCacheObj

This is for general caching of Java serializable objects. Some of the semantics and syntax are patterned after the standard jsp:useBean tag.

■ ojsp:cacheInclude

This tag combines the functionality of the cache tags (cache and cacheXMLObj) and the standard JSP include tag.

This section also describes conditional execution of code within the cache tags, possible resulting problems, and the workaround of dividing cache blocks into individual JSP pages and, optionally, using the cacheInclude tag to combine the pages together appropriately.

Web Object Cache cache TagThis section documents the syntax and attributes of the cache tag, which you can use to set up general caching (as opposed to caching of XML objects or Java serializable objects) in a JSP application.

Syntax

<ojsp:cache [ policy = "filename" ] [ ignoreCache = "true | false" ] [ invalidateCache = "true | false" ] [ scope = "application | session" ] [ autoType = "user | URI | URI_query | URI_allParam | URI_selectedParam | URI_excludedParam" ] [ selectedParam = "space-delimited_string_of_parameter_names" ] [ selectedCookies = "space-delimited_string_of_cookie_names" ]

Note: For caching XML objects, use the cacheXMLObj tag instead. For caching Java serializable objects, use the useCacheObj tag. These tags supports all the cache tag attributes described here. See "Web Object Cache cacheXMLObj Tag" on page 9-27 and "Web Object Cache useCacheObj Tag" on page 9-30.



[ reusableTimeStamp = "yyyy.mm.dd hh:mm:ss z | yyyy.mm.dd hh:mm:ss | yyyy.mm.dd | ignored" ] [ reusableDeltaTime = "number | ignored" ] [ name = "blockname" ] [ expirationType = "TTL | daily | weekly | monthly" ] [ TTL = "number" ] [ timeInaDay = "number" ] [ dayInaWeek = "Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday" ] [ dayInaMonth = "number" ] [ writeThrough = "true | false" ] [ printCacheBlockInfo = "true | false" ] [ printCachePolicy = "true | false" ] [ cacheRepositoryName = "name" ] [ reportException = "true | false" ] >

...Code for cache block...

</ojsp:cache>

Attributes

Most of the parameters of the cache tag correspond to attributes in the CachePolicy or ExpirationPolicy class, described earlier in this chapter (as referenced below).

■ policy—Optionally use this to specify a cache policy descriptor, whose settings would be used in defining the cache policy. You can use a cache policy descriptor instead of using the various individual cache tag attribute settings, or to establish default values that you can optionally override through tag attribute settings.

Specify the descriptor file name according to JSP 1.1 application-relative syntax. (See "Indirectly Requesting a JSP Page" on page 1-9 for information about application-relative syntax.)

Notes:

■ This tag can optionally be in the form of a single tag with no body: <ojsp:cache ... />

■ Key default values are as follows: TTL defaults to 300 seconds; dayInaMonth defaults to 10 (10th of the month); cache repository name defaults to DefaultCacheRepository.


Here is a simple example of a cache policy descriptor:



<cachePolicy scope="application"><expirationPolicy expirationType="TTL" TTL="25" timeInaDay="00:10:00" writeThrough="true" /></cachePolicy>

See "Cache Policy Descriptor" on page 9-63 for more information.

■ ignoreCache—See "Cache Policy Attributes" on page 9-12.

■ invalidateCache—Enable this flag for the corresponding cache block (any pre-existing cache block with the same name) to first be invalidated. This is particularly useful where implicit cache block naming is used, but can also be used for explicit names by specifying the cache block name in the name attribute of the cache tag.

■ scope—See "Cache Policy Attributes" on page 9-12.

■ autoType—See "Cache Policy Attributes" on page 9-12. The correspondence between tag attribute settings and class attribute values (integer constants) is as follows:

– user is equivalent to TYPE_USERSPECIFIED.

– URI is equivalent to TYPE_URI_ONLY.

– URI_query is equivalent to TYPE_URI_QUERYSTR.

– URI_allParam is equivalent to TYPE_URI_ALLPARAM.

– URI_selectedParam is equivalent to TYPE_URI_SELECTEDPARAM.

– URI_excludedParam is equivalent to TYPE_URI_EXCLUDEDPARAM.

■ selectedParam—See "Cache Policy Attributes" on page 9-12.

Note: Do not confuse this attribute with the more general-purpose OracleJSP invalidateCache tag. See "Web Object Cache invalidateCache Tag" on page 9-34. The invalidateCache attribute is for more specialized or advanced use to invalidate individual cache blocks.


■ selectedCookies—See "Cache Policy Attributes" on page 9-12.

■ reusableTimeStamp—See "Cache Policy Attributes" on page 9-12.

■ reusableDeltaTime—See "Cache Policy Attributes" on page 9-12.

■ name—Where explicit cache-block naming is used, use the name parameter to specify the block name.

■ expirationType—See "Expiration Policy Attributes" on page 9-18.

■ TTL—See "Expiration Policy Attributes" on page 9-18.

■ timeInaDay—See "Expiration Policy Attributes" on page 9-18.

■ dayInaWeek—See "Expiration Policy Attributes" on page 9-18.

■ dayInaMonth—See "Expiration Policy Attributes" on page 9-18.

■ writeThrough—See "Expiration Policy Attributes" on page 9-18.

■ printCacheBlockInfo (for debugging)—Enabling this parameter results in printing of the internal cache name, creation time, and expiration time of the cache block (within HTML/XML comment constructs).

■ printCachePolicy (for debugging)—Enabling this parameter results in printing of the values of all cache policy attributes for this cache block (within HTML/XML comment constructs).

■ cacheRepositoryName—See "Cache Policy Attributes" on page 9-12.

■ reportException—See "Cache Policy Attributes" on page 9-12.

Usage Notes

■ The name attribute is relevant only when autoType is set to user.

■ The selectedParam attribute is relevant only when autoType is set to URI_selectedParam or URI_excludedParam.

■ The selectedCookies attribute is not relevant when autoType is set to user or URI.

■ The timeInaDay attribute is not relevant when expirationType is set to TTL.

■ The dayInaWeek attribute is relevant only when expirationType is set to weekly.

■ The dayInaMonth attribute is relevant only when expirationType is set to monthly.



Example: cache Tag

This example lists and caches a set of items, using the ojsp:cache tag.

<%@ taglib uri="/WEB-INF/jwcache.tld" prefix="ojsp" %><title>listitem.jsp</title><% String itemid=request.getParameter("itemid"); if (itemid==null) { out.println("Please select a category from the above drop down box."); return; }%><% long l1=(new java.util.Date()).getTime(); %><ojsp:cache autoType="URI_selectedParam" selectedParam="itemid" printCacheBlockInfo="true" printCachePolicy="true" policy="/WEB-INF/test-policy.cpd" > Item List: <b><%= itemid %></b><br> Time: <%= new java.util.Date() %> <br> <jsp:useBean class="java.util.Hashtable" id="table" scope="application" /> <hr> <% Vector list=(Vector) table.get(itemid); if (list==null) { out.println("No such item!"); } else { for (int i=0; i<list.size(); i++) { %> <%= list.elementAt(i) %><br> <% } } %> timestamp:<%= new java.util.Date() %> <br></ojsp:cache><% long l2=(new java.util.Date()).getTime(); %>Time for general cache operation:<%= l2-l1 %><br>



Web Object Cache cacheXMLObj TagGenerally speaking, use the cacheXMLObj tag instead of the cache tag if you are caching XML DOM objects.

The cacheXMLObj tag supports all the cache tag parameters described in "Web Object Cache cache Tag" on page 9-22, as well as the following.

Syntax (in addition to that of the cache tag)

<ojsp:cacheXMLObj ... [ fromXMLObjName = "objectname" ] [ toXMLObjName = "objectname" ] [ toWriter = "true | false" ] >


</ojsp:cacheXMLObj>

Attributes (in addition to those of the cache tag)

■ fromXMLObjName—For explicit passing, specify the name of the XML input object being passed to the cache (from the PageContext object).

■ toXMLObjName—For explicit passing, specify the name of the XML output object being passed from the cache (to the PageContext object).

■ toWriter—Set this to true to write the XML object to a JSP writer to output directly to the user’s browser.

Notes:

■ This tag can optionally be in the form of a single tag with no body: <ojsp:cacheXMLObj ... />

Be aware of the following regarding the fromXMLObjName and toXMLObjName attributes:

■ They are not request-time attributes, so you do not have the option of using JSP expressions to determine their values. (This restriction may be removed in future releases.)

■ Do not use them if the XML object is being passed implicitly. (See "Notes About XML-Related Tags and the Passing of XML Objects" below.)



See "Notes About XML-Related Tags and the Passing of XML Objects" below.

Notes About XML-Related Tags and the Passing of XML Objects

The cacheXMLObj tag is one of several OracleJSP custom tags that are XML-related, meaning they sometimes (or always) take an XML object as input and/or creates one as output. Other such tags include the sql:dbQuery tag, which can output query results as an XML DOM object, and the jml:transform tag, which can take an XML object as input and use XSLT transformation to create another XML object or a JSP writer as output.

An XML-related operation can be classified as an XML producer, which outputs an XML object, or as an XML consumer, which takes an XML object as input, or as both. Similarly, an XML-related tag can be classified as an XML producer or consumer or both. XML producers can pass XML objects to XML consumers either explicitly or implicitly; the latter is also known as anonymous passing.

For explicit passing between XML-related tags, use the toXMLObjName attribute in the producer tag and the fromXMLObjName attribute in the consumer tag. (Behind the scenes, the passing is done through the getAttribute() and setAttribute() methods of the standard JSP PageContext object.) The following example uses explicit passing:

<sql:dbQuery output="XML" toXMLObjName="foo" ... > ...SQL query...</sql:dbQuery>...<ojsp:cacheXMLObj fromXMLObjName="foo" ... />

For implicit passing between XML-related tags, do not use the toXMLObjName and fromXMLObjName attributes. The passing is accomplished through direct interaction between the tag handlers, typically in a situation where the tags are nested. The following example uses implicit passing:

<ojsp:cacheXMLObj ... > <sql:dbQuery output="XML" > ...SQL query... </sql:dbQuery></ojsp:cacheXMLObj>

Here the XML produced in the dbQuery tag is passed to the cacheXMLObj tag directly, without being stored to the PageContext object.


Example: cacheXMLObj Tag

This example uses Web Object Cache tags, JESI tags, and tags from the OracleJSP JML and SQL tag libraries. (For JESI tag descriptions, see "OracleJSP JESI Tag Descriptions" on page 8-11. For a description of the jml:transform tag, see "OracleJSP Support for XML and XSL" on page 5-9. For SQL tag descriptions, see "OracleJSP Tag Library for SQL" on page 5-24.)

The sql:dbOpen and sql:dbQuery tags connect to the database and execute a query. The ojsp:cacheXMLObj tag caches the XML DOM object produced by the query—in subsequent executions (for output through different stylesheets, for example), the query does not have to be re-executed because the DOM object can be retrieved from the Web Object Cache. The jml:transform tag outputs the query results according to an XML stylesheet (specified through a variable). The jesi:fragment tag encloses HTML output to be cached (which does not require application-level caching). The jesi:template tag disables caching outside the fragment (through the cache="no" setting).

<jesi:template cache="no"><% String userStyleLoc="style/rowset.xsl"; %><h3>Transform DBQuery Tag Example</h3><h4>Current Time=<%= new java.util.Date() %></h4><jesi:fragment expiration="60"> <h4>Cached Time=<%= new java.util.Date() %></h4><sql:dbOpen connId="conn1" URL="<%= connStr %>" user="scott" password="tiger" /><jml:transform href="<%= userStyleLoc %>" > <%-- The XML DOM object is produced by dbQuery And, the DOM object is cached in OracleJSP Web Object Cache. XSLT is performed on the cached object. --%> <ojsp:cacheXMLObj TTL="60" toWriter="false"> <sql:dbQuery connId="conn1" output="xml" queryId="myquery" > select ENAME, EMPNO from EMP </sql:dbQuery> </ojsp:cacheXMLObj></jml:transform> <sql:dbCloseQuery queryId="myquery" /><sql:dbClose connId="con1" /></jesi:fragment></jesi:template>


Web Object Cache useCacheObj TagUse the useCacheObj tag to cache any Java serializable object.

The useCacheObj tag supports all the cache tag parameters described in "Web Object Cache cache Tag" on page 9-22, as well as the following.

Syntax (in addition to that of the cache tag)

<ojsp:useCacheObj ... type="classname" id = "instancename" [ cacheScope = "application | session" ] >


</ojsp:useCacheObj>

Attributes (in addition to those of the cache tag)

■ type (required)—Specify the class name of the Java object to cache.

■ id (required)—Specify the instance name of the Java object to cache.

■ cacheScope—This has the same usage as the scope attribute in the cache and cacheXMLObj tags. See "Cache Policy Attributes" on page 9-12.

The type and id attributes here are used similarly to the type (or class) and id attributes in a standard jsp:useBean tag.

Example: useCacheObj Tag

<ojsp:useCacheObj id="a2" policy="/WEB-INF/test-policy.cpd" type="examples.RStrArray" ><% // create a temp writeable array WStrArray tmpa2=new WStrArray(3); tmpa2.setStr(2,request.getParameter("testing4")); tmpa2.setStr(1,"def"); tmpa2.setStr(0, (new java.util.Date()).toString() ); // create a readonly copy for the cache

Note: This tag can optionally be in the form of a single tag with no body: <ojsp:useCacheObj ... />



a2=new RStrArray(tmpa2); // storing the a2 into pagecontext // so useCacheObj tag can pick it up pageContext.setAttribute("a2",a2);%></ojsp:useCacheObj>

Conditional Execution of Code Inside the Cache TagsBe aware that code inside a cache tag (cache, cacheXMLObj, or useCacheObj) is executed conditionally. In particular:

■ Any code inside a cache tag is executed only when the associated cache block is not reused.


<% String s=null; %><% ojsp:useCacheObj ... > <% s = "abc"; //...more Java code...%></ojsp:useCacheObj><% out.print(s.length()); // May cause null pointer exception

If the cache is available and reused, the code to properly initialize the string s would not be executed.

■ If you put a method-based variable declaration inside a cache tag, the variable will not be available outside the tag.


<ojsp:useCacheObj ... > <% String s = "abc"; //...more Java code...%></ojsp:useCacheObj><% // String s will not be available here %>

If you are using a the cache tag (not cacheXMLObj or useCacheObj), it might be helpful to break your cache blocks into separate JSP pages so that you would be less likely to fall into this type of situation. In this case, each cache block would be represented by its own URI, and you could use dynamic include functionality to combine the pages together as desired.

To make this more convenient, OracleJSP also provides the cacheInclude tag, described in "Web Object Cache cacheInclude Tag" below.



Web Object Cache cacheInclude TagThe cacheInclude tag combines functionality of the cache tag (but not the cacheXMLObj tag or useCacheObj tag) and the standard jsp:include tag.

There are a number of advantages in putting cache blocks into separate pages and using cacheInclude, including general considerations of modularity and clarity as well as the issues discussed in "Conditional Execution of Code Inside the Cache Tags" above.

Be aware of the following limitations, however:

■ You cannot use a runtime JSP expression in the cacheInclude tag.

■ You must use implicit cache-block naming for the cache block.

■ There is no flush parameter (unlike for the standard jsp:include tag).

If any of these limitations presents a problem, then use separate cache and include tags.

Also be aware of an important difference between the cacheInclude tag and the jesi:include tag. (See "JESI include Tag" on page 8-14 for information about that tag.) Because the Oracle Web Cache is in a different caching layer than the Web Object Cache, the including page and included page for a jesi:include tag cannot share the same request object. There is no such limitation with the cacheInclude tag, however—the including page and included page share the same request object, so beans and attributes of request scope can be passed between the two pages.

Syntax

<ojsp:cacheInclude policy = "filename" page = "URI" [ printCacheBlockInfo = "true | false" ] [ reportException = "true | false" ] >


</ojsp:cacheInclude>



Attributes

■ policy (required)—You must use a cache policy descriptor file to specify cache policy settings (individual parameter settings are not supported).

■ page (required)—Use the page attribute to specify the URI of the page to dynamically include (as with a standard jsp:include tag).

■ printCacheBlockInfo (for debugging)—See "Web Object Cache cache Tag" on page 9-22.


Usage Notes

Consider the following ojsp:cacheInclude tag usage:

<ojsp:cacheInclude page="anotherPage.jsp" policy="foo.cpd" >


<ojsp:cache policy="foo.cpd" > <% pageContext.include("anotherPage.jsp"); %></ojsp:cache>

or the following:

<jsp:include page="anotherPage.jsp" flush="true" />

where anotherPage.jsp consists of the following:

<ojsp:cache policy="foo.cpd" >...anotherPage.jsp contents...</ojsp:cache>

Notes: For the cacheInclude tag, policy and page are not runtime attributes, so you do not have the option of determining their values through JSP expressions. (Be aware that policy is a request-time attribute for the cache, cacheXMLObj, and useCacheObj tags.)



Cache Invalidation Tag DescriptionThis section describes how to use the invalidateCache tag.

Web Object Cache invalidateCache TagTo explicitly invalidate a cache block through program logic, you can use the invalidateCache tag. This section documents the syntax and attributes of this tag.

Syntax

<ojsp:invalidateCache [ policy = "filename" ] [ ignoreCache = "true | false" ] [ scope = "application | session" ] [ autoType = "user | URI | URI_query | URI_allParam | URI_selectedParam | URI_excludedParam" ] [ selectedParam = "space-delimited_string_of_parameter_names" ] [ selectedCookies = "space-delimited_string_of_cookie_names" ] [ name = "blockname" ] [ invalidateNameLike = "true | false" ] [ page = "URI" ] [ autoInvalidateLevel = "application | page | param | cookie" ] [ cacheRepositoryName = "name" ] [ reportException = "true | false" ] />

Notes:

■ The invalidateCache tag does not accept new cookies; it can only use existing cookies of the current HTTP request. (For information about inputting new cookies, see "CachePolicy Methods" on page 9-51.)

■ Do not confuse the invalidateCache tag with the invalidateCache attribute of the cache tags. The attribute is for more limited use—to invalidate the pre-existing cache object.



Attributes

Most parameters of the invalidateCache tag also exist in the cache and cacheXMLObj tags and are used in the same way, as described earlier in this chapter (and as referenced below).

■ policy—See "Web Object Cache cache Tag" on page 9-22.

■ scope—See "Cache Policy Attributes" on page 9-12.

■ autoType—See "Cache Policy Attributes" on page 9-12. The correspondence between tag attribute settings and class attribute values (integer constants) is as follows:

– user is equivalent to TYPE_USERSPECIFIED.

– URI is equivalent to TYPE_URI_ONLY.

– URI_query is equivalent to TYPE_URI_QUERYSTR.

– URI_allParam is equivalent to TYPE_URI_ALLPARAM.

– URI_selectedParam is equivalent to TYPE_URI_SELECTEDPARAM.

– URI_excludedParam is equivalent to TYPE_URI_EXCLUDEDPARAM.

■ selectedParam—See "Cache Policy Attributes" on page 9-12.

■ selectedCookies—See "Cache Policy Attributes" on page 9-12.

■ name—Use this with invalidateNameLike to invalidate one or more cache blocks that were named through explicit cache-block naming, according to the instructions in "Use of name and invalidateNameLike" below.

■ invalidateNameLike—Use this with name to invalidate one or more cache blocks that were named through explicit cache-block naming, according to the instructions in "Use of name and invalidateNameLike" below.

■ page—Specify a page-relative or application-relative URI. Use this with autoInvalidateLevel to invalidate one or more cache blocks that were named through implicit cache-block naming, according to the instructions in "Use of page and autoInvalidateLevel" below.

Note: The default for autoInvalidateLevel depends on specifics of the page URI. See "Use of page and autoInvalidateLevel" below.



■ autoInvalidateLevel—Use this with page to invalidate one or more cache blocks that were named through implicit cache-block naming, according to the instructions in "Use of page and autoInvalidateLevel" below.

■ cacheRepositoryName—See "Cache Policy Attributes" on page 9-12.


Use of name and invalidateNameLike To invalidate one or more cache blocks that were named through explicit cache-block naming, use the name and invalidateNameLike attributes together, as follows:

If invalidateNameLike=false, then use the name parameter to specify the name of a single cache block to invalidate.

If invalidateNameLike=true, and the underlying cache repository supports wild card characters, then you can use the wildcard "*" character in the name parameter to invalidate multiple cache blocks whose names fit the criteria. (The Oracle9iAS Object Caching Service for Java currently does not support wild card characters.)

Use of page and autoInvalidateLevel To invalidate one or more cache blocks that were named through implicit cache-block naming, use the page and autoInvalidateLevel attributes together, as follows:

Use the page attribute to specify the appropriate URI of the Web page. (With implicit naming, cache block names are based on Web page URIs.)

Use autoInvalidateLevel to specify the scope of invalidation—application scope, page scope, parameter scope, or cookie scope—as follows:

■ If autoInvalidateLevel="application", then all cache blocks associated with the application that the page belongs to will be invalidated.

For example, if there is an application under the /mycontext context path, and autoInvalidateLevel="application", then all cache entries of all pages under http://host:port/mycontext will be invalidated.

Here is a corresponding usage example:

<ojsp:invalidateCache page="/" autoInvalidateLevel="application" />

■ If autoInvalidateLevel="page", then all cache block entries associated with the page will be invalidated.



For example, if autoInvalidateLevel="page" and the request is the following:

http://host:port/mycontext/mypage01.jsp?foo=bar

then all cache entries of mypage01.jsp will be invalidated, regardless of what request parameters and cookies they are associated with. This includes cache blocks associated with the following, for example:

http://host:port/mycontext/mypage01.jsp?p1=v1

Here is a corresponding usage example:

<ojsp:invalidateCache page="/mypage01.jsp" autoInvalidateLevel="page" />

■ If autoInvalidateLevel="param", then all cache entries of the page that have the identical selected parameter names and values will be invalidated, regardless of what cookies they are associated with.

For example, consider the following:

<ojsp:invalidateCache policy="/WEB-INF/c1.cpd" page="/mypage01.jsp?foo=bar" autoInvalidateLevel="param" />

In this case, cache blocks associated with the following, for example, will not be invalidated:

http://host:port/mycontext/mypage01.jsp?foo=bar2

But cache blocks associated with the following will be invalidated, regardless of what cookies they are associated with:

http://host:port/mycontext/mypage01.jsp?foo=bar

Continuing this example, consider the following:

http://host:port/mycontext/mypage01.jsp?foo=bar&p1=v1

Cache blocks associated with this request will be invalidated if c1.cpd selects the foo HTTP request parameter only, and the cache blocks are stored under the same cache policy, c1.cpd. However, the cache objects will not be invalidated if they were not stored under c1.cpd, or if c1.cpd also selects the p1 parameter.



■ If autoInvalidateLevel="cookie", then the only cache entries invalidated are those associated with the same page, same selected parameters and values, and same cookies.

Example—Use of Cache Invalidation TagThis section provides a brief example of cache invalidation. For complete sample applications, including cache invalidation, see "Samples for the Web Object Cache" on page 11-61.

Example: invalidateCache Tag

The following page adds an item to list of items previously cached, then invalidates the cache. (The list will presumably be re-cached later with the new item.)

<%@ taglib uri="/WEB-INF/jwcache.tld" prefix="ojsp" %><title>added.jsp</title><jsp:useBean class="java.util.Hashtable" id="table" scope="application" /><% String itemid=request.getParameter("itemid"); String addItem=request.getParameter("addItem"); Vector list=(Vector) table.get(itemid); if (list==null) { list=new Vector(); table.put(itemid,list); } list.addElement(addItem);%><b><%= addItem %></b> was added into category <b><%= itemid %></b>.<br><% String viewPage="listitem.jsp?itemid="+itemid; %><% long l1=(new java.util.Date()).getTime(); %><ojsp:invalidateCache page="<%= viewPage %>" autoInvalidateLevel="param" policy="/WEB-INF/test-policy.cpd" /><% long l2=(new java.util.Date()).getTime(); %>Existing cache entry has been invalidated. <br>Invalidation took <%= l2-l1 %> milliseconds.<br><jsp:include page="<%= viewPage %>" flush="true" /><br>

Note: If the page URI includes a question mark, then the default value of autoInvalidateLevel is param. If there is no question mark, then the default value is page.


<a href="seeitems.jsp" >Select items</a>or<a href="additem.html" >Add items</a><br>

Web Object Cache Tag Library Description FileThis section presents a listing of jwcache.tld, the complete tag library description file (TLD) for the OracleJSP Web Object Cache tag library.


<taglib> 

<tlibversion>1.0</tlibversion> <jspversion>1.1</jspversion> <shortname>jwcache</shortname> <info> tag library for Web Object Cache for JSP </info>

<tag> <name>cache</name> <tagclass>oracle.jsp.jwcache.tag.CacheTag</tagclass> <bodycontent>JSP</bodycontent> <info>OracleJSP Web Object Cache</info> <attribute> <name>policy</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>ignoreCache</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>invalidateCache</name>


<required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>scope</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>autoType</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>selectedParam</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>selectedCookies</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>reusableTimeStamp</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>reusableDeltaTime</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>name</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>expirationType</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>TTL</name>



<required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>timeInaDay</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>dayInaWeek</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>dayInaMonth</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>writeThrough</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>printCacheBlockInfo</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>printCachePolicy</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>cacheRepositoryName</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>reportException</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>



<tag> <name>invalidateCache</name> <tagclass>oracle.jsp.jwcache.tag.InvalidateCacheTag</tagclass> <bodycontent>empty</bodycontent> <info>OracleJSP Web Object Cache</info> <attribute> <name>policy</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>ignoreCache</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>scope</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>autoType</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>selectedParam</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>selectedCookies</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>name</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>invalidateNameLike</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute>



<attribute> <name>page</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>autoInvalidateLevel</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>cacheRepositoryName</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>reportException</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

<tag> <name>cacheInclude</name> <tagclass>oracle.jsp.jwcache.tag.CacheIncludeTag</tagclass> <bodycontent>empty</bodycontent> <info>OracleJSP Web Object Cache</info> <attribute> <name>policy</name> <required>true</required> <rtexprvalue>false</rtexprvalue> </attribute> <attribute> <name>page</name> <required>true</required> <rtexprvalue>false</rtexprvalue> </attribute> <attribute> <name>printCacheBlockInfo</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>reportException</name> <required>false</required>



<rtexprvalue>true</rtexprvalue> </attribute> </tag>

<tag> <name>cacheXMLObj</name> <tagclass>oracle.jsp.jwcache.tag.CacheXMLObjTag</tagclass> <teiclass>oracle.jsp.jwcache.tag.CacheXMLObjTEI</teiclass> <bodycontent>JSP</bodycontent> <info>OracleJSP Web Object Cache</info> <attribute> <name>policy</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>ignoreCache</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>invalidateCache</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>scope</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>autoType</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>selectedParam</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>selectedCookies</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute>



<attribute> <name>reusableTimeStamp</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>reusableDeltaTime</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>name</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>expirationType</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>TTL</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>timeInaDay</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>dayInaWeek</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>dayInaMonth</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>writeThrough</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute>



<attribute> <name>printCacheBlockInfo</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>printCachePolicy</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>cacheRepositoryName</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>fromXMLObjName</name> <required>false</required> <rtexprvalue>false</rtexprvalue> </attribute> <attribute> <name>toXMLObjName</name> <required>false</required> <rtexprvalue>false</rtexprvalue> </attribute> <attribute> <name>toWriter</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>reportException</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> </tag>

<tag> <name>useCacheObj</name> <tagclass>oracle.jsp.jwcache.tag.UseCacheObjTag</tagclass> <teiclass>oracle.jsp.jwcache.tag.UseCacheObjTEI</teiclass> <bodycontent>JSP</bodycontent> <info>OracleJSP Web Object Cache</info> <attribute> <name>policy</name>



<required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>ignoreCache</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>invalidateCache</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>cacheScope</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>autoType</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>selectedParam</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>selectedCookies</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>reusableTimeStamp</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>reusableDeltaTime</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>name</name>



<required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>expirationType</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>TTL</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>timeInaDay</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>dayInaWeek</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>dayInaMonth</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>writeThrough</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>printCacheBlockInfo</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>printCachePolicy</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>cacheRepositoryName</name>



<required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>reportException</name> <required>false</required> <rtexprvalue>true</rtexprvalue> </attribute> <attribute> <name>id</name> <required>true</required> <rtexprvalue>false</rtexprvalue> </attribute> <attribute> <name>type</name> <required>true</required> <rtexprvalue>false</rtexprvalue> </attribute> </tag>

</taglib>


Web Object Cache Servlet API Description

Web Object Cache Servlet API DescriptionFrom servlets (or JSP scriptlets), you can use CachePolicy methods to modify cache policy settings or to invalidate a cache block, and ExpirationPolicy methods to modify expiration settings. This requires creating a cache policy object and retrieving its expiration policy object attribute (which the JSP cache tag handlers do automatically).

This section discusses the following:

■ Cache Policy Object Creation

■ CachePolicy Methods

■ Expiration Policy Object Retrieval

■ ExpirationPolicy Methods

■ CacheBlock Methods

■ Sample Servlet Using the Web Object Cache API

For more information about the classes, interfaces, and methods described in this section, see the Javadoc that is supplied with OracleJSP.

Cache Policy Object CreationThere are two approaches to creating a CachePolicy object:

■ Use the static lookupPolicy() method of the CacheClientUtil class.

■ Use one of the public CachePolicy constructors.

Using the lookupPolicy() MethodIn most situations, the most convenient way to create a CachePolicy object is through the static lookupPolicy() method of the CacheClientUtil class (provided with OracleJSP), as in the following example:

CachePolicy cachePolicyObject = oracle.jsp.jwcache.CacheClientUtil.lookupPolicy (servletConfig, request, "/WEB-INF/foo.cpd");

Note: Cache policy objects are not resource objects (such as database connections or cursors), so you can manipulate them without life-cycle or resource management concerns.



Input a servlet configuration object (a javax.servlet.ServletConfig instance), a request object (a javax.servlet.http.HttpServletRequest instance), and the URI path (relative to the application root) of an XML cache policy descriptor file.

Here is a simple example of a cache policy descriptor file:



See "Cache Policy Descriptor" on page 9-63 for more information.

Using a CachePolicy ConstructorThe oracle.jsp.jwcache.CachePolicy class has the following public constructors—a simple constructor requiring only a servlet configuration object, a "copy" constructor that copies another CachePolicy object, and a "copy" constructor with a given servlet configuration object:

public CachePolicy(javax.servlet.ServletConfig config)

public CachePolicy(CachePolicy cPolicy)

public CachePolicy(javax.servlet.ServletConfig config, CachePolicy cPolicy)

CachePolicy MethodsA number of utility methods are available in CachePolicy objects, as well as getter and setter methods for key attributes.

CachePolicy Method Signatures and Common ParametersThe following abbreviated code, for illustration purposes only, contains signatures for key methods available in CachePolicy objects.

See "Cache Policy Attributes" on page 9-12 for a discussion of relevant attributes.



class CachePolicy { boolean isRecent(CacheBlock block); void putCache(Object data, HttpServletRequest req, SectionId sectionId); void putCache(Object data, HttpServletRequest req, String specifiedName); void putAutoCacheForOtherPath(Object data, HttpServletRequest req, String otherPath, StringSectionid sectionId); void putAutoCacheForOtherPath(Object data, HttpServletRequest req, String otherPath, Cookie[] newCookies, StringSectionid sectionId); CacheBlock getCache(HttpServletRequest req, SectionId sectionId); CacheBlock getCache(HttpServletRequest req, String specifiedName); CacheBlock getAutoCacheForOtherPath(HttpServletRequest req, String otherPath, StringSectionId sectionId); CacheBlock getAutoCacheForOtherPath(HttpServletRequest req, String otherPath, Cookie[] newCookies, StringSectionId sectionId); void invalidateCache(HttpServletRequest req, SectionId sectionId); void invalidateCache(HttpServletRequest req, String specifiedName); void invalidateCacheLike(HttpServletRequest req, String specifiedName); void invalidateCacheLike(HttpServletRequest req, int autoInvalidateLevel); void invalidateCacheLike(HttpServletRequest req, String specifiedName, int autoInvalidateLevel); void invalidateCacheOtherPathLike(HttpServletRequest req, String otherPath); void invalidateCacheOtherPathLike(HttpServletRequest req, String otherPath, Cookie[] newCookies, int autoInvalidateLevel); Date getCurrentTime();}

These methods use several common parameters:

■ req, a javax.servlet.http.HttpServletRequest instance

This is the current HTTP request object.

■ newCookies, a javax.servlet.http.Cookie[] array

This is an array of new cookies. If you pass in new cookies, they are used in cache operations that use the otherPath parameter (such as the putAutoCacheForOtherPath() method), assuming the cache policy selects some cookies and invalidation is at the cookie level. If you do not pass in new cookies, then cookies of the current HTTP request would be used instead.

■ specifiedName, a Java string

For explicit cache-block naming, this is the name—either the desired cache block name if you are creating a new cache block, or the existing cache block name if you are retrieving an existing cache block.



■ sectionId, an oracle.jsp.jwcache.SectionId instance (specifically, StringSectionId or NumberSectionId)

For implicit cache-block naming, this is a counter that is used in tracking cache blocks. In JSP pages it is used, incremented, and maintained by JSP cache tag handlers. It is stored in the JSP PageContext object.

SectionId is an interface that is implemented by two classes—StringSectionId and NumberSectionId. Where StringSectionId is specified in a method signature, you must use an instance of that class. Where SectionId is specified, you can use an instance of either class. Typically you should use StringSectionId, however. NumberSectionId is primarily intended for use by tag handlers in JSP pages.

In a servlet, you must create a section ID instance manually. "Sample Servlet Using the Web Object Cache API" on page 9-59 demonstrates the use of a StringSectionId instance.

■ otherPath, a Java string

The URI of another JSP page that has an associated cache block that you want to store, retrieve, or invalidate.

■ autoInvalidateLevel, an integer

For implicit cache-block naming, you can use this to specify a level of invalidation—application, page, parameter, or cookie. Use the CachePolicy integer constant AUTO_INVALIDATE_APP_LEVEL, AUTO_INVALIDATE_PAGE_LEVEL, AUTO_INVALIDATE_PARAM_LEVEL, or AUTO_INVALIDATE_COOKIE_LEVEL.

CachePolicy Method DescriptionsThe CachePolicy methods function as follows:

■ isRecent()

This method checks the timestamp of the specified cache block and determines whether it is recent enough, given the current time and the values of the cache policy reusableTimeStamp and reusableDeltaTime attributes.

Note: When you construct a StringSectionId instance, the string must begin with an alphabetic (not numeric) character.



■ putCache()

Use this method to place an object into the cache repository. The data parameter is any serializable Java object you want to cache that will not require any further modification or mutation. In JSP pages, the JSP cache tag handler calls putCache() to cache a BodyContent instance. The cacheXMLObj tag handler calls it to cache an XML DOM object. In a servlet or useCacheObj tag, the cache target object can be any Java serializable object.

You must also provide an HTTP request object and a cache block name (for explicit naming) or a section ID (for implicit naming).

■ putAutoCacheForOtherPath()

Place an object into the cache repository according to a specified string-based section ID and a specified page path. The cache policy must not use explicit naming (in other words, must not have autoType=TYPE_USERSPECIFIED).

■ getCache()

Use this method to retrieve a cached item from the repository, in the form of an oracle.jsp.jwcache.CacheBlock instance. You can specify the cache block name (for explicit naming) or the section ID (for implicit naming). You must also provide an HTTP request object.

■ getAutoCacheForOtherPath()

Retrieve a cached item from the repository according to a specified string-based section ID and a specified page path. The cache policy must not use explicit naming (in other words, must not have autoType=TYPE_USERSPECIFIED); otherwise, an exception is thrown).

■ invalidateCache()

Use this method to invalidate a single cache block, according to the HTTP request object and the specified cache block name (for explicit naming) or the section ID (for implicit naming).

Note: The putCache() method does nothing if the cache policy ignoreCache attribute is true.

Note: The getCache() method does nothing if the cache policy ignoreCache attribute is true.



■ invalidateCacheLike()

Use this method to invalidate multiple cache blocks. If you use explicit cache-block naming and the cache repository supports wild-card naming, you can input the specifiedName parameter with "*" wild card characters. (The Oracle9iAS Object Caching Service for Java currently does not support wild card characters.)

If you use implicit cache-block naming, you must specify the autoInvalidateLevel parameter to determine, in combination with the HttpServletRequest object, what cache blocks are invalidated. The autoInvalidateLevel parameter has the same functionality as in a JSP invalidateCache tag, as explained in "Web Object Cache invalidateCache Tag" on page 9-34 (using information from the request object, as opposed to using information from the page parameter of the invalidateCache tag).

■ invalidateCacheOtherPathLike()

Use this method to invalidate cache blocks associated with the URI you provide in the otherPath parameter. In the signature taking only a request object and the URI, the autoInvalidateLevel parameter is set automatically according to the URI—to param level if there is a question mark ("?") in the URI; to page level otherwise.

The detailed signature of this method allows you to specifically control the autoInvalidateLevel setting and the cookies used in invalidation.

■ getCurrentTime()

Retrieve the current time value, as a java.util.Date instance, of the underlying cache repository specified in this cache policy.

CachePolicy Getter and Setter MethodsYou can use the following methods to retrieve or alter CachePolicy object attributes.

See "Cache Policy Attributes" on page 9-12 for a discussion of these attributes.

■ boolean getIgnoreCache()

■ void setIgnoreCache(boolean ignoreCache)

■ void setIgnoreCache(String ignoreCacheStr)

■ int getScope()



■ void setScope(int scope)

For scope values, the integer constants SCOPE_APP and SCOPE_SESSION are available.

■ int getAutoType()

■ void setAutoType(int autoType)

For autoType values, the integer constants TYPE_USERSPECIFIED, TYPE_URI_ONLY, TYPE_URI_QUERYSTR, TYPE_URI_ALLPARAM, TYPE_URI_SELECTEDPARAM, and TYPE_URI_EXCLUDEDPARAM are available.

■ String[] getSelectedParam()

■ void setSelectedParam(String[] selectedParameters)

■ void setSelectedParam(String selectedParamStr)

■ String[] getSelectedCookies()

■ void setSelectedCookies(String[] selectedCookies)

■ void setSelectedCookies(String selectedCookiesStr)

■ Date getReusableTimeStamp()

■ void setReusableTimeStamp(Date reusableTimeStamp)

■ void setReusableTimeStamp(long reusableTimeStamp)

For reusableTimeStamp values, the integer constant REUSABLE_ALWAYS is available, indicating that the cache is always reusable.

■ long getReusableDeltaTime()

■ void setReusableDeltaTime(long reusableDeltaTime)

For reusableDeltaTime values, the integer constant REUSABLE_ALWAYS is available, indicating that the cache is always reusable.

■ ExpirationPolicy getExpirationPolicy()

■ void setExpirationPolicy(ExpirationPolicy expirationPolicy)

■ String getCacheRepositoryName()

■ void setCacheRepositoryName(String repoName)

■ boolean getReportException()

■ void setReportException (boolean reportException)



■ void setReportException (String reportExceptionStr)

The following methods are also available, but are primarily intended for use by the Web Object Cache tags:

■ void setScope(String scopeStr)

For scope values, the string constants SCOPE_APP_STR and SCOPE_SESSION_STR are available.

■ void setAutoType(String autoTypeStr)

■ void setReusableTimeStamp(String reusableTimeStampStr)

For reusableTimeStamp values, the string constant REUSABLE_IGNORED is available, indicating that the cache is always reusable.

■ void setReusableDeltaTime(String reusableDeltaTimeStr)

For reusableDeltaTime values, the string constant REUSABLE_IGNORED is available, indicating that the cache is always reusable.

Expiration Policy Object RetrievalEach CachePolicy object has an ExpirationPolicy attribute. If you want to set expiration policies for a cache block, you can use the getExpirationPolicy() method of its CachePolicy object, as in the following example:

CachePolicy cachePolicyObj = CacheClientUtil.lookupPolicy (config, request, "/WEB-INF/mypolicy.cpd");ExpirationPolicy expPolicyObj = cachePolicyObj.getExpirationPolicy();

ExpirationPolicy MethodsThe ExpirationPolicy class has getter and setter methods for its attributes, as follows. For descriptions of these attributes, see "Expiration Policy Attributes" on page 9-18.

■ int getExpirationType()

■ void setExpirationType(int expirationType)

■ void setExpirationType(String expirationTypeStr)

■ long getTTL()

■ void setTTL(long ttl)



■ long getTimeInaDay()

■ void setTimeInaDay(long timeInaDay)

■ void setTimeInaDay(String timeInaDayStr)

■ int getDayInaWeek()

■ void setDayInaWeek(int dayInaWeek)

■ void setDayInaWeek(String dayInaWeekStr)

■ int getDayInaMonth()

■ void setDayInaMonth(int dayInaMonth)

■ boolean getWriteThrough()

■ void setWriteThrough(boolean writeThrough)

■ void setWriteThrough(String writeThroughStr)

Additionally, the ExpirationPolicy class has the following utility method:

■ long getExpirationTime(long createTime)

Given the creation time of a cache block (in terms of milliseconds since midnight January 1, 1970), this method calculates and returns the expiration time (also in milliseconds since midnight January 1, 1970). That is, the timestamp when expiration should occur, according to the expiration policy.

The ExpirationPolicy class also defines the following integer constants for the expirationType attribute:

■ TYPE_TTL

■ TYPE_DAILY

■ TYPE_WEEKLY

■ TYPE_MONTHLY

And the following integer constants are defined for the dayInaWeek attribute:

■ WEEKLY_SUNDAY

■ WEEKLY_MONDAY

■ WEEKLY_TUESDAY

■ WEEKLY_WEDNESDAY

■ WEEKLY_THURSDAY



■ WEEKLY_FRIDAY

■ WEEKLY_SATURDAY

CacheBlock MethodsYou can use the getCache() method of a CachePolicy object to retrieve the associated CacheBlock object (as documented in "CachePolicy Methods" on page 9-51 and shown in "Sample Servlet Using the Web Object Cache API" below).

The following abbreviated code shows the key methods of the oracle.jsp.jwcache.CacheBlock class:

class CacheBlock{ long getCreationTime(); long getExpirationTime(); Serializable getData();}

Here are brief descriptions of these methods:

■ getCreationTime()—Returns the timestamp from when the cache block was created.

■ getExpirationTime()—Returns the timestamp for the expiration time of the cache block.

■ getData()—Returns the cache block data. Use of this method is also shown in "Sample Servlet Using the Web Object Cache API" below.

Sample Servlet Using the Web Object Cache APIThe following sample servlet uses the Web Object Cache. The code is followed by notes about some of its operations. (This servlet is also part of a sample application provided in "Web Object Cache—Tag Code Versus API Code" on page 11-75.)

Sample Code—DemoCacheServlet.javapackage demoPkg;

import javax.servlet.*;

Note: Creation time and expiration time are expressed in milliseconds since midnight, January 1, 1970.



import javax.servlet.http.*;import java.io.IOException;

import java.io.PrintWriter;import java.io.CharArrayWriter;

import oracle.jsp.jwcache.CachePolicy;import oracle.jsp.jwcache.ExpirationPolicy;import oracle.jsp.jwcache.StringSectionId;import oracle.jsp.jwcache.CacheBlock;import oracle.jsp.jwcache.CacheClientUtil;

public class DemoCacheServlet extends HttpServlet{

public void service(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // standard writer object from servlet engine PrintWriter out=response.getWriter(); ServletConfig config=getServletConfig();

try { CachePolicy cachePolicyObj = CacheClientUtil.lookupPolicy(config,request, "/WEB-INF/test-policy.cpd" ); // Note A StringSectionId sectionId=new StringSectionId("s1"); CacheBlock cacheBlockObj=null;

cacheBlockObj = cachePolicyObj.getCache(request,sectionId); // Note B if (!cachePolicyObj.isRecent(cacheBlockObj)) { // Note C CharArrayWriter newOut=new CharArrayWriter(); PrintWriter pw=new PrintWriter(newOut); // actual logic within a cache block pw.println("fragment#1"); pw.println(new java.util.Date()); // which generates content into the "out" object if (cacheBlockObj == null) { // Note E cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId); // Note F } out.write(newOut.toCharArray()); // writing out newly created data back to the original writer }



else { out.write((char[])cacheBlockObj.getData()); // writing the existing cached data to the writer }

sectionId=new StringSectionId("s2"); long timeToLive = 15; // now set TTL to 15 on this block ExpirationPolicy expirationPolicy = cachePolicyObj.getExpirationPolicy(); expirationPolicy.setTTL(timeToLive); cachePolicyObj.setExpirationPolicy(expirationPolicy); cacheBlockObj = cachePolicyObj.getCache(request,sectionId); // Note B if (!cachePolicyObj.isRecent(cacheBlockObj)) { // Note C CharArrayWriter newOut=new CharArrayWriter(); PrintWriter pw=new PrintWriter(newOut); // actual logic within a cache block pw.println("fragment#2"); pw.println(new java.util.Date()); // which generates content into the "out" object if (cacheBlockObj == null) { // Note E cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId); // Note F } out.write(newOut.toCharArray()); // writing out newly created data back to the original writer } else { out.write((char[])cacheBlockObj.getData()); // writing the existing cached data to the writer }

} catch (Throwable th) { // your exception handling code here th.printStackTrace(out); } }}



Code NotesThe following notes describe some of the key functionality of the preceding example:

■ The cache policy object is created in the lookupPolicy() call, with attribute settings according to the cache policy descriptor test-policy.cpd.

■ The section ID is created for each cache block, as required for implicit cache-block naming. See "CachePolicy Methods" on page 9-51 for information about section IDs.

■ The cache block is retrieved from the repository through the getCache() method of the cache policy object, and placed into the repository through the putCache() method (according to the section ID in each case).

■ The isRecent() call determines if the cache block is recent enough to use. If so, the cached data is retrieved through the getData() method of the cache block (see "CacheBlock Methods" on page 9-59). If not, a special PrintWriter object is created to buffer the output and save it back to the cache repository. If the cache block object is not found (is null), then the putCache() method of the cache policy object is called to create a new cache block.


Cache Policy Descriptor

Cache Policy DescriptorYou can optionally use an XML-style cache policy descriptor to specify attribute settings for the CachePolicy and ExpirationPolicy objects. In any JSP pages or servlets that you use, you would then specify the cache policy descriptor through the policy attribute of a cache, cacheXMLObj, useCacheObj, cacheInclude, or invalidateCache tag.

This section provides the cache policy descriptor DTD, a sample cache policy descriptor, and information about loading and refreshing the cache policy descriptor.

Cache Policy Descriptor DTDThis section provides a listing of the Web Object Cache cache policy descriptor DTD, cachepolicy.dtd. For an example of a cache policy descriptor, see "Sample Cache Policy Descriptor" on page 9-64.





<!ELEMENT cachePolicy ( selectedParam*, selectedCookie*, reusableTimeStamp?, reusableDeltaTime?, cacheRepositoryName?, expirationPolicy? ) >

<!ATTLIST cachePolicy ignoreCache (true | false) "false" ><!ATTLIST cachePolicy scope (application | session) "application" ><!ATTLIST cachePolicy autoType (user | URI | URI_query | URI_allParam | URI_selectedParam | URI_excludedParam ) "URI_allParam" ><!ATTLIST cachePolicy reportException (true | false) "true" >


<!ELEMENT selectedParam (#PCDATA) ><!ELEMENT selectedCookie (#PCDATA) ><!ELEMENT reusableTimeStamp (#PCDATA) ><!ELEMENT reusableDeltaTime (#PCDATA) ><!ELEMENT cacheRepositoryName (#PCDATA) >

<!ELEMENT expirationPolicy EMPTY >

<!ATTLIST expirationPolicy expirationType (TTL | daily | weekly | monthly) "TTL" ><!ATTLIST expirationPolicy TTL CDATA "300" ><!ATTLIST expirationPolicy timeInaDay CDATA #IMPLIED ><!ATTLIST expirationPolicy dayInaWeek (Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday) "Wednesday" ><!ATTLIST expirationPolicy dayInaMonth CDATA "10" > <!ATTLIST expirationPolicy writeThrough (true | false) "true" >

Sample Cache Policy DescriptorThis section provides an example of a simple cache policy descriptor that sets the TTL and timeInaDay attributes. For the DTD, see "Cache Policy Descriptor DTD" on page 9-63.



Cache Policy Descriptor Loading and RefreshingTo create a CachePolicy object from an XML cache policy descriptor file, there must be a call to the static lookupPolicy() method of the oracle.jsp.jwcache.CacheClientUtil class. For JSP pages, this is handled automatically. For servlets, you must include the lookupPolicy() call in your code—see "Sample Servlet Using the Web Object Cache API" on page 9-59.

If the caching policy has not been previously loaded, then the lookupPolicy() method results in the XML descriptor being parsed and used in constructing a new



CachePolicy object (and an ExpirationPolicy attribute of this object). See "Cache Policy Object Creation" on page 9-50 for information about the lookupPolicy() method.

The CachePolicy object is stored indirectly under the ServletContext object associated with your application. When the same caching policy is requested again, the stored policy object will be returned without the descriptor being re-read or re-parsed. Because cache policy descriptor files are seldom changed, and for security reasons, OracleJSP does not provide descriptor auto-reloading functionality.

The CachePolicy object will be valid until the servlet context is destroyed or someone calls the static refreshPolicy() method of the CacheClientUtil class. This method has the same calling sequence as the lookupPolicy() method. For example:

oracle.jsp.jwcache.CacheClientUtil.refreshPolicy (servletConfig, request, "/WEB-INF/foo.cpd");

When you alter and refresh the caching policy, active cache blocks are not affected.

Note: To improve performance, OracleJSP does not re-read and re-parse the descriptor file upon every request. Instead, the resulting cache policy object is stored in the middle-tier JVM for faster access.


Cache Repository Descriptor

Cache Repository DescriptorUse an XML-style cache repository descriptor to specify what to use as the back-end cache repository for the Web Object Cache, and how to configure it. This section supplies the DTD for cache repository descriptors, as well as a sample cache repository descriptor.

Cache Repository Descriptor DTDThis section provides a listing of the Web Object Cache cache repository descriptor DTD, wcache.dtd. For an example of a cache repository descriptor, see "Sample Cache Repository Descriptor" below.





<!ELEMENT wcache-config (cache-repository*)>

<!ELEMENT cache-repository (cache-repository-name,cache-repository-class,init-param*)>

<!ELEMENT cache-repository-name (#PCDATA)><!ELEMENT cache-repository-class (#PCDATA)>

<!ELEMENT init-param (param-name,param-value)><!ELEMENT param-name (#PCDATA)><!ELEMENT param-value (#PCDATA)>

Note: By default, the Web Object Cache uses the Oracle9iAS Object Caching Service for Java as its cache repository.


Sample Cache Repository DescriptorThis section lists the cache repository descriptor provided with OracleJSP release 1.1.3.x. For the DTD, see "Cache Repository Descriptor DTD" above.

<wcache-config>

<cache-repository> <cache-repository-name>DefaultCacheRepository</cache-repository-name> <cache-repository-class> oracle.jsp.jwcache.repository.impl.OCSRepoImpl </cache-repository-class></cache-repository>

<cache-repository> <cache-repository-name>SimpleFSRepo</cache-repository-name> <cache-repository-class> oracle.jsp.jwcache.repository.impl.SimpleFSRepositoryImpl </cache-repository-class>

<init-param> <param-name>reporoot</param-name> <param-value>/tmp/reporoot</param-value></init-param></cache-repository>

</wcache-config>

Note: The DTD does not include reporoot, which is a specific-use parameter that only a file system cache implementation requires. (See "Web Object Cache—Using a File System Cache" on page 11-65 for an example that uses a file system cache.)


OracleJSP Globalization S

10
OracleJSP Globalization Support
OracleJSP provides standard globalization support (also known as National Language Support, or NLS) according to the Sun Microsystems JavaServer Pages Specification, Version 1.1, and also offers extended support for servlet environments that do not support multibyte parameter encoding.

Standard Java support for localized content depends on the use of Unicode 2.0 for uniform internal representation of text. Unicode is used as the base character set for conversion to alternative character sets.

This chapter describes key aspects of how OracleJSP supports Oracle Globalization Support. The following topics are covered:

■ Content Type Settings in the page Directive

■ Dynamic Content Type Settings

■ OracleJSP Extended Support for Multibyte Parameter Encoding

Note: For detailed information about Oracle Globalization Support, see the Oracle9i Globalization Support Guide.

upport 10-1

Content Type Settings in the page Directive

Content Type Settings in the page DirectiveYou can use the page directive contentType parameter to set the MIME type and to optionally set the character encoding for a JSP page. The MIME type applies to the HTTP response at runtime. The character encoding, if set, applies to both the page text during translation and the HTTP response at runtime.

Use the following syntax for the page directive:

<%@ page ... contentType="TYPE; charset=character_set" ... %>

or, to set the MIME type while using the default character set:

<%@ page ... contentType="TYPE" ... %>

TYPE is an IANA (Internet Assigned Numbers Authority) MIME type; character_set is an IANA character set. (When specifying a character set, the space after the semi-colon is optional.)

For example:

<%@ page language="java" contentType="text/html; charset=UTF-8" %>

or:

<%@ page language="java" contentType="text/html" %>

The default MIME type is text/html. The IANA maintains a registry of MIME types at the following site:

ftp://www.isi.edu/in-notes/iana/assignments/media-types/media-types

The default character encoding is ISO-8859-1 (also known as Latin-1). The IANA maintains a registry of character encodings at the following site (use the indicated "preferred MIME name" if one is listed):

ftp://www.isi.edu/in-notes/iana/assignments/character-sets

(There is no JSP requirement to use an IANA character set as long as you use a character set that Java and the Web browser support, but the IANA site lists the most common character sets. Using the preferred MIME names they document is recommended.)


Content Type Settings in the page Directive

The parameters of a page directive are static. If a page discovers during execution that a different setting is necessary for the response, it can do one of the following:

■ Use the servlet response object API to set the content type during execution, as described in "Dynamic Content Type Settings" on page 10-4.

■ Forward the request to another JSP page or to a servlet.

Notes:

■ The page directive that sets contentType should appear as early as possible in the JSP page.

■ A JSP page written in a character set other than ISO-8859-1 must set the appropriate character set in a page directive. It cannot be set dynamically because the page has to be aware of the setting during translation. Dynamic settings are for runtime only.

■ The JSP 1.1 specification assumes that a JSP page is written in the same character set that it will use to deliver its content.

■ This document, for simplicity, assumes the typical case that the page text, request parameters, and response parameters all use the same encoding (although other scenarios are technically possible). Request parameter encoding is controlled by the browser, although Netscape browsers and Internet Explorer follow the setting you specify for the response parameters.

OracleJSP Globalization Support 10-3

Dynamic Content Type Settings

Dynamic Content Type SettingsFor situations where the appropriate content type for the HTTP response is not known until runtime, you can set it dynamically in the JSP page. The standard javax.servlet.ServletResponse interface specifies the following method for this purpose:

public void setContentType(java.lang.String contenttype)

(The implicit response object of a JSP page is a javax.servlet.http.HttpServletResponse instance, where the HttpServletResponse interface extends the ServletResponse interface.)

The setContentType() method input, like the contentType setting in a page directive, can include a MIME type only, or both a character set and a MIME type. For example:

response.setContentType("text/html; charset=UTF-8");

or:

response.setContentType("text/html");

As with a page directive, the default MIME type is text/html and the default character encoding is ISO-8859-1.

This method has no effect on interpreting the text of the JSP page during translation. If a particular character set is required during translation, that must be specified in a page directive, as described in "Content Type Settings in the page Directive" on page 10-2.

Be aware of the following important usage notes:

■ The JSP page cannot be unbuffered if you are using the setContentType() method. It is buffered by default; do not set buffer="none" in a page directive.

■ The setContentType() call must appear early in the page, before any output to the browser or any jsp:include command (which flushes the JSP buffer to the browser).

■ In servlet 2.2 environments, the response object has a setLocale() method that sets a default character set based on the specified locale, overriding any previous character set. For example, the following method call results in a character set of Shift_JIS:

response.setLocale(new Locale("ja", "JP"));


OracleJSP Extended Support for Multibyte Parameter Encoding

OracleJSP Extended Support for Multibyte Parameter EncodingCharacter encoding of request parameters is not well defined in the HTTP specification. Most servlet containers must interpret them using the servlet default encoding, ISO-8859-1.

For such environments, where the servlet container cannot encode multibyte request parameters and bean property settings, OracleJSP offers extended support in two ways:

■ through the setReqCharacterEncoding() method

or:

■ through the translate_params configuration parameter

The setReqCharacterEncoding() MethodOracleJSP provides a setReqCharacterEncoding() method that is useful in case the default encoding for the servlet container is not appropriate. Use this method to specify the encoding of multibyte request parameters and bean property settings, such as for a getParameter() call in Java code or a jsp:setProperty statement to set a bean property in JSP code. If the default encoding is already appropriate, then it is not necessary to use this method, and in fact using it may create some performance overhead in your application.

The setReqCharacterEncoding() method is a static method in the PublicUtil class of the oracle.jsp.util package.

This method affects parameter names and values, specifically:

■ request object getParameter() method output

■ request object getParameterValues() method output

■ request object getParameterNames() method output

■ jsp:setProperty settings for bean property values

When invoking the method, input a request object and a string that specifies the desired encoding, as follows:

oracle.jsp.util.PublicUtil.setReqCharacterEncoding(myrequest, "EUC-JP");



The translate_params Configuration ParameterThis section describes how to use the OracleJSP translate_params configuration parameter for encoding of multibyte request parameters and bean property settings, such as for a getParameter() call in Java code or for a jsp:setProperty statement to set a bean property in JSP code.

Note that beginning with OracleJSP release 1.1.3.x, it is preferable to use the PublicUtil.setReqCharacterEncoding() method instead. See "The setReqCharacterEncoding() Method" above.

Also note that you should not enable translate_params in any of the following circumstances:

■ When the servlet container properly handles multibyte parameter encoding itself. Setting translate_params to true in this situation will cause incorrect results. As of this writing, however, it is known that Apache/JServ, JSWDK, and Tomcat all do not properly handle multibyte parameter encoding.

■ When the request parameters use a different encoding from what is specified for the response in the JSP page directive or setContentType() method.

■ When code with workaround functionality equivalent to what translate_params accomplishes is already present in the JSP page. (See "Code Equivalent to the translate_params Configuration Parameter" on page 10-7.)

Effect of translate_params in Overriding Non-Multibyte Servlet ContainersSetting translate_params to true overrides servlet containers that cannot encode multibyte request parameters and bean property settings. (For information

Notes:

■ Beginning with OracleJSP release 1.1.3.x, using the setReqCharacterEncoding() method is preferable to using the translate_params configuration parameter described in "The translate_params Configuration Parameter" on page 10-6.

■ The setReqCharacterEncoding() method is forward-compatible with the method request.setCharacterEncoding(encoding) of the upcoming servlet 2.3 API.



about how to set OracleJSP configuration parameters, see "OracleJSP Configuration Parameter Settings" on page A-26.)

When this flag is enabled, OracleJSP encodes the request parameters and bean property settings based on the character set of the response object, as indicated by the response.getCharacterEncoding() method.

The translate_params flag affects parameter names and values, specifically:

■ request object getParameter() method output

■ request object getParameterValues() method output

■ request object getParameterNames() method output

■ jsp:setProperty settings for bean property values

Code Equivalent to the translate_params Configuration ParameterThe translate_params configuration parameter, being a runtime parameter, cannot be set in the Oracle9i Servlet Engine environment. (Translation-time configuration can be set for the OSE environment through ojspc command-line options. There is no equivalent for runtime parameters.)

For this reason, and possibly other reasons as well, it is useful to be aware of equivalent functionality that can be implemented through scriptlet code in the JSP page, for example:

<%@ page contentType="text/html; charset=EUC-JP" %>...String paramName="XXYYZZ"; // where XXYYZZ is a multibyte stringparamName = new String(paramName.getBytes(response.getCharacterEncoding()), "ISO8859_1");String paramValue = request.getParameter(paramName);paramValue= new String(paramValue.getBytes("ISO8859_1"), "EUC-JP");...

This code accomplishes the following:

■ Sets XXYYZZ as the parameter name to search for. (Presume XX, YY, and ZZ are three Japanese characters.)

■ Encodes the parameter name to ISO-8859-1, the servlet container character set, so that the servlet container can interpret it. (First a byte array is created for the parameter name, using the character encoding of the request object.)



■ Gets the parameter value from the request object by looking for a match for the parameter name. (It is able to find a match because parameter names in the request object are also in ISO-8859-1 encoding.)

■ Encodes the parameter value to EUC-JP for further processing or output to the browser.

See the next two sections for a globalization sample that depends on translate_params being enabled, and one that contains the equivalent code so that it does not depend on the translate_params setting.

Globalization Sample Depending on translate_paramsThe following sample accepts a user name in Japanese characters and correctly outputs the name back to the browser. In a servlet environment that cannot encode multibyte request parameters, this sample depends on the OracleJSP configuration setting of translate_params=true.

Presume XXYY is the parameter name (something equivalent to "user name" in Japanese) and AABB is the default value (also in Japanese).

(See the next section for a sample that has the code equivalent of the translate_params functionality, so does not depend on the translate_params setting.)

<%@ page contentType="text/html; charset=EUC-JP" %><HTML><HEAD><TITLE>Hello</TITLE></HEAD><BODY><% //charset is as specified in page directive (EUC-JP) String charset = response.getCharacterEncoding();%> <BR> encoding = <%= charset %> <BR><%String paramValue = request.getParameter("XXYY");

if (paramValue == null || paramValue.length() == 0) { %> <FORM METHOD="GET"> Please input your name: <INPUT TYPE="TEXT" NAME="XXYY" value="AABB" size=20> <BR> <INPUT TYPE="SUBMIT"> </FORM><% }else



{ %> <H1> Hello, <%= paramValue %> </H1><% } %></BODY></HTML>

Following is the sample input:

and the sample output:



Globalization Sample Not Depending on translate_paramsThe following sample, as with the preceding sample, accepts a user name in Japanese characters and correctly outputs the name back to the browser. This sample, however, has the code equivalent of translate_params functionality, so does not depend on the translate_params setting.

Presume XXYY is the parameter name (something equivalent to "user name" in Japanese) and AABB is the default value (also in Japanese).

For an explanation of the critical code in this sample, see "Code Equivalent to the translate_params Configuration Parameter" on page 10-7.

<%@ page contentType="text/html; charset=EUC-JP" %>

<HTML><HEAD><TITLE>Hello</TITLE></HEAD><BODY><% //charset is as specified in page directive (EUC-JP) String charset = response.getCharacterEncoding();%> <BR> encoding = <%= charset %> <BR><%String paramName = "XXYY";

paramName = new String(paramName.getBytes(charset), "ISO8859_1");

String paramValue = request.getParameter(paramName);

if (paramValue == null || paramValue.length() == 0) { %> <FORM METHOD="GET"> Please input your name: <INPUT TYPE="TEXT" NAME="XXYY" value="AABB" size=20> <BR> <INPUT TYPE="SUBMIT"> </FORM><% }else

Important: If you use translate_params-equivalent code, do not also enable the translate_params flag. This would cause incorrect results. (This is not a concern in the OSE environment, where the translate_params flag is not supported.)



{ paramValue= new String(paramValue.getBytes("ISO8859_1"), "EUC-JP"); %> <H1> Hello, <%= paramValue %> </H1><% } %></BODY></HTML>


Sample App

11
Sample Applications
This chapter provides a variety of code samples for JSP pages and the JavaBeans that they use (as applicable), in the following categories:

■ Basic Samples

■ JDBC Samples

■ Data-Access JavaBean Samples

■ Custom Tag Samples

■ Samples for Oracle-Specific Programming Extensions

■ JESI Tag Sample—Portal Demo

■ Samples for the Web Object Cache

■ Samples Using globals.jsa for Servlet 2.0 Environments

lications 11-1

Basic Samples

Basic SamplesThis section provides JSP samples that are fairly basic but also exemplify use of the Oracle JML datatypes. This includes an elementary "hello" sample, a sample of using a JavaBean, and a more intermediate shopping cart example. The following samples are provided:

■ Hello Page—hellouser.jsp

■ Usebean Page—usebean.jsp

■ Shopping Cart Page—cart.jsp

These examples could use standard datatypes instead, but JML datatypes offer a number of advantages, as described in "JML Extended Datatypes" on page 5-2. JML datatypes are also portable to other JSP environments.

This section concludes with a sample that shows how to obtain environmental information, including the version number of your OracleJSP installation:

■ Information Page—info.jsp

Hello Page—hellouser.jspThis sample is an elementary JSP "hello" page. Users are presented with a form to enter their name. After they submit the name, the JSP page redisplays the form with the name at the top.

<%----------------------------------------------------------- Copyright (c) 1999, Oracle Corporation. All rights reserved.------------------------------------------------------------%>

<%@page session="false" %>

<jsp:useBean id="name" class="oracle.jsp.jml.JmlString" scope="request" > <jsp:setProperty name="name" property="value" param="newName" /></jsp:useBean>

<HTML><HEAD><TITLE>Hello User</TITLE></HEAD>

<BODY>


Basic Samples

<% if (!name.isEmpty()) { %><H3>Welcome <%= name.getValue() %></H3><% } %>

<P>Enter your Name:<FORM METHOD=get><INPUT TYPE=TEXT name=newName size = 20><br><INPUT TYPE=SUBMIT VALUE="Submit name"></FORM>

</BODY></HTML>

Usebean Page—usebean.jspThis page uses a simple JavaBean, NameBean, to illustrate usage of the jsp:useBean tag. Code for both the bean and the page is provided.

Code for usebean.jsp<%----------------------------------------------------------- Copyright (c) 1999, Oracle Corporation. All rights reserved.------------------------------------------------------------%>

<%@ page import="beans.NameBean" %>

<jsp:useBean id="pageBean" class="beans.NameBean" scope="page" /><jsp:setProperty name="pageBean" property="*" />

<jsp:useBean id="sessionBean" class="beans.NameBean" scope="session" /><jsp:setProperty name="sessionBean" property="*" />

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

<H3> Welcome to the UseBean JSP </H3><P><B>Page bean: </B><% if (pageBean.getNewName().equals("")) { %> I don’t know you. <% } else { %> Hello <%= pageBean.getNewName() %> !<% } %>

Sample Applications 11-3

Basic Samples

<P><B>Session bean: </B><% if (sessionBean.getNewName().equals("")) { %> I don’t know you either. <% } else { if ((request.getParameter("newName") == null) || (request.getParameter("newName").equals(""))) { %> Aha, I remember you. <% } %> You are <%= sessionBean.getNewName() %>.<% } %>

<P>May we have your name?<FORM METHOD=get><INPUT TYPE=TEXT name=newName size = 20><INPUT TYPE=SUBMIT VALUE="Submit name"></FORM></BODY></HTML>

Code for NameBean.javapackage beans;

public class NameBean {

String newName="";

public void NameBean() { }

public String getNewName() { return newName; } public void setNewName(String newName) { this.newName = newName; }}


Basic Samples

Shopping Cart Page—cart.jspThis sample shows how to use session state to maintain a shopping cart. The user chooses a T-shirt or sweatshirt to order and the order is then redisplayed. If shopping continues and the order is changed, the page redisplays the order, striking out the previous choices as appropriate.

The cart.jsp file is the primary source file; it references index.jsp. Code for both pages is provided.

Code for cart.jsp<%----------------------------------------------------------- Copyright (c) 1999-2000, Oracle Corporation. All rights reserved.------------------------------------------------------------%><jsp:useBean id="currSS" scope ="session" class="oracle.jsp.jml.JmlString" /><jsp:useBean id="currTS" scope ="session" class="oracle.jsp.jml.JmlString" />

<HTML>

<HEAD> <TITLE>Java Store</TITLE></HEAD>

<BODY BACKGROUND=images/bg.gif BGCOLOR=#FFFFFF>

<jsp:useBean id="sweatShirtSize" scope="page" class="oracle.jsp.jml.JmlString" > <jsp:setProperty name="sweatShirtSize" property="value" param="SS" /></jsp:useBean><jsp:useBean id="tshirtSize" scope="page" class="oracle.jsp.jml.JmlString" > <jsp:setProperty name="tshirtSize" property="value" param="TS" /></jsp:useBean>

<jsp:useBean id="orderedSweatshirt" scope="page" class="oracle.jsp.jml.JmlBoolean" > <jsp:setProperty name="orderedSweatshirt" property="value" value= ’<%= !(sweatShirtSize.isEmpty() || sweatShirtSize.getValue().equals("none")) %>’ /></jsp:useBean>

<jsp:useBean id="orderedTShirt" scope="page" class="oracle.jsp.jml.JmlBoolean" > <jsp:setProperty name="orderedTShirt" property="value" value=’<%= !(tshirtSize.isEmpty() || tshirtSize.getValue().equals("none")) %>’ /></jsp:useBean>


Basic Samples

<P><TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100% HEIGHT=553> <TR> <TD WIDTH=33% HEIGHT=61> </TD> <TD WIDTH=67% HEIGHT=61> </TD> </TR> <TR> <TD WIDTH=33% HEIGHT=246> </TD> <TD WIDTH=67% HEIGHT=246 VALIGN=TOP BGCOLOR=#FFFFFF>

<% if (orderedSweatshirt.getValue() || orderedTShirt.getValue()) { %> Thank you for selecting our fine JSP Wearables!<P> <% if (!currSS.isEmpty() || !currTS.isEmpty()) { %> You have changed your order: <UL> <% if (orderedSweatshirt.getValue()) { %> <LI>1 Sweatshirt <% if (!currSS.isEmpty()) { %> <S>(size: <%= currSS.getValue().toUpperCase() %>)</S>&nbsp <% } %> (size: <%= sweatShirtSize.getValue().toUpperCase() %> ) <% } else if (!currSS.isEmpty()) { %> <LI><S>1 Sweatshirt (size: <%= currSS.getValue().toUpperCase() %>)</S> <% } %>

<% if (orderedTShirt.getValue()) { %> <LI>1 Tshirt <% if (!currTS.isEmpty()) { %> <S>(size: <%= currTS.getValue().toUpperCase() %>)</S>&nbsp <% } %> (size: <%= tshirtSize.getValue().toUpperCase() %>) <% } else if (!currTS.isEmpty()) { %> <LI><S>1 Tshirt (size: <%= currTS.getValue().toUpperCase() %>)</S> <% } %> </UL> <% } else { %> You have selected: <UL> <% if (orderedSweatshirt.getValue()) { %> <LI>1 Sweatshirt (size: <%= sweatShirtSize.getValue().toUpperCase() %>)


Basic Samples

<% } %>

<% if (orderedTShirt.getValue()) { %> <LI>1 Tshirt (size: <%= tshirtSize.getValue().toUpperCase() %>) <% } %>

</UL> <% } %> <% } else { %> Are you sure we can’t interest you in something? <% } %>

<CENTER> <FORM ACTION="index.jsp" METHOD="GET" ENCTYPE="application/x-www-form-urlencoded"> <INPUT TYPE="IMAGE" SRC="images/shop_again.gif" WIDTH="91" HEIGHT="30" BORDER="0"> </FORM> </CENTER> </TD></TR></TABLE>

</BODY>

</HTML>

<% if (orderedSweatshirt.getValue()) { currSS.setValue(sweatShirtSize.getValue());} else { currSS.setValue("");}

if (orderedTShirt.getValue()) { currTS.setValue(tshirtSize.getValue());} else { currTS.setValue("");}%>


Basic Samples

Code for index.jsp<%----------------------------------------------------------- Copyright (c) 1999-2000, Oracle Corporation. All rights reserved.------------------------------------------------------------%><jsp:useBean id="currSS" scope ="session" class="oracle.jsp.jml.JmlString" /><jsp:useBean id="currTS" scope ="session" class="oracle.jsp.jml.JmlString" />

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"><HTML>

<HEAD> <TITLE>untitled</TITLE></HEAD>

<BODY BACKGROUND="images/bg.gif" BGCOLOR="#FFFFFF">

<FORM ACTION="cart.jsp" METHOD="POST" ENCTYPE="application/x-www-form-urlencoded"><P><TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" WIDTH="100%" HEIGHT="553"> <TR> <TD WIDTH="33%" HEIGHT="61"> </TD> <TD WIDTH="67%" HEIGHT="61"> </TD> </TR> <TR> <TD WIDTH="33%" HEIGHT="246"> </TD> <TD WIDTH="67%" HEIGHT="246" VALIGN="TOP" BGCOLOR="#FFFFFF"> <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" WIDTH="81%"> <TR> <TD WIDTH="100%" BGCOLOR="#CCFFFF"> <H4>JSP Wearables </TD> </TR> <TR> <TD WIDTH="100%" BGCOLOR="#FFFFFF">

<BLOCKQUOTE> Sweatshirt <SPACER TYPE="HORIZONTAL" SIZE="10">($24.95)<BR> <SPACER TYPE="HORIZONTAL" SIZE="30"> <INPUT TYPE="RADIO" NAME="SS" VALUE="xl" <%= currSS.getValue().equals("xl") ? "CHECKED" : "" %> >XL <SPACER TYPE="HORIZONTAL" SIZE="10"> <INPUT TYPE="RADIO" NAME="SS" VALUE="l" <%= currSS.getValue().equals("l") ? "CHECKED" : "" %> >L


Basic Samples

<SPACER TYPE="HORIZONTAL" SIZE="10"> <INPUT TYPE="RADIO" NAME="SS" VALUE="m" <%= currSS.getValue().equals("m") ? "CHECKED" : "" %> >M <SPACER TYPE="HORIZONTAL" SIZE="10"> <INPUT TYPE="RADIO" NAME="SS" VALUE="s" <%= currSS.getValue().equals("s") ? "CHECKED" : "" %> >S <SPACER TYPE="HORIZONTAL" SIZE="10"> <INPUT TYPE="RADIO" NAME="SS" VALUE="xs" <%= currSS.getValue().equals("xs") ? "CHECKED" : "" %> >XS <SPACER TYPE="HORIZONTAL" SIZE="10"> <INPUT TYPE="RADIO" NAME="SS" VALUE="none" <%= currSS.getValue().equals("none") || currSS.isEmpty() ? "CHECKED" : "" %> >NONE <BR> <BR> T-Shirt<SPACER TYPE="HORIZONTAL" SIZE="10"> (14.95)<BR> <SPACER TYPE="HORIZONTAL" SIZE="30"> <INPUT TYPE="RADIO" NAME="TS" VALUE="xl" <%= currTS.getValue().equals("xl") ? "CHECKED" : "" %> >XL <SPACER TYPE="HORIZONTAL" SIZE="10"> <INPUT TYPE="RADIO" NAME="TS" VALUE="l" <%= currTS.getValue().equals("l") ? "CHECKED" : "" %> >L <SPACER TYPE="HORIZONTAL" SIZE="10"> <INPUT TYPE="RADIO" NAME="TS" VALUE="m" <%= currTS.getValue().equals("m") ? "CHECKED" : "" %> >M <SPACER TYPE="HORIZONTAL" SIZE="10"> <INPUT TYPE="RADIO" NAME="TS" VALUE="s" <%= currTS.getValue().equals("s") ? "CHECKED" : "" %> >S <SPACER TYPE="HORIZONTAL" SIZE="10"> <INPUT TYPE="RADIO" NAME="TS" VALUE="xs" <%= currTS.getValue().equals("xs") ? "CHECKED" : "" %> >XS <SPACER TYPE="HORIZONTAL" SIZE="10"> <INPUT TYPE="RADIO" NAME="TS" VALUE="none" <%= currTS.getValue().equals("none") || currTS.isEmpty() ? "CHECKED" : "" %> >NONE </BLOCKQUOTE> </TD> </TR> <TR> <TD WIDTH="100%"> <DIV ALIGN="RIGHT"> <P><INPUT TYPE="IMAGE" SRC="images/addtobkt.gif" WIDTH="103" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"> </DIV> </TD>


Basic Samples

</TR> </TABLE> </TD> </TR></TABLE>

</FORM>

</BODY>

</HTML>

Information Page—info.jspThis sample retrieves and displays the following information:

■ OracleJSP version number

■ Java classpath

■ OracleJSP build date

■ OracleJSP configuration parameter settings

<HTML> <HEAD> <TITLE>OJSP Information </TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> OJSP Version:<BR><%= application.getAttribute("oracle.jsp.versionNumber") %> <BR> ClassPath:<BR><%=System.getProperty("java.class.path") %> <BR> OJSP BuildDate:<BR> <% try { %> <%=((oracle.jsp.runtime.OraclePageContext)pageContext).BUILD_DATE%> <% }catch(Exception e){ } %> <BR> OJSP Init Parameters:<BR>


Basic Samples

<% for (Enumeration paraNames = config.getInitParameterNames(); paraNames.hasMoreElements() ;) { String paraName = (String)paraNames.nextElement(); %> <%=paraName%> = <%=config.getInitParameter(paraName)%> <BR> <% } %> </BODY> </HTML>


JDBC Samples

JDBC SamplesExamples in this section use JDBC to query a database or the middle-tier database cache. For the most part they use standard JDBC functionality, although the connection caching examples use Oracle’s particular connection caching implementation. The following examples are provided:

■ Simple Query—SimpleQuery.jsp

■ User-Specified Query—JDBCQuery.jsp

■ Query Using a Query Bean—UseHtmlQueryBean.jsp

■ Connection Caching—ConnCache3.jsp and ConnCache1.jsp

See the Oracle9i JDBC Developer’s Guide and Reference for information about Oracle JDBC in general and the Oracle JDBC connection caching implementation in particular.

Simple Query—SimpleQuery.jspThis page executes a simple query of the scott.emp table, listing employees and their salaries in an HTML table (ordered by employee name).

<%@ page import="java.sql.*" %>

<!------------------------------------------------------------------ * This is a basic JavaServer Page that does a JDBC query on the * emp table in schema scott and outputs the result in an html table. * --------------------------------------------------------------------!><HTML> <HEAD> <TITLE> SimpleQuery JSP </TITLE> </HEAD> <BODY BGCOLOR=EOFFFO> <H1> Hello <%= (request.getRemoteUser() != null? ", " + request.getRemoteUser() : "") %> ! I am SimpleQuery JSP. </H1> <HR> <B> I will do a basic JDBC query to get employee data from EMP table in schema SCOTT.. </B>

JDBC Samples

<P><% try { // Use the following 2 files whening running inside Oracle 9i // Connection conn = new oracle.jdbc.driver.OracleDriver(). // defaultConnection (); Connection conn = DriverManager.getConnection((String)session.getValue("connStr"), "scott", "tiger"); Statement stmt = conn.createStatement (); ResultSet rset = stmt.executeQuery ("SELECT ename, sal " + "FROM scott.emp ORDER BY ename"); if (rset.next()) {%> <TABLE BORDER=1 BGCOLOR="C0C0C0"> <TH WIDTH=200 BGCOLOR="white"> <I>Employee Name</I> </TH> <TH WIDTH=100 BGCOLOR="white"> <I>Salary</I> </TH> <TR> <TD ALIGN=CENTER> <%= rset.getString(1) %> </TD> <TD ALIGN=CENTER> $<%= rset.getDouble(2) %> </TD> </TR>

<% while (rset.next()) {%>

<TR> <TD ALIGN=CENTER> <%= rset.getString(1) %> </TD> <TD ALIGN=CENTER> $<%= rset.getDouble(2) %> </TD> </TR>

<% }%> </TABLE><% } else {%> <P> Sorry, the query returned no rows! </P>

<% } rset.close(); stmt.close(); } catch (SQLException e) { out.println("<P>" + "There was an error doing the query:"); out.println ("<PRE>" + e + "</PRE> \n <P>"); }


JDBC Samples

%>

</BODY></HTML>

User-Specified Query—JDBCQuery.jspThis page queries the scott.emp table according to a user-specified condition and outputs the results.


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

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

<B>Enter a search condition:</B><FORM METHOD=get> <INPUT TYPE="text" NAME="cond" SIZE=30><INPUT TYPE="submit" VALUE="Ask Oracle");</FORM></BODY></HTML><%! private String runQuery(String cond) throws SQLException { Connection conn = null; Statement stmt = null; ResultSet rset = null; try { DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver()); conn = DriverManager.getConnection((String)session.getValue("connStr"), "scott", "tiger"); stmt = conn.createStatement(); rset = stmt.executeQuery ("SELECT ename, sal FROM scott.emp "+ (cond.equals("") ? "" : "WHERE " + cond )); return (formatResult(rset)); } catch (SQLException e) {


JDBC Samples

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

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(1) + " earns $ " + rset.getInt(2) + ".</LI>\n"); } while (rset.next()); sb.append("</B></UL>"); } return sb.toString(); }%>

Query Using a Query Bean—UseHtmlQueryBean.jspThis page uses a JavaBean, HtmlQueryBean, to query the scott.emp table according to a user-specified condition. HtmlQueryBean, in turn, uses the class HtmlTable to format the output into an HTML table. This sample includes code for the JSP page, HtmlQueryBean, and HtmlTable.

Code for UseHtmlQueryBean.jsp<jsp:useBean id="htmlQueryBean" class="beans.HtmlQueryBean" scope="session" /><jsp:setProperty name="htmlQueryBean" property="searchCondition" />

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

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


JDBC Samples

<% } %> <P><B>Enter a search condition:</B></P><FORM METHOD=get> <INPUT TYPE=text NAME="searchCondition" SIZE=30><INPUT TYPE=submit VALUE="Ask Oracle"></FORM></BODY></HTML>

Code for HtmlQueryBean.javapackage beans;

import java.sql.*;

public class HtmlQueryBean {

private String searchCondition = ""; private String connStr = null;

public String getResult() throws SQLException { return runQuery(); } public void setSearchCondition(String searchCondition) { this.searchCondition = searchCondition; } public void setConnStr(String connStr) { this.connStr = connStr; }

private String runQuery() { Connection conn = null; Statement stmt = null; ResultSet rset = null; try { if (conn == null) { DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver()); conn = DriverManager.getConnection(connStr, "scott","tiger"); } stmt = conn.createStatement(); rset = stmt.executeQuery ("SELECT ename as \"Name\", " + "empno as \"Employee Id\","+


JDBC Samples

"sal as \"Salary\"," + "TO_CHAR(hiredate, ’DD-MON-YYYY’) as \"Date Hired\"" + "FROM scott.emp " + (searchCondition.equals("") ? "" : "WHERE " + searchCondition )); return format(rset);; } catch (SQLException e) { return ("<P> SQL error: <PRE> " + e + " </PRE> </P>\n"); } finally { try { if (rset!= null) rset.close(); if (stmt!= null) stmt.close(); if (conn!= null) conn.close(); } catch (SQLException ignored) {} } } public static String format(ResultSet rs) throws SQLException { StringBuffer sb = new StringBuffer(); if (rs == null || !rs.next()) sb.append("<P> No matching rows.<P>\n"); else { sb.append("<TABLE BORDER>\n"); ResultSetMetaData md = rs.getMetaData(); int numCols = md.getColumnCount(); for (int i=1; i<= numCols; i++) { sb.append("<TH><I>" + md.getColumnLabel(i) + "</I></TH>"); } do { sb.append("<TR>\n");

for (int i = 1; i <= numCols; i++) { sb.append("<TD>"); Object obj = rs.getObject(i); if (obj != null) sb.append(obj.toString()); sb.append("</TD>"); } sb.append("</TR>"); } while (rs.next()); sb.append("</TABLE>"); } return sb.toString(); }}


JDBC Samples

Code for HtmlTable.javaimport java.sql.*;

public class HtmlTable {

public static String format(ResultSet rs) throws SQLException { StringBuffer sb = new StringBuffer(); if (rs == null || !rs.next()) sb.append("<P> No matching rows.<P>\n"); else { sb.append("<TABLE BORDER>\n"); ResultSetMetaData md = rs.getMetaData(); int numCols = md.getColumnCount(); for (int i=1; i<= numCols; i++) { sb.append("<TH><I>" + md.getColumnLabel(i) + "</I></TH>"); } do { sb.append("<TR>\n");

for (int i = 1; i <= numCols; i++) { sb.append("<TD>"); Object obj = rs.getObject(i); if (obj != null) sb.append(obj.toString()); sb.append("</TD>"); } sb.append("</TR>"); } while (rs.next()); sb.append("</TABLE>"); } return sb.toString(); }}

Connection Caching—ConnCache3.jsp and ConnCache1.jspThis section provides two examples of connection caching using Oracle’s caching implementation. This implementation uses the Oracle JDBC OracleConnectionCacheImpl class. For introductory information, see "Database Connection Caching" on page 4-9. For further information see, the Oracle9i JDBC Developer’s Guide and Reference.

The first example, ConnCache3.jsp, performs its own cache setup.


JDBC Samples

The second example, ConnCache1.jsp, uses a separate page, setupcache.jsp, to do the setup.

Code is provided for all three pages.

Code for ConnCache3.jsp (with cache setup)This sample page handles its own connection cache setup.

<%@ page import="java.sql.*, javax.sql.*, oracle.jdbc.pool.*" %>

<!------------------------------------------------------------------ * This is a JavaServer Page that uses Connection Caching at Session * scope. --------------------------------------------------------------------!>

<jsp:useBean id="ods" class="oracle.jdbc.pool.OracleConnectionCacheImpl" scope="session" />

<HTML> <HEAD> <TITLE> ConnCache 3 JSP </TITLE> </HEAD> <BODY BGCOLOR=EOFFFO> <H1> Hello <%= (request.getRemoteUser() != null? ", " + request.getRemoteUser() : "") %> ! I am Connection Caching JSP. </H1> <HR> <B> Session Level Connection Caching. </B>

<P><% try { ods.setURL((String)session.getValue("connStr")); ods.setUser("scott"); ods.setPassword("tiger");

Note: As a more convenient alternative, you can use the ConnCacheBean JavaBean provided with OracleJSP. See "Page Using ConnCacheBean—ConnCacheBeanDemo.jsp" on page 11-28.

JDBC Samples

Connection conn = ods.getConnection (); Statement stmt = conn.createStatement (); ResultSet rset = stmt.executeQuery ("SELECT ename, sal " + "FROM scott.emp ORDER BY ename");

if (rset.next()) {%> <TABLE BORDER=1 BGCOLOR="C0C0C0"> <TH WIDTH=200 BGCOLOR="white"> <I>Employee Name</I> </TH> <TH WIDTH=100 BGCOLOR="white"> <I>Salary</I> </TH> <TR> <TD ALIGN=CENTER> <%= rset.getString(1) %> </TD> <TD ALIGN=CENTER> $<%= rset.getDouble(2) %> </TD> </TR>




<% } rset.close(); stmt.close(); conn.close(); // Put the Connection Back into the Pool

} catch (SQLException e) { out.println("<P>" + "There was an error doing the query:"); out.println ("<PRE>" + e + "</PRE> \n <P>"); }%>

</BODY></HTML>


JDBC Samples

Code for ConnCache1.jsp and setupcache.jspThis sample page statically includes another page, setupcache.jsp, for its connection cache setup. Code is provided for both pages.

ConnCache1.jsp

<%@ include file="setupcache.jsp" %><%@ page import="java.sql.*, javax.sql.*, oracle.jdbc.pool.*" %>

<!------------------------------------------------------------------ * This is a JavaServer Page that uses Connection Caching over application * scope. The Cache is created in an application scope in setupcache.jsp * Connection is obtained from the Cache and recycled back once done.--------------------------------------------------------------------!>

<HTML> <HEAD> <TITLE> ConnCache1 JSP </TITLE> </HEAD> <BODY BGCOLOR=EOFFFO> <H1> Hello <%= (request.getRemoteUser() != null? ", " + request.getRemoteUser() : "") %> ! I am Connection Caching JSP. </H1> <HR> <B> I get the Connection from the Cache and recycle it back. </B>

<P><% try { Connection conn = cods.getConnection(); Statement stmt = conn.createStatement (); ResultSet rset = stmt.executeQuery ("SELECT ename, sal " + "FROM scott.emp ORDER BY ename"); if (rset.next()) {%> <TABLE BORDER=1 BGCOLOR="C0C0C0"> <TH WIDTH=200 BGCOLOR="white"> <I>Employee Name</I> </TH> <TH WIDTH=100 BGCOLOR="white"> <I>Salary</I> </TH> <TR> <TD ALIGN=CENTER> <%= rset.getString(1) %> </TD>

JDBC Samples

<TD ALIGN=CENTER> $<%= rset.getDouble(2) %> </TD> </TR>




<% } rset.close(); stmt.close(); conn.close(); // Put the Connection Back into the Pool } catch (SQLException e) { out.println("<P>" + "There was an error doing the query:"); out.println ("<PRE>" + e + "</PRE> \n <P>"); }%>

</BODY></HTML>

setupcache.jsp

<jsp:useBean id="cods" class="oracle.jdbc.pool.OracleConnectionCacheImpl" scope="application"><% cods.setURL((String)session.getValue("connStr")); cods.setUser("scott"); cods.setPassword("tiger"); cods.setStmtCache (5); %></jsp:useBean>


Data-Access JavaBean Samples

Data-Access JavaBean SamplesThis section provides examples using the Oracle data-access JavaBeans. These beans are provided with OracleJSP but are generally portable to other JSP environments. Note, however, that the connection caching bean relies on the Oracle JDBC implementation of connection caching.

DBBean is the simplest of these JavaBeans, with its own connection functionality and supporting queries only. For more complicated operations, use appropriate combinations of ConnBean (for simple connections), ConnCacheBean (for connection caching), and CursorBean (for general SQL DML operations).

For more information, see "Oracle Data-Access JavaBeans" on page 5-13.

The following examples are included:

■ Page Using DBBean—DBBeanDemo.jsp

■ Page Using ConnBean—ConnBeanDemo.jsp

■ Page Using CursorBean—CursorBeanDemo.jsp

■ Page Using ConnCacheBean—ConnCacheBeanDemo.jsp

Page Using DBBean—DBBeanDemo.jspThis page uses a DBBean object to connect to the database or middle-tier database cache, execute a query, and output the results as an HTML table.


<!------------------------------------------------------------------ * This is a basic JavaServer Page that uses a DB Access Bean and queries * dept and emp tables in schema scott and outputs the result in an html table. * --------------------------------------------------------------------!>

<jsp:useBean id="dbbean" class="oracle.jsp.dbutil.DBBean" scope="session"> <jsp:setProperty name="dbbean" property="User" value="scott"/> <jsp:setProperty name="dbbean" property="Password" value="tiger"/> <jsp:setProperty name="dbbean" property="URL" value= "<%= (String)session.getValue(\"connStr\") %>" />

Note: Oracle also provides custom tags for SQL functionality that use these JavaBeans behind the scenes. For samples using these tags, see "SQL Tag Examples" on page 5-29.


</jsp:useBean>

<HTML> <HEAD> <TITLE> DBBeanDemo JSP </TITLE> </HEAD> <BODY BGCOLOR=EOFFFO> <H1> Hello <%= (request.getRemoteUser() != null? ", " + request.getRemoteUser() : "") %> ! I am DBBeanDemo JSP. </H1> <HR> <B> I’m using DBBean and querying DEPT & EMP tables in schema SCOTT..... I get all employees who work in the Research department. </B>

<P><% try { String sql_string = " select ENAME from EMP,DEPT " + " where DEPT.DNAME = 'RESEARCH' " + " and DEPT.DEPTNO = EMP.DEPTNO";

// Make the Connection dbbean.connect();

// Execute the SQL and get a HTML table out.println(dbbean.getResultAsHTMLTable(sql_string));

// Close the Bean to close the connection dbbean.close(); } catch (SQLException e) { out.println("<P>" + "There was an error doing the query:"); out.println ("<PRE>" + e + "</PRE> \n <P>"); }%>

</BODY></HTML>


Page Using ConnBean—ConnBeanDemo.jspThis page uses a ConnBean object (for a simple connection) to retrieve a CursorBean object, then uses the CursorBean object to output query results as an HTML table.

<%@ page import="java.sql.* , oracle.jsp.dbutil.*" %>

<!------------------------------------------------------------------ * This is a basic JavaServer Page that uses a Connection Bean and queries * emp table in schema scott and outputs the result in an html table. * --------------------------------------------------------------------!>

<jsp:useBean id="cbean" class="oracle.jsp.dbutil.ConnBean" scope="session"> <jsp:setProperty name="cbean" property="User" value="scott"/> <jsp:setProperty name="cbean" property="Password" value="tiger"/> <jsp:setProperty name="cbean" property="URL" value= "<%= (String)session.getValue(\"connStr\") %>"/> <jsp:setProperty name="cbean" property="PreFetch" value="5"/> <jsp:setProperty name="cbean" property="StmtCacheSize" value="2"/></jsp:useBean>

<HTML> <HEAD> <TITLE> Connection Bean Demo JSP </TITLE> </HEAD> <BODY BGCOLOR=EOFFFO> <H1> Hello <%= (request.getRemoteUser() != null? ", " + request.getRemoteUser() : "") %> ! I am Connection Bean Demo JSP. </H1> <HR> <B> I’m using connection and a query bean and querying employee names and salaries from EMP table in schema SCOTT.. </B>

<P><% try { // Make the Connection cbean.connect();

String sql = "SELECT ename, sal FROM scott.emp ORDER BY ename";

// get a Cursor Bean CursorBean cb = cbean.getCursorBean (CursorBean.PREP_STMT, sql);

out.println(cb.getResultAsHTMLTable());

// Close the cursor bean cb.close(); // Close the Bean to close the connection cbean.close(); } catch (SQLException e) { out.println("<P>" + "There was an error doing the query:"); out.println ("<PRE>" + e + "</PRE> \n <P>"); }%>

</BODY></HTML>

Page Using CursorBean—CursorBeanDemo.jspThis page uses a ConnBean object (for a simple connection) and a CursorBean object to execute a PL/SQL statement, get a REF CURSOR, and translate the results into an HTML table.

<%@ page import="java.sql.* , oracle.jsp.dbutil.*" %>

<!------------------------------------------------------------------ * This is a basic JavaServer Page that uses a Cursor and Conn Beans and queries * dept table in schema scott and outputs the result in an html table. * --------------------------------------------------------------------!>

<jsp:useBean id="connbean" class="oracle.jsp.dbutil.ConnBean" scope="session"> <jsp:setProperty name="connbean" property="User" value="scott"/> <jsp:setProperty name="connbean" property="Password" value="tiger"/> <jsp:setProperty name="connbean" property="URL" value= "<%= (String)session.getValue(\"connStr\") %>" /></jsp:useBean><jsp:useBean id="cbean" class="oracle.jsp.dbutil.CursorBean" scope="session"> <jsp:setProperty name="cbean" property="PreFetch" value="10"/> <jsp:setProperty name="cbean" property="ExecuteBatch" value="2"/>


</jsp:useBean>

<HTML> <HEAD> <TITLE> CursorBean Demo JSP </TITLE> </HEAD> <BODY BGCOLOR=EOFFFO> <H1> Hello <%= (request.getRemoteUser() != null? ", " + request.getRemoteUser() : "") %> ! I am Cursor Bean JSP. </H1> <HR> <B> I‘m using cbean and i’m quering department names from DEPT table in schema SCOTT.. </B>

<P><% try {

// Make the Connection connbean.connect();

String sql = "BEGIN OPEN ? FOR SELECT DNAME FROM DEPT; END;"; // Create a Callable Statement cbean.create ( connbean, CursorBean.CALL_STMT, sql); cbean.registerOutParameter(1,oracle.jdbc.driver.OracleTypes.CURSOR);

// Execute the PLSQL cbean.executeUpdate (); // Get the Ref Cursor ResultSet rset = cbean.getCursor(1);

out.println(oracle.jsp.dbutil.BeanUtil.translateToHTMLTable (rset));

// Close the RefCursor rset.close();

// Close the Bean cbean.close();


// Close the connection connbean.close();

} catch (SQLException e) { out.println("<P>" + "There was an error doing the query:"); out.println ("<PRE>" + e + "</PRE> \n <P>"); }%>

</BODY></HTML>

Page Using ConnCacheBean—ConnCacheBeanDemo.jspThis page uses a ConnCacheBean object to obtain a connection from a connection cache. It then uses standard JDBC functionality to execute a query, formatting the results as an HTML table.

<%@ page import="java.sql.*, javax.sql.*, oracle.jsp.dbutil.ConnCacheBean" %>

<!------------------------------------------------------------------ * This is a basic JavaServer Page that does a JDBC query on the * emp table in schema scott and outputs the result in an html table. * Uses Connection Cache Bean.--------------------------------------------------------------------!>

<jsp:useBean id="ccbean" class="oracle.jsp.dbutil.ConnCacheBean" scope="session"> <jsp:setProperty name="ccbean" property="user" value="scott"/> <jsp:setProperty name="ccbean" property="password" value="tiger"/> <jsp:setProperty name="ccbean" property="URL" value= "<%= (String)session.getValue(\"connStr\") %>" /> <jsp:setProperty name="ccbean" property="MaxLimit" value="5" /> <jsp:setProperty name="ccbean" property="CacheScheme" value= "<%= ConnCacheBean.FIXED_RETURN_NULL_SCHEME %>" /></jsp:useBean><HTML> <HEAD> <TITLE> SimpleQuery JSP </TITLE> </HEAD> <BODY BGCOLOR=EOFFFO>


<H1> Hello <%= (request.getRemoteUser() != null? ", " + request.getRemoteUser() : "") %> ! I am Connection Cache Demo Bean </H1> <HR> <B> I will do a basic JDBC query to get employee data from EMP table in schema SCOTT. The connection is obtained from the Connection Cache. </B>

<P><% try { Connection conn = ccbean.getConnection(); Statement stmt = conn.createStatement (); ResultSet rset = stmt.executeQuery ("SELECT ename, sal " + "FROM scott.emp ORDER BY ename"); if (rset.next()) {%> <TABLE BORDER=1 BGCOLOR="C0C0C0"> <TH WIDTH=200 BGCOLOR="white"> <I>Employee Name</I> </TH> <TH WIDTH=100 BGCOLOR="white"> <I>Salary</I> </TH> <TR> <TD ALIGN=CENTER> <%= rset.getString(1) %> </TD> <TD ALIGN=CENTER> $<%= rset.getDouble(2) %> </TD> </TR>




<% } rset.close();



stmt.close(); conn.close(); ccbean.close(); } catch (SQLException e) { out.println("<P>" + "There was an error doing the query:"); out.println ("<PRE>" + e + "</PRE> \n <P>"); }%>

</BODY></HTML>


Custom Tag Samples

Custom Tag SamplesThis section includes the following:

■ a sample using some of the Oracle JSP Markup Language (JML) custom tags

■ referrals to additional custom tag samples elsewhere in this document

JML Tag Sample—hellouser_jml.jspThis section provides a basic sample using some of the Oracle JML custom tags.

This is a modified version of the hellouser.jsp sample provided earlier in this chapter. For contrast, both the JML code and the original code are provided here.

Note that the runtime implementation of the JML tag library is portable to other JSP environments. For an overview of the runtime implementation, see "Overview of the JSP Markup Language (JML) Sample Tag Library" on page 7-20. For information about the compile-time (non-portable) implementation, see Appendix C, "Compile-Time JML Tag Support".

Code for hellouser_jml.jsp (using JML tags)<%----------------------------------------------------------- Copyright (c) 1999, Oracle Corporation. All rights reserved.------------------------------------------------------------%>

<%@page session="false" %><%@ taglib uri="WEB-INF/jml.tld" prefix="jml" %>

<jml:useForm id="name" param="newName" scope="request" />


<BODY>

<jml:if condition="!name.isEmpty()" ><H3>Welcome <jml:print eval="name.getValue()" /></H3></jml:if>

<P>


Custom Tag Samples

Enter your Name:<FORM METHOD=get><INPUT TYPE=TEXT name=newName size = 20><br><INPUT TYPE=SUBMIT VALUE="Submit name"></FORM>

</BODY></HTML>

Code for hellouser.jsp (not using JML tags)<%----------------------------------------------------------- Copyright (c) 1999, Oracle Corporation. All rights reserved.------------------------------------------------------------%>

<%@page session="false" %>

<jsp:useBean id="name" class="oracle.jsp.jml.JmlString" scope="request" > <jsp:setProperty name="name" property="value" param="newName" /></jsp:useBean>


<BODY>

<% if (!name.isEmpty()) { %><H3>Welcome <%= name.getValue() %></H3><% } %>

<P>Enter your Name:<FORM METHOD=get><INPUT TYPE=TEXT name=newName size = 20><br><INPUT TYPE=SUBMIT VALUE="Submit name"></FORM>

</BODY></HTML>


Custom Tag Samples

Pointers to Additional Custom Tag SamplesAdditional custom tag samples are provided elsewhere in this document:

■ For a complete example of defining and using a standard JSP 1.1-compliant custom tag, see "End-to-End Example: Defining and Using a Custom Tag" on page 7-15.

■ For samples using the Oracle custom tag library for SQL functionality, see "SQL Tag Examples" on page 5-29.


Samples for Oracle-Specific Programming Extensions

Samples for Oracle-Specific Programming ExtensionsThis section provides a variety of examples using Oracle-specific extensions. This includes the following:

■ Page Using JspScopeListener—scope.jsp

■ XML Query—XMLQuery.jsp

■ SQLJ Queries—SQLJSelectInto.sqljsp and SQLJIterator.sqljsp

Page Using JspScopeListener—scope.jspThis sample illustrates the use of a JspScopeListener implementation to allow JSP objects attached to a scope to be notified when they are going "out of scope". The sample implements a generic listener that redispatches the out-of-scope notification to the registered object or method. In using this listener, scope.jsp is able to simulate page event handlers for request and page out-of-scope notification.

This sample creates and attaches a listener object to the request and page scopes. It registers local methods to handle out-of-scope notifications forwarded by the listener. To illustrate this, the sample keeps two counters—the first is a page count; the second is a count of the number of included files.

The current page count is logged when the page goes out of scope. The included page count is logged when the request goes out of scope. The sample then proceeds to include itself five times.

The sample outputs six messages indicating a page count of 1, followed by a single message indicating five jsp:include operations occurred.

For general information about the JspScopeListener mechanism, see "OracleJSP Event Handling—JspScopeListener" on page 5-33.

Listener Implementation—PageEventDispatcherPageEventDispatcher is a JavaBean that implements the JspScopeListener interface. The interface defines the outOfScope() event method, which takes a JspScopeEvent object as input. The outOfScope() method of a PageEventDispatcher object is called when the scope (application, session, page, or request) associated with the object is ending.

In this sample, a PageEventDispatcher object acts as a redispatcher for the JSP page, allowing the JSP page to host the equivalent of globals.jsa "on end" functionality for page and request events. The JSP page creates a PageEventDispatcher object for each scope for which it wants to provide an



event handler. It then registers the event handler method with the PageEventDispatcher object. When the PageEventDispatcher object is notified that it is going out of scope, it calls the registered "on end" method of the page.

package oracle.jsp.sample.event;

import java.lang.reflect.*;import oracle.jsp.event.*;

public class PageEventDispatcher extends Object implements JspScopeListener {

private Object page; private String methodName; private Method method;

public PageEventDispatcher() { }

public Object getPage() { return page; }

public void setPage(Object page) { this.page = page; }

public String getMethodName() { return methodName; }

public void setMethodName(String m) throws NoSuchMethodException, ClassNotFoundException { method = verifyMethod(m); methodName = m; }

public void outOfScope(JspScopeEvent ae) { int scope = ae.getScope();

if ((scope == javax.servlet.jsp.PageContext.REQUEST_SCOPE || scope == javax.servlet.jsp.PageContext.PAGE_SCOPE) && method != null) { try { Object args[] = {ae.getApplication(), ae.getContainer()};



method.invoke(page, args); } catch (Exception e) { // catch all and continue } } }

private Method verifyMethod(String m) throws NoSuchMethodException, ClassNotFoundException { if (page == null) throw new NoSuchMethodException ("A page hasn’t been set yet.");

/* Don’t know whether this is a request or page handler so try one then the other */ Class c = page.getClass(); Class pTypes[] = {Class.forName("javax.servlet.ServletContext"), Class.forName("javax.servlet.jsp.PageContext")};

try { return c.getDeclaredMethod(m, pTypes); } catch (NoSuchMethodException nsme) { // fall through and try the request signature }

pTypes[1] = Class.forName("javax.servlet.http.HttpServletRequest"); return c.getDeclaredMethod(m, pTypes); }}

scope.jsp SourceThis JSP page uses the preceding PageEventDispatcher class (which implements the JspScopeListener interface) to track events of page or request scope.

<%-- declare request and page scoped beans here --%>

<jsp:useBean id = "includeCount" class = "oracle.jsp.jml.JmlNumber" scope = "request" /><jsp:useBean id = "pageCount" class = "oracle.jsp.jml.JmlNumber" scope = "page" > <jsp:setProperty name = "pageCount" property = "value" value = "<%= pageCount.getValue() + 1 %>" /> </jsp:useBean>



<%-- declare the event dispatchers --%><jsp:useBean id = "requestDispatcher" class = "oracle.jsp.sample.event.PageEventDispatcher" scope = "request" > <jsp:setProperty name = "requestDispatcher" property = "page" value = "<%= this %>" /> <jsp:setProperty name = "requestDispatcher" property = "methodName" value = "request_OnEnd" /></jsp:useBean>

<jsp:useBean id = "pageDispatcher" class = "oracle.jsp.sample.event.PageEventDispatcher" scope = "page" > <jsp:setProperty name = "pageDispatcher" property = "page" value = "<%= this %>" /> <jsp:setProperty name = "pageDispatcher" property = "methodName" value = "page_OnEnd" /></jsp:useBean>

<%! // request_OnEnd Event Handler public void request_OnEnd(ServletContext application, HttpServletRequest request) { // acquire beans oracle.jsp.jml.JmlNumber includeCount = (oracle.jsp.jml.JmlNumber) request.getAttribute("includeCount");

// now cleanup the bean if (includeCount != null) application.log ("request_OnEnd: Include count = " + includeCount.getValue()); }

// page_OnEnd Event Handler public void page_OnEnd(ServletContext application, PageContext page) { // acquire beans oracle.jsp.jml.JmlNumber pageCount = (oracle.jsp.jml.JmlNumber) page.getAttribute("pageCount");

// now cleanup the bean -- uncomment code for real bean if (pageCount != null) application.log ("page_OnEnd: Page count = " + pageCount.getValue()); } %>

<%-- Page implementation goes here --%>

<jsp:setProperty name = "includeCount" property = "value" value = ’<%= (request.getAttribute("javax.servlet.include.request_uri") != null) ? includeCount.getValue() + 1 : 0 %>’ />

<h2> Hello World </h2>



Included: <%= request.getAttribute("javax.servlet.include.request_uri") %> Count: <%= includeCount.getValue() %> <br>

<% if (includeCount.getValue() < 5) { %> <jsp:include page="scope.jsp" flush = "true" /><% } %>

XML Query—XMLQuery.jspThis example connects to a database or middle-tier database cache, executes a query, and uses functionality of the oracle.xml.sql.query.OracleXMLQuery class to output the results as an XML string.

This is Oracle-specific functionality. The OracleXMLQuery class is provided with Oracle9i as part of the XML-SQL utility.

For general information about XML and XSL usage with JSP pages, see "OracleJSP Support for XML and XSL" on page 5-9.

<%----------------------------------------------------------- Copyright (c) 1999, Oracle Corporation. All rights reserved.------------------------------------------------------------%>

<%@ page import = "java.sql.*,oracle.xml.sql.query.OracleXMLQuery" %><html> <head><title> The XMLQuery Demo </title></head><body><h1> XMLQuery Demo </h1><h2> Employee List in XML </h2><b>(View Page Source in your browser to see XML output)</b><% Connection conn = null; Statement stmt = null; ResultSet rset = null; try {

// determine JDBC driver name from session value // if null, use JDBC kprb driver if in Oracle9i, JDBC oci otherwise String dbURL = (String)session.getValue("connStr"); if (dbURL == null) dbURL = (System.getProperty("oracle.jserver.version") == null? "jdbc:oracle:oci8:@" : "jdbc:oracle:kprb:@");

DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());



conn = DriverManager.getConnection(dbURL, "scott", "tiger"); stmt = conn.createStatement (); rset = stmt.executeQuery ("SELECT ename, sal " + "FROM scott.emp ORDER BY ename"); OracleXMLQuery xq = new OracleXMLQuery(conn, rset); %> <PRE> <%= xq.getXMLString() %> </PRE><% } catch (java.sql.SQLException e) { %> <P> SQL error: <PRE> <%= e %> </PRE> </P><% } finally { if (stmt != null) stmt.close(); if (rset != null) rset.close(); if (conn != null) conn.close(); } %></body></html>

SQLJ Queries—SQLJSelectInto.sqljsp and SQLJIterator.sqljspThis section provides examples of using SQLJ in JSP pages to query a database or the middle-tier database cache.

The first example, SQLJSelectInto.sqljsp, selects a single row using SQLJ SELECT INTO syntax.

The second example, SQLJIterator.sqljsp, selects multiple rows into a SQLJ iterator, which is similar to a JDBC result set.

For information about using SQLJ in JSP pages, see "OracleJSP Support for Oracle SQLJ" on page 5-34.

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

Code for SQLJSelectInto.sqljsp (select single row)This example selects a single row from the database or middle-tier database cache, using SQLJ SELECT INTO syntax.

<%@ page import="sqlj.runtime.ref.DefaultContext,oracle.sqlj.runtime.Oracle" %>

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

<%



String connStr=request.getParameter("connStr"); if (connStr==null) { connStr=(String)session.getValue("connStr"); } else { session.putValue("connStr",connStr); } if (connStr==null) { %><jsp:forward page="../setconn.jsp" /><% }%>

<% String empno = request.getParameter("empno"); if (empno != null) { %> <H3> Employee # <%=empno %> Details: </H3> <%= runQuery(connStr,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 connStr, 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(connStr, "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(); }%>

Code for SQLJIterator.sqljsp (select multiple rows)This example selects multiple rows from the database or middle-tier database cache, using a SQLJ iterator.

<%@ page import="java.sql.*" %><%@ page import="sqlj.runtime.ref.DefaultContext,oracle.sqlj.runtime.Oracle" %>

<!------------------------------------------------------------------ * This is a SQLJ JavaServer Page that does a SQLJ query on the * emp table in schema scott and outputs the result in an html table. * --------------------------------------------------------------------!>

<%! #sql iterator Empiter(String ename, double sal, java.sql.Date hiredate) %>

<% String connStr=request.getParameter("connStr"); if (connStr==null) { connStr=(String)session.getValue("connStr"); } else { session.putValue("connStr",connStr); } if (connStr==null) { %><jsp:forward page="../setconn.jsp" /><% }%>

<% DefaultContext dctx = null; dctx = Oracle.getConnection(connStr, "scott", "tiger");%>

<HTML>


<HEAD> <TITLE> The SqljIterator SQLJSP </TITLE> </HEAD><BODY BGCOLOR="E0FFF0"> <% String user; #sql [dctx] {SELECT user INTO :user FROM dual}; %>

<H1> Hello, <%= user %>! </H1> <HR> <B> I will use a SQLJ iterator to get employee data from EMP table in schema SCOTT.. </B> <P><% Empiter emps; try { #sql [dctx] emps = { SELECT ename, sal, hiredate FROM scott.emp ORDER BY ename}; if (emps.next()) {%> <TABLE BORDER=1 BGCOLOR="C0C0C0"> <TH WIDTH=200 BGCOLOR=white> Employee Name </TH> <TH WIDTH=100 BGCOLOR=white> Salary </TH> <TR> <TD> <%= emps.ename() %> </TD> <TD> <%= emps.sal() %> </TD> </TR>

<% while (emps.next()) {%> <TR> <TD> <%= emps.ename() %> </TD> <TD> <%= emps.sal() %> </TD> </TR><% } %> </TABLE><% } else { %> <P> Sorry, the query returned no rows! </P><% } emps.close(); } catch (SQLException e) { %> <P>There was an error doing the query:<PRE> <%= e %> </PRE> <P><% } %></BODY></HTML>


JESI Tag Sample—Portal Demo

JESI Tag Sample—Portal DemoThis section lists and explains the JESI tag "portal demo" sample application, a simplified example of a personalized dynamic portal page.

For general information about JESI tags and Edge Side Includes caching technology, see Chapter 8, "JESI Tags for Edge Side Includes".

Portal Demo ExplanationIn this sample, a user logs in and is shown stock, weather, news, and sports information based on portfolio, city, state, and previously determined topics of interest.

In a part of the application that is not shown, the user creates an account and enters their location and preferences. In particular, they specify stocks they want to follow, their home city and state, which one of a selection of news topics they prefer, and which one of a selection of sports topics they prefer. These choices result in creation of a personal portal page that displays and updates stock quotes of interest, weather reports for their area, and headlines and stories for their news and sports topics of interest. A series of advertising banners are also displayed.

The following files are listed:

■ Login.jsp

■ PersonalPortal.java

■ Portal.jsp

■ Advert.jsp

■ PersonalizedStockSelection.jsp

■ Quote.jsp

■ Weather.jsp

■ News.jsp

■ ConnectBean.java

(Image files for the advertising banners, advert1.gif through advert5.gif, are not included.)



When a user accesses the portal, the following sequence occurs:

1. The URL of the application brings users to Login.jsp, where they are prompted to enter their names.

2. The Login.jsp page takes the user name and executes a forward to the servlet page PersonalPortal, forwarding the user name as a request parameter.

3. The PersonalPortal servlet has a table of known user preferences, using it to determine the city, state, sports topic, and news topic of the user who logged in. The page then executes a forward to the main page of the application, Portal.jsp, sending along the user name, city, state, sports topic, and news topic as request parameters.

4. The Portal.jsp page has jesi:include tags for pages that will display dynamic content, such as the advertising banners, weather, news, and sports—Advert.jsp, Weather.jsp, and News.jsp (included twice, once for news and once for sports). Each of these pages has a jesi:control tag to set caching parameters. When each page is included, the copyparam attribute is used to copy request parameters from the Portal.jsp request object to the request object of the included page. Stock information is based on the user's portfolio; weather information is based on the user’s city and state; news and sports topics are based on the user's preferences.

Stock information and ad banner displays are cached for 10 minutes. Weather information is cached for one hour. News and sports stories are cached for 15 minutes.

The page returned by the PersonalPortal servlet is automatically refreshed by the browser every 10 minutes, because that is the shortest expiration time of any of the news/information pages. Although the browser sends a request for this page every ten minutes, the page content is kept in the cache for 24 hours. This is because the page itself contains only the general layout of the portal, which is static. Each time it is refreshed, the browser sends another request to the PersonalPortal servlet, but the information that is returned comes out of the cache.

5. The PersonalizedStockSelection.jsp page has the portfolio information for each known user. It uses jesi:include tags to include the Quote.jsp

Important: For the application to work correctly, the cache policy must be sensitive to request parameters (for all pages except Advert.jsp).


page for each stock in the portfolio. This forces the quote for each stock symbol to be cached as a separate entity. Note that Portal.jsp includes PersonalizedStockSelection.jsp through a jsp:include tag, not a jesi:include tag. This means that a particular combination of stock symbols for each user becomes a part of the cached top-level PersonalPortal page, and does not change for a given user. At the same time, all users who are tracking the same stock will be served from the same cached entry for that particular stock symbol.

6. The Weather.jsp, News.jsp, and Quote.jsp pages have jsp:useBean tags to invoke the ConnectBean JavaBean, which connects to the appropriate information Web sites, processes the XML output it receives from those sites, and places the output into the response object.

7. The Advert.jsp page randomly chooses the next ad banner from a set of GIF files. The resulting <href> HTML tag will be served from the cache until the expiration time is reached, at which time Advert.jsp will be re-executed on the server and a new <href> tag will be generated. (Advert.jsp generates an <href> HTML tag that contains an <img> subtag. Browsers typically make separate requests to fetch images, so the cache should be configured to cache all GIF files. This will significantly speed up delivery of the banner images.)

Portal Demo Source CodeThis section lists the source code for each JSP page, servlet, and bean in the application.

Login Page—Login.jsp<HTML><HEAD><TITLE>MyPortal Login</TITLE></HEAD>

Note: Another part of the application that is not shown would use jesi:invalidation tags to invalidate entities stored in the cache, as appropriate, when users change any of their preferences.


<BODY>

<% if (request.getParameter("username")== null || (request.getParameter("username").equals("")) || request.getParameter("username").length()== 0 ) { %>

<P><H3> Please, Login into MyPortal Site <FORM METHOD=get><INPUT TYPE=TEXT name=username size = 20><br><INPUT TYPE=SUBMIT VALUE="Login"></FORM>

<% } else {/* came back with username. Forward to portal page */ String red="/servlet/PersonalPortal?username="+request.getParameter("username"); %><jsp:forward page=<%=red%> flush="true" /><% } %>

</BODY></HTML>

Personal Portal Servlet—PersonalPortal.javaimport javax.servlet.*;import javax.servlet.http.*;import java.io.*;import java.util.*;import java.net.URL;import java.net.URLEncoder;import java.net.HttpURLConnection;

public class PersonalPortal extends HttpServlet { String username; String news=""; String city=""; String state=""; String sport=""; public void init(ServletConfig config) throws ServletException {



super.init(config); } /* We usually expect requests with parameters, delegate to Post */ public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { doPost(request,response); } /* * Process the HTTP Post request * Gets the parameter symbol from the request */ public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { username = request.getParameter("username"); if (username == null) return; /* retrieve personal settings for a given user */ personalize(username); /* finally, forward request to the main portal page */ RequestDispatcher d = request.getRequestDispatcher ("/examples/jsp/jesi/cook/Portal.jsp?username="+username+ "&city="+city+"&state="+state+"&news="+news+"&sport="+sport); d.forward(request, response); } /* Set personal preferences based on "username" */ /* This is a demo application, thus a few "user" preferences are hard-coded into the servlet. For a full scale portal, here you would hetreive personal preferences form persistent storage, such as file or database. */ private void personalize(String username) { if(username.equalsIgnoreCase("Larry")) { news = "internet"; city = "San_Francisco"; state="CA"; sport="baseball"; } else { if(username.equalsIgnoreCase("Scott")) { news="business"; city="New_York"; state="NY"; sport="soccer"; }


if(username.equalsIgnoreCase("Soo")) { news="technology"; city="Boston"; state="MA"; sport="basketball"; } if(username.equalsIgnoreCase("Jesse")) { news="business"; city="Seattle"; state="WA"; sport="golf"; } /* Unknown User */ else { news="business"; city="Washington"; state="DC"; sport="golf"; } } }}

Main Page—Portal.jsp<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>

<%@ page errorPage="www.oracle.com" %><%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %>

<jesi:control cache="yes" expiration="86400" />

<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"><meta name="description" content="Demonstration Portal for Oracle Web Cache 2.0 ESI features. Copyright 2001 Oracle Consulting."><title>Portal page</title><meta http-equiv="refresh" content="600;url=/servlet/PersonalPortal?username=<%=request.getParameter ("username")%>">

</head><body><table width="100%" cellpadding="2" cellspacing="0" border="0" align="Center" height="98"> <tbody> <tr> <td width="345" height="56" valign="top" bgcolor="#3366ff"> <h1><font face="Helvetica, Arial, sans-serif"><big><big><big><big><big><big><font color="#6666cc"><font color="#ffffff"> Company Portal </font></font></big></big></big></big></big></big></font></h1> <br> </td> <td width="448" valign="top" bgcolor="#3366FF" height="56">  <jesi:include page="Advert.jsp" ignoreError="true"/> </td><td valign="Top" align="Right" bgcolor="#3366ff" width="7" height="56"><br> </td> </tr> <tr> <td bgcolor="#000099" colspan="2" height="42"><spacer type="block"height="4"><b><font face="Helvetica, Arial, sans-serif"><font color="#ffffff"><p>

<% String username = request.getParameter("username"); %>Welcome<%= (username == null)? "" : ", "+username %> !</p></font></font></b></td> <td valign="Top" bgcolor="#000099" width="7"><br> </td> </tr> </tbody></table><br><table width="100%" cellpadding="2" cellspacing="0" border="0"> <tbody> <tr> <td bgcolor="#ff6600" width="50%"><b><font size="-1" face="arial,helvetica"color="#ffffff"><font color="#ffffff">My Stocks</font></font></b></td> <td valign="Top" bgcolor="#ff6600" width="50%"><b><font color="#ffffff" face="Helvetica, Arial, sans-serif" size="-1">Weather</font></b></td> </tr> <tr> <td width="26%"><spacer type="block" height="4"> <table width="160" cellspacing="0" cellpadding="0" border="0">

<tbody> <tr> <td> </td>

<font size="-1" face="Helvetica, Arial, sans-serif"><br>  <jsp:include page="PersonalizedStockSelection.jsp" flush="true" /> </font>

</tr> </tbody> </table> </td> <td valign="Top" width="23%"> <jesi:include page="Weather.jsp" copyparam="true" ignoreError="true"/> </tr> </tbody></table><table width="100%" cellpadding="2" cellspacing="0" border="0"> <tbody> <tr> <td valign="top" width="50%" height="26" bgcolor="#ff6600"><b><font size="-1" face="arial,helvetica" color="#ffffff"> Latest Headlines </font></b></td> <td width="50%" valign="top" bgcolor="#FF6600" height="26"><b><font color="#ffffff" face="Helvetica, Arial, sans-serif" size="-1">Sports</font></b></td> </tr> <td valign="top" height="81"> <FONT SIZE=-1 FACE=Verdana, Arial,Helvetica, sans-serif COLOR=’#333333’> <% if(request.getParameter("news") != null) { %> <jesi:include page="News.jsp?type=Top" copyparam="true"

ignoreError="true" /> <% } %> </font>

</table></table> <td valign="top"> <FONT SIZE=-1 FACE=Verdana, Arial,Helvetica, sans-serif COLOR=’#333333’> <% if(request.getParameter("sport") != null) { %>

<jesi:include page="News.jsp?type=Sports" copyparam="true" ignoreError="true" /> <% } %> </font></td> <tr valign="Top"> <td height="42" valign="Top"><br> </td> <td width="59"></td> <td valign="Top" colspan="2"><br> </td> </tr> </tbody> <tr> <td height="22" colspan="2"> <td width="165"></td> <td></td> <tr> <td height="22" colspan="2"> <td></td> <td></td>

</body></html>

Advertising Page—Advert.jsp

<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %><!-- This is a changing ad banner: cache for 10 min, then changed to something else.

But policy is tolerant to delays -->

<jesi:control cache="yes" maxRemovalDelay="1800" expiration="600"/>

<% final int NUMBER_OF_ADVERTS = 5; int i = new Double(Math.random() * NUMBER_OF_ADVERTS + 1).intValue(); %> <a href="http://www.oracle.com"> <img src="advert<%= i%>.gif" align="right"> </a>

Stock Quote Page—PersonalizedStockSelection.jsp<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %>

 <% String username = request.getParameter("username"); if(username != null) { if (username.equals("Scott")) { %> <jesi:include page="Quote.jsp?symbol=ORCL" /> <BR> <jesi:include page="Quote.jsp?symbol=IBM" /> <BR> <jesi:include page="Quote.jsp?symbol=CSCO" /> <BR> <% } else if (username.equals("Soo")) { %> <jesi:include page="Quote.jsp?symbol=ORCL" /> <BR> <jesi:include page="Quote.jsp?symbol=AAPL" /> <BR> <% } else if (username.equals("Larry")) { %> <jesi:include page="Quote.jsp?symbol=IBM" /> <BR> <jesi:include page="Quote.jsp?symbol=DIS" /> <BR> <jesi:include page="Quote.jsp?symbol=YHOO" /> <BR> <% }

else if (username.equals("Jesse")) { %> <jesi:include page="Quote.jsp?symbol=AMD" /> <BR> <jesi:include page="Quote.jsp?symbol=IBM" /> <BR> <jesi:include page="Quote.jsp?symbol=YHOO" /> <BR> <% } else { %> <jesi:include page="Quote.jsp?symbol=YHOO" /> <BR> <jesi:include page="Quote.jsp?symbol=ORCL" /> <BR> <jesi:include page="Quote.jsp?symbol=CAT" /> <BR> <jesi:include page="Quote.jsp?symbol=SUNW" /> <BR> <jesi:include page="Quote.jsp?symbol=CSCO" /> <BR> <% } } %>

Individual Stock Quote—Quote.jsp<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %><jesi:control cache="yes" maxRemovalDelay="60" expiration="600"/><jsp:useBean id="yahooQuote" class="ConnectBean" scope="session" />

<jsp:setProperty name="yahooQuote" property="symbol" /><jsp:getProperty name="yahooQuote" property="reply" />

Weather Page—Weather.jsp<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %><jesi:control cache="yes" maxRemovalDelay="180" expiration="3600"/>

<jsp:useBean id="weatherBean" class="ConnectBean" scope="session" />

<jsp:setProperty name="weatherBean" property="city" /><jsp:setProperty name="weatherBean" property="state" /><jsp:getProperty name="weatherBean" property="forecast" />

News Page—News.jsp


<jesi:control cache="yes" maxRemovalDelay="180" expiration="900"/>

<jsp:useBean id="newsBean" class="ConnectBean" scope="session" /><jsp:setProperty name="newsBean" property="type"/><jsp:setProperty name="newsBean" property="news"/><jsp:setProperty name="newsBean" property="sport"/><jsp:getProperty name="newsBean" property="newsfeed" />

Connection JavaBean—ConnectBean.javaimport java.io.*;import java.util.*;import java.net.URL;import java.net.URLEncoder;import java.net.HttpURLConnection;

public class ConnectBean { /** URL for Yahoo quotes */ final String quoteSendURL = "http://quote.yahoo.com/d/quotes.csv"; //XML Feed of weather at Yahoo final String weatherSendURL = "http://weather.yahoo.com/forecast/"; //XML Feed of News


final String newsSendURL = "http://p.moreover.com/cgi-local/page?c="; static final String CRLF = "\r\n"; //Bean properties String symbol = ""; String city = ""; String state= ""; String type= ""; String news= ""; String sport= ""; String topic= ""; public ConnectBean() { /** Set PROXY to be able to make HTTP calls outside the firewall **/ Properties props = System.getProperties(); props.put("proxySet","true"); props.put("proxyHost", "www-proxy.us.oracle.com"); props.put("proxyPort", "80"); props.put("http.proxyHost", "www-proxy.us.oracle.com"); props.put("http.proxyPort", "80"); System.setProperties(props); } public void setSymbol(String sym) { symbol = sym; } public String getSymbol() { return symbol; } public void setCity(String c) { city = c; } public String getCity() { return city; } public void setState(String st) { state = st; } public String getState() { return state; }

public void setType(String st) { type = st; } public String getType() {



return type; } public void setNews(String st) { news = st; } public String getNews() { return news; } public void setSport(String st) { sport = st; } public String getSport() { return sport; }

/* choose topic (due to bug, cannot do it in News.jsp ) */ private void setTopic() { if (type == null) return;

if(type.equals("Top")) { if (news.equals("internet") || news.equals("business")) { topic=news; } else { topic="technology"; } }

if(type.equals("Sports")) { if (sport.equals("golf") || sport.equals("basketball") || sport.equals("baseball") ) { topic=sport; } else { topic="soccer"; // Yeah!! } } }

public String getNewsfeed() {

StringTokenizer st;



int iCurField; String token; String line = null; String completeURL = null; StringBuffer reply = new StringBuffer(1024); String url = null; String source = null; int count = 0;

setTopic();

try { if (type.indexOf("Sports")!= -1) { // http://p.moreover.com/cgi-local/page?c=Sports%3A%20baseball%20news&o=xml completeURL=(newsSendURL + "Sports%3A%20" + topic + "%20news&o=xml"); } else { // http://p.moreover.com/cgi-local/page?c=Top%20technology%20stories&o=xml completeURL= (newsSendURL + "Top%20" + topic + "%20stories&o=xml"); }

URL u = new URL(completeURL); BufferedReader d = new BufferedReader(new InputStreamReader(u.openStream()));

while((line = d.readLine()) != null) {

if (line.indexOf("<url>") != -1) { url=replace(line,"<url>","<a href=\""); url=replace(url,"</url>","\">"); } // end if

if (line.indexOf("<source>") != -1) { source=replace(line,"<source>", ""); source=replace(source,"</source>",""); } // end if

if (line.indexOf("<headline_text>") != -1 ){ if (count < 5) { reply.append(replace(line, "headline_text","i")); reply.append(url); if ((source == null) || (source.length() ==0)) { source = "MO";



} reply.append(source); reply.append("</a>"); reply.append("<br>"); count++; } // end if

} // end if } // end while return reply.toString(); } catch (Exception e) { return "Problem getting News from p.moreover.com !\n\n"+e.getMessage(); } }

public String getForecast() {

StringTokenizer st; int iCurField; String token; String line = null; String completeURL = null; String reply = ""; StringBuffer tmpbuf = new StringBuffer(1024);

try {

//New_York_NY_US_f.html completeURL=(this.weatherSendURL + city + "_" + state + "_US_f.html" );

URL u = new URL(completeURL); BufferedReader d = new BufferedReader(new InputStreamReader(u.openStream()));

while((line = d.readLine()) != null) { //Currently:</font><br><font size="5" face="arial"><b>63ºF</b></font></td> if (line.indexOf("Currently:") != -1) { //read next N lines tmpbuf.append(line); line = d.readLine(); tmpbuf.append(line); line = d.readLine(); tmpbuf.append(line); line = d.readLine();



tmpbuf.append(line); line = d.readLine(); tmpbuf.append(line); line = d.readLine(); tmpbuf.append(line); line = d.readLine(); tmpbuf.append(line); break; } // end if

} // end while

// Now, edit some errors in HTML, sent by Yahoo:

// remove </tr> reply = replace(tmpbuf.toString(),"</tr>", "");

// remove <tr align=center> reply = replace(reply, "<tr align=center>", "");

// add rowspan=2 reply = replace(reply,"<td bgcolor=", "<td rowspan=2 bgcolor=");

// add spaces reply = replace(reply, "Hi:", " Hi:"); reply = replace(reply, "Lo:", " Lo:");

return reply; } catch (Exception e) { return "Problem getting weather from Yahoo!\n\n"+e.getMessage(); } } public String getReply() { StringTokenizer st; int iCurField; String token; String line = null; String reply = new String(); try { //example url and quotes //http://quote.yahoo.com/d/quotes.csv?s=ORCL+CSCO&f=sl1d1t1c1ohgv&e=.csv //"ORCL",17.09,"5/4/2001","4:01PM",+0.64,16.14,17.20,15.96,48155400 //"CSCO",19.64,"5/4/2001","4:00PM",+0.98,17.93,19.77,17.74,103555600



URL u = new URL(quoteSendURL + "?s=" + symbol + "&f=sl1d1t1c1ohgv&e=.csv"); BufferedReader d = new BufferedReader(new InputStreamReader(u.openStream())); while((line = d.readLine()) != null) { st = new StringTokenizer(line,"\","); iCurField = 1; while(st.hasMoreTokens() == true) { token = st.nextToken(); if(iCurField == 1) { reply += "<a href=\"http://finance.yahoo.com/q?d=t&s=" + token + "\">" + token + "</a> "; } else if(iCurField == 5) { reply += token + CRLF; break; } else { reply += token + " "; } iCurField++; } } return(reply);

} catch (Exception e) { return "Problem getting stock quotes from Yahoo!\n\n"+e.getMessage(); } } private String replace(String str, String pattern, String replace) { int s = 0; int e = 0; StringBuffer result = new StringBuffer(); while ((e = str.indexOf(pattern, s)) >= 0) { result.append(str.substring(s, e)); result.append(replace); s = e+pattern.length(); } result.append(str.substring(s)); return result.toString(); }}


Samples for the Web Object Cache

Samples for the Web Object CacheThis section lists code for sample applications that use the OracleJSP Web Object Cache:

■ Web Object Cache—Using Oracle9iAS Object Caching Service for Java

■ Web Object Cache—Using a File System Cache

■ Web Object Cache—Caching XML DOM Objects

■ Web Object Cache—Caching Generic Java Objects

■ Web Object Cache—Tag Code Versus API Code

The first and second samples are functionally the same, but the first uses the default Oracle9i Application Server Object Caching Service for Java and the second uses a simple file system cache for the cache repository.

The third and fourth samples cache different kinds of objects—XML DOM objects and generic Java objects.

The fifth sample provides code for three different approaches to a simple application that caches and prints results from two fragments.

For details about the Web Object Cache, see Chapter 9, "Web Object Cache Tags and API".

Web Object Cache—Using Oracle9 iAS Object Caching Service for JavaThis application demonstrates the use of the OracleJSP Web Object Cache tags. The underlying cache repository is the default Oracle9i Application Server Object Caching Service for Java.

If you run the application, you can tell that the data is being cached by checking for entries in the directory given in the OCS4J.properties file diskPath entry.

This application is functionally the same as "Web Object Cache—Using a File System Cache" on page 11-65, but uses a different cache repository. (Note the differences between the two applications in the ojsp:cache tag in the listitem.jsp code, and the ojsp:invalidateCache tag in the added.jsp code.) Additionally, this application specifies a cache policy descriptor (test-policy.cpd); the file system cache example does not.

The following listings are provided:

■ additem.html—HTML form to prompt you to add an item in a specified category



■ added.jsp—JSP page to add a specified new item and invalidate the cache

■ seeitems.jsp—JSP page to prompt you to choose a category whose entries you want listed (includes listitem.jsp)

■ listitem.jsp—JSP page to list the items in a chosen category and cache the results

■ test-policy.cpd—cache policy descriptor

HTML Form—additem.html<title>additem.html</title>Add your shopping item:<br><form method="post" action="added.jsp" >To add: <input type="text" name="addItem"> <br>in category: <SELECT name="itemid"><OPTION value="Veggie" >Veggie<OPTION value="Meat">Meat<OPTION value="Fish">Fish</SELECT><br><input type=submit value="Add item"> <input type=reset></form>

Add Specified Item—added.jspKey lines are highlighted.

<%@ taglib uri="/WEB-INF/jwcache.tld" prefix="ojsp" %><title>added.jsp</title><jsp:useBean class="java.util.Hashtable" id="table" scope="application" /><% String itemid=request.getParameter("itemid"); String addItem=request.getParameter("addItem"); Vector list=(Vector) table.get(itemid); if (list==null) { list=new Vector(); table.put(itemid,list); } list.addElement(addItem);%><b><%= addItem %></b> was added into category <b><%= itemid %></b>.<br><% String viewPage="listitem.jsp?itemid="+itemid; %><% long l1=(new java.util.Date()).getTime(); %><ojsp:invalidateCache page="<%= viewPage %>" autoInvalidateLevel="param" policy="/WEB-INF/test-policy.cpd" /><% long l2=(new java.util.Date()).getTime(); %>Existing cache entry has been invalidated. <br>



Invalidation took <%= l2-l1 %> milliseconds.<br><jsp:include page="<%= viewPage %>" flush="true" /><br><a href="seeitems.jsp" >Select items</a>or<a href="additem.html" >Add items</a><br>

Prompt for Category to List Items—seeitems.jspKey lines are highlighted.

<title>seeitems.jsp</title>See the list of :<br><form method="get" action="seeitems.jsp" ><% String itemid=request.getParameter("itemid"); if (itemid==null) itemid="";%>Category: <SELECT name="itemid"><OPTION value="select" >Select<OPTION value="Veggie" <%= itemid.equals("Veggie")?"selected":"" %> >Veggie<OPTION value="Meat" <%= itemid.equals("Meat")?"selected":"" %> >Meat<OPTION value="Fish" <%= itemid.equals("Fish")?"selected":"" %> >Fish</SELECT><br><input type=submit> <input type=reset></form><br>

<jsp:include page="listitem.jsp" flush="true" /><br><a href="additem.html" >Add items</a><br>

List Items in Chosen Category—listitem.jspKey lines are highlighted.

<%@ taglib uri="/WEB-INF/jwcache.tld" prefix="ojsp" %><title>listitem.jsp</title><% String itemid=request.getParameter("itemid");


if (itemid==null) { out.println("Please select a category from the above drop down box."); return; }%><% long l1=(new java.util.Date()).getTime(); %><ojsp:cache autoType="URI_selectedParam" selectedParam="itemid" printCacheBlockInfo="true" printCachePolicy="true" policy="/WEB-INF/test-policy.cpd" >Item List: <b><%= itemid %></b><br>Time: <%= new java.util.Date() %><br><jsp:useBean class="java.util.Hashtable" id="table" scope="application" /><hr><% Vector list=(Vector) table.get(itemid); if (list==null) { out.println("No such item!"); } else { for (int i=0; i<list.size(); i++) {%><%= list.elementAt(i) %><br><% } }%>timestamp:<%= new java.util.Date() %><br></ojsp:cache><% long l2=(new java.util.Date()).getTime(); %>Time for general cache operation:<%= l2-l1 %><br>

Cache Policy Descriptor—test-policy.cpd


Configuration Notes for Oracle9iAS Object Caching Service for JavaTo use the default cache repository, Oracle9iAS Object Caching Service for Java, a couple of preparatory steps are required:

1. In an Apache/JServ environment, such as in the Oracle9i Application Server, update the zone.properties file to point to the Object Caching Service for Java configuration file, OCS4J.properties.

For example, for a UNIX system:

servlet.oracle.jsp.JspServlet.initArgs=ocs4j_file=jsp_demo_dir/WEB-INF/misc-file/OCS4J.properties

(The misc-file directory is created automatically when the OracleJSP demo.zip file is extracted.)

or for a Windows NT system:

servlet.oracle.jsp.JspServlet.initArgs=ocs4j_file=jsp_demo_dir\WEB-INF\misc-file\OCS4J.properties

2. Update OCS4J.properties as appropriate. To set a root directory for the Object Caching Service for Java, update the diskPath entry.

For a UNIX system, do this as follows:

distribute = truediskPath = /mydir/ocs4jdirdiscoveryAddress = :6666

or, for a Windows NT system (note that you have to specify a drive letter):

distribute = truediskPath = c:\mydir\ocs4jdirdiscoveryAddress = :6666

Web Object Cache—Using a File System CacheThis application demonstrates the use of the OracleJSP Web Object Cache tags. The underlying cache repository is a simple file system implementation.

If you run the application, you can tell that the data is being cached by checking the reporoot directory you set up. (See "Configuration Notes for File System Cache" on page 11-69.) The directory will contain the cache entries, which are files whose names start with "CN".

This application is functionally the same as "Web Object Cache—Using Oracle9iAS Object Caching Service for Java" on page 11-61, but uses a different cache repository.



(Note the differences between the two applications in the ojsp:cache tag in the listitem.jsp code, and the ojsp:invalidateCache tag in the added.jsp code.) In addition, the application using the Oracle9iAS Object Caching Service for Java specifies a cache policy descriptor (test-policy.cpd); this file system cache example does not.

The following listings are provided:

■ additem.html—HTML form to prompt you to add an item in a specified category

■ added.jsp—JSP page to add a specified new item and invalidate the cache

■ seeitems.jsp—JSP page to prompt you to choose a category whose entries you want listed (includes listitem.jsp)

■ listitem.jsp—JSP page to list the items in a chosen category and cache the results

HTML Form—additem.html<title>additem.html</title>Add your shopping item:<br><form method="post" action="added.jsp" >To add: <input type="text" name="addItem"> <br>in category: <SELECT name="itemid"><OPTION value="Veggie" >Veggie<OPTION value="Meat">Meat<OPTION value="Fish">Fish</SELECT><br><input type=submit value="Add item"> <input type=reset></form>

Add Specified Item—added.jspKey lines are highlighted.

<%@ taglib uri="/WEB-INF/jwcache.tld" prefix="ojsp" %><title>added.jsp</title><jsp:useBean class="java.util.Hashtable" id="table" scope="application" /><% String itemid=request.getParameter("itemid"); String addItem=request.getParameter("addItem"); Vector list=(Vector) table.get(itemid); if (list==null) { list=new Vector(); table.put(itemid,list); }



list.addElement(addItem);%><b><%= addItem %></b> was added into category <b><%= itemid %></b>.<br><% String viewPage="listitem.jsp?itemid="+itemid; %><% long l1=(new java.util.Date()).getTime(); %><ojsp:invalidateCache page="<%= viewPage %>" autoInvalidateLevel="param" autoType="URI_selectedParam" selectedParam="itemid" cacheRepositoryName="SimpleFSRepo" />

<% long l2=(new java.util.Date()).getTime(); %>Existing cache entry has been invalidated. <br>Invalidation took <%= l2-l1 %> milliseconds.<br><jsp:include page="<%= viewPage %>" flush="true" /><br><br><a href="seeitems.jsp">Select items</a>or<a href="additem.html">Add items</a><br>

Prompt for Category to List Items—seeitems.jspKey lines are highlighted.

<title>seeitems.jsp</title>See the list of :<br><form method="get" action="seeitems.jsp" ><% String itemid=request.getParameter("itemid"); if (itemid==null) itemid="";%>Category: <SELECT name="itemid"><OPTION value="select" >Select<OPTION value="Veggie" <%= itemid.equals("Veggie")?"selected":"" %> >Veggie<OPTION value="Meat" <%= itemid.equals("Meat")?"selected":"" %> >Meat<OPTION value="Fish" <%= itemid.equals("Fish")?"selected":"" %> >Fish</SELECT><br><input type=submit> <input type=reset></form><br>

<jsp:include page="listitem.jsp" flush="true" />



<br><a href="additem.html" >Add items</a><br>

List Items in Chosen Category—listitem.jspKey lines are highlighted.

<%@ taglib uri="/WEB-INF/jwcache.tld" prefix="ojsp" %><title>listitem.jsp</title><% String itemid=request.getParameter("itemid"); if (itemid==null) { out.println("Please select a category from the above drop down box."); return; }%><% long l1=(new java.util.Date()).getTime(); %><ojsp:cache autoType="URI_selectedParam" selectedParam="itemid" printCacheBlockInfo="true" printCachePolicy="true" cacheRepositoryName="SimpleFSRepo" >Item List: <b><%= itemid %></b><br>Time: <%= new java.util.Date() %><br><jsp:useBean class="java.util.Hashtable" id="table" scope="application" /><hr><% Vector list=(Vector) table.get(itemid); if (list==null) { out.println("No such item!"); } else { for (int i=0; i<list.size(); i++) {%><%= list.elementAt(i) %><br><% } }%>timestamp:<%= new java.util.Date() %><br></ojsp:cache><% long l2=(new java.util.Date()).getTime(); %>Time for general cache operation:<%= l2-l1 %><br>



Configuration Notes for File System CacheEdit the cache repository descriptor (wcache.xml) to set reporoot to specify a root directory for the file system cache. (This file is located in the WEB-INF directory where the OracleJSP samples are installed. See "Cache Repository Descriptor" on page 9-66 for general information and for an example of a cache repository descriptor that sets a reporoot value.)

For example, for a UNIX system:

<init-param> <param-name>reporoot</param-name> <param-value>/mydir/repositoryroot</param-value></init-param>

or for a Windows NT system:

<init-param> <param-name>reporoot</param-name> <param-value>c:\mydir\repositoryroot</param-value></init-param>

Web Object Cache—Caching XML DOM ObjectsThis sample accomplishes the following:

1. An XML DOM object is produced from database query results through the sql:dbQuery tag.

2. The DOM object is cached in the Web Object Cache through the cacheXMLObj tag.

3. The DOM object is then transformed according to an XSL stylesheet through the OracleJSP transform tag. (You can use different stylesheets for different users.)

4. The transformed results are also cached in the Web Object Cache, through the cache tag.

(See "About Caching Transformed Results" on page 11-71.)

Cache XML DOM Objects—xmldomcache.jspKey lines are highlighted.

<%@ page import="oracle.sql.*, oracle.jdbc.driver.*, oracle.jdbc.*, java.sql.*" %>


<%@ taglib uri="/WEB-INF/jml.tld" prefix="jml" %><%@ taglib uri="/WEB-INF/sqltaglib.tld" prefix="sql" %><%@ taglib uri="/WEB-INF/jwcache.tld" prefix="ojsp" %><%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %>

<% String connStr=request.getParameter("connStr"); if (connStr==null) { connStr=(String)session.getValue("connStr"); } else { session.putValue("connStr",connStr); } if (connStr==null) { %><jsp:forward page="../sql/setconn.jsp" /><% }

%>

<% String userStyleLoc="../xml/xmldom/style/rowset.xsl"; // userStyleLoc can be retrieved some user personal profile %>

<h3>Transform DBQuery Tag Example</h3><h4>Current Time=<%= new java.util.Date() %></h4><ojsp:cache TTL="60"> <h4>Cached Time=<%= new java.util.Date() %></h4><sql:dbOpen connId="conn1" URL="<%= connStr %>" user="scott" password="tiger" /><jml:transform href="<%= userStyleLoc %>" > <%-- The XML DOM object is produced by dbQuery And, the DOM object is cached in OracleJSP Web Object Cache. XSLT is performed on the cached object. --%> <ojsp:cacheXMLObj TTL="60" toWriter="false"> <sql:dbQuery connId="conn1" output="xml" queryId="myquery" > select ENAME, EMPNO from EMP </sql:dbQuery> </ojsp:cacheXMLObj></jml:transform> <sql:dbCloseQuery queryId="myquery" /><sql:dbClose connId="con1" /></ojsp:cache>


About Caching Transformed ResultsYou can further cache transformed HTML results in the Oracle Web Cache through JESI tags, or in the Web Object Cache through its cache tag as in this example. As much as possible, you should use JESI tags and the Oracle Web Cache for this purpose. This will reduce the load in the Java layer and offer greater performance benefits. This example caches final results in the Web Object Cache for illustrative purposes only.

Web Object Cache—Caching Generic Java ObjectsThis application demonstrates how to use the Web Object Cache useCacheObj tag to cache generic serializable Java objects. The cache uses the same Web-based namespace for cached Java objects as it does for any other cache objects.

In this example, cache objects are stored under the name a1 and a2 under /demo/cache/objcache/objcache.jsp?testing4=101. Each cache object can be retrieved under the same name later, as desired. Similarly, cache objects can be invalidated under the same name. Automatic (implicit) cache naming offers an intuitive Web-based naming hierarchy and convenient features such as using selected request parameters to help determine caching behavior.

The application uses serializable Java string array implementations as the generic cache object targets. The base class, StrArray, provides most of the string array functionality through protected methods. There are two classes that extend StrArray:

■ RStrArray, a read-only version that exposes only read/getter operations

■ WStrArray, a writable version that exposes write/setter operations as well as read/getter operation

Because the read-only string arrays are immutable, there is no need to clone them during cache operations. RStrArray does not implement the CloneableCacheObj interface, so the Web Object Cache does not clone RStrArray objects when they are cached.

Because the writeable string arrays are mutable, however, it is advisable for the WStrArray class to implement the CloneableCacheObj interface so that WStrArray objects are cloned when they are cached. This will provide complete hierarchical copies of the data, thereby promoting Java thread safety and protecting against unintentional object mutation.



Here is some sample output from the sample application:

a1: (writeable a1 is cloned for every cache operation)examples.WStrArray@5225a70:Thu Jun 07 14:51:31 GMT-08:00 2001 1:abc 2:101 3:Thu Jun 07 14:51:31 GMT-08:00 2001

a2: (readonly a2 is not cloned)examples.RStrArray@1f50110:Thu Jun 07 14:51:31 GMT-08:00 2001 1:def 2:101

JSP Page—objcache.jspKey lines are highlighted.

<%@ page import="examples.*" %><%@ taglib uri="/WEB-INF/jwcache.tld" prefix="ojsp" %>

<ojsp:useCacheObj id="a1" policy="/WEB-INF/test-policy.cpd" cacheScope="application" type="examples.WStrArray" ><% a1=new WStrArray(4); a1.setStr(2,request.getParameter("testing4")); a1.setStr(1,"abc"); a1.setStr(0, (new java.util.Date()).toString() ); // storing the a1 into pagecontext // so useCacheObj tag can pick it up pageContext.setAttribute("a1",a1);%> </ojsp:useCacheObj><% a1.setStr(3, (new java.util.Date()).toString() );%><pre>a1: (writeable a1 is cloned for every cache operation)<%= a1 %><%= a1.getInfo() %></pre>

<ojsp:useCacheObj id="a2" policy="/WEB-INF/test-policy.cpd" type="examples.RStrArray" ><% // create a temp writeable array WStrArray tmpa2=new WStrArray(3); tmpa2.setStr(2,request.getParameter("testing4")); tmpa2.setStr(1,"def");



tmpa2.setStr(0, (new java.util.Date()).toString() ); // create a readonly copy for the cache a2=new RStrArray(tmpa2); // storing the a2 into pagecontext // so useCacheObj tag can pick it up pageContext.setAttribute("a2",a2);%></ojsp:useCacheObj>

<pre>a2: (readonly a2 is not cloned)<%= a2 %><%= a2.getInfo() %></pre>

Base String Array Class—StrArray.javapackage examples;

import java.io.Serializable;

/** * The generic version of StrArray class<p> * There are 2 derived classes: one is RStrArray - for read-only, * WStrArray - for write operations */public class StrArray implements Serializable {

protected String a[];

/** * a simple constructor */ protected StrArray(int size) { a=new String[size]; }

/** * a copy constructor: a swallow copy constructor. * We just copy the array itself. We do not copy the elements within * the array in this case, because java.lang.String itself is immutable. */ protected StrArray(StrArray givenArray) { this.a=new String[givenArray.a.length];



System.arraycopy(givenArray.a,0,this.a,0,givenArray.a.length); }

protected void setStr(int i, String s) { a[i]=s; }

protected String getStr(int i) { return a[i]; }

public String getInfo() { StringBuffer sb=new StringBuffer(); for (int i=0; i<a.length; i++) { sb.append(i+":"+a[i]+" "); } return new String(sb); }

}

Read-Only String Array Implementation—RStrArray.javapackage examples;

/** * Readonly String Array: no need to be cloned in cache operations. * We expose the read methods only. */public class RStrArray extends StrArray{ public RStrArray(int size) { super(size); } public RStrArray(StrArray a) { super(a); }

public String getStr(int i) { return super.getStr(i); } }



Writable String Array Implementation—WStrArray.javaKey lines are highlighted.

package examples;

import oracle.jsp.jwcache.CloneableCacheObj;

/** * writeable string array - needs to be cloned in cache operation. * Hence, we implements CloneableCacheObj interface. * Both of read and write methods of this String Array class are * exposed. */public class WStrArray extends StrArray implements CloneableCacheObj {

public WStrArray(int size) { super(size); } public WStrArray(StrArray a) { super(a); }

public void setStr(int i, String s) { super.setStr(i,s); }

public String getStr(int i) { return super.getStr(i); }

public Object cloneCacheObj() { return new WStrArray(this); }

}

Web Object Cache—Tag Code Versus API CodeThis example presents code for three approaches to an application that caches and presents timestamp output from two cache fragments:

■ The first approach, tagcode.jsp, is a simple JSP page that uses the OracleJSP Web Object Cache tags.



■ The second approach, servletcode.jsp, is a more involved JSP page that uses the Web Object Cache servlet API (instead of the cache tags) inside a Java scriptlet.

■ The third approach, DemoCacheServlet.java, uses the Web Object Cache servlet API inside a standard servlet page.

Following the three code samples is a listing of the cache policy descriptor, test-policy.cpd.

In each approach, the application will cache the two fragments it displays. You can reload repeatedly, but the times displayed in the fragments will not change until the cached fragments expire. The first fragment takes 25 seconds to expire, getting the 25-second time-to-live value from the TTL setting in the cache policy descriptor (test-policy.cpd). The second fragment takes 15 seconds to expire, overriding the cache policy descriptor time-to-live value with a value set directly in the page code.

Output for the sample applications looks something like the following:

fragment#1 (expires in 25 seconds as per TTL value test-policy)Sun May 27 15:20:46 PDT 2001

fragment#2 (expires in 15 seconds because TTL overrides test-policy value)Sun May 27 15:20:46 PDT 2001

Simple JSP Page—tagcode.jsp<%@ taglib uri="/WEB-INF/jwcache.tld" prefix="ojsp" %><title>tagcode.jsp</title><pre>tagcode.jsp<ojsp:cache policy="/WEB-INF/test-policy.cpd" > fragment#1 (expires in 25 seconds as per TTL value test-policy) <%= new java.util.Date() %></ojsp:cache><ojsp:cache policy="/WEB-INF/test-policy.cpd" TTL="15" > fragment#2 (expires in 15 seconds because TTL overrides test-policy value) <%= new java.util.Date() %></ojsp:cache></pre>



Scriptlet JSP Page—servletcode.jspCode notes are the same as for the servlet version below, which is repeated and described in "Sample Servlet Using the Web Object Cache API" on page 9-59.

<%@ page import="oracle.jsp.jwcache.*,java.io.*" %><title>servletcode.jsp</title><pre>servletcode.jsp<% CachePolicy cachePolicyObj = CacheClientUtil.lookupPolicy(config,request, "/WEB-INF/test-policy.cpd" ); // Note A StringSectionId sectionId=new StringSectionId("s1"); CacheBlock cacheBlockObj=null; cacheBlockObj = cachePolicyObj.getCache(request,sectionId); // Note B if (!cachePolicyObj.isRecent(cacheBlockObj)) { // Note C CharArrayWriter newOut=new CharArrayWriter(); PrintWriter pw=new PrintWriter(newOut);

// actual logic within a cache block pw.println("fragment#1 (expires in 25 seconds as per TTL value test-policy)"); pw.println(new java.util.Date()); // which generates content into the "out" object

if (cacheBlockObj == null) { // Note E cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId); // Note F } out.write(newOut.toCharArray()); // writing out newly created data back to the original writer } else { out.write((char[])cacheBlockObj.getData()); // writing the existing cached data to the writer }

sectionId=new StringSectionId("s2"); long timeToLive = 15; // now set TTL to 15 on this block ExpirationPolicy expirationPolicy = cachePolicyObj.getExpirationPolicy(); expirationPolicy.setTTL(timeToLive); cachePolicyObj.setExpirationPolicy(expirationPolicy); cacheBlockObj = cachePolicyObj.getCache(request,sectionId); // Note B if (!cachePolicyObj.isRecent(cacheBlockObj)) { // Note C



CharArrayWriter newOut=new CharArrayWriter(); PrintWriter pw=new PrintWriter(newOut);

// actual logic within a cache block pw.println("fragment#2 (expires in 15 seconds because TTL overrides test-policy value)"); pw.println(new java.util.Date()); // which generates content into the "out" object

if (cacheBlockObj == null) { // Note E cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId); // Note F } out.write(newOut.toCharArray()); // writing out newly created data back to the original writer } else { out.write((char[])cacheBlockObj.getData()); // writing the existing cached data to the writer }

%></pre>

Servlet Page—DemoCacheServlet.javaThis sample also appears in "Sample Servlet Using the Web Object Cache API" on page 9-59. Refer there for information about the code notes.

package demoPkg;

import javax.servlet.*;import javax.servlet.http.*;import java.io.IOException;

import java.io.PrintWriter;import java.io.CharArrayWriter;

import oracle.jsp.jwcache.CachePolicy;import oracle.jsp.jwcache.ExpirationPolicy;import oracle.jsp.jwcache.StringSectionId;import oracle.jsp.jwcache.CacheBlock;import oracle.jsp.jwcache.CacheClientUtil;



public class DemoCacheServlet extends HttpServlet{

public void service(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // standard writer object from servlet engine PrintWriter out=response.getWriter(); ServletConfig config=getServletConfig();

try { CachePolicy cachePolicyObj = CacheClientUtil.lookupPolicy(config,request, "/WEB-INF/test-policy.cpd" ); // Note A StringSectionId sectionId=new StringSectionId("s1"); CacheBlock cacheBlockObj=null;

cacheBlockObj = cachePolicyObj.getCache(request,sectionId); // Note B if (!cachePolicyObj.isRecent(cacheBlockObj)) { // Note C CharArrayWriter newOut=new CharArrayWriter(); PrintWriter pw=new PrintWriter(newOut); // actual logic within a cache block pw.println("fragment#1"); pw.println(new java.util.Date()); // which generates content into the "out" object if (cacheBlockObj == null) { // Note E cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId); // Note F } out.write(newOut.toCharArray()); // writing out newly created data back to the original writer } else { out.write((char[])cacheBlockObj.getData()); // writing the existing cached data to the writer }

sectionId=new StringSectionId("s2"); long timeToLive = 15; // now set TTL to 15 on this block ExpirationPolicy expirationPolicy = cachePolicyObj.getExpirationPolicy(); expirationPolicy.setTTL(timeToLive); cachePolicyObj.setExpirationPolicy(expirationPolicy); cacheBlockObj = cachePolicyObj.getCache(request,sectionId); // Note B



if (!cachePolicyObj.isRecent(cacheBlockObj)) { // Note C CharArrayWriter newOut=new CharArrayWriter(); PrintWriter pw=new PrintWriter(newOut); // actual logic within a cache block pw.println("fragment#2"); pw.println(new java.util.Date()); // which generates content into the "out" object if (cacheBlockObj == null) { // Note E cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId); // Note F } out.write(newOut.toCharArray()); // writing out newly created data back to the original writer } else { out.write((char[])cacheBlockObj.getData()); // writing the existing cached data to the writer }

} catch (Throwable th) { // your exception handling code here th.printStackTrace(out); } }}

Cache Policy Descriptor—test-policy.cpdThis cache policy descriptor is used by all three approaches to the sample application—tagcode.jsp, servletcode.jsp, and DemoCacheServlet.java:




Samples Using globals.jsa for Servlet 2.0 Environments

Samples Using globals.jsa for Servlet 2.0 EnvironmentsThis section has examples of how the Oracle globals.jsa mechanism can be used in servlet 2.0 environments to provide an application framework and application-based and session-based event handling. The following examples are provided:

■ globals.jsa Example for Application Events—lotto.jsp

■ globals.jsa Example for Application and Session Events—index1.jsp

■ globals.jsa Example for Global Declarations—index2.jsp

For information about globals.jsa usage, see "OracleJSP Application and Session Support for Servlet 2.0" on page 5-38.

globals.jsa Example for Application Events—lotto.jspThis sample illustrates OracleJSP globals.jsa event handling through the application_OnStart and application_OnEnd event handlers. In this sample, numbers are cached on a per-user basis for the duration of the day. As a result, only one set of numbers is ever presented to a user for a given lottery drawing. In this sample, a user is identified by their IP address.

Code has been written for application_OnStart and application_OnEnd to make the cache persistent across application shutdowns. The sample writes the cached data to a file as it is being terminated and reads from the file as it is being restarted (presuming the server is restarted the same day that the cache was written).

Note: The examples in this section base some of their functionality on application shutdown. Many servers do not allow an application to be shut down manually. In this case, globals.jsa cannot function as an application marker. However, you can cause the application to be automatically shut down and restarted (presuming developer_mode=true) by updating either the lotto.jsp source or the globals.jsa file. (The OracleJSP container always terminates a running application before retranslating and reloading an active page.)



globals.jsa File for lotto.jsp<%@ page import="java.util.*, oracle.jsp.jml.*" %>

<jsp:useBean id = "cachedNumbers" class = "java.util.Hashtable" scope = "application" />


<% Calendar today = Calendar.getInstance(); application.setAttribute("today", today); try { FileInputStream fis = new FileInputStream (application.getRealPath("/")+File.separator+"lotto.che"); ObjectInputStream ois = new ObjectInputStream(fis); Calendar cacheDay = (Calendar) ois.readObject(); if (cacheDay.get(Calendar.DAY_OF_YEAR) == today.get(Calendar.DAY_OF_YEAR)) { cachedNumbers = (Hashtable) ois.readObject(); application.setAttribute("cachedNumbers", cachedNumbers); } ois.close(); } catch (Exception theE) { // catch all -- can’t use persistent data }%>



<% Calendar now = Calendar.getInstance(); Calendar today = (Calendar) application.getAttribute("today"); if (cachedNumbers.isEmpty() || now.get(Calendar.DAY_OF_YEAR) > today.get(Calendar.DAY_OF_YEAR)) { File f = new File(application.getRealPath("/")+File.separator+"lotto.che"); if (f.exists()) f.delete(); return; }

try { FileOutputStream fos = new FileOutputStream (application.getRealPath("/")+File.separator+"lotto.che"); ObjectOutputStream oos = new ObjectOutputStream(fos); oos.writeObject(today); oos.writeObject(cachedNumbers);


oos.close(); } catch (Exception theE) { // catch all -- can’t use persistent data }%>


lotto.jsp Source<%@ page session = "false" %><jsp:useBean id = "picker" class = "oracle.jsp.sample.lottery.LottoPicker" scope = "page" />

<HTML><HEAD><TITLE>Lotto Number Generator</TITLE></HEAD><BODY BACKGROUND="images/cream.jpg" BGCOLOR="#FFFFFF"><H1 ALIGN="CENTER"></H1>

<BR>

<H1 ALIGN="CENTER">Your Specially Picked</H1><P ALIGN="CENTER"><IMG SRC="images/winningnumbers.gif" WIDTH="450" HEIGHT="69" ALIGN="BOTTOM" BORDER="0"></P><P>

<P ALIGN="CENTER"><TABLE ALIGN="CENTER" BORDER="0" CELLPADDING="0" CELLSPACING="0"><TR><% int[] picks; String identity = request.getRemoteAddr();

// Make sure its not tomorrow Calendar now = Calendar.getInstance(); Calendar today = (Calendar) application.getAttribute("today"); if (now.get(Calendar.DAY_OF_YEAR) > today.get(Calendar.DAY_OF_YEAR)) { System.out.println("New day...."); cachedNumbers.clear(); today = now; application.setAttribute("today", today); }

synchronized (cachedNumbers) {


if ((picks = (int []) cachedNumbers.get(identity)) == null) { picks = picker.getPicks(); cachedNumbers.put(identity, picks); } } for (int i = 0; i < picks.length; i++) { %> <TD> <IMG SRC="images/ball<%= picks[i] %>.gif" WIDTH="68" HEIGHT="76" ALIGN="BOTTOM" BORDER="0"> </TD>

<% }%></TR></TABLE>

</P>

<P ALIGN="CENTER"><BR><BR><IMG SRC="images/playrespon.gif" WIDTH="120" HEIGHT="73" ALIGN="BOTTOM" BORDER="0">

</BODY></HTML>

globals.jsa Example for Application and Session Events—index1.jspThis example uses a globals.jsa file to process applications and session lifecycle events. It counts the number of active sessions, the total number of sessions, and the total number of times the application page has been hit. Each of these values is maintained at the application scope. The application page (index1.jsp) updates the page hit count on each request. The globals.jsa session_OnStart event handler increments the number of active sessions and the total number of sessions. The globals.jsa session_OnEnd handler decrements the number of active sessions by one.

The page output is simple. When a new session starts, the session counters are output. The page counter is output on every request. The final tally of each value is output in the globals.jsa application_OnEnd event handler.



Note the following in this example:

■ When the counter variables are updated, access must be synchronized, as these values are maintained at application scope.

■ The count values use the OracleJSP oracle.jsp.jml.JmlNumber extended datatype, which simplifies the use of data values at application scope. (For information about the JML extended datatypes, see "JML Extended Datatypes" on page 5-2.)

globals.jsa File for index1.jsp<%@ taglib uri="oracle.jsp.parse.OpenJspRegisterLib" prefix="jml" %>



<%-- Consider storing pageCount persistently -- If you do read it here --%>


<event:application_OnEnd> <%-- Acquire beans --%> <jsp:useBean id="pageCount" class="oracle.jsp.jml.JmlNumber" scope = "application" /> <jsp:useBean id="sessionCount" class="oracle.jsp.jml.JmlNumber" scope = "application" />

<% application.log("The number of page hits were: " + pageCount.getValue() ); %> <% application.log("The number of client sessions were: " + sessionCount.getValue() ); %>

<%-- Consider storing pageCount persistently -- If you do write it here --%>



<%-- Acquire beans --%> <jsp:useBean id="sessionCount" class="oracle.jsp.jml.JmlNumber" scope = "application" /> <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" />

<% synchronized (sessionCount) {



sessionCount.setValue(sessionCount.getValue() + 1); %> <br> Starting session #: <%= sessionCount.getValue() %> <br> <% } %> <% synchronized (activeSessions) { activeSessions.setValue(activeSessions.getValue() + 1); %> There are currently <b> <%= activeSessions.getValue() %> </b> active sessions <p> <% } %>



<%-- Acquire beans --%> <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" />

<% synchronized (activeSessions) { activeSessions.setValue(activeSessions.getValue() - 1); } %>


index1.jsp Source<%-- Acquire beans --%><jsp:useBean id="pageCount" class="oracle.jsp.jml.JmlNumber" scope = "application" />

<% synchronized(pageCount) { pageCount.setValue(pageCount.getValue() + 1); }%>

This page has been accessed <b> <%= pageCount.getValue() %> </b> times.<p>



globals.jsa Example for Global Declarations—index2.jspThis example uses a globals.jsa file to declare variables globally. It is based on the event handler sample in "globals.jsa Example for Application and Session Events—index1.jsp" on page 11-84, but differs in that the three application counter variables are declared globally. (In the original event-handler sample, by contrast, each event handler and the JSP page itself had to provide jsp:useBean statements to locally declare the beans they were accessing.)

Declaring the beans globally results in implicit declaration in all event handlers and the JSP page.

globals.jsa File for index2.jsp<%-- globally declares variables and initializes them to zero --%>

<jsp:useBean id="pageCount" class="oracle.jsp.jml.JmlNumber" scope = "application" /><jsp:useBean id="sessionCount" class="oracle.jsp.jml.JmlNumber" scope = "application" /><jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" />


<%-- Consider storing pageCount persistently -- If you do read it here --%>



<% application.log("The number of page hits were: " + pageCount.getValue() ); %> <% application.log("The number of client sessions were: " + sessionCount.getValue() ); %>

<%-- Consider storing pageCount persistently -- If you do write it here --%>



<% synchronized (sessionCount) { sessionCount.setValue(sessionCount.getValue() + 1); %>

<br> Starting session #: <%= sessionCount.getValue() %> <br>



<% } %>

<% synchronized (activeSessions) { activeSessions.setValue(activeSessions.getValue() + 1); %> There are currently <b> <%= activeSessions.getValue() %> </b> active sessions <p> <% } %>



<% synchronized (activeSessions) { activeSessions.setValue(activeSessions.getValue() - 1); } %>


index2.jsp Source<%-- pageCount declared in globals.jsa so active in all pages --%>

<% synchronized(pageCount) { pageCount.setValue(pageCount.getValue() + 1); }%>

This page has been accessed <b> <%= pageCount.getValue() %> </b> times.

<p>


General Installation and Configu

A
General Installation and Configuration
This appendix provides general information about installing OracleJSP, configuring the Web server to run OracleJSP, and configuring OracleJSP. The technical information focuses on common Web servers and servlet environments:

■ Apache/JServ

■ JSWDK (the Sun Microsystems JavaServer Web Developer’s Kit)

■ Tomcat (from Apache, in cooperation with Sun Microsystems)

For Oracle environments that support OracleJSP, reference is made to documentation for those products for installation and configuration instructions.

For the Oracle9i Servlet Engine, translation-time configuration is handled through options of the OracleJSP pre-translation utility, as described in "The ojspc Pre-Translation Tool" on page 6-26.

This appendix includes the following topics:

■ System Requirements

■ OracleJSP Installation and Web Server Configuration

■ OracleJSP Configuration

ration A-1

System Requirements

System RequirementsOracleJSP is a pure Java environment. The system on which you install it must meet the following minimum requirements.

operating system: any OS that supports JDK 1.1.x or higher

Java version: JDK 1.1.x or 1.2.x (or higher)(Oracle recommends the most current version available for your platform, preferably JDK 1.1.8 or higher.)

Java compiler: the standard javac provided with your JDK(You can, however, use alternative compilers instead.)

Web server: any Web server that supports servlets

servlet environment: any servlet container implementing the servlet 2.0 specification or higher

Note: The servlet library for your servlet environment must be installed on your system and included in the classpath in your Web server configuration file. This library contains the standard javax.servlet.* packages.

For example, in an Apache/JServ environment (including the Oracle9i Application Server), you will need jsdk.jar, which is provided with the Sun Microsystems JSDK 2.0. In a Sun Microsystems JSWDK environment, you will need servlet.jar (servlet 2.1 version), which is provided with JSWDK 1.0. In a Tomcat environment, you will need servlet.jar (servlet 2.2 version), which is provided with Tomcat 3.1. Do not confuse JSDK (Java Servlet Developer’s Kit) with JSWDK (JavaServer Web Developer’s Kit).

See "Configuration of Web Server and Servlet Environment to Run OracleJSP" on page A-7 for further discussion of classpath settings in a Web server configuration file.

A-2 OracleJSP Support for JavaServer Pages Developer’s Guide and Reference

OracleJSP Installation and Web Server Configuration

OracleJSP Installation and Web Server ConfigurationThis section discusses OracleJSP installation and related Web server configuration for various JSP environments. The following environments are considered:

■ Apache/JServ

■ Sun Microsystems JSWDK

■ Tomcat

■ Oracle9i Servlet Engine (OSE)

■ other Oracle environments

This discussion assumes that your target system, which might be either a development environment or a deployment environment, meets the requirements specified in "System Requirements" on page A-2. It also assumes that you have verified you can do the following:

■ run Java

■ run a Java compiler (typically the standard javac)

■ run an HTTP servlet

Required and Optional Files for OracleJSPThis section summarizes JAR and ZIP files required for OracleJSP, as well as optional JAR and ZIP files to use Oracle JDBC and SQLJ functionality, JML or SQL custom tags, or custom data-access JavaBeans. The summary of files is followed by a discussion of how to install OracleJSP files on non-Oracle environments, and a list of Oracle environments that already provide OracleJSP.

Required files must also be added to your classpath. (See "Add OracleJSP-Related JAR and ZIP Files to Web Server Classpath" on page A-8.)

Note:

■ Examples here are for a UNIX environment, but the basic information (such as directory names and file names) applies to other environments as well.

■ Web server configuration information focuses on prevalent non-Oracle environments. For Oracle environments, refer to documentation for the particular product (such as the Oracle9i Application Server or Web-to-go).

General Installation and Configuration A-3


Summary of Files

The following files are provided with OracleJSP and must be installed on your system:

■ ojsp.jar (OracleJSP)

■ xmlparserv2.jar (for XML parsing—required for the web.xml deployment descriptor and any tag library descriptors)

■ servlet.jar (standard servlet library, servlet 2.2 version)

In addition, if your JSP pages will use Oracle JSP Markup Language (JML) tags, SQL tags, or data-access JavaBeans, you will need the following files:

■ ojsputil.jar

■ xsu12.jar, for JDK 1.2.x, or xsu111.jar, for JDK 1.1.x (in OSE, or for XML functionality on the client)

To run in the Oracle9i Servlet Engine, xsu12.jar or xsu111.jar must be installed prior to or simultaneously with ojsputil.jar. (This should be handled automatically in a normal Oracle9i installation.) To run in a client environment, however, xsu12.jar or xsu111.jar is required only if you will use XML functionality in the data-access JavaBeans (such as getting a result set as an XML string). The xsu12.jar and xsu111.jar files are included with Oracle9i.

For Oracle data access, you will also need the following:

■ Oracle JDBC class files (for any Oracle data access)

■ Oracle SQLJ class files (if using SQLJ code in your JSP pages)

See "Files for JDBC (optional)" on page A-5 and "Files for SQLJ (optional)" on page A-5 for more information.

To use JDBC data sources or Enterprise JavaBeans, you will need the following:

■ jndi.jar

(This file is required for some of the OracleJSP demos.)

Servlet Library Notes Note that OracleJSP 1.1.x releases require and supply the 2.2 version of the servlet library, which is where the standard javax.servlet.*

Note: Refer to the Oracle9i Java Developer’s Guide for the locations of these files on the Oracle9i product CD.



packages are located. Your Web server environment likely requires and supplies a different servlet library version. You must be careful in your classpath to have the version for your Web server precede the version for OracleJSP. "Add OracleJSP-Related JAR and ZIP Files to Web Server Classpath" on page A-8 further discusses this.

Table A–1 summarizes the servlet library versions. Do not confuse the Sun Microsystems JSWDK (JavaServer Web Developer’s Kit) with the Sun Microsystems JSDK (Java Servlet Developer’s Kit).

(For Apache/JServ, download jsdk.jar separately.)

Files for JDBC (optional) The following files are required if you will use Oracle JDBC for data access. (Be aware that Oracle SQLJ uses Oracle JDBC.)

■ classes12.zip or .jar (for JDK 1.2.x environments)

or:

■ classes111.zip or .jar (for JDK 1.1.x environments)

Files for SQLJ (optional) The following files are necessary if your JSP pages use Oracle SQLJ for their data access:

■ translator.zip or .jar (for the SQLJ translator, for JDK 1.2.x or 1.1.x)

as well as the appropriate SQLJ runtime:

■ runtime12.zip or .jar (for JDK 1.2.x with Oracle9i JDBC)

or:

■ runtime12ee.zip or .jar (for JDK 1.2.x enterprise edition with Oracle9i JDBC)

or:

■ runtime11.zip or .jar (for JDK 1.1.x with Oracle9i JDBC)

Table A–1 Servlet Library Versions

Servlet Library Version Library File Name Provided with:

servlet 2.2 servlet.jar OracleJSP, Tomcat 3.1

servlet 2.1 servlet.jar Sun JSWDK 1.0

servlet 2.0 jsdk.jar Sun JSDK 2.0; also used with Apache/JServ



or:

■ runtime.zip or .jar (more general—for JDK 1.2.x or 1.1.x with any Oracle JDBC version)

or:

■ runtime-nonoracle.zip or .jar (generic—for use with non-Oracle JDBC drivers and any JDK environment)

(The JDK 1.2.x enterprise edition allows datasource support, in compliance with the SQLJ ISO specification.)

File Installation for Non-Oracle EnvironmentsTo run OracleJSP in a non-Oracle environment—typically Apache/JServ, the Sun Microsystems JSWDK, or Tomcat—download the OracleJSP files from the Oracle Technology Network (OTN) at the following URL:

http://technet.oracle.com/tech/java/servlets/index.htm

Click on "Software" in the button bar near the top of this page.

You will need an OTN account, but membership is free of charge. Click on "Membership" in the bar at the top of the page if you do not already have an account.

For the OTN download, OracleJSP files are contained within ojsp.zip, which includes files mentioned in this section, configuration files discussed later in this appendix, release notes, documentation files, and sample applications.

Installation and configuration instructions are included in ojsp.zip—see install.htm for top-level information and links. However, you can use this appendix for detailed information about configuring the predominant non-Oracle Web server environments—Apache/JServ, the Sun Microsystems JSWDK, and Tomcat—to use OracleJSP.

You can choose any desired root directory for OracleJSP, as long as the location you choose is reflected in your Web server classpath settings (discussed in "Add OracleJSP-Related JAR and ZIP Files to Web Server Classpath" on page A-8).

Oracle JDBC and SQLJ files are also available from OTN separately at the following URL:

http://technet.oracle.com/tech/java/sqlj_jdbc/index.htm

Click on "Software" in the button bar near the top of this page.



(Alternatively, if you have an appropriate Oracle product CD such as for the Oracle9i database, Oracle9i Application Server, Oracle Web-to-go, or Oracle JDeveloper, you can get OracleJSP files from that CD and place them as desired.)

Oracle Environments Providing OracleJSPThe following Oracle environments provide OracleJSP and a Web server or Web listener, starting with the release numbers noted:

■ Oracle9i Servlet Engine (OSE), release 8.1.7 and beyond

■ Oracle9i Application Server (or Oracle Internet Application Server), release 1.0.0 and beyond

■ Oracle Application Server (previous product, pre-dating the Oracle Internet Application Server), release 4.0.8.2 and beyond

■ Oracle Web-to-go, release 1.3 and beyond (can be used with Oracle9i Lite)

■ Oracle JDeveloper, release 3.0 and beyond

In any of these environments, OracleJSP components are included with the product installation.

If you are targeting OSE you will need a client-side development and testing environment—probably Oracle JDeveloper or perhaps a non-Oracle development tool. When you have completed preliminary testing in your development environment, you can deploy JSP pages to Oracle9i, as described in Chapter 6, "JSP Translation and Deployment".

Configuration of Web Server and Servlet Environment to Run OracleJSPConfiguring your Web server to run OracleJSP pages requires the following general steps:

1. Add OracleJSP-related JAR and ZIP files to the Web server classpath.

2. Configure the Web server to map JSP file name extensions (.jsp and .JSP and, optionally, .sqljsp and .SQLJSP) to the Oracle JspServlet, which is the front-end of the OracleJSP container.

Notes: The Oracle9i Application Server uses an Apache/JServ environment, but you should use application server installation and configuration instructions instead of the Apache/JServ instructions in this appendix.



These steps apply to any Web server environment, but the information in this section focuses on the most prevalent non-Oracle environments— Apache/JServ, the Sun Microsystems JSWDK, and Tomcat.

The Oracle9i Servlet Engine, provided with Oracle9i, is automatically configured upon installation to run OracleJSP, other than the steps documented in "Additional Steps to Run Servlets and JSP Pages in OSE" on page A-14. For other Oracle environments, refer to the documentation for those products, because procedures vary. (Much of the installation and configuration may be automatic.)

Add OracleJSP-Related JAR and ZIP Files to Web Server ClasspathYou must update the Web server classpath to add JAR and ZIP files that are required by OracleJSP, being careful to add them in the proper order. (In particular, you must be careful as to where you place the servlet 2.2 version of servlet.jar in the classpath, as described below.) This includes the following:

■ ojsp.jar

■ xmlparserv2.jar

■ servlet.jar (servlet 2.2 version)

(Note that the servlet.jar supplied with OracleJSP is identical to the servlet.jar provided with Tomcat 3.1.)

■ ojsputil.jar (optional, for JML tags, SQL tags, and data-access JavaBeans)

■ xsu12.jar, for JDK 1.2.x, or xsu111.jar, for JDK 1.1.x (optional, for JML tags, SQL tags, and data-access JavaBeans)

■ additional optional ZIP and JAR files, as necessary, for JDBC and SQLJ

See "Summary of Files" on page A-4 for additional information.

Apache/JServ Environment In an Apache/JServ environment, add appropriate wrapper.classpath commands to the jserv.properties file in the JServ conf directory. Note that jsdk.jar should already be in the classpath. This file is

Important: You must also ensure that OracleJSP can find javac (or an alternative Java compiler, according to your javaccmd configuration parameter setting). For javac in a JDK 1.1.x environment, the JDK classes.zip file must be in the Web server classpath. For javac in a JDK 1.2.x environment, the JDK tools.jar file must be in the Web server classpath.



from the Sun Microsystems JSDK 2.0 and provides servlet 2.0 versions of the javax.servlet.* packages that are required by Apache/JServ. Additionally, files for your JDK environment should already be in the classpath.

The following example (which happens to use UNIX directory paths) includes files for OracleJSP, JDBC, and SQLJ. Replace [Oracle_Home] with your Oracle Home path.

# servlet 2.0 APIs (required by Apache/JServ, from Sun JSDK 2.0):wrapper.classpath=jsdk2.0/lib/jsdk.jar## servlet 2.2 APIs (required and provided by OracleJSP):wrapper.classpath=[Oracle_Home]/ojsp/lib/servlet.jar# OracleJSP packages:wrapper.classpath=[Oracle_Home]/ojsp/lib/ojsp.jarwrapper.classpath=[Oracle_Home]/ojsp/lib/ojsputil.jar# XML parser (used for servlet 2.2 web deployment descriptor):wrapper.classpath=[Oracle_Home]/ojsp/lib/xmlparserv2.jar# JDBC libraries for Oracle database access (JDK 1.2.x environment):wrapper.classpath=[Oracle_Home]/ojsp/lib/classes12.zip# SQLJ translator (optional):wrapper.classpath=[Oracle_Home]/ojsp/lib/translator.zip# SQLJ runtime (optional) (for JDK 1.2.x enterprise edition):wrapper.classpath=[Oracle_Home]/ojsp/lib/runtime12.zip

Now consider an example where you have the following useBean command:

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

You can add the following wrapper.classpath command to the jserv.properties file. (This example happens to be for a Windows NT environment.)

wrapper.classpath=D:\Apache\Apache1.3.9\beans\

And then JDBCQueryBean.class should be located as follows:

D:\Apache\Apache1.3.9\beans\mybeans\JDBCQueryBean.class

Important: In an Apache/JServ environment, jsdk.jar must precede servlet.jar in the classpath.



JSWDK Environment Update the startserver script in the jswdk-1.0 root directory to add OracleJSP files to the jspJars environment variable. Append them to the last .jar file listed, using the appropriate directory syntax and separator character for your operating system, such as a colon (":") for UNIX or a semi-colon (";") for Windows NT. Here is an example:

jspJars=./lib/jspengine.jar:./lib/ojsp.jar:./lib/ojsputil.jar

This example (with UNIX syntax) assumes that the JAR files are in the lib subdirectory under the jswdk-1.0 root directory.

Similarly, update the startserver script to specify any additional required files in the miscJars environment variable, such as in the following example:

miscJars=./lib/xml.jar:./lib/xmlparserv2.jar:./lib/servlet.jar

This example (with UNIX syntax) also assumes that the files are in the lib subdirectory under the jswdk-1.0 root directory.

Tomcat Environment For Tomcat, the procedure for adding files to the classpath is more operating-system dependent than for the other servlet environments discussed here.

For a UNIX operating system, copy the OracleJSP JAR and ZIP files to your [TOMCAT_HOME]/lib directory. This directory is automatically included in the Tomcat classpath.

For a Windows NT operating system, update the tomcat.bat file in the [TOMCAT_HOME]\bin directory to individually add each OracleJSP file to the CLASSPATH environment variable. The following example presumes that you have copied the files to the [TOMCAT_HOME]\lib directory:

set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\ojsp.jar;%TOMCAT_HOME%\lib\ojsputil.jar

Important: In a JSWDK environment, the servlet 2.1 version of servlet.jar (provided with Sun JSWDK 1.0) must precede the servlet 2.2 version of servlet.jar (provided with OracleJSP) in your classpath.

The servlet 2.1 version is typically in the jsdkJars environment variable. The overall classpath is formed through a combination of various xxxJars environment variables, including jsdkJars, jspJars, and miscJars. Examine the startserver script to verify that miscJars is added to the classpath after jsdkJars.



The servlet 2.2 version of servlet.jar (the same version that is provided with OracleJSP) is already included with Tomcat, so it needs no consideration.

Map JSP File Name Extensions to Oracle JspServletYou must configure the Web server to be able to do the following:

■ recognize appropriate file name extensions as JSP pages

Map .jsp and .JSP. Also map .sqljsp and .SQLJSP if your JSP pages use Oracle SQLJ.

■ find and execute the servlet that begins processing JSP pages

In OracleJSP, this is oracle.jsp.JspServlet, which you can think of as the front-end of the Oracle JSP container.

Apache/JServ Environment In an Apache/JServ environment, mapping each JSP file name extension to the Oracle JspServlet requires just a single step. In the JServ conf directory, update the configuration file—jserv.conf or mod_jserv.conf—to add ApJServAction commands to perform the mappings.

(In older versions, you must instead update the httpd.conf file in the Apache conf directory. In newer versions, the jserv.conf or mod_jserv.conf file is "included" into httpd.conf during execution—look at the httpd.conf file to see which one it includes.)

Following is an example (which happens to use UNIX syntax):

# Map file name extensions (.sqljsp and .SQLJSP are optional).ApJServAction .jsp /servlets/oracle.jsp.JspServletApJServAction .JSP /servlets/oracle.jsp.JspServletApJServAction .sqljsp /servlets/oracle.jsp.JspServletApJServAction .SQLJSP /servlets/oracle.jsp.JspServlet

Important: With the above configurations, OracleJSP will support page references that use either a .jsp file name extension or a .JSP file name extension, but the case in the reference must match the actual file name in a case-sensitive environment. If the file name is file.jsp, you can reference it that way, but not as file.JSP. If the file name is file.JSP, you can reference it that way, but not as file.jsp. (The same holds true for .sqljsp versus .SQLJSP.)



The path you use in this command for oracle.jsp.JspServlet is not a literal directory path in the file system. The path to specify depends on your Apache/JServ servlet configuration—how the servlet zone is mounted, the name of the zone properties file, and the file system directory that is specified as the repository for the servlet. ("Servlet zone" is an Apache/JServ term that is similar conceptually to "servlet context".) Consult your Apache/JServ documentation for more information.

JSWDK Environment In a JSWDK environment, mapping each JSP file name extension to the Oracle JspServlet requires two steps.

The first step is to update the mappings.properties file in the WEB-INF directory of each servlet context to define JSP file name extensions. Do this with the following commands:

# Map JSP file name extensions (.sqljsp and .SQLJSP are optional)..jsp=jsp.JSP=jsp.sqljsp=jsp.SQLJSP=jsp

The second step is to update the servlet.properties file in the WEB-INF directory of each servlet context to define the Oracle JspServlet as the servlet that begins JSP processing. In addition, be sure to comment out the previously defined mapping for the JSP reference implementation. Do this as follows:

#jsp.code=com.sun.jsp.runtime.JspServlet (replacing this with Oracle)jsp.code=oracle.jsp.JspServlet

Tomcat Environment In a Tomcat environment, mapping each JSP file name extension to the Oracle JspServlet requires a single step. Update the servlet mapping section of the web.xml file as shown below.

Note: There is a global web.xml file in the [TOMCAT_HOME]/conf directory. To override any settings in this file for a particular application, update the web.xml file in the WEB-INF directory under the particular application root.



# Map file name extensions (.sqljsp and .SQLJSP are optional).

<servlet-mapping> <servlet-name> oracle.jsp.JspServlet </servlet-name> <url-pattern> *.jsp </url-pattern></servlet-mapping>

<servlet-mapping> <servlet-name> oracle.jsp.JspServlet </servlet-name> <url-pattern> *.JSP </url-pattern></servlet-mapping>

<servlet-mapping> <servlet-name> oracle.jsp.JspServlet </servlet-name> <url-pattern> *.sqljsp </url-pattern></servlet-mapping>

<servlet-mapping> <servlet-name> oracle.jsp.JspServlet </servlet-name> <url-pattern> *.SQLJSP </url-pattern></servlet-mapping>

You can optionally set an alias for the oracle.jsp.JspServlet class name, as follows:

<servlet> <servlet-name> ojsp </servlet-name>



<servlet-class> oracle.jsp.JspServlet </servlet-class> ...</servlet>

Setting this alias allows you to use "ojsp" instead of the class name for your other settings, as follows:

<servlet-mapping> <servlet-name> ojsp </servlet-name> <url-pattern> *.jsp </url-pattern></servlet-mapping>

Additional Steps to Run Servlets and JSP Pages in OSEBy default, database users are locked when you install the Oracle database. The following special users must be unlocked by the database administrator before you can run servlet, JSP, or EJB applications in the Oracle9i Servlet Engine:

■ AURORA$JIS$UTILITY$

■ OSE$HTTP$ADMIN

■ AURORA$ORB$UNAUTHENTICATED

The ALTER USER command is used for this purpose, as in the following example:

alter user ose$http$admin account unlock;


OracleJSP Configuration

OracleJSP ConfigurationThe OracleJSP front-end servlet, JspServlet, supports a number of configuration parameters to control OracleJSP operation. They are set as servlet initialization parameters for JspServlet. How you accomplish this depends on the Web server and servlet environment you are using.

This section describes the OracleJSP configuration parameters and how to set them in the most prevalent Web server and servlet environments.

Only a limited number of these parameters are of interest in the Oracle products that supply OracleJSP, and how to set them may vary from product to product. Consult the product documentation for more information.

Configuration settings that apply to the Oracle9i Servlet Engine are typically supported as equivalent options in the OracleJSP pre-translation tool (ojspc). OSE does not employ the Oracle JspServlet in translating or running JSP pages.

OracleJSP Configuration Parameters (Non-OSE)This section describes the configuration parameters supported by the Oracle JspServlet for environments such as Apache/JServ, the Sun Microsystems JSWDK, or Tomcat. (Note that the Oracle9i Application Server uses an Apache/JServ environment.)

For the Oracle9i Servlet Engine environment, some of the equivalent configuration functionality is supported through equivalent ojspc options.

Configuration Parameters Summary TableTable A–2 summarizes the configuration parameters supported by Oracle JspServlet (the front-end of the OracleJSP container). For each parameter, the table notes the following:

■ whether it is used during page translation or page execution

■ whether it is typically of interest in a development environment, deployment environment, or both

■ any equivalent ojspc translation options for pages that are targeted for the Oracle9i Servlet Engine (which does not use JspServlet)

OSE does not support execution-time configuration parameters.




■ The parameters debug_mode and send_error are supported from OracleJSP release 1.1.2.0 onward.

■ The parameters bypass_source, emit_debuginfo, external_resource, javaccmd, and sqljcmd are supported from OracleJSP release 1.1.0.0.0 onward.

■ The parameter alias_translation is for use in the Apache/JServ environment only.

■ The parameter session_sharing is for use with globals.jsa only (presumably in a servlet 2.0 environment such as Apache/JServ).

Notes:

■ See "The ojspc Pre-Translation Tool" on page 6-26 for a description of the ojspc options.

■ The distinction between execution-time and translation-time is not particularly significant in a real-time translation environment, but may be of interest with respect to OSE.



Table A–2 OracleJSP Configuration Parameters

ParameterRelated ojspc Options Description Default

Used in JSP Translation or Execution?

Used in Development or Deployment Environment?

alias_translation(Apache-specific)

n/a boolean; true to work around Apache/JServ limitations in directory aliasing for JSP page references

false execution development and deployment

bypass_source n/a boolean; true for OracleJSP to ignore FileNotFound exceptions on .jsp source; uses pre-translated and compiled code when source is not available

false execution deployment (also used by JDeveloper)

classpath -addclasspath (related, but different functionality)

additional classpath entries for OracleJSP class loading

null (no addl. path)

translation or execution

development and deployment

debug_mode n/a boolean; true for OracleJSP to print the stack trace when a runtime exception occurs

true execution development

developer_mode n/a boolean; false to not check timestamps to see if page retranslation and class reloading is necessary when a page is requested

true execution development and deployment

emit_debuginfo -debug boolean; true to generate a line map to the original .jsp file for debugging

false translation development

external_resource -extres boolean; true for OracleJSP to place all static content of the page into a separate Java resource file during translation

false translation development and deployment

javaccmd -noCompile Java compiler command line—javac options, or alternative Java compiler run in a separate JVM (null means use JDK javac with default options)

null translation development and deployment



page_repository_root -srcdir-d

alternative root directory (fully qualified path) for OracleJSP to use in loading and generating JSP pages

null(use default root)

translation or execution

development and deployment

send_error n/a boolean; true to output standard "404" messages for file-not-found, "500" messages for compilation errors (instead of outputting customized messages)

false execution deployment

session_sharing(for use with globals.jsa)

n/a boolean; for applications using globals.jsa, true for JSP session data to be propagated to underlying servlet session

true execution development and deployment

sqljcmd -S SQLJ command line—sqlj options, or alternative SQLJ translator run in a separate JVM (null means use the Oracle SQLJ version provided with OracleJSP, with default option settings)

null translation development and deployment

translate_params n/a boolean; true to override servlet containers that do not perform multibyte encoding

false execution development and deployment

unsafe_reload n/a boolean; true to not restart the application and sessions whenever a JSP page is retranslated and reloaded

false execution development

Table A–2 OracleJSP Configuration Parameters (Cont.)

ParameterRelated ojspc Options Description Default

Used in JSP Translation or Execution?

Used in Development or Deployment Environment?



Configuration Parameter DescriptionsThis section describes the OracleJSP configuration parameters in more detail.

alias_translation (boolean; OracleJSP default: false) (Apache-specific)

This parameter allows OracleJSP to work around limitations in the way Apache/JServ handles directory aliasing. For information about the current limitations, see "Directory Alias Translation" on page 4-42.

You must set alias_translation to true for httpd.conf directory aliasing commands, such as the following example, to work properly in the Apache/JServ servlet environment:

Alias /icons/ "/apache/apache139/icons/"

bypass_source (boolean; OracleJSP default: false)

Normally, when a JSP page is requested, OracleJSP will throw a FileNotFound exception if it cannot find the corresponding .jsp source file, even if it can find the page implementation class. (This is because, by default, OracleJSP checks the page source to see if it has been modified since the page implementation class was generated.)

Set this parameter to true for OracleJSP to proceed and execute the page implementation class even if it cannot find the page source.

If bypass_source is enabled, OracleJSP will still check for retranslation if the source is available and is needed. One of the factors in determining whether it is needed is the setting of the developer_mode parameter.

Notes:

■ The bypass_source option is useful in deployment environments that have the generated classes only, not the source. (For related discussion, see "Deployment of Binary Files Only" on page 6-75.)

■ Oracle JDeveloper enables bypass_source so that you can translate and run a JSP page before you have saved the JSP source to a file.



classpath (fully qualified path; OracleJSP default: null)

Use this parameter to add classpath entries to the OracleJSP default classpath for use during translation, compilation, or execution of JSP pages. For information about the OracleJSP classpath and class loader, see "Classpath and Class Loader Issues (Non-OSE Only)" on page 4-25.

The exact syntax depends on your Web server environment and operating system. See "OracleJSP Configuration Parameter Settings" on page A-26 for some examples.

Overall, OracleJSP loads classes from its own classpath (including entries from this classpath parameter), the system classpath, the Web server classpath, the page repository, and predefined locations relative to the root directory of the JSP application.

Be aware that classes loaded through the path specified in the classpath setting path are loaded by the JSP class loader, not the system class loader. During JSP execution, classes loaded by the JSP class loader cannot access (or be accessed by) classes loaded by the system class loader or any other class loader.

debug_mode (boolean; OracleJSP default: true)

Use the default true setting of this flag to direct OracleJSP to print a stack trace whenever a runtime exception occurs. Set it to false to disable this feature.

developer_mode (boolean; OracleJSP default: true)

Set this flag to false to instruct OracleJSP to not routinely compare the timestamp of the page implementation class to the timestamp of the .jsp source file when a page is requested. With developer_mode=true, OracleJSP checks every time to see if the source has been modified since the page implementation class was generated. If that is the case, OracleJSP retranslates the page. With

Notes:

■ OracleJSP runtime automatic class reloading applies only to classes in the OracleJSP classpath. This includes paths specified through this classpath parameter. (See "Dynamic Class Reloading" on page 4-30 for information about this feature.)

■ When you pre-translate pages to run in the Oracle9i Servlet Engine, the ojspc -addclasspath option offers some related, though different, functionality. See "Option Descriptions for ojspc" on page 6-30.



developer_mode=false, OracleJSP will check only upon the initial request for the page or application. For subsequent requests, it will simply re-execute the generated page implementation class.

This flag also affects dynamic class reloading for JavaBeans and other support classes called by a JSP page. With developer_mode=true, OracleJSP checks to see if such classes have been modified since being loaded by the OracleJSP class loader.

Oracle generally recommends setting developer_mode to false, particularly in a deployment environment where code is not likely to change and where performance is a significant issue.

Also see "OracleJSP Runtime Page and Class Reloading (Non-OSE Only)" on page 4-29.

emit_debuginfo (boolean; OracleJSP default: false) (for developer only)

Set this flag to true to instruct OracleJSP to generate a line map to the original .jsp file for debugging. Otherwise, lines will be mapped to the generated page implementation class.

external_resource (boolean; OracleJSP default: false)

Set this flag to true to instruct the OracleJSP translator to place generated static content (the Java print commands that output static HTML code) into a Java resource file instead of into the service method of the generated page implementation class.

The resource file name is based on the JSP page name, with the .res suffix. With Oracle9i, translation of MyPage.jsp, for example, would create _MyPage.res in addition to normal output. The exact implementation may change in future releases, however.

The resource file is placed in the same directory as generated class files.

If there is a lot of static content in a page, this technique will speed translation and may speed execution of the page. In extreme cases, it may even prevent the service

Notes:

■ Oracle JDeveloper enables emit_debuginfo.

■ When you are pre-translating pages to run in the Oracle9i Servlet Engine, the ojspc -debug option is equivalent. See "Option Descriptions for ojspc" on page 6-30.



method from exceeding the 64K method size limit imposed by the Java VM. For more information, see "Workarounds for Large Static Content in JSP Pages" on page 4-16.

javaccmd (compiler executable; OracleJSP default: null)

This parameter is useful in either of the following circumstances:

■ if you want to set javac command-line options (although default settings are typically sufficient)

■ if you want to use a compiler other than javac (optionally including command-line options)

Specifying an alternative compiler results in OracleJSP spawning that executable as a separate process in a separate JVM, instead of spawning the JDK default compiler within the same JVM in which OracleJSP is running. You can fully specify the path for the executable, or specify only the executable and let OracleJSP look for it in the system path.

Following is an example of a javaccmd setting to enable the javac -verbose option:

javaccmd=javac -verbose

The exact syntax depends on your servlet environment. See "OracleJSP Configuration Parameter Settings" on page A-26.

Note: When you are pre-translating pages to run in the Oracle9i Servlet Engine, the ojspc -extres option is equivalent.

The ojspc -hotload option is also relevant, performing the -extres functionality along with additional steps to allow hotloading into Oracle9i. See "Option Descriptions for ojspc" on page 6-30.



page_repository_root (fully qualified directory path; OracleJSP default: null)

OracleJSP uses the Web server document repository to generate or load translated JSP pages. By default, in an on-demand translation scenario, the root directory is the Web server doc root directory (for Apache/JServ) or the servlet context root directory of the application the page belongs to. JSP page source is in the root directory or some subdirectory. Generated files are written to a _pages subdirectory or some corresponding subdirectory.

Set the page_repository_root option to instruct OracleJSP to use a different root directory.

For information about file locations relative to the root directory and _pages subdirectory, see "OracleJSP Translator Output File Locations" on page 6-9.

send_error (boolean; OracleJSP default: false)

Set this flag to true to direct OracleJSP to output generic "404" messages for file-not-found conditions, and generic "500" messages for compilation errors.

Notes:

■ The specified Java compiler must be installed in the classpath and any front-end utility (if applicable) must be installed in the system path.

■ When you are pre-translating pages to run in the Oracle9i Servlet Engine, the ojspc -noCompile option allows similar functionality. It results in no compilation by javac, so you can compile the translated classes manually using your desired compiler. See "Option Descriptions for ojspc" on page 6-30.

Notes:

■ The specified directory, _pages subdirectory, and any appropriate subdirectories under these are created automatically if they do not already exist.

■ When you are pre-translating pages to run in the Oracle9i Servlet Engine, the ojspc options -srcdir and -d provide related functionality. See "Option Descriptions for ojspc" on page 6-30.



This is as opposed to outputting customized messages that provide more information (such as the name of the file not found). Some environments, such as Apache/JServ, do not allow output of a customized message if a "404" or "500" message is output.

session_sharing (boolean; OracleJSP default: true) (for use with globals.jsa)

When a globals.jsa file is used for an application, presumably in a servlet 2.0 environment, each JSP page uses a distinct JSP session wrapper attached to the single overall servlet session object provided by the servlet container.

In this situation, the default true setting of the session_sharing parameter results in JSP session data being propagated to the underlying servlet session. This allows servlets in the application to access the session data of JSP pages in the application.

If session_sharing is false (which parallels standard behavior in most JSP implementations), JSP session data is not propagated to the servlet session. As a result, application servlets would not be able to access JSP session data.

This parameter is meaningless if globals.jsa is not used. For information about globals.jsa, see "Overview of globals.jsa Functionality" on page 5-38.

sqljcmd (SQLJ translator executable and options; OracleJSP default: null)

This parameter is useful in any of the following circumstances:

■ if you want to set one or more SQLJ command-line options

(You can set multiple SQLJ options in the sqljcmd setting.)

■ if you want to use a different SQLJ translator (or at least a different version) than the one provided with OracleJSP

■ if you want to run SQLJ in a separate process from OracleJSP

Specifying a SQLJ translator executable results in OracleJSP spawning that executable as a separate process in a separate JVM, instead of spawning the default SQLJ translator within the same JVM in which OracleJSP is running.

You can fully specify the path for the executable, or specify only the executable and let OracleJSP look for it in the system path.

Following is an example of a sqljcmd setting:

sqljcmd=sqlj -user=scott/tiger -ser2class=true



(The exact syntax depends on your servlet environment. See "OracleJSP Configuration Parameter Settings" on page A-26.)

translate_params (boolean; OracleJSP default: false)

Set this flag to true to override servlet containers that do not encode multibyte (globalization support) request parameters or bean property settings. With this setting, OracleJSP encodes request parameters and bean property settings. Otherwise, OracleJSP returns the parameters from the servlet container unchanged.

Because the Oracle9i Servlet Engine does not support execution-time configuration parameters, translate_params cannot be set for the OSE environment. See "Code Equivalent to the translate_params Configuration Parameter" on page 10-7 for a workaround.

For more information about the functionality and use of translate_params, including situations where it should not be used, see "OracleJSP Extended Support for Multibyte Parameter Encoding" on page 10-5.

Notes:

■ Appropriate SQLJ files must be in the classpath, and any front-end utility (such as sqlj in the example) must be in the system path. (For Oracle SQLJ, the translator ZIP or JAR file and the appropriate SQLJ runtime ZIP or JAR file must be in the classpath. See "Summary of Files" on page A-4.)

■ Presumably the great majority of OracleJSP developers will use Oracle SQLJ (as opposed to some other SQLJ product) if they use SQLJ code in their JSP pages; however, this option is useful if you want to use a different Oracle SQLJ version (for example, one intended for use with Oracle JDBC 8.0.x/7.3.x drivers instead of Oracle9i drivers) or if you want to set SQLJ options.

■ When you are pre-translating pages to run in the Oracle9i Servlet Engine, the ojspc -S option provides related functionality. See "Option Descriptions for ojspc" on page 6-30.



unsafe_reload (boolean; OracleJSP default: false) (for developer only)

By default, OracleJSP restarts the application and sessions whenever a JSP page is dynamically retranslated and reloaded (which occurs when the JSP translator finds a .jsp source file with a more recent timestamp than the corresponding page implementation class).

Set this parameter to true to instruct OracleJSP not to restart the application after dynamic retranslations and reloads. This avoids having existing sessions become invalid.

For a given JSP page, this parameter has no effect after the initial request for the page if developer_mode is set to false (in which case OracleJSP never retranslates after the initial request).

OracleJSP Configuration Parameter SettingsHow to set the JSP configuration parameters discussed in the preceding section—"OracleJSP Configuration Parameters (Non-OSE)" on page A-15—depends on your Web server and servlet environment.

Non-Oracle environments support configuration parameter settings through properties files or similar functionality.

The Oracle9i Servlet Engine, provided with Oracle9i, does not directly support OracleJSP configuration parameters (because it does not use JspServlet). However, some of the translation parameter settings have equivalent OracleJSP translator options. These options are noted in the "Configuration Parameters Summary Table" on page A-15.

Other Oracle products that support OracleJSP have their own mechanisms for configuration settings—consult the product documentation.

Note: Beginning with OracleJSP release 1.1.3.x, it is preferable to use the PublicUtil.setReqCharacterEncoding() method instead of using the translate_params parameter. See "The setReqCharacterEncoding() Method" on page 10-5.

Important: This parameter is intended for developers only and is not recommended for deployment environments.



The remainder of this section describes how to set configuration parameters in the Apache/JServ, Sun Microsystems JSWDK, and Tomcat environments.

Setting OracleJSP Parameters in Apache/JServEach Web application in an Apache/JServ environment has its own properties file, known as a zone properties file. In Apache terminology, a zone is essentially the same as a servlet context.

The name of the zone properties file depends on how you mount the zone. (See the Apache/JServ documentation for information about zones and mounting.)

To set OracleJSP configuration parameters in an Apache/JServ environment, set the JspServlet initArgs property in the application zone properties file, as in the following example (which happens to use UNIX syntax):

servlet.oracle.jsp.JspServlet.initArgs=developer_mode=false,sqljcmd=sqlj -user=scott/tiger -ser2class=true,classpath=/mydir/myapp.jar

(This is a single wrap-around line.)

The servlet path, servlet.oracle.jsp.JspServlet, also depends on how you mount the zone. It does not represent a literal directory path.


■ The effects of multiple initArgs commands are cumulative and overriding. For example, the combination of the following two commands (in order):

servlet.oracle.jsp.JspServlet.initArgs=foo1=val1,foo2=val2servlet.oracle.jsp.JspServlet.initArgs=foo1=val3

is equivalent to the following single command:

servlet.oracle.jsp.JspServlet.initArgs=foo1=val3,foo2=val2

In the first two commands, the val3 value overrides the val1 value for foo1, but does not affect the foo2 setting.

■ Because initArgs parameters are comma-separated, there can be no commas within a parameter setting. Spaces and other special characters (such as "=" in this example) do not cause a problem, however.



Setting OracleJSP Parameters in JSWDKTo set OracleJSP configuration parameters in a JSWDK environment, set the jsp.initparams property in the servlet.properties file in the WEB-INF directory of the application servlet context, as in the following example (which happens to use UNIX syntax):

jsp.initparams=developer_mode=false,classpath=/mydir/myapp.jar

Setting OracleJSP Parameters in TomcatTo set OracleJSP configuration parameters in a Tomcat environment, add init-param entries in the web.xml file as shown below.

<servlet> <init-param> <param-name> developer_mode </param-name> <param-value> true </param-value> </init-param> <init-param> <param-name> external_resource </param-name> <param-value> true </param-value> </init-param> <init-param> <param-name>

Note: Because initparams parameters are comma-separated, there can be no commas within a parameter setting. Spaces and other special characters do not cause a problem, however.

Note: There is a global web.xml file in the [TOMCAT_HOME]/conf directory. To override any settings in this file for a particular application, update the web.xml file in the WEB-INF directory under the particular application root.



javaccmd </param-name> <param-value> javac -verbose </param-value> </init-param></servlet>

Oracle9i Servlet Engine JSP ConfigurationBecause the Oracle9i Servlet Engine does not use the OracleJSP JspServlet front-end, it requires other mechanisms for OracleJSP configuration settings.

Appropriate translation-time configuration parameters have equivalent support through command-line options of ojspc, which is the utility to pre-translate JSP pages for the OSE environment. The correlation between OracleJSP configuration parameters and ojspc options is noted in the table in "Configuration Parameters Summary Table" on page A-15.

There is no such equivalent support for runtime configuration parameters, however. The most significant of these is translate_params, required for use in supporting globalization in servlet environments that do not support multibyte encoding of request parameters. The Oracle9i Servlet Engine requires this functionality, but it is left to the developer to write equivalent code in the JSP page. For details, see "Code Equivalent to the translate_params Configuration Parameter" on page 10-7.


Servlet and JSP Technical Backgr

B
Servlet and JSP Technical Background
This appendix provides technical background on servlets and JavaServer Pages. Although this document is written for users who are well grounded in servlet technology, the servlet information here may be a useful refresher for some.

Standard JavaServer Pages interfaces, implemented automatically by generated JSP page implementation classes, are briefly discussed as well. Most readers, however, will not require this information.


■ Background on Servlets

■ Web Application Hierarchy

■ Standard JSP Interfaces and Methods

ound B-1

Background on Servlets

Background on ServletsBecause JSP pages are translated into Java servlets, a brief review of servlet technology may be helpful. Refer to the Sun Microsystems Java Servlet Specification, Version 2.2 for more information about the concepts discussed here.

For more information about the methods this section discusses, refer to Sun Microsystems Javadoc at the following location:

http://java.sun.com/products/servlet/2.2/javadoc/index.html

Review of Servlet TechnologyIn recent years, servlet technology has emerged as a powerful way to extend Web server functionality through dynamic HTML pages. A servlet is a Java program that runs in a Web server (as opposed to an applet, which is a Java program that runs in a client browser). The servlet takes an HTTP request from a browser, generates dynamic content (such as by querying a database), and provides an HTTP response back to the browser.

Prior to servlets, CGI (Common Gateway Interface) technology was used for dynamic content, with CGI programs being written in languages such as Perl and being called by a Web application through the Web server. CGI ultimately proved less than ideal, however, due to its architecture and scalability limitations.

Servlet technology, in addition to improved scalability, offers the well-known Java advantages of object orientation, platform independence, security, and robustness. Servlets can use all standard Java APIs, including the JDBC API (for Java database connectivity, of particular interest to database programmers).

In the Java realm, servlet technology offers advantages over applet technology for server-intensive applications such as those accessing a database. One advantage is that a servlet runs in the server, which is usually a robust machine with many resources, minimizing use of client resources. An applet, by contrast, is downloaded into the client browser and runs there. Another advantage is more direct access to the data. The Web server or data server in which a servlet is running is on the same side of the network firewall as the data being accessed. An applet running on a client machine, outside the firewall, requires special measures (such as signed applets) to allow the applet to access any server other than the one from which it was downloaded.

B-2 OracleJSP Support for JavaServer Pages Developer’s Guide and Reference


The Servlet InterfaceA Java servlet, by definition, implements the standard javax.servlet.Servlet interface. This interface specifies methods to initialize a servlet, process requests, get the configuration and other basic information of a servlet, and terminate a servlet instance.

For Web applications, the Servlet interface is implemented indirectly by subclassing the standard javax.servlet.http.HttpServlet abstract class. The HttpServlet class includes the following methods:

■ init(...) and destroy(...), to initialize and terminate the servlet, respectively

■ doGet(...), for HTTP GET requests

■ doPost(...), for HTTP POST requests

■ doPut(...), for HTTP PUT requests

■ doDelete(...), for HTTP DELETE requests

■ service(...), to receive HTTP requests and, by default, dispatch them to the appropriate doXXX() methods

■ getServletInfo(...), which the servlet uses to provide information about itself

A servlet class that subclasses HttpServlet must implement some of these methods, as appropriate. Each method takes as input a standard javax.servlet.http.HttpServletRequest instance and a standard javax.servlet.http.HttpServletResponse instance.

The HttpServletRequest instance provides information to the servlet regarding the HTTP request, such as request parameter names and values, the name of the remote host that made the request, and the name of the server that received the request. The HttpServletResponse instance provides HTTP-specific functionality in sending the response, such as specifying the content length and MIME type and providing the output stream.

Servlet ContainersServlet containers, sometimes referred to as servlet engines, execute and manage servlets. A servlet container is usually written in Java and is either part of a Web server (if the Web server is also written in Java) or otherwise associated with and used by a Web server.

Servlet and JSP Technical Background B-3


When a servlet is called (such as when a servlet is specified by URL), the Web server passes the HTTP request to the servlet container. The container, in turn, passes the request to the servlet. In the course of managing a servlet, a simple container performs the following:

■ creates an instance of the servlet and calls its init() method to initialize it

■ calls the service() method of the servlet

■ calls the destroy() method of the servlet to discard it when appropriate, so that it can be garbage collected

For performance reasons, it is typical for a servlet container to keep a servlet instance in memory for reuse, rather than destroying it each time it has finished its task. It would be destroyed only for infrequent events, such as Web server shutdown.

If there is an additional servlet request while a servlet is already running, servlet container behavior depends on whether the servlet uses a single-thread model or a multiple-thread model. In a single-thread case, the servlet container prevents multiple simultaneous service() calls from being dispatched to a single servlet instance—it may spawn multiple separate servlet instances instead. In a multiple-thread model, the container can make multiple simultaneous service() calls to a single servlet instance, using a separate thread for each call, but the servlet developer is responsible for managing synchronization.

Servlet SessionsServlets use HTTP sessions to keep track of which user each HTTP request comes from, so that a group of requests from a single user can be managed in a stateful way. Servlet session-tracking is similar in nature to HTTP session-tracking in previous technologies, such as CGI.

HttpSession InterfaceIn the standard servlet API, each user is represented by an object that implements the standard javax.servlet.http.HttpSession interface. Servlets can set and get information about the session in this HttpSession object, which must be of application-level scope.

A servlet uses the getSession() method of an HttpServletRequest object (which represents an HTTP request) to retrieve or create an HttpSession object for the user. This method takes a boolean argument to specify whether a new session object should be created for the user if one does not already exist.



The HttpSession interface specifies the following methods to get and set session information:

■ public void setAttribute(String name, Object value)

This binds the specified object to the session, under the specified name.

■ public Object getAttribute(String name)

This retrieves the object that is bound to the session under the specified name (or null if there is no match).

Depending on the implementation of the servlet container and the servlet itself, sessions may expire automatically after a set amount of time or may be invalidated explicitly by the servlet. Servlets can manage session lifecycle with the following methods, specified by the HttpSession interface:

■ public boolean invalidate()

This method immediately invalidates the session and unbinds any objects from it.

■ public boolean setMaxInactiveInterval(int interval)

This method sets a timeout interval, in seconds, as an integer.

■ public boolean isNew()

This method returns true within the request that created the session; it returns false otherwise.

■ public boolean getCreationTime()

This method returns the time when the session object was created, measured in milliseconds since midnight, January 1, 1970.

■ public boolean getLastAccessedTime()

This method returns the time of the last request associated with the client, measured in milliseconds since midnight, January 1, 1970.

Note: Older servlet implementations use putValue() and getValue() instead of setAttribute() and getAttribute(), with the same signatures.



Session TrackingThe HttpSession interface supports alternative mechanisms for tracking sessions. Each involves some way to assign a session ID. A session ID is an intermediate handle that is assigned and used by the servlet container. Multiple sessions by the same user can share the same session ID, if appropriate.

The following session-tracking mechanisms are supported:

■ cookies

The servlet container sends a cookie to the client, which returns the cookie to the server upon each HTTP request. This associates the request with the session ID indicated by the cookie. JSESSIONID must be the name of the cookie.

This is the most frequently used mechanism and is supported by any servlet container that adheres to the servlet 2.2 specification.

■ URL rewriting

The servlet container appends a session ID to the URL path. The name of the path parameter must be jsessionid, as in the following example:

http://host[:port]/myapp/index.html;jsessionid=6789

This is the most frequently used mechanism where clients do not accept cookies.

■ SSL Sessions

SSL (Secure Sockets Layer, used in the HTTPS protocol) includes a mechanism to take multiple requests from a client and define them as belonging to a single session. Some servlet containers use the SSL mechanism for their own session tracking as well.

Servlet ContextsA servlet context is used to maintain state information for all instances of a Web application within any single Java virtual machine (that is, for all servlet and JSP page instances that are part of the Web application). This is similar to the way a session maintains state information for a single client on the server; however, a servlet context is not specific to any single user and can handle multiple clients. There is usually one servlet context for each Web application running within a given Java virtual machine. You can think of a servlet context as an "application container".



Any servlet context is an instance of a class that implements the standard javax.servlet.ServletContext interface, with such a class being provided with any Web server that supports servlets.

A ServletContext object provides information about the servlet environment (such as name of the server) and allows sharing of resources between servlets in the group, within any single JVM. (For servlet containers supporting multiple simultaneous JVMs, implementation of resource-sharing varies.)

A servlet context maintains the session objects of the users who are running the application and provides a scope for the running instances of the application. Through this mechanism, each application is loaded from a distinct class loader and its runtime objects are distinct from those of any other application. In particular, the ServletContext object is distinct for an application, as is the HttpSession object for each user of the application.

As of the Sun Microsystems Java Servlet Specification, Version 2.2, most implementations can provide multiple servlet contexts within a single host, which is what allows each Web application to have its own servlet context. (Previous implementations usually provided only a single servlet context with any given host.)

The ServletContext interface specifies methods that allow a servlet to communicate with the servlet container that runs it, which is one of the ways that the servlet can retrieve application-level environment and state information.

Application Lifecycle Management Through Event ListenersThe Java Servlet Specification, Version 2.1 (and higher) provides limited application lifecycle management through the standard Java event-listener mechanism. HTTP session objects can use event listeners to make objects stored in the session object aware of when they are added or removed. Because the typical reason for removing objects within a session object is that the session has become invalid, this mechanism allows the developer to manage session-based resources. Similarly, the event-listener mechanism also allows the managing of page-based and request-based resources.

Note: In earlier versions of the servlet specification, the concept of servlet contexts was not sufficiently defined. Beginning with version 2.1(b), however, the concept was further clarified and it was specified that an HTTP session object could not exist across multiple servlet context objects.



Unfortunately, servlet context objects do not support this sort of notification. Standard servlet application support does not provide a way to manage application-based resources.

Servlet InvocationA servlet, like an HTML page, is invoked through a URL. The servlet is launched according to how servlets are mapped to URLs in the Web server implementation. Following are the possibilities:

■ A specific URL can be mapped to a specific servlet class.

■ An entire directory can be mapped so that any class in the directory is executed as a servlet. For example, the special /servlet directory can be mapped so that any URL of the form /servlet/<servlet_name> executes a servlet.

■ A file name extension can be mapped, so that any URL specifying a file whose name includes that extension executes a servlet.

This mapping would be specified as part of the Web server configuration.


Web Application Hierarchy

Web Application HierarchyThe entities relating to a Web application (which consists of some combination of servlets and JSP pages) do not follow a simple hierarchy, but can be considered in the following order:

1. servlet objects (including page implementation objects)

There is a servlet object for each servlet and for each JSP page implementation in a running application (and possibly more than one object, depending on whether a single-thread or multiple-thread execution model is used). A servlet object processes request objects from a client and sends response objects back to the client. A JSP page, as with servlet code, specifies how to create the response objects.

You can think of multiple servlet objects as being within a single request object in some circumstances, such as when one page or servlet "includes" or forwards to another.

A user will typically access multiple servlet objects in the course of a session, with the servlet objects being associated with the session object.

Servlet objects, as well as page implementation objects, indirectly implement the standard javax.servlet.Servlet interface. For servlets in a Web application, this is accomplished by subclassing the standard javax.servlet.http.HttpServlet abstract class. For JSP page implementation classes, this is accomplished by implementing the standard javax.servlet.jsp.HttpJspPage interface.

2. request and response objects

These objects represent the individual HTTP requests and responses that are generated as a user runs an application.

A user will typically generate multiple requests and receive multiple responses in the course of a session. The request and response objects are not "contained in" the session, but are associated with the session.

As a request comes in from a client, it is mapped to the appropriate servlet context object (the one associated with the application the client is using) according to the virtual path of the URL. The virtual path will include the root path of the application.

A request object implements the standard javax.servlet.http.HttpServletRequest interface.



A response object implements the standard javax.servlet.http.HttpServletResponse interface.

3. session objects

Session objects store information about the user for a given session and provide a way to identify a single user across multiple page requests. There is one session object per user.

There may be multiple users of a servlet or JSP page at any given time, each represented by their own session object. All these session objects, however, are maintained by the servlet context that corresponds to the overall application. In fact, you can think of each session object as representing an instance of the Web application associated with a common servlet context.

Typically, a session object will sequentially make use of multiple request objects, response objects, and page or servlet objects, and no other session will use the same objects; however, the session object does not "contain" those objects per se.

A session lifecycle for a given user starts with the first request from that user. It ends when the user session terminates (such as when the user quits the application) or there is a timeout.

HTTP session objects implement the javax.servlet.http.HttpSession interface.

4. servlet context object

A servlet context object is associated with a particular path in the server. This is the base path for modules of the application associated with the servlet context, and is referred to as the application root.

There is a single servlet context object for all sessions of the application in any given JVM, providing information from the server to the servlets and JSP pages that comprise the application. The servlet context object also allows application sessions to share data within a secure environment isolated from other applications.

The servlet container provides a class that implements the standard javax.servlet.ServletContext interface, instantiates this class the first time a user requests an application, and provides this ServletContext object with the path information for the location of the application.

Note: Prior to the 2.1(b) version of the servlet specification, a session object could span multiple servlet context objects.



The servlet context object typically has a pool of session objects to represent the multiple simultaneous users of the application.

A servlet context lifecycle starts with the first request (from any user) for the corresponding application. The lifecycle ends only when the server is shut down or otherwise terminated.

(For additional introductory information about servlet contexts, see "Servlet Contexts" on page B-6.)

5. servlet configuration object

The servlet container uses a servlet configuration object to pass information to a servlet when it is initialized—the init() method of the Servlet interface takes a servlet configuration object as input.

The servlet container provides a class that implements the standard javax.servlet.ServletConfig interface and instantiates it as necessary. Included within the servlet configuration object is a servlet context object (also instantiated by the servlet container).


Standard JSP Interfaces and Methods

Standard JSP Interfaces and MethodsTwo standard interfaces, both in the javax.servlet.jsp package, are available to be implemented in code that is generated by a JSP translator:

■ JspPage

■ HttpJspPage

JspPage is a generic interface that is not intended for use with any particular protocol. It extends the javax.servlet.Servlet interface.

HttpJspPage is an interface for JSP pages using the HTTP protocol. It extends JspPage and is typically implemented directly and automatically by any servlet class generated by a JSP translator.

JspPage specifies the following methods used in initializing and terminating instances of the generated class:

■ jspInit()

■ jspDestroy()

Any code for these methods must be included in scriptlets in your JSP page, as in the following example:

<%! void jspInit() { ...your implementation code... }%>

(JSP syntax is described later in this chapter. See "Scripting Elements" on page 1-12.)

HttpJspPage adds specification for the following method:

■ _jspService()

Code for this method is typically generated automatically by the translator and includes the following:

■ code from scriptlets in the JSP page

■ code resulting from any JSP directives

■ any static content of the page.



(JSP directives are used to provide information for the page, such as specifying the Java language for scriptlets and providing package imports. See "Directives" on page 1-10.)

As with the Servlet methods discussed in "The Servlet Interface" on page B-3, the _jspService() method takes an HttpServiceRequest instance and an HttpServiceResponse instance as input.

The JspPage and HttpJspPage interfaces inherit the following methods from the Servlet interface:

■ init()

■ destroy()

■ service()

■ getServletConfig()

■ getServletInfo()

Refer back to "The Servlet Interface" on page B-3 for a discussion of the Servlet interface and its key methods.


Compile-Time JML Tag Su

C
Compile-Time JML Tag Support
OracleJSP 1.0.0.6.x releases, because they were JSP 1.0 implementations, could support JML tags only as Oracle-specific extensions. (The tag library framework was not added to the JavaServer Pages specification until JSP 1.1.) For those releases, JML tag processing was built into the OracleJSP translator. This is referred to as "compile-time JML support".

OracleJSP 1.1.x releases continue to support the compile-time JML implementation; however, it is generally advisable to use the runtime implementation whenever possible. The runtime implementation is documented in Chapter 7, "JSP Tag Libraries and the Oracle JML Tags".

This appendix discusses features of the compile-time implementation that are not in common with the runtime implementation. This includes the following topics:

■ JML Compile-Time Versus Runtime Considerations and Logistics

■ JML Compile-Time/1.0.0.6.x Syntax Support

■ JML Compile-Time/1.0.0.6.x Tag Support

pport C-1

JML Compile-Time Versus Runtime Considerations and Logistics

JML Compile-Time Versus Runtime Considerations and LogisticsThis section discusses two aspects of compile-time tag libraries compared to runtime tag libraries:

■ general considerations in when it may be advantageous to use a compile-time tag library implementation (for any library, not just JML)

■ the taglib directive required for the compile-time JML implementation in particular

General Compile-Time Versus Runtime ConsiderationsThe Sun Microsystems JavaServer Pages Specification, Version 1.1, describes a runtime support mechanism for custom tag libraries. This mechanism, using an XML-style tag library description file to specify the tags, is covered in "Standard Tag Library Framework" on page 7-2.

Creating and using a tag library that adheres to this model assures that the library will be portable to any standard JSP environment.

There are, however, reasons to consider compile-time implementations:

■ A compile-time implementation may produce more efficient code.

■ A compile-time implementation allows the developer to catch errors during translation and compilation, instead of the end-user seeing them at runtime.

In the future, Oracle may offer a general framework for creating custom tag libraries with compile-time tag implementations. Such implementations would depend on the OracleJSP translator, so would not be portable to other JSP environments.

The general advantages and disadvantages of compile-time implementations apply to the Oracle JML tag library as well. There may be situations where it is advantageous to use the compile-time JML implementation as first introduced in older versions of OracleJSP. There are also a few additional tags in that implementation, and some additional expression syntax that is supported. (See "JML Compile-Time/1.0.0.6.x Syntax Support" on page C-4 and "JML Compile-Time/1.0.0.6.x Tag Support" on page C-7.)

It is generally advisable, however, to use the JML runtime implementation that adheres to the JSP 1.1 specification.

C-2 OracleJSP Support for JavaServer Pages Developer’s Guide and Reference

JML Compile-Time Versus Runtime Considerations and Logistics

The taglib Directive for Compile-Time JML SupportThe OracleJSP 1.0.0.6.x/compile-time JML support implementation uses a custom class supplied by Oracle, OpenJspRegisterLib, to implement JML tag support.

In a JSP page using JML tags with the compile-time implementation, the taglib directive must specify the fully qualified name of this class (as opposed to specifying a TLD file as in standard JSP 1.1 tag library usage).



For information about usage of the taglib directive for the JML runtime implementation, see "The taglib Directive" on page 7-14.

Compile-Time JML Tag Support C-3

JML Compile-Time/1.0.0.6.x Syntax Support

JML Compile-Time/1.0.0.6.x Syntax SupportThis section describes Oracle-specific bean reference syntax and expression syntax supported by the compile-time JML implementation, for specifying tag attribute values. The following topics are covered:

■ JML Bean References and Expressions, Compile-Time Implementation

■ Attribute Settings with JML Expressions

This functionality is not portable to other JSP environments.

JML Bean References and Expressions, Compile-Time ImplementationGenerally speaking, a bean reference is any reference to a JavaBean instance (bean) that results in accessing either a property or a method of the bean. This includes a reference to a property or method of a bean where the bean itself is a property of another bean.

This becomes cumbersome, because standard JavaBeans syntax requires that properties be accessed by calling their accessor methods rather than by direct reference. For example, consider the following direct reference:

a.b.c.d.doIt()

This must be expressed as follows in standard JavaBeans syntax:

a.getB().getC().getD().doIt()

Oracle’s compile-time JML implementation, however, offers abbreviated syntax.

JML Bean ReferencesOracle-specific syntax supported by the compile-time JML implementation allows bean references to be expressed using direct dot (".") notation. Note that standard bean property accessor method syntax is also still valid.

Consider the following standard JavaBean reference:

customer.getName()

In JML bean reference syntax, you can express this in either of the following ways:

customer.getName()

or:

customer.name



JavaBeans can optionally have a default property, whose reference is assumed if no reference is explicitly stated. Default property names can be omitted in JML bean references. In the example above, if name is the default property, then the following are all valid JML bean references:

customer.getName()

or:

customer.name

or simply:

customer

Most JavaBeans do not define a default property. Of those that do, the most significant are the JML datatype JavaBeans described in "JML Extended Datatypes" on page 5-2.

JML ExpressionsJML expression syntax supported by the compile-time JML implementation is a superset of standard JSP expression syntax, adding support for the JML bean reference syntax documented in the preceding section.

A JML bean reference appearing in a JML expression must be enclosed in the following syntax:

$[JML_bean_reference]

Attribute Settings with JML ExpressionsTag attribute documentation under "JSP Markup Language (JML) Tag Descriptions" on page 7-30 notes standard syntax that is portable. You can set attributes, as documented there, for either the runtime or the compile-time JML implementation and even for non-Oracle JSP environments.

If you intend to use only the Oracle-specific compile-time implementation, however, you can set attributes using JML bean references and JML expression syntax, as documented in "JML Bean References and Expressions, Compile-Time Implementation" above.



Note the following requirements:

■ Wherever Chapter 7 documents an attribute that accepts either a string literal or an expression, you can use a JML expression in its $[...] syntax inside standard JSP <%=...%> syntax.

Consider an example using the JML useVariable tag. You would use syntax such as the following for the runtime implementation:

<jml:useVariable id = "isValidUser" type = "boolean" value = "<%= dbConn.isValid() %>" scope = "session" />

You can alternatively use syntax such as the following for the compile-time implementation (the value attribute can be either a string literal or an expression):

<jml:useVariable id = "isValidUser" type = "boolean" value = "<%= $[dbConn.valid] %>" scope = "session" />

■ Wherever Chapter 7 documents an attribute that accepts an expression only, you can use a JML expression in its $[...] syntax without being nested in <%=...%> syntax.

Consider an example using JML choose...when tags. You would use something such as the following syntax for the runtime implementation (presume orderedItem is a JmlBoolean instance):

<jml:choose> <jml:when condition = "<%= orderedItem.getValue() %>" > You have changed your order: -- outputs the current order -- </jml:when> <jml:otherwise> Are you sure we can’t interest you in something? </jml:otherwise></jml:choose>

You can alternatively use syntax such as the following for the compile-time implementation (the condition attribute can be an expression only):

<jml:choose> <jml:when condition = "$[orderedItem]" > You have changed your order: -- outputs the current order -- </jml:when> <jml:otherwise> Are you sure we can’t interest you in something? </jml:otherwise></jml:choose>


JML Compile-Time/1.0.0.6.x Tag Support

JML Compile-Time/1.0.0.6.x Tag SupportThis section presents the following:

■ a summary of all compile-time tags, noting which are desupported in the runtime implementation

■ a description of tags supported by the compile-time implementation that are desupported in the runtime implementation

These tags are not documented in "JSP Markup Language (JML) Tag Descriptions" on page 7-30.

JML Tag Summary, 1.0.0.6.x/Compile-Time Versus 1.1.x.x/RuntimeMost JML tags are available in both the runtime model and the compile-time model; however, there are exceptions, as summarized in Table C–1.

Note: In most cases, JML tags that are desupported in the runtime implementation have standard JSP equivalents. Some of the compile-time tags, however, were desupported because they have functionality that is difficult to implement when adhering to the JSP 1.1 specification.

Table C–1 JML Tags Supported: Compile-Time Model Versus Runtime Model

TagSupported in OracleJSP Compile-Time Implementation?

Supported in OracleJSP Runtime Implementation?

Bean Binding Tags:

useBean yes no; use jsp:useBean

useVariable yes yes

useForm yes yes

useCookie yes yes

remove yes yes

Bean Manipulation Tags

getProperty yes no; use jsp:getProperty

setProperty yes no; use jsp:setProperty

set yes no



Descriptions of Additional JML Tags, Compile-Time ImplementationThis section provides detailed descriptions of JML tags that are still supported by the JML compile-time implementation, but are not supported by the JML runtime implementation. These tags are not documented under "JSP Markup Language (JML) Tag Descriptions" on page 7-30.

In summary, this consists of the following JML tags.

■ JML useBean Tag

■ JML getProperty Tag

■ JML setProperty Tag

call yes no

lock yes no

Control Flow Tags

if yes yes

choose yes yes

for yes yes

foreach yes; type attribute is optional yes; type attribute is required

return yes yes

flush yes yes

include yes no; use jsp:include

forward yes no; use jsp:forward

XML Tags

transform yes yes

styleSheet yes yes

Utility Tags

print yes; use double-quotes to specify a string literal

no; use JSP expressions

plugin yes no; use jsp:plugin

Table C–1 JML Tags Supported: Compile-Time Model Versus Runtime Model (Cont.)

TagSupported in OracleJSP Compile-Time Implementation?

Supported in OracleJSP Runtime Implementation?



■ JML set Tag

■ JML call Tag

■ JML lock Tag

■ JML include Tag

■ JML forward Tag

■ JML print Tag

■ JML plugin Tag

For the syntax documentation in the tag descriptions, note the following:

■ Italics indicate you must specify a value or string.


■ Default values of optional attributes are indicated in bold.


■ The prefix "jml:" is used. This is by convention, but is not required. You can specify any desired prefix in your taglib directive.

JML useBean TagThis tag declares an object to be used in the page, locating the previously instantiated object at the specified scope by name if it exists. If it does not exist, the tag will create a new instance of the appropriate class and attach it to the specified scope by name.

The syntax and semantics are the same as for the standard jsp:useBean tag, except that wherever a JSP expression is valid in jsp:useBean usage, either a JML expression or a JSP expression is valid in JML useBean usage.

Syntax

<jml:useBean id = "beanInstanceName" scope ="page | request | session | application" class ="package.class" | type = "package.class" | class ="package.class" type = "package.class" | beanName = "package.class | <%= jmlExpression %>" type = "package.class" />

Alternatively, you can have additional nested tags, such as setProperty tags, and use a </jml:useBean> end tag.



Attributes

Refer to the Sun Microsystems JavaServer Pages Specification, Version 1.1 for information about attributes and their syntax.

Example

<jml:useBean id = "isValidUser" class = "oracle.jsp.jml.JmlBoolean" scope = "session" />

JML getProperty TagThis tag is functionally identical to the standard jsp:getProperty tag. It prints the value of the bean property into the response.

For general information about getProperty usage, refer to "JSP Actions and the <jsp: > Tag Set" on page 1-18 or to the Sun Microsystems JavaServer Pages Specification, Version 1.1.

Syntax

<jml:getProperty name = "beanInstanceName" property = "propertyName" />

Attributes

■ name—This is the name of the bean whose property is being retrieved. This attribute is required.

■ property—This is the name of the property being retrieved. This attribute is required.

Example The following example outputs the current value of the salary property. (Assume salary is of type JmlNumber.)

<jml:getProperty name="salary" property="value" />


<%= salary.getValue() %>

JML setProperty TagThis tag covers the functionality supported by the standard jsp:setProperty tag, but also adds functionality to support JML expressions. In particular, you can use JML bean references.



For general information about setProperty usage, refer to "JSP Actions and the <jsp: > Tag Set" on page 1-18 or to the Sun Microsystems JavaServer Pages Specification, Version 1.1.

Syntax

<jml:setProperty name = "beanInstanceName" property = " * " | property = "propertyName" [ param = "parameterName" ] | property = "propertyName" value = "stringLiteral | <%= jmlExpression %>" />

Attributes

■ name—This is the name of the bean whose property is being set. This attribute is required.

■ property—This is the name of the property being set. This attribute is required.

■ value—This is an optional parameter that lets you set the value directly instead of from a request parameter. The JML setProperty tag supports JML expressions in addition to standard JSP expressions to specify the value.

Example The following example updates salary with a six percent raise. (Assume salary is of type JmlNumber.)

<jml:setProperty name="salary" property="value" value="<%= $[salary] * 1.06 %>" />


<% salary.setValue(salary.getValue() * 1.06); %>

JML set TagThis tag provides an alternative for setting a bean property, using syntax that is more convenient than that of the setProperty tag.

Syntax

<jml:set name = "beanInstanceName.propertyName" value = "stringLiteral | <%= jmlExpression %>" />



Attributes

■ name—This is a direct reference (JML bean reference) to the bean property to be set. This attribute is required.

■ value—This is the new property value. It is expressed either as a string literal, a JML expression, or a standard JSP expression. This attribute is required.

Example Each of the following examples updates salary with a six percent raise. (Assume salary is of type JmlNumber.)

<jml:set name="salary.value" value="<%= salary.getValue() * 1.06 %>" />

or:

<jml:set name="salary.value" value="<%= $[salary.value] * 1.06 %>" />

or:

<jml:set name="salary" value="<%= $[salary] * 1.06 %>" />

These are equivalent to the following:

<% salary.setValue(salary.getValue() * 1.06); %>

JML call TagThis tag provides a mechanism to invoke bean methods that return nothing.

Syntax

<jml:call method = "beanInstanceName.methodName(parameters)" />

Attributes

■ method—This is the method call as you would write it in a scriptlet, except that the beanInstancename.methodName portion of the statement can be written as a JML bean reference if enclosed in JML expression $[... ] syntax. This attribute is required.

Example The following example redirects the client to a different page:

<jml:call name=’response.sendRedirect("http://www.oracle.com/")’ />




<% response.sendRedirect("http://www.oracle.com/"); %>

JML lock TagThis tag allows controlled, synchronous access to the named object for any code that uses it within the tag body.

Generally, JSP developers need not be concerned with concurrency issues. However, because application-scoped objects are shared across all users running the application, access to critical data must be controlled and coordinated.

You can use the JML lock tag to prevent concurrent updates by different users.

Syntax

<jml:lock name = "beanInstanceName" > ...body...</jml:lock>

Attributes

■ name—This is the name of the object that should be locked during execution of code in the lock tag body. This is a required attribute.

Example In the following example, pageCount is an application-scoped JmlNumber value. The variable is locked to prevent the value from being updated by another user between the time this code gets the current value and the time it sets the new value.

<jml:lock name="pageCount" > <jml:set name="pageCount.value" value="<%= pageCount.getValue() + 1 %>" /></jml:lock>


<% synchronized(pageCount) { pageCount.setValue(pageCount.getValue() + 1); } %>



JML include TagThis tag includes the output of another JSP page, a servlet, or an HTML page in the response of this page (the page invoking the include). It provides the same functionality as the standard jsp:include tag except that the page attribute can also be expressed as a JML expression.

For general information about include usage, refer to "JSP Actions and the <jsp: > Tag Set" on page 1-18 or to the Sun Microsystems JavaServer Pages Specification, Version 1.1.

Syntax

<jml:include page = "relativeURL | <%= jmlExpression %>" flush = "true" />

Attributes

For general information about include attributes and usage, refer to the Sun Microsystems JavaServer Pages Specification, Version 1.1.

Example The following example includes the output of table.jsp, a presentation component that renders an HTML table, based on data in the query string and request attributes.

<jml:include page="table.jsp?maxRows=10" flush="true" />

JML forward TagThis tag forwards the request to another JSP page, a servlet, or an HTML page. It provides the same functionality as the standard jsp:forward tag except that the page attribute can also be expressed as a JML expression.

For general information about forward usage, refer to "JSP Actions and the <jsp: > Tag Set" on page 1-18 or to the Sun Microsystems JavaServer Pages Specification, Version 1.1.

Syntax

<jml:forward page = "relativeURL | <%= jmlExpression %>" />



Attributes

For general information about forward attributes and usage, refer to the Sun Microsystems JavaServer Pages Specification, Version 1.1.

Example

<jml:forward page="altpage.jsp" />

JML print TagThis tag provides essentially the same functionality as a standard JSP expression: <%= expr %>. A specified JML expression or string literal is evaluated, and the result is output into the response. With this tag, the JML expression does not have to be enclosed in <%= ... %> syntax; however, a string literal must be enclosed in double-quotes.

Syntax

<jml:print eval = ’" stringLiteral"’ | " jmlExpression" />

Attributes

eval—Specifies the string or expression to be evaluated and output. This attribute is required.

Examples Either of the following examples outputs the current value of salary, which is of type JmlNumber:

<jml:print eval="$[salary]"/>

or:

<jml:print eval="salary.getValue()" />

The following example prints a string literal:

<jml:print eval=’"Your string here"’ />



JML plugin TagThis tag has functionality identical to that of the standard jsp:plugin tag.

For general information about plugin usage, refer to "JSP Actions and the <jsp: > Tag Set" on page 1-18 or to the Sun Microsystems JavaServer Pages Specification, Version 1.1.


Index
Symbols_jspService() method, B-12
Aaction tags

forward tag, 1-21getProperty tag, 1-19include tag, 1-20overview, 1-18param tag, 1-20plugin tag, 1-22setProperty tag, 1-18useBean tag, 1-18

addclasspath, ojspc option, 6-30alias translation, Apache/JServ

alias_translation configuration parameter, A-19overview, 4-42

Apache/JServApache "mods", 2-6classpath configuration, A-8config, map file name extensions, A-11mod_jserv module, 2-7mod_ose module, 2-7OracleJSP application framework, 4-41OracleJSP dynamic include support, 4-39overview of JSP-servlet session sharing, 4-42overview of special considerations, 4-38setting configuration parameters, A-27support for OracleJSP, 2-11use with Oracle9i Application Server, 4-38

application eventsservlet application lifecycles, B-7

with globals.jsa, 5-43with JspScopeListener, 5-33

application framework for Apache/JServ, 4-41application hierarchy, B-9application object (implicit), 1-16application root functionality, 3-4application scope (JSP objects), 1-15application support

overview, 3-6servlet application lifecycles, B-7through globals.jsa, 5-39

application_OnEnd tag, globals.jsa, 5-44application_OnStart tag, globals.jsa, 5-43application-relative path, 1-9appRoot, ojspc option, 6-31

Bbatch updates--see update batchingbean references, compile-time JML, C-4binary data, reasons to avoid in JSP, 4-22binary file deployment, 6-75binary file location, ojspc d option, 6-32bypass_source config param, A-19

Ccache block expiration, Web Object Cache, 9-10cache block invalidation, Web Object Cache, 9-11cache block methods, Web Object Cache, 9-59cache block naming, Web Object Cache, 9-7, 9-16cache policy and scope, Web Object Cache, 9-6cache policy attributes, Web Object Cache, 9-12cache policy creation, Web Object Cache, 9-50

Index-1

cache policy descriptor, Web Object Cache, 9-63cache policy methods, Web Object Cache, 9-51cache repository descriptor, Web Object

Cache, 9-66cache tag (Web Object Cache), 9-22, 9-31cacheInclude tag (Web Object Cache), 9-32cacheXMLObj tag (Web Object Cache), 9-27, 9-31caching

Edge Side Includes, 8-2JESI tags for Edge Side Includes, 8-6Oracle Web Cache, 8-4Oracle9i and OracleJSP caching features,

overview, 2-19OracleJSP Web Object Cache, 9-1

call servlet from JSP, JSP from servlet, 3-7call tag, compile-time JML, C-12checker pages, 4-15choose tag, JML, 7-35class loader issues, 4-25class naming, translator, 6-6class reloading, dynamic, 4-30classesXX.zip, required file for JDBC, A-5classpath

classpath and class loader issues, 4-25classpath config param, A-20configuration, Apache/JServ, A-8configuration, JSWDK, A-10configuration, Tomcat, A-10Web server classpath configuration, A-8

client-side considerations, 3-3client-side translation, Oracle9i deployment

hotloading page implementation classes, 6-68loading translated pages, 6-64overview, 6-59pre-translating with ojspc, 6-59publishing pages with publishservlet, 6-69vs. server-side translation, 6-22

cloneable cache objects (Web Object Cache), 9-8code, generated by translator, 6-3comments (in JSP code), 1-14compilation

javaccmd config param, A-22ojspc noCompile option, 6-35

compile-time JML tagssyntax support, C-4

tag summary and descriptions, C-7taglib directive, C-3

config object (implicit), 1-17configuration

classpath and class loader issues, 4-25classpath, Apache/JServ, A-8classpath, JSWDK, A-10classpath, Tomcat, A-10config param descriptions (non-OSE), A-19config params, summary table (non-OSE), A-15equivalent code for config params, OSE, 4-37map file name extensions, Apache/JServ, A-11map file name extensions, JSWDK, A-12map file name extensions, Tomcat, A-12map JSP file name extensions, A-11optimization of execution, 4-24overview, OSE configuration, A-29setting configuration parameters, A-26setting parameters, Apache/JServ, A-27setting parameters, JSWDK, A-28setting parameters, Tomcat, A-28Web server and servlet environment, A-7Web server classpath, A-8

configuration parameters (non-OSE)setting, A-26summary table and descriptions, A-15

ConnBean JavaBeansample application, 11-25usage (for connection), 5-14

ConnCacheBean JavaBeansample application, 11-28usage (for connection cache), 5-16

connection cachingoverview, 4-9sample applications, 11-18through ConnCacheBean JavaBean, 5-16

connection, server-side (for OSE), 4-33containers

JSP containers, 1-7OSE JSP container, 2-27servlet containers, B-3

content type settingsdynamic (setContentType method), 10-4static (page directive), 10-2

context path, URLs, 6-17

Index-2

context, publishjsp option, 6-48context-relative path, 1-9control tag (JESI), 8-12control/include model (JESI tags)

examples, 8-15overview, 8-8

cookie tag (JESI), 8-24cookies, B-6createcontext command, 6-17, 6-20, 6-21, 6-48CursorBean JavaBean

sample application, 11-26usage (for DML), 5-20

custom tags--see tag libraries

Dd, ojspc option (binary output dir), 6-32data access

data-access JavaBeans, 5-13server-side JDBC connection, 4-33starter sample, 3-21strategies, 2-8

data-access JavaBeansConnBean for connection, 5-14ConnCacheBean for connection cache, 5-16CursorBean for DML, 5-20DBBean for queries, 5-19overview, 5-13sample applications, 11-23

database schema objects--see schema objectsdatatypes

JML datatypes example, 5-7JmlBoolean extended type, 5-3JmlFPNumber extended type, 5-5JmlNumber extended type, 5-4JmlString extended type, 5-6Oracle JML extended types, 5-2overview of OracleJSP extensions, 2-12

DBBean JavaBeansample application, 11-23usage (for queries), 5-19

dbClose SQL tag, close connection, 5-26dbCloseQuery SQL tag, close cursor, 5-27dbExecute SQL tag, DML/DDL, 5-28dbNextRow SQL tag, process results, 5-28

dbOpen SQL tag, open connection, 5-25dbQuery SQL tag, execute query, 5-26debugging

debug, ojspc option, 6-33debug_mode config param, A-20emit_debuginfo config param, A-21through JDeveloper, 2-28

declarationsglobal declarations, globals.jsa, 5-48member variables, 1-12method variable vs. member variable, 4-18

deployment environment, 3-2deployment to Oracle9i

ojspc pre-translation tool, 6-26overview of hotloading, 6-24overview of loadjava tool, 6-40overview of session shell tool, 6-42overview of tools, 6-26overview, features and logistics, 6-14server-side vs. client-side translation, 6-22static file location, 6-20with client-side translation, 6-59with server-side translation, 6-45

deployment, general considerationsdeploying pages with JDeveloper, 6-79deployment of binary files only, 6-75doc root, iAS vs. OSE, 6-73general pre-translation without execution, 6-75ojspc for non-OSE environments, 6-74overview, 6-73WAR deployment, 6-77

developer_mode config param, A-20development environment, 3-2directives

global directives, globals.jsa, 5-48include directive, 1-11overview, 1-10page directive, 1-10taglib directive, 1-11

directory alias translation--see alias translationdoc root

functionality, 3-4iAS vs. OSE, 6-73

dynamic class reloading, 4-30dynamic forward, special support for

Index-3

Apache/JServ, 4-39dynamic include

action tag, 1-20for large static content, 4-16logistics, 4-13special support for Apache/JServ, 4-39vs. static include, 4-12

dynamic page reloading, 4-29dynamic page retranslation, 4-29

EEdge Side Includes

access through JESI tags, 8-6JESI-ESI conversion, 8-28overview, 8-2

EJBs, calling from JSPsfrom the middle tier, 4-3from the Oracle9i Servlet Engine, 4-5overview, 4-3through a Java, 4-6through a JavaBean wrapper, 4-6

emit_debuginfo config param, A-21Enterprise JavaBeans--see EJBsenvironments, development vs. deployment, 3-2error processing

at runtime, 3-18send_error config param, A-23

ESI--see Edge Side Includesevent handling

servlet application lifecycles, B-7with globals.jsa, 5-43with HttpSessionBindingListener, 3-12with JspScopeListener, 5-33

exception object (implicit), 1-17execution models for OracleJSP, 2-26execution of a JSP page, 1-7expiration policy attributes, Web Object

Cache, 9-18expiration policy methods, Web Object Cache, 9-57expiration policy retrieval, Web Object Cache, 9-57expiration, Web Object Cache, 9-10explicit cache block naming, Web Object

Cache, 9-7, 9-16explicit JSP objects, 1-15

expressions, 1-12extend, ojspc option, 6-33extend, publishjsp option, 6-51extensions

extended functionality for servlet 2.0, 2-2overview of data-access JavaBeans, 2-14overview of extended datatypes, 2-12overview of extended globalization

support, 2-16overview of globals.jsa (application

support), 2-16overview of JML tag library, 2-14overview of JspScopeListener, 2-16overview of Oracle-specific extensions, 2-15overview of PL/SQL Server Pages support, 2-16overview of portable extensions, 2-12overview of programmatic extensions, 2-12overview of SQL tag library, 2-14overview of SQLJ support, 2-15overview of XML/XSL support, 2-13

external resource filefor static text, 4-17through external_resource parameter, A-21through ojspc extres option, 6-33

external_resource config param, A-21extres, ojspc option, 6-33

Ffallback tag (with plugin tag), 1-23Feiner, Amy (welcome), 1-3file name extensions, mapping, A-11files

generated by translator, 6-7installation for non-Oracle environments, A-6locations, ojspc d option, 6-32locations, ojspc srcdir option, 6-37locations, page_repository_root config

param, A-23locations, translator output, 6-9OracleJSP required files, A-4

flush tag, JML, 7-39for tag, JML, 7-36foreach tag, JML, 7-37forward tag, 1-21

Index-4

forward tag, compile-time JML, C-14fragment tag (JESI), 8-19full names, schema objects, 6-15

Ggenerated code, by translator, 6-3generated output names, by translator, 6-4getCache() method (Web Object Cache), 9-51getProperty tag, 1-19getProperty tag, compile-time JML, C-10globalization support

content type settings (dynamic), 10-4content type settings (static), 10-2multibyte parameter encoding, 10-5overview, 10-1sample depending on translate_params, 10-8sample not depending on

translate_params, 10-10globals.jsa

application and session lifecycles, 5-40application deployment, 5-39application events, 5-43distinct applications and sessions, 5-39event handling, 5-43example, declarations and directives, 5-49extended support for servlet 2.0, 5-38file contents, structure, 5-49global declarations, 5-48global JavaBeans, 5-48global JSP directives, 5-48overview of functionality, 5-38overview of syntax and semantics, 5-40sample application, application and session

events, 11-84sample application, application events, 11-81sample application, global declarations, 11-87sample applications, 11-81session events, 5-45

Hheader tag (JESI), 8-25hotload, ojspc option, 6-34hotload, publishjsp option, 6-50

hotloading (for OSE)enabling and accomplishing, 6-24enabling through ojspc, 6-61features and advantages, 6-25hotloading page implementation classes, 6-68ojspc hotload option, 6-34overview, 6-24publishjsp hotload option, 6-50

HttpJspPage interface, B-12HttpSession interface, B-4HttpSessionBindingListener, 3-12

Iif tag, JML, 7-34implement, ojspc option, 6-34implement, publishjsp option, 6-51implicit cache block naming, Web Object

Cache, 9-7, 9-16implicit JSP objects

overview, 1-15using implicit objects, 1-17

include directive, 1-11include tag, 1-20include tag (JESI), 8-14include tag, compile-time JML, C-14inner class for static text, 6-3installation of files, non-Oracle environment, A-6interaction, JSP-servlet, 3-7Internet Application Server--see Oracle9i

Application Serverinvalidate tag (JESI), 8-21invalidateCache tag (Web Object Cache), 9-34invalidateCacheXXX() methods (Web Object

Cache), 9-51invalidation

JESI invalidation examples, 8-25JESI page invalidation, 8-10

invalidation, Web Object Cache, 9-11invoke servlet from JSP, JSP from servlet, 3-7

Jjava command (session shell), 6-68JavaBeans

Index-5

bean references, compile-time JML, C-4data-access JavaBean samples, 11-23global JavaBeans, globals.jsa, 5-48JML bean binding tags, 7-30Oracle data-access beans, 5-13query bean sample application, 11-15use for separation of business logic, 1-5use with useBean tag, 1-18useBean sample application, 11-3vs. scriptlets, 4-2

javaccmd config param, A-22JDBC in JSP pages

performance enhancements, 4-9required files, A-5sample applications, 11-12server-side internal driver (for OSE), 4-33

JDeveloperOracleJSP support, 2-28use for deploying JSP pages, 6-79

jesi control tag, 8-12jesi cookie tag, 8-24jesi fragment tag, 8-19jesi header tag, 8-25jesi include tag, 8-14jesi invalidate tag, 8-21jesi object tag, 8-23jesi personalize tag, 8-27JESI tags

control/include examples, 8-15control/include model, 8-8JESI includes, functionality, 8-9motivation, 8-6overview of Oracle implementation, 8-7page invalidation, 8-10page invalidation examples, 8-25page invalidation tag and subtags, 8-21page personalization, 8-10page personalization example, 8-28page personalization tag, 8-27page setup and content tags, 8-12sample application, 11-43syntax symbology and notes, 8-11tag descriptions, 8-11tag handling, JESI-ESI conversion, 8-28template/fragment examples, 8-19

template/fragment model, 8-8usage models, 8-8

jesi template tag, 8-17jml call tag, compile-time JML, C-12jml choose tag, 7-35JML datatypes

descriptions, 5-2example, 5-7

JML expressions, compile-time JMLattribute settings, C-5syntax, C-5

jml flush tag, 7-39jml for tag, 7-36jml foreach tag, 7-37jml forward tag, compile-time JML, C-14jml getProperty tag, compile-time JML, C-10jml if tag, 7-34jml include tag, compile-time JML, C-14jml lock tag, compile-time JML, C-13jml otherwise tag, 7-35jml plugin tag, compile-time JML, C-16jml print tag, C-15jml remove tag, 7-33jml return tag, 7-38jml set tag, compile-time JML, C-11jml setProperty tag, compile-time JML, C-10jml styleSheet tag, 5-10JML tags

attribute settings, compile-time JML, C-5bean references, compile-time JML, C-4descriptions, additional compile-time tags, C-8descriptions, bean binding tags, 7-30descriptions, logic/flow control tags, 7-34descriptions, XSL stylesheet tags, 5-10expressions, compile-time JML, C-5overview, 7-20philosophy, 7-21requirements, 7-20sample application, 11-31summary of tags, categories, 7-21summary, compile-time vs. runtime, C-7tag descriptions, symbology and notes, 7-30tag library description file, 7-22taglib directive, 7-22taglib directive, compile-time JML, C-3

Index-6

jml transform tag, 5-10jml useBean tag, compile-time JML, C-9jml useCookie tag, 7-32jml useForm tag, 7-31jml useVariable tag, 7-30jml when tag, 7-35JmlBoolean extended datatype, 5-3JmlFPNumber extended datatype, 5-5JmlNumber extended datatype, 5-4JmlString extended datatype, 5-6JNDI in Oracle9i Servlet Engine, 4-36jsp fallback tag (with plugin tag), 1-23jsp forward tag, 1-21jsp getProperty tag, 1-19jsp include tag, 1-20JSP Markup Language--see JMLjsp param tag, 1-20jsp plugin tag, 1-22jsp setProperty tag, 1-18JSP translator--see translatorjsp useBean tag

sample application, 11-3syntax, 1-18

JspPage interface, B-12JspScopeEvent class, event handling, 5-33JspScopeListener

sample application, 11-34usage for event handling, 5-33

jspService() method, B-12JSP-servlet interaction

invoking JSP from servlet, request dispatcher, 3-8

invoking servlet from JSP, 3-7passing data, JSP to servlet, 3-8passing data, servlet to JSP, 3-9sample code, 3-10

JSWDKclasspath configuration, A-10config, map file name extensions, A-12setting configuration parameters, A-28support for OracleJSP, 2-11

Lloadjava tool (load to Oracle9i)

complete option syntax, 6-40loading translated pages, 6-64loading translated pages as class files, 6-64loading translated pages as source files, 6-66loading untranslated pages, 6-45overview, 6-40

lock tag, compile-time JML, C-13lookupPolicy() method (Web Object Cache), 9-50

Mmapping JSP file name extensions, A-11member variable declarations, 4-18method variable declarations, 4-18multibyte parameter encoding, globalization

support, 10-5

NNational Language Support--see Globalization

SupportNLS--see Globalization SupportnoCompile, ojspc option, 6-35

OObject Caching Service for Java--see Oracle9iAS

Object Caching Service for Javaobject tag (JESI), 8-23objects and scopes (JSP objects), 1-14ojspc pre-translation tool

command-line syntax, 6-30enabling hotloading, 6-61examples, 6-62for SQLJSP pages, 6-60key features and options, 6-61option descriptions, 6-30option summary table, 6-28output files, locations, related options, 6-38overview, 6-26overview of functionality, 6-27pre-translating for deployment to Oracle9i, 6-59simplest usage, 6-60use for non-OSE environments, 6-74

ojsp.jar, required file, A-4

Index-7

ojsputil.jar, optional file, A-4on-demand translation (runtime), 1-7, 2-26optimization

not checking for retranslation, 4-24not using HTTP session, 4-25unbuffering a JSP page, 4-24

Oracle Application Server, OracleJSP support, 2-9Oracle HTTP Server

advantages in using, 2-9role with OracleJSP, 2-6with mod_jserv, 2-7with mod_ose, 2-7

Oracle JVM, 4-33Oracle platforms supporting OracleJSP

JDeveloper, 2-28Oracle Application Server, 2-9Oracle9i Application Server, 2-5summary of releases, 2-23Web-to-go, 2-10

Oracle Servlet Engine--see Oracle9i Servlet EngineOracle Web Cache

introduction, 2-19versus Web Object Cache, 2-21

Oracle Web Cache, ESI processor, 8-4Oracle9i Application Server

OracleJSP support, 2-5use of Apache/JServ, 4-38

Oracle9i Servlet Enginecalling EJBs from JSPs in OSE, 4-5config parameters, equivalent code, 4-37configuration overview, A-29doc root, vs. iAS, 6-73JSP integration with PL/SQL Pages, 2-16OSE JSP container, 2-27overview, 2-4overview of pre-translation model, 2-26overview of special considerations, 4-32server-side JDBC connection, 4-33static files, 6-20URLs, 6-17use of JNDI, 4-36virtual paths, 6-17

Oracle9iAS Object Caching Service for Javaas default Web Object Cache repository, 9-4configuration notes, 11-65

introduction, 2-20versus Web Object Cache, 2-22

OracleJSP translator--see translatorotherwise tag, JML, 7-35out object (implicit), 1-17output files

generated by translator, 6-7locations, 6-9locations and related options, ojspc, 6-38ojspc d option (binary location), 6-32ojspc srcdir option (source location), 6-37page_repository_root config param, A-23

output names, conventions, 6-4

Ppackage naming

by translator, 6-6ojspc packageName option, 6-35publishjsp packageName option, 6-49

packageName, ojspc option, 6-35packageName, publishjsp option, 6-49page directive

characteristics, 4-19contentType setting for globalization

support, 10-2overview, 1-10

page events (JspScopeListener), 5-33page implementation class

generated code, 6-3overview, 1-7sample code, 6-9

page object (implicit), 1-16page reloading, dynamic, 4-29page retranslation, dynamic, 4-29page scope (JSP objects), 1-15page_repository_root config param, A-23pageContext object (implicit), 1-16page-relative path, 1-9param tag, 1-20personalize tag (JESI), 8-27PL/SQL Server Pages, use with OracleJSP, 2-16plugin tag, 1-22plugin tag, compile-time JML, C-16portability of OracleJSP, 2-2

Index-8

prefetching rows--see row prefetchingpre-translation

client-side (for OSE), 6-59for OSE (overview), 2-26server-side (for OSE), 6-46without execution, general, 6-75

pre-translation for deployment to Oracle9i, 6-59pre-translation tool, ojspc, 6-26print tag, JML, C-15properties, publishservlet option, 6-71PSP pages, use with OracleJSP, 2-16publishjsp command

examples, 6-51overview, 6-46publishing SQLJSP pages, 6-55syntax and options, 6-47

publishservlet commandexample, 6-71overview, 6-69syntax and options, 6-69

putCache() method (Web Object Cache), 9-51

Rrelease number, OracleJSP, code to display, 2-24reloading classes, dynamic, 4-30reloading page, dynamic, 4-29remove tag, JML, 7-33request dispatcher (JSP-servlet interaction), 3-8request events (JspScopeListener), 5-33request object (implicit), 1-16request objects, servlets, B-9request scope (JSP objects), 1-15RequestDispatcher interface, 3-8requesting a JSP page, 1-8requirements

summary of required files, A-4system requirements for OracleJSP, A-2

resolver, publishjsp option, 6-51resource management

application (JspScopeListener), 5-33overview of OracleJSP extensions, 3-17page (JspScopeListener), 5-33request (JspScopeListener), 5-33session (JspScopeListener), 5-33

standard session management, 3-12response object (implicit), 1-16response objects, servlets, B-9retranslation of page, dynamic, 4-29return tag, JML, 7-38reuse, publishservlet option, 6-70row prefetching

overview, 4-11through OracleJSP ConnBean, 5-14

rowset caching, 4-12runtime considerations

dynamic class reloading, 4-30dynamic page reloading, 4-29dynamic page retranslation, 4-29

runtime functionality, Web Object Cache, 9-10runtimeXX.zip, required file for SQLJ, A-5

SS, ojspc option (for SQLJ options), 6-35sample applications

basic samples, 11-2ConnBean sample, 11-25ConnCacheBean sample, 11-28connection caching pages, 11-18CursorBean sample, 11-26custom tag definition and use, 7-15data access, starter sample, 3-21data-access JavaBean samples, 11-23DBBean sample, 11-23get information, 11-10globalization, depending on

translate_params, 10-8globalization, not depending on

translate_params, 10-10globals.jsa samples, 11-81globals.jsa, application and session

events, 11-84globals.jsa, application events, 11-81globals.jsa, global declarations, 11-87hello page, 11-2HttpSessionBindingListener sample, 3-13JDBC samples, 11-12JESI tag sample, 11-43JML datatypes example, 5-7

Index-9

JML tag sample, 11-31JspScopeListener, event handling, 11-34JSP-servlet interaction, 3-10page implementation class code, 6-9query bean, 11-15query page (simple), 11-12shopping cart page, 11-5SQL tag examples, 5-29SQLJ example, 5-34SQLJ queries, 11-39useBean page, 11-3user-specified query page, 11-14Web Object Cache samples, 11-61XML query output, 11-38

schema objectsfor Java, 6-14full names and short names, 6-15loading Java files to create, 6-14package determination, 6-15publishing, 6-16

schema, publishjsp option, 6-48scopes (JSP objects), 1-15scripting elements

comments, 1-14declarations, 1-12expressions, 1-12overview, 1-12scriptlets, 1-13

scripting variables (tag libraries)defining, 7-8scopes, 7-9

scriptletsoverview, 1-13vs. JavaBeans, 4-2

section IDs (Web Object Cache), 9-53send_error config param, A-23server-side JDBC driver, 4-33server-side translation, Oracle9i deployment

loading untranslated pages into Oracle9i, 6-45overview, 6-45translating and publishing, publishjsp, 6-46vs. client-side translation, 6-22

service method, JSP, B-12servlet 2.0 environments

added support through globals.jsa, 5-38

globals.jsa sample applications, 11-81OracleJSP application root functionality, 3-5overview of OracleJSP functionality, 2-2

servlet containers, B-3servlet contexts

overview, B-6servlet context objects, B-10

servlet library, A-4servlet path, URLs, 6-18servlet sessions

HttpSession interface, B-4session tracking, B-6

servlet.jarrequired file, A-4versions, A-5

servlet-JSP interactioninvoking JSP from servlet, request

dispatcher, 3-8invoking servlet from JSP, 3-7passing data, JSP to servlet, 3-8passing data, servlet to JSP, 3-9sample code, 3-10

servletName, publishjsp option, 6-49servletName, publishservlet option, 6-70servlets

application lifecycle management, B-7request and response objects, B-9review of servlet technology, B-2servlet configuration objects, B-11servlet containers, B-3servlet context objects, B-10servlet contexts, B-6servlet interface, B-3servlet invocation, B-8servlet objects, B-9servlet sessions, B-4session objects, B-10session sharing, JSP, Apache/JServ, 4-42technical background, B-2wrapping servlet with JSP page, 4-39

sess_sh--see session shellsession events

with globals.jsa, 5-45with HttpSessionBindingListener, 3-12with JspScopeListener, 5-33

Index-10

session object (implicit), 1-16session objects, servlets, B-10session scope (JSP objects), 1-15session sharing

overview, JSP-servlet, Apache/JServ, 4-42session_sharing config param, A-24

session shell toolcreatecontext command, 6-17java command, 6-68key commands, 6-43key syntax elements, 6-42overview, 6-42publishjsp command, 6-46publishservlet command, 6-69unpublishjsp command, 6-58unpublishservlet command, 6-72

session supportdefault session requests, 3-6overview, 3-6through globals.jsa, 5-39

session tracking, B-6session_OnEnd tag, globals.jsa, 5-46session_OnStart tag, globals.jsa, 5-45session_sharing config param, A-24set tag, compile-time JML, C-11setContentType() method, globalization

support, 10-4setProperty tag, 1-18setProperty tag, compile-time JML, C-10setReqCharacterEncoding() method, multibyte

parameter encoding, 10-5short names, schema objects, 6-15showVersion, publishjsp option, 6-47source file location, ojspc srcdir option, 6-37SQL tags

examples, 5-29overview, tag list, 5-24requirements, 5-25

SQLJJSP code example, 5-34ojspc S option for SQLJ options, 6-35OracleJSP support, 5-34publishing SQLJSP pages with publishjsp, 6-55required files for use in JSP, A-5sample applications, 11-39

server-side SQLJ options, 6-56setting Oracle SQLJ options, 5-37sqljcmd config param, A-24sqljsp files, 5-37triggering SQLJ translator, 5-37

sqljcmd config param, A-24sqljsp files for SQLJ, 5-37srcdir, ojspc option, 6-37SSL sessions, B-6stateless, publishjsp option, 6-50stateless, publishservlet option, 6-70statement caching

overview, 4-10through OracleJSP ConnBean, 5-14through OracleJSP ConnCacheBean, 5-16

static files, Oracle9i Servlet Engine, 6-20static include

directive, 1-11logistics, 4-13vs. dynamic include, 4-12

static textexternal resource file, 4-17external resource, ojspc extres option, 6-33external_resource parameter, A-21generated inner class, 6-3workaround for large static content, 4-16

styleSheet tag, JML, 5-10Sun Microsystems JSWDK--see JSWDKsurrogates (Edge Side Includes), 8-3syntax (overview), 1-10system requirements for OracleJSP, A-2

Ttag handlers (tag libraries)

access to outer tag handlers, 7-10overview, 7-4sample tag handler class, 7-16tags with bodies, 7-6tags without bodies, 7-6

tag librariesdefining and using, end-to-end example, 7-15JESI tags, descriptions, 8-11JESI tags, overview, 8-6Oracle JML tag descriptions, 7-30

Index-11

Oracle JML tags, overview, 7-20Oracle SQL tags, 5-24overview, 1-23overview of standard implementation, 7-2runtime vs. compile-time implementations, C-2scripting variables, 7-8standard framework, 7-2strategy, when to create, 4-14tag handlers, 7-4tag library description files, 7-11tag-extra-info classes, 7-8taglib directive, 7-14web.xml use, 7-12

tag library description filesdefining shortcut URI in web.xml, 7-13for JESI tags, 8-29for Oracle JML tags, 7-22for Oracle SQL tags, 5-25for Web Object Cache, 9-39general features, 7-11sample file, 7-18

tag-extra-info classes (tag libraries)general use, getVariableInfo() method, 7-9sample tag-extra-info class, 7-17

taglib directivecompile-time JML, C-3for Oracle JML tags, 7-22for Oracle SQL tags, 5-25general use, 7-14syntax, 1-11use of full TLD name and location, 7-14use of shortcut URI, 7-14

template tag (JESI), 8-17template/fragment model (JESI tags)

examples, 8-19overview, 8-8

tipsavoid JSP use with binary data, 4-22JavaBeans vs. scriptlets, 4-2JSP page as servlet wrapper, 4-39JSP preservation of white space, 4-20key configuration issues, 4-24method vs. member variable declaration, 4-18page directive characteristics, 4-19static vs. dynamic includes, 4-12

using a "checker" page, 4-15when to create tag libraries, 4-14workaround, large static content, 4-16

TLD file--see tag library description fileTomcat

classpath configuration, A-10config, map file name extensions, A-12setting configuration parameters, A-28support for OracleJSP, 2-11

toolsfor deployment to Oracle9i, 6-26ojspc for client-side translation, 6-26overview of loadjava (load to Oracle9i), 6-40overview of session shell, 6-42

transform tag, JML, 5-10translate_params config param

code equivalent, 10-7effect in overriding non-multibyte servlet

containers, 10-6general information, A-25globalization sample depending on it, 10-8globalization sample not depending on it, 10-10overview, multibyte parameter encoding, 10-6

translationclient-side pre-translation (for OSE), 6-59on-demand (runtime), 1-7server-side pre-translation (for OSE), 6-46server-side vs. client-side (for OSE), 6-22

translatorgenerated class names, 6-6generated code features, 6-3generated files, 6-7generated inner class, static text, 6-3generated names, general conventions, 6-4generated package names, 6-6output file locations, 6-9sample generated code, 6-9

translator.zip, required file for SQLJ, A-5

Uunpublishjsp command, 6-58unpublishservlet command, 6-72unsafe_reload config param, A-26update batching

Index-12

overview, 4-11through OracleJSP ConnBean, 5-14

URLscontext path, 6-17for Oracle9i Servlet Engine, 6-17servlet path, 6-18URL rewriting, B-6

usage, publishjsp option, 6-47useBean tag

sample application, 11-3syntax, 1-18

useBean tag, compile-time JML, C-9useCacheObj tag (Web Object Cache), 9-30, 9-31useCookie tag, JML, 7-32useForm tag, JML, 7-31useVariable tag, JML, 7-30

Vverbose, ojspc option, 6-37verbose, publishjsp option, 6-50version number, OracleJSP, code to display, 2-24version, ojspc option, 6-38virtual path (in OSE URLs), 6-17virtualpath, publishjsp option, 6-48virtualpath, publishservlet option, 6-70

WWAR deployment, 6-77Web application hierarchy, B-9Web Object Cache

benefits, 9-2cache block methods, 9-59cache block naming, 9-7, 9-16cache block runtime functionality, 9-10cache policy and scope, 9-6cache policy attributes, 9-12cache policy creation, 9-50cache policy descriptor, 9-63cache policy methods, 9-51cache repository descriptor, 9-66cache tag, 9-22cache tag examples, 9-38cacheInclude tag, 9-32

cacheXMLObj tag, 9-27cloneable cache objects, 9-8configuration notes for file system cache, 11-69configuration notes for Oracle9iAS Object

Caching Service for Java, 11-65data invalidation and expiration, 9-10expiration policy attributes, 9-18expiration policy retrieval, 9-57expiraton policy methods, 9-57invalidateCache tag, 9-34overview, 9-2overview, cache repository, 9-4overview, programming interfaces, 9-5role, versus other caches, 2-21sample applications, 11-61section IDs, 9-53servlet API descriptions, 9-50servlet example, 9-59tag descriptions, 9-21tag library description file, 9-39useCacheObj tag, 9-30

Web-to-go, OracleJSP support, 2-10web.xml, usage for tag libraries, 7-12when tag, JML, 7-35wrapping servlet with JSP page, 4-39

Xxmlparserv2.jar, required file, A-4XML/XSL support

JML tags for XSL stylesheets, 5-10overview, 5-9sample application, 11-38XML-alternative syntax, 5-9XSL transformation example, 5-11

xsu12.jar or xsu111.jar, optional file, A-4

Index-13

Index-14

[orc-xx] oraclejsp

Documents

htmlxml comment

side internal

integer constant

httpservlet

web object

cache policy

commercial

initargsfoo1val3