Introduction
Application Overview
Software Requirements
Terminology
Configuring the Application
Deploying and Running the Application
Sample Application Files
Additional References

Introduction

• Prerequisite
  
  
• Technical Overview

Prerequisite

• JSP
  
  
• JDBC

Technical Overview

In most of the web applications users happen to browse through a large lists of data, may be resulted through a search. Often it is impractical to transmit the whole set of results as the list is often discarded after the first few elements are examined. Typically, a client uses the results of a query for read-only purposes, such as viewing the results list. In such situations transmitting the whole list, results in poor performance due to latency of response and need of large memory footprint.

The Value List Handler pattern provides an efficient way while retrieving large amounts of data from the data sources. This pattern is designed for cases when:

• The user is interested in only a portion of the list at any time
  
• The whole list will not fit on the client display
  
• The whole list will not fit in memory
  
• Transmitting the entire list at once would take too much time
  

A value list handler provides the client with an iterator for a virtual list that resides in another application tier. The iterator typically accesses a local ordered collection of Value Objects, representing a subrange of the large list. A Data Access Object usually manages access to the list data, and may provide caching.

Application Overview

Consider that a fictitious organization has internet enabled all its applications. Sales and marketing employees of this organization use web-based Order Entry application to monitor various Orders and order status for various products .

This simplified Order Entry application connects to the database and fetches all the orders and displays it to the user. User can select a particular order and view its details. Also from the order details page one can view the product details for a particular product.

In this sampe application, when the user invokes orders.jsp page, the ClientBean class connects to the database through DBManager and fetches the records to display it to the user. As it may be impractical to display the entire list of orders to user when the list is large, the application manages the list using the ValueListHandler. So the DBManager returns an instance of ValueListHandler which is then used by the JSP to display the records. Instead of displaying all the records at a time, this page displays only ten records for each request. The user can iterate thorough the rest of the records using the navigational links provided.
Same sequence of actions take place when the order details are viewed. Here only five records are displayed per page.

The following class diagram depicts the important classes in the Value List Handler pattern.

The following sequence diagram depicts the interactions in the sample application.

Software Requirements

List the softwares required for configuring and running this sample application.

• Oracle JDeveloper 10g
• Oracle Containers for J2EE (OC4J) - version 9.0.4
  and ANT - version 1.5 or above for building the EAR file
  and J2ESDK1.4.x
• Oracle 10g Database
• Oracle Database 10g JDBC Driver
  

Terminology

Term	Definition
<OC4J_HOME>	The directory where OC4J is installed. For e.g., D:\oc4j
<J2EE_HOME>	The directory j2ee/home under <OC4J_HOME>. For e.g., D:\oc4j\j2ee\home
<JAVA_HOME>	Directory where JAVA is installed.
<ORACLE_HOME>	The directory where Oracle Database is installed

Configuring the Application

• Unjar the provided ValueListHandler.jar using the following command 
  
  jar xvf ValueListHandler.jar
  
  

  Note: You will find jar.exe in <JAVA_HOME>\bin. Ensure <JAVA_HOME>\bin is present in your system path.  For setting up environment variables in different platforms, please refer environment set up document.
  
  This creates a folder ValueListHandler with all the source files.

• Edit ValueListHandler/config/Connection.properties file in your favorite editor. Change the HostName, Port, SID, UserName and Password to connect to your own database Example,
  
  

  HostName	=	localhost (or name of the server where database is installed)
  SID	=	ORCL
  Port	=	1521
  UserName	=	oe
  Password	=	oe

Deploying and Running the Application

The application can be deployed and run in either of the following ways:

• Run the Application using Oracle JDeveloper 10g
  
  
• Run the Application using JDK/ANT

Run the Application using JDeveloper

This section describes the steps required in deploying and running this application inside embedded OC4J using Oracle JDeveloper 10g.

• Open Oracle JDeveloper 10g and use File/Open option to select the ValueListHandler.jws from the ValueListHandler directory
  
  
• Select Project->ValueListHandler.jpr->Project Settings->Configurations->Development->Libraries
  Edit Oracle 10g JDBC to include ojdbc14.jar in the classpath.
  
  
• Next, select Project/Make ValueListHandler.jpr from main menu
  
  
• Now, select Run/Run ValueListHandler.jpr from main menu which opens up the browser and runs the ValueListHandler

Run the Application using JDK

This section describes the steps required in deploying this application to the Standalone OC4J using ANT Tool and running using the browser.

Note: Make sure that the environment variables[<JAVA_HOME>, <ANT_HOME>/bin in the PATH;, <JAVA_HOME>/bin in the PATH] have been set before proceeding further. For more information on how to setup these environment variables, please refer environment set up readme document.

• Ensure that OC4J is up and running. To start the OC4J server, navigate to <OC4J_HOME>/j2ee/home and execute the following command,
  > java -jar oc4j.jar
  
  
• Build and deploy the EAR file using ANT. From ValueListHandler directory, execute the ant command,
  > ant
  
  Note: This will ask for various parameters at the start such as ojdbc14.jar location, <OC4J_HOME>, host address of the machine where the OC4J server is running, port in which the OC4J listens for ormi requests[default value is 23791], admin user name[default value is admin ] and admin password. Upon successful execution, this script will create the ValueListHandler.ear file and deploy it to the standalone OC4J server.
  
  
• Open your favorite browser and access the sample application, using the following URL,
  http://hostName:port/ValueListHandler/orders.jsp
  
  where,
  <host_name> is the machine on which OC4J is running and <port> is Port in which the OC4J server listens to HTTP requests. By default OC4J listens for HTTP requests in port # 8888
  Example: http://localhost:8888/ValueListHandler/orders.jsp

Sample Application Files 

This section will provide a tabular listing of the sample application files, along with their respective directory locations and a description of what they do in the overall scheme of the application.

Directory	File	Description
ValueListHandler\doc	Readme.html	This file
ValueListHandler\src\oracle\otnsamples\vlh	*Java	Java source files used in this sample application
ValueListHandler\public_html	*.jsp	JSP files used in this sample application
ValueListHandler\public_html\WEB-INF\web.xml	web.xml	Web deployment descriptor
ValueListHandler\config	Connection.properties	The properties file that holds the database details
ValueListHandler\config	application.xml	This file is used in the ANT deployment of this application
ValueListHandler	build.xml	The ANT build file

Additional References 

• Core J2EE Patterns Value List Handler
• Design Patterns for Optimizing the Performance of J2EE Applications
• Patterns repository on OTN
  
  

Please enter your comments about this sample application here.